Overview of using web requests

The OneBot API allows you to trigger your OneBot workflows, enabling seamless automation with Ivanti Neurones for ITSM and ITAM. In this guide, we cover the necessary API configuration and steps to trigger workflows from ISM.

Use OneBot to support your users and your team, helping you to:

• Provide resolution details to service users

• Enable a streamlined approval process

• Deliver an engaging survey experience

• Provide major incident notifications and updates

• Give your technicians data rich communication tools to support their clients.

Use Ivanti’s powerful web request quick actions from right within Ivanti Neurons for ITSM to trigger OneBot workflows, enabling Neurons to exchange information with your OneBot instance and send messages to your OneBot users.

Understand web requests

Understand systems and configuration

There are several steps to trigger workflows using a Neuron’s Web Request Quick Action. We cover the process in detail below, but in outline it addresses the following areas:

1. OneBot workflows – access the OneBot workflow you want to trigger.

2. MS Teams clients – access the Teams configuration that Neurons should use.

3. Webhooks – access the OneBot webhook used to trigger the workflow.

4. Information preparation – collate and format information used in the request.

5. Actions and triggers – create and configure the action and its trigger in Neurons.

Set up and manage web requests

Access OneBot information

Gather the information needed to target the workflow you want to trigger and understand any information the workflow is expecting to process. In addition, you need to get a Default Chat Client Configuration ID from OneBot to target the Teams configuration that should be used to communicate with your users. Finally, you will also need access credentials and the address for the webhook that will be used to trigger the workflow in OneBot.

Access Workflow ID and workflow inputs.

The Workflow ID is used within a web request to identify and target the correct workflow once OneBot receives a web request from Neurons. The ID forms part of the workflow’s URL and is visible in the address bar while editing the workflow in the portal.

To find the workflow ID:

1. Click ‘Workflow’ in the left navigation bar in the OneBot portal.

2. Click the workflow you wish to trigger from the list of displayed configurations. Alternatively, create a workflow by clicking ‘New Workflow’ in the top right.

3. Find the Workflow ID from the URL in the address bar of your browser while in the editor view.

   
   The URL has the following structure:

   • https://{ your tenant ID }/workflow/< the workflow ID >

   For example:

   • https://acme.onebot.co.uk/workflow/c8e8aa5b-116d-435c-c714-d08fb54cb6a3

4. You may want to note any data that should be provided to the workflow if it is meant to process information supplied from within Neurons for ITSM.

Access information for your MS Teams configuration

Use the endpoint ID of your Teams configuration to direct messages to OneBot users.

1. Click ‘Chat Clients’ in the left navigation bar in the OneBot portal.

2. Click ‘Configure’ on the Microsoft Teams chat configurations manager.

3. Click the Teams configuration that Neurons should use to message your users. Alternatively, create a new configuration by clicking ‘New Config’ in the top right.

4. Copy the endpoint ID of your Teams client to use as your Default Chat Client Configuration ID. Copy the whole endpoint URL using the adjacent button and paste it somewhere (e.g. notepad) to view it in full. The Endpoint ID is the dashed alphanumeric string at the end of the URL.
   
   For example:

   • https://{ tennent }/hook/chatclients/teams/< defaultChatClientConfigId >

Access webhook information used to trigger the workflow

Use the access credentials of your OneBot webhook and its endpoint address to securely trigger your OneBot workflow.

1. Click ‘Chat Clients’ in the left navigation bar in the OneBot portal.

2. Click ‘Configure’ on the WebHook chat configurations manager

3. Click the WebHook configuration you want Neurons to use to message your users. Alternatively, create a new WebHook configuration by clicking ‘New Config’ in the top right.

4. Note the webhook endpoint username and password. The password is not visible in the configuration view, though it can be updated.

5. Note the ‘run workflow’ endpoint address as your Webhook URL. This can be easily copied using the adjacent button.

Confirm user chat client configuration

Any users you want to send a Teams message to via a web request will need to have a Teams chat client account configured. Confirm that any users have a OneBot account with a configured Teams chat client to ensure that the workflow triggers correctly. To view the chat client configurations of your OneBot users:

1. Click on ‘User information’ in the left navigation bar.

2. Review the list of users in the user management view: the column titled ‘Chat Clients’ shows a Teams logo for each user with a configured Teams Chat Client.

Collate and prepare information for the web request

The information used to configure your web request needs to be collected and formatted before it can be used to create the web request quick action.

Preparing the request body

We will use the Web Request Quick Action as part of a composite action to make the web request. OneBot expects the data payload to be provided as JSON. Care is needed to form expressions for payloads if they also embed calls for data from Neurons.

There are several approaches. Two alternatives might be:

• Pre-package data for the web request body as string variables within a composite action.

• Use nested quote marks to wrap parts of the JSON data object as substrings and interlace these with calls to the application for data.

Multiple OneBot emails must be packaged as a JSON array.

Any data used as part of the data field needs to be parsed using a JSON object format.

An example of the body of a web request quick action is below. Note the use of the defaultChatClientConfigId, OneBot Email, and Workflow ID. These would be substituted as appropriate, without the angle brackets.

Example
JavaScript
Copy
$('{"defaultChatClientConfigId":"<defaultChatClientConfigId>",' + '"users":["'+ <OneBot Email> +'"],' + '"workflowId":"<Workflow ID>",' + '"data":{"recId":"' + RecId + '","incidentNumber":"' + IncidentNumber + '" ,"title":"' + Subject +'","description":"' + Resolution +'","fromUser":"' + Owner + '"}}')

Preparing the request header

Format the webhook username and password as Base64 to prepare it for use in the Authorization Header.

To prepare the username and password in Base64 as the Authorization Header:

1. Join the username and password into a single string, separated by a single colon (i.e. username:password ). This will form the credential used for authentication.

2. Convert the joined string to Base64.

3. Append the prefix ‘Basic ’ to the front of the converted string (note: there should be a single space between the prefix and the converted credential.)

4. An example of the final form for the Authorization Header might look like this:
   
   Basic T25lQm90OkhhdmVGdW5HZXR0aW5nVGhpbmdzRG9uZQ==

Create the web request action

Create the web request as part of a composite action. The arguments to use within the web request are as follows:

General settings

Header settings

Trigger the request

Once the Quick Action has been built it can be placed in Business Rules, Workflows, Escalation Schedules, and fired manually.