Adapter - Business ConneCT
This page describes version 2.0.11 of the adapter.
Overview
This page describes the usage of the Business ConneCT adapter. This adapter can be used to receive events from and/or send commands to a Business ConneCT (BCT) system.
Note
To integrate UIP in BCT you require BCT version 10.10 repair release 2 and up. On the BCT server you need to enable UIP integration, therefore see Appendix about UIP integration in the BCT installation manual.
Adapter Configuration
Before the adapter can be used, first it needs some configuration-data. To locate the BCT system, the hostname or IP-address and port-number must be configured. To authorize towards the BCT system, a user-name and password are required. This user must be created in BCT and must have the role "Allow user to use all OWI features". To receive statistical data (optional) from the BCT system (see RouterStatus event), the related BCT Router-name must be set.
These settings must be configured using the next parameters:
Properties
| Name | Display | Is Required | Comments | Type | Default Value | Maximum Value | Minimum Value | Maximum Length | Minimum Length |
|---|---|---|---|---|---|---|---|---|---|
| bctServerAddress | BCT Server Hostname or IP Address | True | Hostname or IP-address of the BCT server | string | 1024 | ||||
| bctServerPort | BCT Server OWI Port Number | True | IP port-number of the BCT Open Web Interface | integer | 32011 | 5 | |||
| bctServerUseHttps | Use secure connection | True | boolean | true | |||||
| bctUserName | BCT Username | True | Name of a configured BCT user | string | 128 | ||||
| bctPassword | Password of the BCT user | True | BCT password for the user | password | 128 | ||||
| bctRouterName | BCT Router to be monitored | False | Monitor this Router, or leave empty | string | 128 | ||||
| bctNotifyAlarms | Enable event generation of BCT Alarms | False | Subscribe to BCT Alarms | boolean | false | ||||
| bctEmergencyNumbers | Emergency Number(s) to be monitored | False | Monitor (comma separated) number(s), or leave empty | string | 128 |
Commands
Get Current Alarms (GetCurrentAlarms)
Gives all unresolved BCT Alarms. Possible BCT Alarms are described in the BCT install guide
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
| activeAlarms | Number of unresolved BCT Alarms | string |
| alarms | An array of alarm objects (empty when no alarm is active). | array |
| alarms.dateTime | Raised alarm time. E.g.: 8/5/2018 3:37:13 PM | string |
| alarms.source | Raised by process. E.g.: [Monitoring Service] | string |
| alarms.id | 4 digits Alarm ID. E.g.: 2101, PBX connection Alarm [2101]. | string |
| alarms.message | Cause of the alarm. E.g.: Connection failed to PBX: Headq1 - 10.128.122.67 | string |
Set Agent Ready (SetAgentReady)
This command sets the status of the given agent to Ready.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| agentName | Agent Name | The BCT login-name of the agent for which the status must be set to Ready | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Set Agent Not Ready (SetAgentNotReady)
This command sets the status of the given agent to NotReady, with the given reason.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| agentName | Agent Name | The BCT login-name of the agent for which the status must be set to Not-Ready. | True | string |
| reason | Reason | The reason why the agent switches himself NotReady. This must be one of the reasons that has been configured in the BCT system. In case it is left empty, or does not match a configured reason, BCT will switch the agent NotReady without a reason. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Route Message (RouteMessage)
Send a message to either a starter or a router. The starter must directly forward to a router. BCT will select (or wait for) an available agent for the router and route this message to this agent.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| message | Message | The (text) message that will be routed to an agent. | True | string |
| starterName | Starter Name | The name of the starter where the message will be sent to (Optional, but either a starter or a router is required). | False | string |
| routerName | Router Name | "The name of the router that will be used for queuing this message (Optional, but either a starter or a router is required. Starter takes precedence)." | False | string |
| senderName | Sender Name | Any (user) name that will be displayed (in the queue and to the agent) as the sender of this message. | False | string |
| senderEmail | Sender Email | Any email-address that will be displayed to the agent as the sender's email-address. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Send Web Chat Response (SendWebChatResponse)
Responde to accept or reject a web chat request
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| sessionId | Session ID | The web chat session identification | True | string |
| rejected | Reject the web chat request | Check this box to reject the web chat request | False | boolean |
| reason | Rejection reason | The reason why the web chat request is rejected | False | string |
| name | User Name | The name of the user that respondes to the web chat request | True | string |
| externalId | External ID | The external ID associated with web chat session | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Send Web Chat Message (SendWebChatMessage)
Send a web chat message
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| message | Message | The (text) message that will be sent | True | string |
| sessionId | Session ID | The web chat session identification | True | string |
| onlyToAgent | Only intended for agent | Check this box to send this message only to the agent | False | boolean |
| externalId | External ID | The external ID associated with web chat session | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Send Web Chat Choice (SendWebChatChoice)
Send a web chat choice
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| sessionId | Session ID | The web chat session identification | True | string |
| choiceOptions | List with choice options | Pipe separated list with choice options | True | string |
| externalId | External ID | The external ID associated with web chat session | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Request An Agent For Web Chat Session (RequestAgentForWebChatSession)
Request an agent for a web chat session
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| sessionId | Session ID | The web chat session identification | True | string |
| starterName | Starter Name | Name of the starter to be used | False | string |
| routerName | Router Name | Name of the router to be used (Starter takes precedence) | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Leave Web Chat Session (LeaveWebChatSession)
Request to leave a web chat session
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| sessionId | Session ID | The web chat session identification | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| isSuccess | Was the request successful | boolean |
Events
Router Status (RouterStatus)
Router status has changed
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| routerName | Router Name | The name of the router for which this event is generated. | string |
| maxWaitingTime | Maximum Waiting Time | The time (in seconds) of the longest-waiting task for this router waiting in the queue. | string |
| queueLength | Queue Length | The number of tasks that are waiting in the queue. | string |
| idleAgents | Idle Agents | The number of agents that are available to handle one or more tasks but are currently not handling any task. | string |
| loggedOnAgents | Logged On Agents | The number of agents that have currently registered (could handle tasks) for this router. | string |
| notReadyAgents | Not Ready Agents | The number of registered agents that set themselves Not Ready (are temporary not available to handle any task for any router). | string |
| workingAgents | Working Agents | Number of working agents | string |
| activeAgents | Active Agents | The number of agents that are currently handling one or more tasks for the router. | string |
| inactiveAgents | Inactive Agents | The number of registered (and Ready) agents that set themselves not active for this specific router. | string |
Connection Status (ConnectionStatus)
This event signals the connection-status from the BCT adapter towards BCT. It is sent when the connection is either established or gets lost.
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| status | Status | Status of the connection to BCT (value true implies it is connected) | boolean |
| bctServerAddress | BCT Server Address | IP-address of BCT for which the status changes | string |
| bctServerPort | BCT Server Port | IP-Portnumber of BCT for which the status changes | string |
Alarm Notification (AlarmNotification)
The AlarmNotification event is given when a BCT Alarm is raised or solved and Notify Alarms is active. Possible BCT Alarms are described in the BCT install guide.
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| activeAlarms | Active Alarms | Number of unresolved BCT Alarms | string |
| dateTime | The date and time the alarm was raised or resolved | E.g.: 8/5/2018 3:37:13 PM | string |
| source | The process that raised the Alarm | E.g.: [Monitoring Service] | string |
| id | 4 digits Alarm ID | E.g.: 2101, PBX connection Alarm [2101]. | string |
| message | Message with cause of the alarm | E.g.: Connection failed to PBX: Headq1 - 10.128.122.67 | string |
| resolved | Resolved | True if alarm is resolved. | boolean |
Emergency Call Event (EmergencyCall)
This event is fired when a monitored emergency number is called.
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| calledEmergencyNumber | Called Emergency Number | The emergency number that was called. | string |
| callingNumber | Calling Number | The extension from which the emergency number was called. | string |
| callerName | Caller Name | The full name of the caller or empty if not known. | string |
| callerLocation | Caller Location | The location (building/room) of the caller or empty if not known. | string |
Web Chat Request (WebChatRequest)
This event signals the incoming of a web chat request
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| sessionId | Session ID | The web chat session identification | string |
| initiator | Initatior Name | The name of the web chat initiator | string |
| Initatior Email | The email of the web chat initiator | string | |
| router | Router | The name of the requested router | string |
| language | Language | The web chat language | string |
Web Chat Message (WebChatMessage)
This event signals the incoming of a web chat message
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| sessionId | Session ID | The web chat session identification | string |
| message | Message | The chat message | string |
| senderName | Sender name | The name of the sender of the message | string |
| isSenderAgent | Is Sender Agent | The sender of this message is agent | boolean |
| agentRequested | Agent Requested | There is an agent requested for this chat session | boolean |
| agentJoined | Agent Joined | An agent joined this chat session | boolean |
| externalId | External ID | The external ID associated with web chat session | string |
Web Chat Choice Answer (WebChatChoiceAnswer)
This event signals the incoming of a web chat choice answer request
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| sessionId | Session ID | The web chat session identification | string |
| choiceAnswer | Answer | The chat choice answer | string |
| senderName | Sender name | The name of the sender of the message | string |
| externalId | External ID | The external ID associated with web chat session | string |
Web Chat Session Ended (WebChatSessionEnded)
This event signals that a specific web chat session has ended
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| sessionId | Session ID | The web chat session identification | string |
| externalId | External ID | The external ID associated with web chat session | string |
Warning
It is allowed to instantiate multiple Business Connect Adapters, but for web chat messaging you must always use the same adapter instance.
Release History
| Version | Type | Description | Tracking # | Date |
|---|---|---|---|---|
| 2.0.1 | Initial | First release in the Adapter Type store. | ||
| 2.0.8 | Feature | Added support for starter and router in RequestAgentForWebChatSession | NAP-16536 NAP-16956 |
|
| 2.0.10 | Bugfix Maintenance |
Chats were not always routed to UIP. Updated third-party components and improved maintainability. |
NAP-10206 NAP-11518 |
|
| 2.0.11 | Maintenance | Updated third-party components and improved maintainability. | NAP-23945 | 2022-11-29 |