Third-Party ACD SDK Developer Guide

Introduction and Positioning

The Third-Party ACD Integration SDK is a developer toolkit for building integrations that feed workforce data into CXone WFM. You embed it inside a connector for your ACD, and it sends the data CXone WFM needs to run intraday reporting, forecasting and adherence.

Use this SDK when your ACD is not one of the natively supported platforms and you want its real-time and historical data represented in CXone WFM without building a bespoke connector protocol for each system.

What the SDK is

• A Java toolkit that acts as a REST client to the CXone WFM ASC Manager service. It is distributed as a .jar named asc-manager-3rd-party-sdk and consumed as a dependency inside your ACD connector.

• Built in pure Java so it works regardless of the Java framework your connector uses.

What it does within CXone WFM

• Sends agent state events, queue and skill metrics, and agent activity data into CXone WFM.

• Handles authentication, token refresh, a periodic heartbeat, and ACD-type lookup on your behalf.

Key constraints

• Developer-facing : Intended for developers. Integration is code-level, built into your connector.

• One-way: The SDK sends data into CXone WFM. It does not read or pull any data back from your ACD.

• Server-side validation: Payload validation happens in the ASC Manager service, not in the SDK. Invalid payloads are rejected with an error response.

End-to-End Flow

The diagram below shows the path from authentication through to data landing in CXone WFM. Your connector authenticates once, receives a Bearer access token, then makes authenticated API calls that the ASC Manager service validates and ingests.

The four stages are: authenticate with your credentials; obtain and hold an access token; make authenticated API calls per data type; and let ASC Manager validate and ingest the data into CXone WFM through Kinesis, Firehose and S3.

Authentication and Getting Started

Authentication uses a set of credentials tied to your tenant. You supply three values to the SDK, and it manages the token exchange for you.

Credentials you provide

The authentication request also carries your tenantName. You obtain the tenant name, access key and secret from your CXone provisioning. Where a value is not yet known in your environment, mark it To be confirmed and confirm it against the Developer API documentation before going live.

For the full authentication contract, see the CXone Developer API documentation (confirm the exact URL for your region).

Getting started: the authentication flow

1. Initialize a security context in your connector with the access key and secret.

2. Build a WFM connection configuration with the service URL and credentials.

3. Open the connection. The SDK calls /public/asc/accessToken and receives a Bearer token that expires in 3600 seconds (1 hour).

4. The SDK attaches the token to every API call, refreshes it every 45 minutes via /public/asc/refreshToken, sends a heartbeat every 60 seconds, and fetches the ACD type every 30 minutes.

Connection setup

Run the following in your connector during initialization:

WFMConnectionConfig wfmConnectionConfig = WFMConnectionConfigBuilder()
                .setURL(serviceUrl)
                .set(accessKey)
                .set(secretKey)
                .build();

                WFMConnection wfmConnection = WFMConnection.getConnection(wfmConnectionConfig);
                wfmConnection.connect();
            

Access token response

A successful token request returns HTTP 200 with a Bearer token:

{
                "id_token": "",
                "token_type": "Bearer",
                "expires_in": 3600,
                "refresh_token": "",
                "access_token": ""
                }
            

API Endpoints

Your connector, through the SDK, calls the endpoints below. The SDK sends every payload; ASC Manager validates each one and assigns default values to any missing non-mandatory field.

For queue-report and agent-activity-report, send a payload for every interval even when there are no interactions. In that case, send an empty report for the interval rather than skipping it.

Field Reference

These tables describe each field in the request payloads: what it means, its format and units, whether it is mandatory, and an example value. Where the source design does not state a value definitively, it is marked To be confirmed.

Time fields follow the UTC format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. A payload with a missing or malformed time, a missing acdType, or an endDate earlier than startDate is rejected with an INVALID_REQUEST error.

queue-report

Top-level fields

reportData.queueReport[]

reportData.agentQueueReport[]

reportData.agentSystemPerformanceReport[]

agent-activity-report (adherence)

Top-level fields

reportData[]

reportData[].agentActivity[]

agent-states

agentStateList[]

Common Questions

Q: What format should startDate use?

Ans: UTC, in the form yyyy-MM-dd'T'HH:mm:ss.SSS'Z', for example 2024-01-15T16:45:00.000Z. The same format applies to endDate, startTime and eventUtcTime. A malformed value is rejected with an INVALID_REQUEST error.

Q: What do queueValue and queueName represent?

Ans: queueValue is the ACD-side identifier of the queue and queueName is its display name. How these map to WEM skills in CXone WFM is To be confirmed.

Q: Are both queueValue and queueName required?

Ans: Both appear in every sample payload and are treated as mandatory for a queue record. Confirm the exact mandatory set against the Developer API documentation; items shown as To be confirmed in the tables above have not been stated definitively in the source design.

Q: Can historical data be re-posted or overwritten?

Ans: The re-post and overwrite behaviour is To be confirmed. Confirm whether re-sending a payload for an interval already ingested replaces or duplicates the stored data before relying on it.

Q: What are the units for time and duration fields?

Ans: Queue and agent time fields (for example handleTime, workTime, loginTime) appear to be in seconds, and the adherence duration field appears to use a finer scale. Exact units are To be confirmed and should be verified against the Developer API documentation.

Q: Why is active present if I use a non-TTI paradigm?

Ans: active carries the count of active contacts under the TTI paradigm. Whether it is required, and what value to send, when your ACD does not use TTI is To be confirmed.