Integration - Cloud API

 

The Cloud API allows an arbitrary external (or internal!) system to invoke a Workflow pop for a specified agent, via a secured public RESTful API. To deliver the pop, requires that the targeted agent be logged in and on the Desktop to be able to receive the Workflow pop.

 

 

The Integration - Cloud API Plugin needs to be enabled in the Plugins section of the Admin module. No additional settings are required before the Plugin can be activated.

 

 

 

To receive a Cloud API pop, the targeted agent will need access to a Cloud API (Remote Pop) licence part. Checking inside the Licences or About sections can reveal the type of licence and access requirements:

 

 

As with all popping mechanisms, a campaign needs to exist for the pop to specify which Workflow will be launched. Any Campaign can be used for these purposes, whether it be an internal or external campaign. However, remember that External Links are only available for configured external campaigns.

 

 

External Links allow the easy passing of information into the Workflow as part of the pop, letting the Designer specify linked Fields and/or Workflow Variables that will be directly populated on launch.

 

The Cloud API is a one-way linkage, so any changes to these fields won't be automatically returned to the source after the Workflow run is completed.

 

 

Triggering the Workflow pop requires is a two-step process: an initial call is made to the authentication endpoint to acquire an authentication token, and this authentication token can then be used on a number of pop requests until it expires.

 

The targeted agent must be on the Desktop and have access to a Remote Pop licence (described above) to receive the pop.

 

You will have been provided with a Cloud API Username and Password by your Scripting vendor, and these should simply be used in a HTTP GET request to the authentication endpoint via Basic Auth.

 

If successful, this will return a structure similar to that below. The IdToken is the authentication token that will be needed in the second step, and by default will expire an hour after generation.

 

 

Once the authentication token has been retrieved, then it can be used in a HTTP POST request to the pop endpoint via Bearer Auth. The POST requires the following JSON structure be included as its body:

 

 

The ScriptData structure is entirely optional, but if included then items within it will be included in the Script.Data layer. Additionally, if the names match External Links for Fields or Workflow Variables within the popped Workflow, then they will be populated with the provided data.

 

If successfully received, then it will return a structure similar to that below. Note that this doesn't guarantee that the user in question was logged in and on the Desktop to receive the pop attempt.

 

 

As the process is asynchronous, there is no direct feedback to the calling process that the pop has actually been successfully received within Scripting and opened.

 

The endpoint communicates to the Scripting instance via Websocket technology, and so communication needs to be unobstructed between the endpoint and the Scripting instance.

 

If submitting a pop request for an agent already in a record, if the reference is the same as the current record then nothing occurs. If the reference is distinct, then the current record will be suspended to the Activities list and a new record popped over it.

 

Due to the distributed nature of the process, a record shouldn't be popped for multiple users simultaneously. A check will be done during the pop attempt to see if record is open elsewhere, but if the pop requests are rapid enough then multiple users may still end up popping copies of the same record.

 

Any failures to pop (for instance, because another user had already got the record open, or the campaign name wasn't recognised) are logged by Scripting at the Warn level. Refer to the logging documentation for guidance on configuring your system's logging level.