Guided Path Apps

Audience

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

Definition

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 Support.com 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.

Contents

How It Works

  • The Guided Path App (App) is configured in Support.com Cloud Admin
  • Steps provided by the Guided Path App are added to a Guided Path in the Support.com Cloud Designer
  • The Guided Path is executed in Support.com 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 Support.com Cloud Javascript Library
  • (Optionally) The App fetches the OAUTH JSON Web Token (JWT) for B2B Authentication
  • Optionally) The App applies the Support.com Cloud CSS
  • (Optionally) The App retrieves session / device / agent etc. data from Support.com Cloud to be used for loading external data

Requirements

  • An HTTP/JSON endpoint must be made available for the Support.com 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 Support.com Cloud Admin area. These are the steps to configure a Guided Path App in Support.com 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 https://gpa-samples.herokuapp.com/device/_nexusinfo/.
  • 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 Support.com Cloud designer to author a new Guided Path. Support.com Cloud has just queried the catalog URL and merged the resultant content with the Support.com 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 Support.com Cloud client-side javascript library:

GPA Step Execution

Catalog

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 Support.com Cloud backend by either an HTTP GET or POST, depending on how it is configured on the Support.com 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 Support.com 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": "https://static.hkg.firebet.dev.support.com/gpa/v1/nexusNavigatorTestPreview.gif",
      "ContentUrl": "https://static.hkg.firebet.dev.support.com/gpa/v1/nexusNavigatorTest.html?device=%sessionDevice.deviceInfo.serial%",
      "Config": {}
    },
  {
    "Name": "Support.com Wikipedia Step",
    "Description": "",
    "PreviewImage": "https://static.hkg.firebet.dev.support.com/gpa/v1/SPRT-wikipedia.GIF",
    "ContentUrl": "https://www.wikipedia.com/%sessionDevice.os_name%",
    "Config": {}
  }
  ]
}

ContentUrl

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 Support.com Cloud Javascript Library provides a way to authenticate the agent against the Support.com Cloud backend.

Support.com Cloud Javascript Library

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

     <script src="https://static.nexus.support.com/gpa/v1/nexusNavigator.js"></script>

The following code is required to initialize the library:

    <script>
        var conn = nexusNavigator.api();
        nexusNavigator.on('ready', function (api) {
            conn = api;
            // start making calls to the conn object
        });
    </script>

Support.com Cloud Javascript Library API - Events

Support.com 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 Support.com 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

Support.com Cloud Javascript Library API - RPC

noOp()

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

  • returns: void

setHeight(height)

Set the IFRAME height.

  • height: integer value in pixels
  • returns: void

isConnected(callback)

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

  • callback: function(isConnected)
  • isConnected: boolean value indicating whether the parent Support.com Cloud windows websocket is connected to the Support.com 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

getSession(callback)

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": "firebet@support.com",
        "given_name": "NA",
        "family_name": "NA",
        "phone": "0000000000",
        "display_name": "firebet@support.com",
        "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": "testuser@mycompany.org",
        "given_name": "Test",
        "family_name": "User",
        "phone": [
          "3033030033"
        ],
        "external_id": "myco_id_123",
        "time_created": "2015-04-24T05:29:38.167Z"
      },
      "extension": {
          "my_custom_field_1": "Blue",
          "consumer_t_shirt_color": "Orange"
      }
    }

getSessionDevice(callback)

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"
    }

getSessionPath(callback)

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.

getToken(callback)

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 Support.com 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.

 eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0IjoibXljb21wYW55IiwiZCI6ImhrZy5
 maXJlYmV0LmRldi5zdXBwb3J0LmNvbSIsInBybSI6WyIqOioiXSwianRpIjoiYjUxNjBjZWU
 tODcxOC00OGEwLWI2NzQtMjcyOTJjODkxYTZmIiwiaWF0IjoxNDI5NzI5NDUzLCJleHAiOjE
 0Mjk3MzY2NTMsImF1ZCI6WyJuZXh1cyIsImFwaSIsImFwcCJdLCJpc3MiOiJTdXBwb3J0LmN
 vbSIsInN1YiI6ImhhcnJ5d0BzdXBwb3J0LmNvbSJ9.xTfV3Wd1kdwEHcxiK3ZhaZfm1KAmvw
 93xqYsohjmvZM

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

  {
    "typ": "JWT",
    "alg": "HS256"
  }
  {
    "t": "mycompany",
    "d": "hkg.firebet.dev.support.com",
    "prm": [
      "user:search",
      "user:passwordupdate",
      "consumer:*",
      "session:*",
      "os:view",
      "category:view",
      "workflow:view",
      "brand:view"
    ],
    "jti": "b5160cee-8718-48a0-b674-27292c891a6f",
    "iat": 1429729453,
    "exp": 1429736653,
    "aud": [
      "nexus",
      "api",
      "app"
    ],
    "iss": "Support.com",
    "sub": "mr_agent@mycompany.com"
  }

JWT Validation

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

getTask(callback)

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": []
  }

getAgent(callback)

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": "https://play.google.com/store/apps/details?id=com.sprt.android.esnext",
      "iOSAppUrl": "https://itunes.apple.com/us/app/nexus-connect/id910054837",
      "iOSAppName": "Support.com Connect",
      "iOSAppConnectionGuideUrl": "",
      "id": 10000,
      "email": "firebet@support.com",
      "given_name": "NA",
      "family_name": "NA",
      "permissions": [
        "*:*"
      ],
      "is_global": true,
      "display_name": "firebet@support.com",
      "roles": [
        "Administrator",
        "Agent",
        "Author",
        "Analytics"
      ]
    }

cache

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);

Support.com Cloud Javascript Library API - Other Functionality

origin

A string representing the HTTPS base url of the parent window. i.e. https://global.nexus.support.com

window.nexusNavigator.loadCss()

Apply Support.com Cloud css to the document. Invoking this method will cause the Support.com 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 Support.com Cloud. To establish a trust relationship, a token can be generated from within Support.com Cloud admin (Admin » Configuration » Configure App Tokens). The token can be decoded and inspected at http://jwt.io. 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 %session.id%, the percent symbols are stripped, then the path session.id is evaluated against the object model, leading to %session.id% being

Macro Examples

  • %session.id% : 10110
  • %session.consumer.email%: “john.doe@gmail.com”
  • %sessionDevice.deviceInfo.serial%: “E7697C43-4D32-42BF-897B-DE716E44”
  • %sessionDevice.os_name%: “iOS”

Example Catalog Entry

  {
      "Name": "Test Step",
      "Description": "Exercise some GPA functions",
      "PreviewImage": "https://test.com/Preview.gif",
      "ContentUrl": "https://test.com/session/%session.id%",
  }

Object Model

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

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