How to Create a Web Service using Siemens HiPath ProCenter Toolkit (SDK) and a .NET Application Consuming The Web Service

I will try to demonstrate with a sample application enable an Siemens HiPath ProCenter agent to log on automatically, dial a phone number and log off from the HiPath ProCenter system consuming a web service application built upon HiPath ProCenter SDK.
This sample CTI (Computer Telepony Integration) application is simple and can be easily developed to enable more functionality of agents on a HiPath ProCenter server.
This application is built on a HiPath ProCenter 5.1 system. But it can easily be upgraded for a HiPath ProCenter 7 system by altering the reference ddl file ttkhppc.dll.

First create a ASP.NET Web Service application. You can also create a WCF Application.
I named the sample web site name as HPPCSDKWebService.
After you have created the HPPCSDKWebService sample web service application, remove the Default.aspx web file by deleting from the web site solution.
Then add a Web Service item to the project by selecting "Add New Item" context menu item on the web site name in the Solution Explorer screen.
I named the new web service item as HPPCWS

siemens-hipath-new-web-service-project

Add ttkhppc.dll dll file as reference to the project.

siemens-hipath-procenter-toolkit-sdk

You can browse to the folder "C:\Program Files\Siemens\HiPath ProCenter 5.1 SMRC Toolkit" for pointing to the ttkhppc.dll file for reference.

add-hipath-toolkit-ttkhppc-dll-as-reference

After you have added the ttkhppc.dll dll file as reference to the HPPCSDKWebService web site project, you will see the Interop file in the bin folder of the web site application.

interop-hipath-procenter-library-dll

Now let's define the following application configuration parameters in the web.config file within the <configuration> and </configuration> tags.
Within the sample .NET codes we'll get the configuration parameter values in the web.config configuration file using the System.Configuration.ConfigurationManager.AppSettings() method.


 <appSettings>
  <add key="RRServer" value="6000@hppcserver.kodyaz.com"/>
  <add key="LocalPort" value="6050"/>
  <add key="WorkingThreads" value="50"/>
 </appSettings>

Code

RRServer is the HiPath ProCenter server application which we will try to connect using the HPPC SDK Toolkit.
The port used for connection HiPath ProCenter server is generally set as 6000.
LocalPort is used during the connection to identify the port on the side where this application is going to run on.
WorkingThreads parameter is used for multi processing to enable the application to work in multiple threads.

Then double click the HPPCWS.vb code behind file in order to start coding.
First start by removing the HelloWorld() sample WebMethod function.

Import the namespaces HiPathProCenterLibrary, System.Configuration, System.IO, System.Text into the web site project by adding the following code block.


Imports HiPathProCenterLibrary

Imports System.Configuration

Imports System.IO

Imports System.Text

Code

Define the following pubic shared and private variables within the class HPPCWS.

objHPPC is HiPathProCenterManager object which enables developers the ability to connect HiPath ProCenter - HPPC.
HiPathProCenterManager class instance object objHPPC is used in codes to Hire or ....


Public Shared objHPPC As HiPathProCenterManager

Public Shared objAdmin As AdministrationManager

Public Shared objMedia As MediaManager

Public Shared objRouting As RoutingManager



Private objVoiceCall As VoiceCall

Private objRoutingCall As RoutingCall



Private Const KeyOfAdmin As Integer = 1

Private Const PasswordOfAdmin As String = "password"

Private NonEstablishedCalls() As String

Code

Now I will define the three web methods that the applications consuming the HPPCWS web service will call:
CTI_AGENT_LOGON : This function is used by an agent to log on to the PBX/PBX-Application Server. The agent is using the phone with extension I_Extension.
CTI_AGENT_DIAL : This function is used to make a call by dialing an input telephone number by an agent who is logged on to the PBX/PBX-Application Server.
CTI_AGENT_LOGOFF : This function is used by an agent to log off from the PBX/PBX-Application Server.

CTI_AGENT_LOGON

The CTI_AGENT_LOGON web method requires three parameters.
An AgentId parameter as String to define the agent that is going to log on to the HiPath ProCenter system.
An AgentExtension parameter as String to define the phone extension that the agent is going to use during his/her session is active.
And as last an AgentPassword parameter as String is required to authenticate to the HiPath Procenter system.


<WebMethod(Description:="Used by an agent to log on")> _

Public Function CTI_AGENT_LOGON(ByVal AgentId As String, _

      ByVal AgentExtension As String, _

      ByVal AgentPassword As String) As String



  Return "FAIL" 'We will replace this code later



End Function

Code

CTI_AGENT_LOGOFF

The CTI_AGENT_LOGOFF web method requires only the AgentId parameter.
An AgentId parameter as String to define the agent that is going to log off from the HiPath ProCenter system.


<WebMethod(Description:="Used by an agent to log off")> _

Public Function CTI_AGENT_LOGOFF(ByVal AgentId As String) As String



  Return "FAIL" 'We will replace this code later



End Function

Code

CTI_AGENT_DIAL

The CTI_AGENT_DIAL web method requires four parameters to enable an HPPC agent make a call automatically by calling this web service method within an third party application.
An AgentId parameter as String to define the agent that is going to log off from the HiPath ProCenter system.
An AgentExtension parameter as String to identify which phone extension is the agent using to make the dial.
An AgentPassword parameter as String which will be used to log on the agent to the HPPC system if the user is logged off.
A PhoneNumber String parameter which is the target telephone number that the call center agent aims to dial.


<WebMethod(Description:="Used by an agent to dial or make a phone call")> _

Public Function CTI_AGENT_DIAL(ByVal AgentId As String, _

      ByVal AgentExtension As String, _

      ByVal AgentPassword As String, _

      ByVal PhoneNumber As String) As String



  Return "FAIL" 'We will replace this code later



End Function

Code

Now let's define the main code block that we'll call each time when any of the web wethods we have created above.
In this code block, we will check if there exists a HiPathProCenterManager object instance.
If there is one then the code block will end execution and return the main web method function.
If there is not a HiPathProCenterManager object instance, then we will create one using the NEW constructor.
Then we will configure the object in order to connect to the HiPath ProCenter server or the RRServer using the Initialize of the HiPathProCenterManager object using the required parameters.
We need the RRServer address, local port and an additional parameter to catch connection level admin object events.


Call objHPPC.Initialize(rrserver, enEventModes.EventMode_IgnoreEvents, localport)

Code

After the HiPathProCenterManager object is initialized next step is creating or by the HPPC SDK Toolkit terminology hiring AdministrationManager object.
HireAdministrationManager method of the HiPathProCenterManager object creates an AdministrationManager object instance.


objAdmin = objHPPC.HireAdministrationManager(enEventModes.EventMode_IgnoreEvents)

Code

The appliactions creates a connection and logs on to the HiPath ProCenter RRServer using the Admin Key and the Admin password.
The Admin Key is the id value of the user as integer which is equal to 1.
And you should have known the password of your Admin user in the HiPath ProCenter (Note that this admin is not the server admin).


Call objHPPC.Logon(KeyOfAdmin, PasswordOfAdmin)

Code

The main object we will work through out the application is actually the objMedia object which is a MediaManager instance.
As all other Manager objects in the HiPathProCenterLibrary namespace the MediaManager is too created by HiPathProCenterManager object using a Hire method HireMediaManager.


objMedia = objHPPC.HireMediaManager(enEventModes.EventMode_IgnoreEvents)

Code

Since we are developing this web service application just for making outbound calls we do not have to listen events triggered by agent actions on the HiPath ProCenter server.
Because of that reason I coded the HireMediaManager() method call with EventMode as IgnoreEvents.

Below I copied all the source code of the private sub routine named HPPC.
This code block actually prepares everything an agent needs to make an outbound call in connection with the ProCenter.
In fact the three methods, CTI_AGENT_LOGON, CTI_AGENT_LOGOFF and the most important one CTI_AGENT_DIAL will call the HPPC() method in order to make RRServer connection if not connected already and create necessary objects.


Private Sub HPPC()



  If objHPPC Is Nothing Then

    objHPPC = New HiPathProCenterManager

  Else

    Exit Sub

  End If



  Dim rrserver As String

  rrserver = ConfigurationManager.AppSettings("RRServer")



  Dim localport As Integer

  localport = CType(ConfigurationManager.AppSettings("LocalPort"), Integer)



  Dim workingthreads As Integer

  workingthreads = CType(ConfigurationManager.AppSettings("WorkingThreads"), Integer)



  Call objHPPC.Initialize(rrserver, enEventModes.EventMode_IgnoreEvents, localport)



  objAdmin = objHPPC.HireAdministrationManager(enEventModes.EventMode_IgnoreEvents)



  Call objHPPC.Logon(KeyOfAdmin, PasswordOfAdmin)



  objMedia = objHPPC.HireMediaManager(enEventModes.EventMode_IgnoreEvents)



End Sub

Code

Of course for a reliable code and a reliable development, you should add logging structures and control methods in order to check the state of the objects, managers and the HPPC connectivity.
I ignored those codes since they are not actually the main concern for this ASP.NET web service application.

After completing the coding of HPPC() method, next we will add call to this method as the first line of code in the three web service web methods.

The web method CTI_AGENT_LOGON will call the function AgentLogon to complete the log on of the agent to the HiPath Pro Center HPPC system with the given credentials as agent key and password.
Now we will program the AgentLogon private function to log on an agent to the HPPC RRServer.
First we have to find the AgentKey of the related agent. Since call center agents do not really know their AgentKey values. They know the AgentId values which is a string value like a code of the related agent.
But the AgentKey is the integer value and used as a unique identifier for the related call center agent users and required while calling methods related with agents.
In order to get the AgentKey value of a user by his/her AgentId value, first I will create a HiPathProCenterLibrary User object.
And using this User object I will check each user in the Users collection returned by the QueryUsers() method of the objAdmin AdministrationManager object instance.


Dim user As HiPathProCenterLibrary.User

For Each user In objAdmin.QueryUsers()

 If user.ID = AgentId Then

  AgentKey = user.Key

  Exit For

 End If

Next

Code

By the above .NET code block, I managed to fetch the AgentKey corresponding to an AgentId value in HiPath Procenter.
If you download and review the sample application .NET codes you will see that I have gathered all the above code block within a private function GetAgentKey().
The next step is getting all information about the Agent and logging on using this Agent.
So first we will create an Agent object from the HiPathProCenterLibrary namespace using the MediaManager object with NewAgent() method.
Then set the AgentKey property of this new created Agent object and query for this Agent using the MediaManager object instance objMedia.


Dim objAgent As HiPathProCenterLibrary.Agent

objAgent = objMedia.NewAgent()

objAgent.Key = AgentKey



Call objMedia.Query(objAgent)

Code

The MediaManager object with Query method will return me the required HiPathProCenterLibrary Agent object. Then I can call all the methods of the HiPathProCenterLibrary Agent object without a problem.
Now I'll first make a control by calling the LoggedOnForMediaType() method of the Agent class. The LoggedOnForMediaType() method will return me a boolean value True or False indicating that the related agent is already logged on to the media type I passed to the method as an parameter. Since we are dealing with dialing phone numbers we will develop all our sample codes using the enMediaTypes.MediaType_Voice which is the phone related call center activities.
You know that the HiPath ProCenter and the SDK Toolkit also supports e-Mail and Chat media types as well as Voide.


objAgent.LoggedOnForMediaType(enMediaTypes.MediaType_Voice)

Code

If the agent is already logged on for the voice media type then you do not need to perform further.
But if the agent is not logged for the voice media type that is for phone, we should develop code for Agent object to log on.
We can manage this by calling the Logon() method of the Agent object as follows :


objAgent.Logon(enMediaTypes.MediaType_Voice, Extension)

Code

Agent Logon() method requires a valid extension as parameter that is already defined in the HiPath ProCenter as a phone extension.

Last step in coding of the web method CTI_AGENT_LOGON is adding the call to the recently created private function AgentLogon().


AgentLogon(AgentId, AgentExtension, AgentPassword)

Code

In order to use within the codes placed in CTI_AGENT_LOGOFF web method, I will now try to develop a private method named AgentLogOff().
The AgentLogOff() function expects the AgentId parameter as string to identify which agent is going to log off from the HiPath ProCenter RRServer.
Actually the AgentLogOff() function starts with the conversion of the AgentId to AgentKey by using the GetAgentKey() function.


Dim AgentKey As Integer = GetAgentKey(AgentId)

Code

After I got the AgentKey value of the related call center agent, now I will reuse the code that I created an instance of HiPathProCenterLibrary Agent and populated that instance using the MediaManager Query() method.
You will recognize that code from the AgentLogOn probably.


Dim objAgent As HiPathProCenterLibrary.Agent



objAgent = objMedia.NewAgent()

objAgent.Key = AgentKey



Call objMedia.Query(objAgent)

Code

Again after making a control if the agent is already logged off from the HiPath ProCenter and confirming that the agent is still logged on, I will execute the below code statement :


objAgent.Logoff(enMediaTypes.MediaType_Voice)

Code

This will log off the agent from the HPPC. Of course for reliable code development you can make cross-check controls to confirm the desired situation is obtained.
So I will end up the CTI_AGENT_LOGOFF web method with a call the the recenlt developed private function by adding the code :


AgentLogOff(AgentId)

Code

Now, it is time for us developers to build a private function AgentDial which can be used in web method CTI_AGENT_DIAL.
AgentDial function requires AgentId, Password, Extension and PhoneNumber parameters.
AgentId is necessary to identify the Agent. Password is required to log on the agent to the HiPath ProCenter system if the agent is not already logged on. Extension is the extension number of the agent that he or she is using. And the last parameter PhoneNumber is the second party in the connection. The telephone number that the agent wants to dial.

Within this AgentDial function again I need the AgentKey value of the Call Center agent. And we have developed re-usable code fragments earlier in this article to get the AgentKey value from the AgentId. Then GetAgentKey() function will do this for us.
We have to control if the related agent is logged on to the HPPC. If the agent is not logged on we can not activate a phone dial in the name of the agent. So we will code AgentLogon() function which we have coded earlier in this sample project.

The last steps in order to complete coding our web service application is creating a VoiceCall object instance.


objVoiceCall = objMedia.NewVoiceCall()

Code

After we have created the VoiceCall instance by calling the MediaManager object's NewVoiceCall() method, we can now start a telephone call between two parties. Here is the single line of .NET code that will create a phone dial in the name of the agent.


Call objVoiceCall.Dial(Extension, PhoneNumber)

Code

Tips and Tricks on HiPath ProCenter SDK Programming for Building Web Service Methods for Agents

Be sure that the approtiate version of HiPath ProCenter Toolkit SDK is installed on server/client where you will run the application.
You can connect to HiPath ProCenter RRServers if your major versions match. This means you can not connect to a RRServer which is 7.0 by using a Toolkit SDK of 5.1
The patch number you used while developing your application should match where you deployed you application.
First create the HiPathProCenterManager object. Then Initialize it to the RRServer.
Create AdministrationManager object by calling the HireAdministrationManager method.
Create the MediaManager object by calling the HireMediaManager method.

Download Sample Web Service Web Site Application using HiPath ProCenter SDK Toolkit to Enable Agents Dial Automatically

You can find and download free the source codes of the ASP.NET web services application HPPCSDKWebService at HiPath ProCenter Toolkit SDK ASP.NET Web Service Sample Project.
If you are building your applications based on an other version of HPPC SDK, the codes will work without a problem 99% if you reference your HPPC Toolkit SDK ttkhppc.dll .dll file.