Direct URL

With Service Assist you can create forms that can be distributed to users who are not onboarded in the Service Assist platform by creating URLs pointing to external applications and forms.

The Direct URL functionality allows you to:

  • Interact with external users without onboarding them to the platform.
  • Limit the number of times a form can be accessed and how long it is accessible for, for example, a form can only be submitted once and will expire after a set number of days.
  • Create forms with a different look and feel. For more details, see Application configuration.

Use cases

Specifically configured users are sent tiles by the digital workers. The digital workers then generate the access tokens and URLs to send to the third-party application.

External

  • Gathering structured data from customers or suppliers.
  • Getting digital signatures from customers or suppliers.
  • Providing formatted data to customers or suppliers.
  • Getting data from outsource providers.

Internal

  • Approval workflows, for example when management don't want to maintain an account.
  • Getting information ad-hoc from internal teams.

Embedded

  • Embedding a Service Assist form in an existing workflow system, for example, ServiceNow. For more details, see Embedding Service Assist into ServiceNow.

  • Embedding a Service Assist form in a CRM, for example, Salesforce. For more details, see Embedding Service Assist into Salesforce.

  • Embedding Service Assist in a public website.

Direct URL configuration

Config.json file

The Direct URL settings can be configured in the config.json file as follows:

Copy
{
"transient": {
"user_id": 4,
"duration": 6,
"secret": "password"
}
}

Where:

  • User_id is the id of the user used for access tokens .
  • Duration is the validity period of the access token in days.
  • Secret is the passphrase used to encrypt / decrypt by the API.

From version 2022.1 onwards, the Direct URL feature can only be configured using the [email protected] user (id 4). Any previously created Direct URL access tokens using different users, for example, application_user may have to be recreated in order to work as expected. Any access tokens created via the Access Tokens VBO using an incorrect user will be set to revoked.

Access Tokens VBO

Access tokens are used to associate Direct URLs with a particular form and can be re-used or created for single use purposes only. You can also set a validity period for access tokens, and once an access token expires, it is deleted from the database and can no longer be used.

The Access Tokens VBO exposes actions used to generate, get and delete Direct URL(s), as well as to navigate to a given Direct URL in a user's default browser. The actions used are Create Access Token Payload and Send Access Token.

The following parameters can be defined in the VBO:

  • Bound Schema ID – The identifier of the object the Direct URL should point to, for example, the ID of the TpForm or the TpPage.
  • Number of Tokens – The number of tokens that will be used.
  • Valid For – How many days the Direct URL will be valid for.
  • Reusable – Set to True if the token should be reused, set to False if the token should only be used once.
  • Theme ID – The theme to be used to display the Direct URL form.
  • Bound Schema Name – The type of object the Direct URL will point to, for example, TpForm or TpPage.
  • Queue Item Queue Name – The name of the queue to which the request is sent.
  • Queue Item Page Name – The name of the page with which the queue is associated.

There are several ways Direct URL can be used:

  1. To display a defined static form or page.

    In this scenario, a form or page is created for the user configured as the transient user in the config.json file, then the Direct URL is created to reference it.

  2. To create a queue item, which can be picked up by a digital worker, and a new form dynamically returned and displayed.

    This requires creating a Direct URL that defines a queue item. A digital worker then picks up the queue item (and any passed in data) and creates a form dynamically in response. The form is then sent back to the browser using the Reply to QueueItem with Form action in the QueueItems VBO.

  3. To display a page, which contains multiple forms that submit multiple queue items returning multiple dynamic forms.

    This requires creating a Direct URL that refers to a previously created page. The page contains multiple forms, each with a TpQueueItem defined. When the page is referenced via the Direct URL, the queue items for each form in the page are sent, and multiple digital workers may pick up these queue items and respond with forms dynamically. In this case, the TpPage should be defined with multiple TpQueueItems. For more details, see .

In all these scenarios, further data may be passed into the forms or pages referenced by the Direct URL:

  • Fields in one or more forms can be pre-filled with data passed into the Direct URL.

  • Other data can be passed that can be picked up with the queue item.

Data passed into Service Assist via Direct URL can be base64-encoded or plain-text.

The following table shows which option is recommended based on your requirements:

Scenario Example Option A Option B

Option C

Static form or page with static forms Simple self-service form embedded in websites and systems where users are not logged in. Yes No No
Static form or page with static forms with pre-filled fields Simple self-service form embedded in websites and systems, but passing some context (for example, type of product, user's email address). Yes No No
Simple form dynamically generated based on passed data Generate a new form based on data passed in from websites and systems (for example, user ID, account number), and looked up by the digital worker. All components of the form are returned together. No Yes No
Complex page with multiple dynamically generated forms Generate a page with multiple forms based on data passed in from websites and systems, where each form can be populated by separate digital workers. Each form is populated by a separate digital worker. No No Yes

Examples

Passing data into Direct URL static forms or pages

For passing data into fields in a Direct URL static form or page with multiple static forms, the unique Name input parameter is matched with data passed as a parameter to the Direct URL. In the example below, the Name input parameter has been defined as 'Email'. To pass the data [email protected] into this field, a Direct URL is defined as https://<DirectURL>&[email protected].

Passing data into Direct URL dynamic pages

For passing data into fields in a DirectURL page with multiple forms, the unique Name input parameter is matched with data passed as a parameter to the Direct URL for all forms in the page. In the example below, the Name input parameter has been defined as 'Email'. To pass the data [email protected] into this field, a Direct URL is defined as https://<DirectURL>&[email protected].

Access Tokens tab in the admin user interface

You can also create new access tokens to be used for Direct URLs on the Access Tokens tab in the admin user interface.

  1. Click the Admin icon in the toolbar.

    The admin options display.

  2. Click Access Tokens and then Add New Access Token.

  3. Complete the following fields as required:
  • Name – Enter a name for the token, for example, Direct URL to Salesforce.
  • Description – Enter a description for the token.
  • Access Token – This will display once you click Save and the token is created.
  • Access URL – This will display once you click Save and the token is created. A copy to clipboard icon allows you to save the URL for a later use.
  • Product Type – This can be a form, page, or a queue item. This field is mandatory.
  • Form ID/Page ID/Queue Name – This is a mandatory field and is based on the product type selected above. For a form or page, enter the ID of the form or page you want the Direct URL to link to – this is the Bound Schema ID input parameter in the Access Tokens VBO. For a queue item, enter the queue name as defined in the Queue Item Queue Name parameter in the Access Tokens VBO.
  • Multi use – If required, enable this toggle to allow the token to be reused. This is disabled by default so the token is only set to be used once.
  • Theme ID – The name of the theme to be used in the Direct URL form.
  • Valid for (days) – Enter the number of days the token will be valid for. This is a mandatory field.
  • Valid Until – This is populated by automatically when you click Save based on the number of days entered above,
  • Created At – The date when the token was created. This is populated by automatically when you click Save.

  • If you have saved a new token but no longer want to use it, you can click Revoke.
  • Embedding Direct URLs in external applications

    You can update the settings in the config.json file to allow external websites and applications to display Service Assist content via Direct URLs.

    1. Locate the config.json file in /var/local/[your API server]/config/.
    2. In the config.json file, find the “headers” section.

      Copy
      {
        "headers": {
          "xframe": "SAMEORIGIN",
          "csp": {
            "frame-ancestors": "https://website-where-you-want-to-embed-tp-form.com https://my-tp-website.com"
          }
        }
      }
    3. Replace the URL in “frame-ancestors:” with the URL of the websites where you would like to embed Direct URL forms.

    4. Save your changes.

    5. Restart the API docker to apply the changes.