Web Services with Finesse 10.5 and UCCE Packaged

[Luis Enrique Perez Trujillo]

Hi, We installed a new Packaged UCCE 10.5 for 20 agents, We need communicate the UCCE with third party through Web Services, it's our first installation and I don't know very well the solution when integrate Web Services.

In the implementation I have Finesse 10.5 for both sides.

Can you help me with any experience or documentation?

I hope your comments.

[dekwan]

Hi,

To better assist you, I would like to know more about the third party application you are trying to build. Then, I can point you in the right direction. Is this going to be a UI? Are you using the out of the box finesse agent desktop?

You say "We need to communicate the UCCE", what do you need to communicate?

Since I do not know exactly what you need, here is the developer guide for Finesse 10.5.

Thanx,

Denise

[Luis Enrique Perez Trujillo]

Hi Denise, the scenario is the next

UCCE <==> Web Services <=====> AWeb

Where: UCCE have Finesse and is the version packaged 10.5 for CCE; the Web services are development for us and the AWeb is other web service was build

The dynamic for agents is:

1. The agent login in AWeb, when login is successful send the agent data to Web Services.

2. Web Services receive the user y password and send this information to Finesse.

3. When Finesse receive the data, the agent login automatic in Finesse for take calls.

4. When logout in the AWeb is the reverse process

When I say "We need to communicate the UCCE"; I refer to Finesse.

So, the Web Services is the I need build.

I hope that my comments helped you.

[dekwan]

Hi,

If all you need is logging in and logging out of Finesse, you will need these two APIs. Note that these links are from the Finesse 11.0 doc. It is just easier for me to give you a direct link versus telling you to scroll in the PDF. For these APIs, they are the same as 10.5.

Login: https://developer.cisco.com/media/finesseDevGuide2/CFIN_RF_S21A5A70_00_sign-in.html

Logout: https://developer.cisco.com/media/finesseDevGuide2/CFIN_RF_SC0D86B5_00_sign-out-of-finesse.html

In most contact center setups, the agent needs to be in READY state in order to take calls. If so, you need the change agent state API: https://developer.cisco.com/media/finesseDevGuide2/CFIN_RF_C1D2CCD7_00_change-agent-state.html

So for your scenario, this is what you would need to do:

1. The agent login in AWeb, when login is successful send the agent data to Web Services.

2. Web Services receive the user y password and send this information to Finesse.

3. When Finesse receive the data, the agent login automatic in Finesse for take calls.

          Call the Login API.

          Call the Change State API if the agent needs to be in READY state to receive calls.

4. When logout in the AWeb is the reverse process

          Call the Change State API if the agent was put to READY state in the previous step.

          Call the Logout API.

For the full Finesse developers guide specifically for 10.5.

I hope this information helps.

Thanx,

Denise

[Luis Enrique Perez Trujillo]

Hi Denise, how are you?

We will test with your notes.

I hope have good news very soon. Thanks soo much.

[dekwan]

Hi,

I hope you have good news too! I just reread my answer and I think I was a bit confusing  for the change state. For Step 3's change state, you will be changing to READY state. For Step 4's change state, you will be changing back to NOT_READY state.

I am just assuming that you will need these steps because most contact center applications requires agents to be in READY state to receive calls.

Thanx,

Denise

[Luis Enrique Perez Trujillo]

Hi Denise, among us this Mario that is a developer Finesse. Mario have some doubts about API and Finesse, him continue with the discussion.

I hope the comments by Mario.

Thanks Denise

[dekwan]

Hi Mario,

What questions do you have about the API and Finesse?

Thanx,

Denise

[mario.covarrubias]

Hi Denise:

As Enrique mentioned, we are trying to integrate UCCE 10.5 with a Web application using Web Services, the objective is to allow communication between both, and register changes in UCCE databases depending on the actions executed in the web app. We believe Finesse should be the way to affect UCCE’s databases, in order to protect the data of those databases.

Our web services are being developed using C#.NET, Web API and XML/Json. My questions for this are:

• Can we call Finesse APIs from web services with these technologies?
• How can we call the Finesse APIs? Do we just have to use the corresponding URI specified in the API?

There are many functions we need to do, and first of all, we would like to know which of these functions can be really done using Finesse. These are the functionalities that are needed to perform in this integration:

FROM ADMINISTRATOR ROLE:

• Register agent (add new agent to database).
• Unregister agent (delete agent of database). Note: in this case, is it better to just change the agent’s status instead of deleting (for data integrity)? Which status would apply in this case?
• Get a list of registered agents.
• Register telephone extension (add new extension to database).
• Unregister telephone extension (delete extension of database). Note: in this case, is it better to just change the extension’s status instead of deleting (for data integrity)? Which status would apply in this case?
• Get list of registered telephone extensions.

FROM AGENT ROLE:

• Agent login.
• Agent logout.
• Get a list of logged agents.
• Change status of agent.
• Blacklist management (add and delete phone numbers and actions, and get a list of registered numbers or actions). Note: We don’t really know if UCCE 10.5 manages a blacklist of phone numbers. Does it have this kind of information?
• Whitelist management (add and delete phone numbers, and get a list of registered numbers). Note: We don’t really know if UCCE 10.5 manages a whitelist of phone numbers. Does it have this kind of information?
• Transfer a call to another extension.
• Make a call from an extension to a phone number.
• Answer a call.
• Finish a call (hang up).

FROM SUPERVISOR ROLE:

• Monitor a call, without agent and caller knowing.
• Coaching, helping the agent without caller knowing.
• Call conference, active participation in the call with agent and caller.
• Unregister number from blacklist.
• Unregister number from whitelist.

As you can see, there are many things we need to do. Hope you can help us to know if they can be done using Finesse and, if they can be done using Finesse, detecting the correct APIs for each function.

Thanks in advance.

Mario

[dekwan]

Hi Mario,

I will try to answer each question individually:

• Can we call Finesse APIs from web services with these technologies?

Finesse is just a REST API, so yes. I found a tutorial that might help: Calling a Web API From a .NET Client in ASP.NET Web API 2

• How can we call the Finesse APIs? Do we just have to use the corresponding URI specified in the API?

I think the above tutorial will help. The Finesse documentation has a table for each API and it tells you what is the URI, HTTP method, HTTP request, etc. If you are not familiar with REST APIs, I suggest searching for an introduction on the web. Then, the Finesse documentation has a section called Lab Development Environment Validation with Cisco Finesse Web Services APIs on how to use a client to test out your lab environment. This will be helpful for you to understand the basic usage of Finesse APIs before programatically using it.

FROM ADMINISTRATOR ROLE:

• Register agent (add new agent to database).
• Unregister agent (delete agent of database). Note: in this case, is it better to just change the agent’s status instead of deleting (for data integrity)? Which status would apply in this case?
• Get a list of registered agents.
• Register telephone extension (add new extension to database).
• Unregister telephone extension (delete extension of database). Note: in this case, is it better to just change the extension’s status instead of deleting (for data integrity)? Which status would apply in this case?
• Get list of registered telephone extensions.

The APIs for administrator role would be a PCCE API, if available. I suggest that you take a look at the PCCE API documentation. I have not used the PCCE APIs myself, but I did a quick look at it to see what is available. I noticed APIs to create, delete, and get a list of agents, but didn't see the other 3 items. If you have further questions, you can ask the question in the PCCE forum.

• Agent login.

User—Sign In to Finesse

• Agent logout.

User—Sign Out of Finesse

• Get a list of logged agents.

This cannot be done from the agent role. It can be done via the administrator role: User—Get List

• Change status of agent.

User—Change Agent State

• Blacklist management (add and delete phone numbers and actions, and get a list of registered numbers or actions). Note: We don’t really know if UCCE 10.5 manages a blacklist of phone numbers. Does it have this kind of information?

This cannot be done using Finesse APIs

• Whitelist management (add and delete phone numbers, and get a list of registered numbers). Note: We don’t really know if UCCE 10.5 manages a whitelist of phone numbers. Does it have this kind of information?

This cannot be done using Finesse APIs

• Transfer a call to another extension.

There are two versions of transfer.

1. Dialog—Initiate a Single Step Transfer
2. Do a Dialog—Make a Consult Call Request, then Dialog—Take Action on Participant with TRANSFER as the action

• Make a call from an extension to a phone number.

Dialog—Create a New Dialog (Make a Call)

• Answer a call.

Dialog—Take Action on Participant with ANSWER as the action

• Finish a call (hang up).

Dialog—Take Action on Participant with DROP as the action

• Monitor a call, without agent and caller knowing.

Dialog—Make a Silent Monitor Call

Dialog—End a Silent Monitor Call

• Coaching, helping the agent without caller knowing.

I am not familiar with this. The only things a supervisor can do is silent monitor or barge, so I am guessing the answer is that Finesse does not support this.

• Call conference, active participation in the call with agent and caller.

There are two concepts of conference for a supervisor

1. The supervisor is already silent monitoring the call and Dialog—Make a Barge Call to form a conferencehttps://developer.cisco.com/media/finesseDevGuide2/CFIN_RF_D1EA2B1B_00_dialog-make-a-barge-call.html
2. The agent Dialog—Make a Consult Call Request the supervisor and Dialog—Take Action on Participant with CONFERENCE as the action

• Unregister number from blacklist.

This cannot be done using Finesse APIs

• Unregister number from whitelist.

This cannot be done using Finesse APIs

As you can see, there are many things we need to do. Hope you can help us to know if they can be done using Finesse and, if they can be done using Finesse, detecting the correct APIs for each function.

Although I have pointed to the correct API for each function, I suggest that you take a look at the Finesse documentation to understand all of the APIs Finesse has to offer.

Thanx,

Denise

[mario.covarrubias]

Hi Denise:

Thanks for your patience and response, we know that they were many doubts to present.

We have actually been reviewing Finesse documentation in order to identify the APIs that might be needed for all the functionalities that I enlisted before, and I believe that we detected almost the same APIs that you have proposed. We are still reviewing the documentation, so your answer will help us a lot to confirm our selected APIs.

What we didn’t know was about PCCE API, so we will review the documentation that you kindly gave us to see if it is what we need.

I’m sure we will still need your help in this matter, so expect more questions in the near future.

Thanks a lot for your help.

Mario.

[dekwan]

Hi,

Good to hear that you identified almost the same APIs that I proposed. Seems to me that you guys are on the right track! I always tell Finesse developers that the Finesse developers guide holds most of the answers.

Definitely take a look at the PCCE APIs. I don't think it does everything you want, but maybe you can use the PCCE forum to see if there are any other suggestions for the items that aren't covered.

Thanx,

Denise

[mario.covarrubias]

Hi Denise:

Some questions while we continue with the integration of Finesse…

• Do APIs User—Sign In to Finesse and User—Sign Out of Finesse apply to any user role (Administrator, Supervisor or Agent)?
• For the Login, do we need to?
  • Use User—Sign In to Finesse
  • Use the User—Change Agent State in order to put the agent in NOT_READY state (or UCCE puts the agent automatically in NOT_READY state?) and then,
  • Again use the User—Change Agent State to put the agent in READY state?

Note: This according to the supported state transitions in specified in the API specification.

• For the Login also...
  • How does User—Sign In to Finesse validates User password when it is called from a Web Service?
• For the Logout then, would we need to?
  • Use the User—Change Agent State in order to put the agent in NOT_READY state and then
  • Use User—Sign Out of Finesse

Note: This according to the supported state transitions in specified in the API specification.

• If an Administrator successfully logs in (using the procedure specified before), and is kept in READY state, then the Administrator wants to use the  User—Get List

Thanks in advance.

Mario.

[dekwan]

Hi Mario,

Again, I will address each question individually:

• Do APIs User—Sign In to Finesse and User—Sign Out of Finesse apply to any user role (Administrator, Supervisor or Agent)?

Take a look at the Security Constraints row of the table in each API. It tells you which role is able to use the APIs.

    For Sign In, Users can only act on their own User objects.

    For Sign Out, Agents and supervisors can use this API. Users can only act on their own User objects.

• For the Login, do we need to?
  • Use User—Sign In to Finesse
  • Use the User—Change Agent State in order to put the agent in NOT_READY state (or UCCE puts the agent automatically in NOT_READY state?) and then,
  • Again use the User—Change Agent State to put the agent in READY state?

Note: This according to the supported state transitions in specified in the API specification.

When you call the Sign in API, UCCE automatically puts the agent in NOT_READY state. Then, you need to use the Cange Agent State API to put the agent in READY state.

• For the Login also...
• How does User—Sign In to Finesse validates User password when it is called from a Web Service?

Almost all of the Finesse REST APIs require an authentication. It uses Basic Auth. There you would provide it the username and password. Finesse takes that username and password and it goes to the realm where it authenticates the user (via UCCE AWDB).

• For the Logout then, would we need to?
  • Use the User—Change Agent State in order to put the agent in NOT_READY state and then
  • Use User—Sign Out of Finesse

Note: This according to the supported state transitions in specified in the API specification.

Yes. The user must be in NOT_READY state before using the Sign Out API.

• If an Administrator successfully logs in (using the procedure specified before), and is kept in READY state, then the Administrator wants to use the  User—Get List

Administrators actually cannot sign in unless they are an agent too. Administrators do not need to be signed in to use the administrator APIs. Like I mentioned before, the APIs require a Basic Authentication so that is where the user permissions is verified for the API. So, if the Administrator wants to use the Get List method, you just call the API using the administrator's credentials.

Again, I suggest you use Poster & Pidgin to manually try out these APIs. I think it will give you a better understanding of the flow, and also what you can and cannot do.

Thanx,

Denise

[mario.covarrubias]

Hi Denise,

Thanks for your reply.

We will try the APIs with Poster and Pidgin as you propose, in order to verify what can be done.

Mario.