Set Up Connection

Integration Hub connections allow you to set up integrations to third-party web services to use in CXone.

Complete each of these tasks in the order given.

Create a Connection Template

A connection template defines the basic information about an integration. Templates are used to create connections, where you can configure specific requests and other information.

Connection templates cannot be modified after creation. If you need to change any details, including the headers, you must create a new template.

Screenshot of the Add Template page in Integration Hub.
  1. In CXone, click the app selector and select Automation & AI > Integration Hub.
  2. Click Add Template.
  3. On the Details tab, enter a Name for the template.
  4. Enter the name of the Application you're connecting to. This could be an application, platform, or web service.
  5. Select REST as the Integration Method. Currently, REST is the only supported method.

  6. Select an option for Authentication Type.

    Option Details
    OAuth 2.0 Select this option if you want the template to include OAuth 2.0 authentication. Currently, this is the only supported authentication type.
    No Auth Select this option if you do not want the template to include authentication.
  7. Enter a Description of the template. Other users can see it when they select this template from the connection library.
  8. Attach an icon by dragging and dropping an image or by clicking Browse files. This icon is displayed for this template in the connection library for all connections created from this template.
  9. On the Configuration tab, select the methods (verbs) that you want to be available for use with this template. Not all web services support all REST verbs.
  10. To define custom authentication headers for this template, click Add Custom Header. This option is only available if you enabled authentication for the template. To define a header: 
    1. Enter the header name in the field that appears.
    2. Click Add Custom Header to add more custom headers.
    3. Select Required? for any headers that must be used in connections created from this template.
    4. Click the X to delete a header.
  11. Double-check all settings. You cannot edit a template after you save it.
  12. Do one of the following: 
    • Click Icon of a floppy disk Save to add the template to the connection library.
    • Click Save + My Connections to add the template to the connection library and create a connection from it. After the connection is created, you can configure it by adding authentication details, variables, or requests. Your request can include any or all of these configurations.

Create a Connection

Connections allow you to create requests and add authentication details. Connections appear under My Connections in Integration Hub. You can create new connections from connection templates. The connection library shows all the connection templates that exist in your CXone system. If there isn't a template that matches what you need to do, create one.

You can also copy an existing connection to save time in creating new connections that are similar to existing ones. When you create a copy of an existing connection, the new connection contains the original connection's URL, headers, parameters, body, timeout configuration, variable names, and secret names. The new connection does not contain the original connection's requests, client certificate, keys, passphrases, variable values, or secret values.

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Create a new connection in one of the following ways: 

    • To create a new connection from scratch, find a template in the connection library. The library is on the right side of the page. If you're viewing a connection or template, click the X in the upper right corner of the page. This closes it so you can see the connection library. Click + My Connection on the template properties page to create a connection based on the template.

    • To create a new connection by copying an existing one, find the connection you want to copy in the My Connections pane on the left and click it. Click Icon of two stacked sheets of paper Copy.

  3. In the My Connection Name field on the pop-up window, enter a unique name for the new connection.

  4. Click Icon of a floppy disk Save.

Configure Authentication Details

You can configure authentication details on the Authentication tab in your connection. This tab is visible only when authentication is enabled in the template used for this connection.

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Click the connection you want to work with from My Connections on the left side of the page.

  3. Click the Authentication tab.

  4. Enter the URL used for the authentication request. The URL cannot be dynamic, but you can reference secrets in it.

  5. Select the REST Method (verb) used in the authentication request. The available verbs are defined by the template used for this connection.

  6. Under Headers, enter the appropriate value in each field. Fields with an asterisk ( * ) are required. These fields are defined in the template used for this connection.

  7. To add a custom header to this connection:

    1. Click Add Custom Header.

    2. Enter a Header Name and Header Value.

  8. To add a query parameter to the authentication request:
    1. Click Add Query Parameter.
    2. For each query parameter you add, enter a Query Parameter Name and Query Parameter Value.

  9. Select a Media Type and enter the Body content. The media type affects the format of the body content. It should match the type required by the authorization server you're using.

    Option Details

    ApplicationJson

    The body content must be in JSON.

    ApplicationJsonPatch The body content must be in JSON Patch format.
    FormURLEncoded

    The body content must be in key-value pairs. This media type sends requests using common URL notations.

    Click +Add Form Parameter, then enter the Form Parameter Name and Form Parameter Value.

    TextHtml The body content must be in HTML.
    TextPlain The body content must be in plain text.
    TextXml The body content must be in XML.

  10. Click Icon of a floppy disk Save.

Configure an mTLS Self-Signed Certificate

You can use the Configuration tab of a connection to configure the timeout setting and configure an mTLS self-signed certificate.

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Click the connection you want to work with from My Connections on the left side of the page.

  3. Click the Configuration tab.

  4. Adjust the Timeout (MS) setting as needed. The timeout applies to all request configured in the connection, including authentication. If you're using an mTLS self-signed certificate, fill in the following fields:

    • Client Certificate
    • Client Private Key
    • Key Passphrase

    These fields will only appear if you use OAuth 2.0 as your authentication type. You should enter the Client Certificate and Client Private Key together. If your Client Private Key is encrypted, you must enter a Key Passphrase. mTLS certificates will only work if your authentication URL is in HTTPS. Validation of these fields will occur after the connection is saved. You can reference these fields in the Secrets tab.

  5. Click Icon of a floppy disk Save.

Add Variables to a Connection

Integration Hub variables allow you to share certain information in a connection. You can determine whether this information is encrypted or not. An encrypted variable, or a secret, provides an added layer of security when using sensitive information, such as passwords in Studio scripts.

When you create a variable, you can convert it to a secret at any time. Once a variable becomes a secret and the connector has been saved, you cannot turn the secret back into a variable.

Secrets are not reversible. When you click away from the Secret Value field, the content is encrypted and replaced with masking asterisks ( * ). There is no way to retrieve the value you entered into the field after it's masked.

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Click the connection you want to work with from My Connections on the left side of the page.

  3. On the Variables tab, click + Add Variable.

  4. Enter a Variable Name that identifies what the variable contains. Names can contain spaces or special characters.

  5. Enter the Variable Value. This is the value of the variable and the information that will be encrypted if you make the variable a secret. Verify that the information is correct before you enable it as a secret.

  6. To encrypt the variable, enable the Secret toggle.

  7. To remove a variable from the connection, click the X on the right side of it.

  8. Click Icon of a floppy disk Save.

Use Variables in a Connection

You can use variables in manual or Studio script requests. You can use them in headers, query parameters, and body content.

Use a Variable in Authentication Details or a Manual Request

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Click the connection you want to work with from My Connections on the left side of the page.

  3. Click the tab where you want to use a variable. Variables can be used on the Authentication and Requests tabs.

  4. Enter the variable in the place where you want the variable value to be, following these guidelines:

    • Enclose the name in double brackets. For example, [[ variableName ]].
    • Use the name exactly as entered in the Variable Name field on the Variables tab.
    • Variables can only be used with the connection where they were created.

Use a Variable in a Studio Request

To use variables in a Studio script, the script must have a CONNECTAuth or CONNECTREQUEST action. The action must link the script to the connection containing the variable.

  1. In Studio, open the script you want to use the variable in.

  2. Double-click the Snippet action you want to add the variable to.

  3. In the Snippet editor window, add the variable in the place where you want the variable value to be used, following these guidelines:

    • Enclose the name in double brackets. For example, [[ variableName ]].
    • Use the name exactly as entered in the Variable Name field on the Variables tab.
    • Enclose the brackets and variable name in double quotes ( " ). For example, "[[ variableName ]]". If the variable is part of a string, such as a URL, the entire string must be enclosed in double quotes, not just the variable. For example, "[[ variableName ]]/location/anotherlocation/".
    • Variables can only be used with the connection where they were created. The connection must be specified in the script with a CONNECTAuth or CONNECTREQUEST action.

    Examples: 

    • ASSIGN requestPayload.body = "[[client_id]]"

    • ASSIGN requestPayload.URL = "[[INSTANCEURI]]/INCONTACTAPI/SERBICES/V26.0/AGENTS"

Create a Manual Request

Requests are how you obtain the information you need from the web service your integration connects to. You can use manual requests in Studio scripts or execute them from Integration Hub.

If your request requires path parameters or variable substitution in the URL, headers, or parameters, you must create a Studio request. Manual requests don't support these options.

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Click the connection you want to work with from My Connections on the left side of the page.

  3. On the Requests tab, click Add Request.

  4. Enter a Request Name.

  5. Select Manual as the Trigger.

  6. Enter the URL for this request.

  7. Click the Method (verb) for this request.

  8. Under Headers, add any headers that are required for your request:

    1. Click Add Header.

    2. Enter a Header Name and Header Value.

  9. Under Query Parameters, add any query parameters that are required for your request: 
    1. Click Add Query Parameter.
    2. Enter a Query Parameter Name and a Query Parameter Value.

  10. Select a Media Type and enter the Body content. The media type affects the format of the body content. It should match the type required by the web service you're connecting to.

    Option Details

    ApplicationJson

    The body content must be in JSON with application/json as the content header.

    ApplicationJsonPatch The body content must be in JSON Patch format with application/json-patch+json as the content header.
    FormURLEncoded

    The body content must be in key/value pairs with application/x-www-form-urlencoded as the content header. This media type sends requests using common URL notations.

    Click +Add Form Parameter, then enter the Form Parameter Name and Form Parameter Value.

    TextHtml The body content must be in HTML with text/html as the content header.
    TextPlain The body content must be in plain text with text/plain as the content header.
    TextXml The body content must be in XML with text/xml as the content header.
  11. If you want to change this request's active status, click Active at the top of the page. The text changes to Inactive.
  12. Click Confirm.
  13. On the Requests tab, click Test for the request you just added. Integration Hub attempts the request. A window appears and displays the results of the test.
  14. Click Edit and make changes to the request or click Icon of a floppy disk Save.

Create a Studio Request

A Studio request is helpful when you have API requests that cannot be created in Integration Hub but you want to be able to use Integration Hub for authentication and secrets.

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Click the connection you want to work with from My Connections on the left side of the page.

  3. On the Requests tab, click Add Request.

  4. Enter a Request Name.

  5. Select Studio as the Trigger.

  6. Select and copy the example request payload from the Add Request page if you want to use the example to build the JSON in your script.

  7. Click Confirm.

    Studio requests cannot be tested from Integration Hub. You must test them in Studio by running the script with a trace.

  8. Click Icon of a floppy disk Save.

  9. Launch Studio and log in.
  10. Open an existing script or create a new one.
  11. Add a Snippet action to your script and double-click it to open the Snippet editor window.

  12. Build a dynamic object in the Snippet editor window and convert it to JSON. The object you create must contain members that hold the headers, query parameters, and body content required for the request.

    Use the example payload you copied from Integration Hub in an earlier step as a guide when you create your object. The example payload is: 

    {
 "URL": "[[INSTANCEURI]]/INCONTACTAPI/SERBICES/V26.0/AGENTS",
 "HTTPMETHOD": "POST",
 "HEADERS": {
	"CONTENT-TYPE": "APPLICATION/JSON",
	"AUTHORIZATION": "BEARER[[BEARERTOKEN]]"
	},
 "QUERYPARAMETERS": {
	"ANI": "[[ANI]]",
	"ACCOUNTID": "123456"
	},
 "BODY": {
	"ANI": "[[ANI]]",
	"ACCOUNTID": "123456",
	"ACCOUNTNAME": "TESTACCOUNT"
	}
}

    A dynamic object created using the example payload as a guide is:

    DYNAMIC requestPayload 
ASSIGN requestPayload.URL = "[[INSTANCEURI]]/INCONTACTAPI/SERBICES/V26.0/AGENTS"
ASSIGN requestPayload.HTTPMETHOD = "POST"
ASSIGN requestPayload.HEADERS.CONTENTHYPHENPLACEHOLDERTYPE = "APPLICATION/JSON"
ASSIGN requestPayload.HEADERS.AUTHORIZATION = "BEARER[[BEARERTOKEN]]"
ASSIGN requestPayload.QUERYPARAMETERS.ANI = "[[ANI]]"
ASSIGN requestPayload.QUERYPARAMETERS.ACCOUNTID = "123456"
ASSIGN requestPayload.BODY.ANI = "[[ANI]]"
ASSIGN requestPayload.BODY.ACCOUNTID = "123456"
ASSIGN requestPayload.BODY.ACCOUNTNAME = "TESTACCOUNT"
ASSIGN requestPayloadJSON = "{requestPayload.asjson()}"
ASSIGN requestPayloadJSON = "{requestPayloadJSON.replace("HYPHENPLACEHOLDER", "-")}"

    The last line of the preceding example uses the replace() function to insert the hyphen ( - ) character into the CONTENT-TYPE key name. In Studio, variable names cannot include special characters such as hyphens, so this approach is used as a workaround.

  13. Configure the script to use the request.

Change a Request's State

Each Integration Hub connection can have up to 50 requests. There is no restriction on how many requests can be active at a time. Requests are active by default.

  1. In CXone, click the app selector and select Automation & AI > Integration Hub.

  2. Click the connection you want to work with from My Connections on the left side of the page.

  3. On the Requests tab, click the request you want to work with.

  4. Click Inactive or Active at the top of the page to change the state.