Guided Path Apps


This guide is intended to assist software developers who want to develop Guided Path Apps for Cloud.


A Guided Path App is a Web Application that exposes a (JSON) catalog of HTTPS content (such as forms, JavaScript, HTML, images, etc.). Each item of content can be used as a step in a Guided Path, where it will be rendered in an IFRAME. The Guided Path App content has access to a Cloud javascript library which provides services that the Guided Path App can use for styling (CSS), security, and access to the support session context.

Most commonly, a Guided Path App will serve as an adapter to a third-party system (e.g.: Content Management System, Knowledge Base, IoT control hub) by defining the catalog of resources that can be added as steps to a Guided Path.


How It Works

  • The Guided Path App (App) is configured in Cloud Admin
  • Steps provided by the Guided Path App are added to a Guided Path in the Cloud Designer
  • The Guided Path is executed in Cloud Agent Navigator
  • The App step is reached in Agent Navigator and:
  • The App step is loaded in the Guided Path IFRAME
  • (Optionally) The App authenticates the user (i.e. Windows Authentication)
  • (Optionally) The App loads the Cloud Javascript Library
  • (Optionally) The App fetches the OAUTH JSON Web Token (JWT) for B2B Authentication
  • Optionally) The App applies the Cloud CSS
  • (Optionally) The App retrieves session / device / agent etc. data from Cloud to be used for loading external data


  • An HTTP/JSON endpoint must be made available for the Cloud backend to query at design time.
  • All content published by the catalog must be over HTTPS, since browsers block mixed HTTP/HTTPS content.

There are no constraints on where the Guided Path App is hosted or what language it is written in. Content needs not be publicly accessible, as long as it is accessible to the agent’s browser. For example, an intranet resource can be added to the catalog, which can then be further protected with Active Directory Windows Authentication.

Sample Guided Path App

The code for a full example app is available here.

This app is running and can be tested by configuring its URL in the Cloud Admin area. These are the steps to configure a Guided Path App in Cloud:

  • Navigate to Admin –> GPA Config –> Add
  • Enter a value in the Name field. This is an arbitrary name that will uniquely identify the Guided Path App. The example shown below uses the name Sample GPA.
  • Enter a value in the Catalog URL field. This is the URL that renders the catalog of content. This sample app has the URL
  • Check the Enabled box to make the catalog available for Guided Path authoring.
  • Select the access type for the Catalog URL by choosing the GET or the POST option. The POST option allows additional data (JSON format) to be posted when rendering the catalog. For this sample app, choose GET.

Here is the configuration for the Sample App.

GPA Admin Configuration

Click save. At this point, the content provided by the Sample App is available to be added as a step in a Guided Path.

To verify that, browse to the Cloud designer to author a new Guided Path. Cloud has just queried the catalog URL and merged the resultant content with the Cloud library steps, and any other Guided Path App content. The content from the Sample App, namely, a new step called “Registered Devices”, is now visible in the step library panel on the left.

GPA Designer Steps

Go ahead and add the “Registered Devices” step to your “Path View”. A preview image will be displayed to the designer. The “Content Url” will be displayed in a IFRAME when the Guided Path is run by an agent. Save and publish your new Guided Path.

Next, head over to the Navigator and run the new Guided Path you just created. You will be presented with a page that exercises some of the services provided by the Cloud client-side javascript library:

GPA Step Execution


The Catalog is a JSON resource that provides a list of steps to be made available in the Guided Path Designer. The Catalog resource will be fetched by the Cloud backend by either an HTTP GET or POST, depending on how it is configured on the Cloud Admin page.

Catalog Format

The HTTP content type MUST be application/json or application/javascript or text/javascript. The JSON must represent a JSON object (not an array).

Property Type Required Maximum Description
Name string YES 50 chars Handy name for the Guided Path App
Jti string YES UUID Unique JWT jti for the Guided Path App
Resources array NO N/A Array of content resources
Resources[].Name string YES 256 chars Guided Path Step Name - displayed in Designer and Navigator
Resources[].Description text NO unlimited Guided Path Step Description
Resources[].PreviewImage HTTPS URL NO 2000 chars Preview image to be displayed in the Cloud Designer
Resources[].ContentUrl HTTPS URL YES 2000 chars The URL to be loaded in the IFRAME on execution of the step; Supports [Macro Substitution](#macro-substitution)
Resources[].Config JSON NO unlimited Additional JSON content (not yet used)
  "Name": "Sample Guided Path App",
  "Jti": "984a0260-7d08-43cf-a533-bc6036d3a390",
  "Resources": [
      "Name": "Test Step",
      "Description": "Exercise some functions",
      "PreviewImage": "",
      "ContentUrl": "",
      "Config": {}
    "Name": " Wikipedia Step",
    "Description": "",
    "PreviewImage": "",
    "ContentUrl": "",
    "Config": {}


The ContentUrl will be loaded in an IFRAME with the execution of the specific step. It must begin with https://. Because the target page will usually require a consumer, session or connected device context, The content URL will be searched for macro tags and updated. See Macro Substitution.

Security Concerns

Due to browser security requirements, the ContentUrl must be HTTPS. Since the content is loaded directly into the agents browser, it may be hosted within the agents network, i.e. an intranet site. The site may also be protected with various browser authentication mechanisms, ie. Windows Authentication.

Additionally, the Cloud Javascript Library provides a way to authenticate the agent against the Cloud backend. Cloud Javascript Library

The Cloud Javascript Library provides a client side API to interact with the IFRAME parent ( Cloud). Place the following element at the top of the page, in the head section:

     <script src=""></script>

The following code is required to initialize the library:

        var conn = nexusNavigator.api();
        nexusNavigator.on('ready', function (api) {
            conn = api;
            // start making calls to the conn object
    </script> Cloud Javascript Library API - Events Cloud raises events, which can be consumed. The code above was the first example of that. The following events are raised by the library:

  • ready: A connection has been made to Cloud
  • workflow_step_start: The Guided Path has switched focus to this frame (note that the event wont be available the first time because the library has not been initialized yet)
  • workflow_step_pause: The Guided Path has switched focus away from this frame Cloud Javascript Library API - RPC


No Operation. Will throw an exception if the RPC call fails.

  • returns: void


Set the IFRAME height.

  • height: integer value in pixels
  • returns: void


Retrieves value indicating whether the parent Cloud windows websocket is connected to the Cloud

  • callback: function(isConnected)
  • isConnected: boolean value indicating whether the parent Cloud windows websocket is connected to the Cloud backend
  • returns: void

pushCommand(type, cmdId, method, params)

Push a command over websocket channel.

  • type:
  • cmdId: Deprecated
  • method:
  • params:
  • callback: function(success)
  • success: boolean value indicating that the command was sent successfully
  • returns: void

sendCommand(type, cmdId, method, params, callback)

Send a command over websocket channel and expect response.

  • type:
  • cmdId: Deprecated
  • method:
  • params:
  • callback: function(result)
  • result: boolean false on failure, or data requested
  • returns: void

sendChatMessage(msg, callback)

Send a chat message

  • msg: The message to send to the connected device
  • callback: function(success)
  • success: boolean value indicating that the message was sent successfully
  • returns: void


Retrieves the current Session object.

  • callback: function(session)
  • session: session object (see example)
  • returns: void

Example Session Object

      "id": 10002,
      "external_id": "myref_id_456",
      "user": {
        "id": 10000,
        "email": "",
        "given_name": "NA",
        "family_name": "NA",
        "phone": "0000000000",
        "display_name": "",
        "time_created": "2015-04-23T06:11:14.817Z",
        "time_modified": "2015-04-24T05:28:17.254Z",
        "time_deleted": null,
        "time_accessed": "2015-04-24T05:28:17.254Z",
        "external_id": null
      "consumer": {
        "id": 10001,
        "email": "",
        "given_name": "Test",
        "family_name": "User",
        "phone": [
        "external_id": "myco_id_123",
        "time_created": "2015-04-24T05:29:38.167Z"
      "extension": {
          "my_custom_field_1": "Blue",
          "consumer_t_shirt_color": "Orange"


Retrieves the current Session Device object.

  • callback: function(sessionDevice)
  • sessionDevice: session device object (see example)
  • returns: void

Example Session Device Object

      "id": 10000,
      "connection_id": "2a957290-e945-11e4-b519-455897140b7b",
      "session_id": 10000,
      "state": "0",
      "machine_id": "E7697C43-4D32-42BF-897B-DE716E4475B4",
      "device_id": 10000,
      "device_type": "mobile",
      "os_id": 3,
      "os_name": "iOS",
      "connectionKey": 812165,
      "isRemoteCapable": true,
      "isMobile": true,
      "SDKVersion": {},
      "deviceInfo": {
        "id": 10000,
        "name": "iOS",
        "os": "iOS 8.1.2",
        "serial": "E7697C43-4D32-42BF-897B-DE716E44",
        "serial2": "",
        "os_sdk": null,
        "os_build": "",
        "os_lang": "English (United Stat",
        "model": "Apple iPhone",
        "manufacturer": "Apple",
        "brand": "apple",
        "cpu": "",
        "cpu_arch": "",
        "cpu_verbose": null,
        "ip_address_public": null,
        "memory": " 988.00 MB",
        "networkInfo": [],
        "os_version": "8.1.2"
      "DeviceName": "Apple iPhone"


Retrieves the current Session Path object.

  • callback: function(sessionPath)
  • sessionpath: session path object (see example)
  • returns: void

Example Session Path Object

    "id": 12545,
    "session_id": 12237,
    "session_device_id": 13200,
    "workflow_version_id": 10637,
    "status": "In progress",
    "time_start": "2015-04-22T18:38:58.622Z",
    "time_modified": "2015-04-22T18:38:58.622Z",
    "time_end": null,
    "is_active": true,
    "category_id": 10012,
    "feedback_comments": null,
    "feedback_comments_archived": false,
    "feedback_question": null,
    "feedback_answer": null,
    "feedbacker_id": null,
    "sessionDevice": {
      "id": 13200,
      "connection_id": "d25a6e30-e91e-11e4-815d-abdbce5432cc",
      "session_id": 12237,
      "state": "0",
      "machine_id": null,
      "device_id": null,
      "device_type": null,
      "os_id": null,
      "os_name": null
    "workflowVersion": {
      "id": 10637,
      "workflow_id": 10215,
      "version": "(1,0)",
      "status": "Published",
      "os": null,
      "json": {
        "Id": "fa0f6aa4-9d61-4cfe-88c8-dbe09f5809d4",
        "WorkflowId": 10215,
        "Name": "Google Chromecast Setup",
        "Description": "Google Chromecast Setup",
        "Feedback": null,
        "Tasks": [
            "Id": "26cb8662-8804-4edd-8e86-ae5859d57c53",
            "StepId": 15271,
            "Details": "

Familiarize the customer with Chromecast.

", "Name": "Prerequisites for using Google Chromecast", "Tags": [], "ReportDetails": "The step was successfully completed.", "ReportNADetails": "The step was not run.", "OSId": null, "OSName": null, "CustomID": "INLINEPAGE", "ContentUrl": "../guides/113bf7d7-f4d2-45e8-9073-cb9227846f84.html", "Auto": false, "Depends": null, "Paths": [], "LastModifiedBy": "undefined undefined", "LibraryStepId": 10395, "SessionWorkflowStepId": 24363, "TaskStatus": "IN_PROGRESS", "Feedback": [] }, { "Id": "cba85f9f-b375-45f8-a857-35ebc3ce8e8b", "StepId": 15272, "Details": "Guide the customer to connect their Chromecast to their TV.", "Name": "Connecting Chromecast to the TV", "Tags": [], "ReportDetails": "The step was successfully completed.", "ReportNADetails": "The step was not run.", "OSId": null, "OSName": null, "CustomID": "INLINEPAGE", "ContentUrl": "../guides/9ee3ffab-4d3d-4084-99c8-7dfd2bdd21a0.html", "Auto": false, "Depends": null, "Paths": [], "LastModifiedBy": "undefined undefined", "LibraryStepId": 10448, "SessionWorkflowStepId": 24364, "TaskStatus": "IN_PROGRESS", "Feedback": [] }, { "Id": "bb9260b5-fc35-468c-803a-6cfacdbf85cf", "StepId": 15278, "Details": "

Ensure the Chromecast setup is complete

", "Name": "Complete Chromecast Setup", "Tags": [], "ReportDetails": "The step was successfully completed.", "ReportNADetails": "The step was not run.", "OSId": null, "OSName": null, "CustomID": "INLINEPAGE", "ContentUrl": "../guides/24762dd1-9fe5-411c-8500-225a15d47a03.html", "Auto": false, "Depends": null, "Paths": [], "LastModifiedBy": "undefined undefined", "LibraryStepId": 10438, "SessionWorkflowStepId": 24370, "TaskStatus": "IN_PROGRESS", "Feedback": [] } ] } } }

Note that the array of Tasks are the same as the task returned by the getTask() api.


Retrieves the current agents authentication token. The token is in JSON Web Token(jwt) format. The token is useful for two functions; Determining who the agent is, and impersonating the agent when executing Cloud back-end API calls.

  • callback(token) : function to invoke on completion
  • token : JWT
  • returns : void

Example JWT

The raw token is made of 3 parts, each base-64 encoded.


Decoded, the first 2 parts looks like: (the third part is the signing checksum)

    "typ": "JWT",
    "alg": "HS256"
    "t": "mycompany",
    "d": "",
    "prm": [
    "jti": "b5160cee-8718-48a0-b674-27292c891a6f",
    "iat": 1429729453,
    "exp": 1429736653,
    "aud": [
    "iss": "",
    "sub": ""

JWT Validation

To validate the token, it can be sent to the Cloud back-end API server (See JWT for backend calls).


Retrieves the task that the current agent has focused.

  • callback(task): function to invoke on completion
  • task: task object (See example)
  • returns: void

Example Task Object

    "Id": "cba85f9f-b375-45f8-a857-35ebc3ce8e8b",
    "StepId": 15272,
    "Details": "Guide the customer to connect their Chromecast to their TV.",
    "Name": "Connecting Chromecast to the TV",
    "Tags": [],
    "ReportDetails": "The step was successfully completed.",
    "ReportNADetails": "The step was not run.",
    "OSId": null,
    "OSName": null,
    "CustomID": "INLINEPAGE",
    "ContentUrl": "../guides/9ee3ffab-4d3d-4084-99c8-7dfd2bdd21a0.html",
    "Auto": false,
    "Depends": null,
    "Paths": [],
    "LastModifiedBy": "undefined undefined",
    "LibraryStepId": 10448,
    "SessionWorkflowStepId": 24364,
    "TaskStatus": "IN_PROGRESS",
    "Feedback": []


Retrieves information about the current agent.

  • callback(agent): function to invoke on completion
  • agent: agent object (See example)
  • returns: void

Example Agent Object

      "PasswordPolicy": "((?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,})",
      "ConnectSessionId": "mcwUumEY1T5Kjg6ciPTU9zb3",
      "installation": "dev",
      "Tenant": "mycompany",
      "tenantId": "b7ddf956-accf-4679-941a-a3f5a2ee5b88",
      "IsLoggedIn": true,
      "Status": 0,
      "ErrorMessage": null,
      "TenantSettings": {
        "Config": {
          "company_name": "mycompany",
          "time_zone": "Pacific Standard Time",
          "connect_url": "",
          "terms_of_service_url": "",
          "privacy_policy_url": "",
          "survey_url": "",
          "survey_url_enabled": true,
          "logo_file_name": null,
          "icon_file_name": null,
          "cobranding": true,
          "calling_card_enabled": false,
          "calling_card_phone_number": null,
          "calling_card_shortcut_logo_file_name": null,
          "calling_card_reuse_my_brand_logo": null,
          "calling_card_shortcut_text": null,
          "ios_third_party_app_enabled": false,
          "ios_third_party_app_name": null,
          "ios_third_party_app_url": null,
          "ios_third_party_app_connection_guide_url": null
        "CustomFields": []
      "appContainer": "sdc",
      "appVersion": "0.0.1",
      "totangoSid": "",
      "androidAppUrl": "",
      "iOSAppUrl": "",
      "iOSAppName": " Connect",
      "iOSAppConnectionGuideUrl": "",
      "id": 10000,
      "email": "",
      "given_name": "NA",
      "family_name": "NA",
      "permissions": [
      "is_global": true,
      "display_name": "",
      "roles": [


Dictionary that can be used for inter-step communication.

To retrieve a value from the cache:

  var value = conn.cache('mykey');

To insert a value in to the cache:

  var value = 123;
  conn.cache('mykey', value); Cloud Javascript Library API - Other Functionality


A string representing the HTTPS base url of the parent window. i.e.


Apply Cloud css to the document. Invoking this method will cause the Cloud CSS to be appended to the dom.

  • returns: void

JWT for backend API calls

Guided Path Apps may need to make REST API calls to Cloud. To establish a trust relationship, a token can be generated from within Cloud admin (Admin » Configuration » Configure App Tokens). The token can be decoded and inspected at The token has a property called JTI, which should be copied to the catalog “Jti” (see Catalog format) to establish the trust relationship. The token should then be used for authenticating all REST API calls to the back end.

To generate the token: GPA Token Generate

Any JWT with aud containing api can be used to make API calls to the back end. A full list of APIs can be found here.

Macro Substitution

The content Url supports macro substitution. All properties on the session, session device and Task objects can be used.

Macro Format

The macro is in dot notation format and wrapped with the percent % symbol on each side. It is case-sensitive. The following symbols are supported:

  • a-z , A-Z
  • 0-9
  • .
  • [ and ] : array indexer
  • _ : underscore

The macro is then evaluated against the object model. For example, given the macro, the percent symbols are stripped, then the path is evaluated against the object model, leading to being

Macro Examples

  • : 10110
  • “”
  • %sessionDevice.deviceInfo.serial%: “E7697C43-4D32-42BF-897B-DE716E44”
  • %sessionDevice.os_name%: “iOS”

Example Catalog Entry

      "Name": "Test Step",
      "Description": "Exercise some GPA functions",
      "PreviewImage": "",
      "ContentUrl": "",

Object Model

    "agent": {},
    "session": {},
    "sessionDevice": {},
    "sessionPath": {},
    "task": {},
    "token" ""

For further information on each of the nested objects, see: