Documentation forSolarWinds Service Desk

Use data retrieved from third-party applications in workflows

On this page

Introduction

Through integrations with third-party applications, you can collect data via API calls and use the resulting JSON-formatted data in workflows for Service Catalog, Change Catalogs, and Runbooks.

Target audience: The target audience for this topic is administrators with basic knowledge of JavaScript Object Notation (JSON). You need to understand how to use the JSON path provided in the API response.

Navigation

Service Desk > Service Catalog or Change Catalog

Setup > Service Desk > Runbooks

Use JSON formatted data collected from an API response

API response data from third-party systems or applications can be used to benefit your business processes. Administrators can store this data in custom or system fields and use it to define advanced conditions and actions in workflows based on the received responses. The data extracted from the responses and stored in the fields can be used as conditions for triggering advanced actions as a part of a workflow, completing the entire cycle of a service process within the service or change request.

The feature can be used to send notifications and updates or update data in a record based on the responses received from third-party applications. Potential use cases include retrieving meeting details from MS Teams, Zoom or Google Calendar, storing it in a service or a change request field, and sending them to meeting stakeholders. Another example is calling an HR system, for example Workday, to retrieve employee information such as hire date or PTO balance and including the returned data in a notification sent to the requester.

Prerequisite

Read Process integrations and follow the steps on how to Create a new process integration.

Set up your workflow

Create a new process workflow or edit an existing one for a service catalog item, change catalog item, or runbook.

Use a valid JSON path to pinpoint the desired data. If you need guidance in identifying the proper JSON path, see Wikipedia.

You can create a new service catalog item, change catalog item, or runbook or edit an existing one. The navigation path for each is provided in the linked documentation.

  1. Either create a new process workflow (or edit an existing one) by hovering over an existing object, clicking the three horizontal dots to the right in the Actions column, and selecting Edit.

  2. In the new object, scroll down to the grey bar labeled Process. Click Add, then from the dropdown, select Process integration.

  3. Create the process integration. See Step 2: Create the process integration for instructions.

Data validation for troubleshooting and debugging

The process integration identifies data validation errors between the endpoints.

  • The information about the status of the process integration is displayed in the workflow node. The relevant data validation message is presented to the user.

  • Each validation error includes the JSON path where data retrieval or update has failed.

  • The administrator can add the following validations an input variable in the email notifications. The proper input variable is: {{process_integration_validation_error}}.

  • For further investigation and troubleshooting, you can download the complete JSON response available in process integration step within the workflow node.

Runtime validation errors

Runtime validation errors include:

  • HTTP method not allowed. This message is displayed when the API call to the URL specified in the process integration fails. It includes the URL used for the API call.

  • The requested data is missing. Specifies a JSON path that was not marked as mandatory but fails to return data or update successfully.

  • Unable to retrieve mandatory data. This message displays when a JSON path marked as mandatory fails to return data or update successfully.

  • The path provided in the process integration settings is invalid. Specifies where the provided JSON path is incorrect.

  • Data tree contains more than one value in the provided path. Multiple values found at specified path.

  • A Datatype mismatch exists between two endpoints. The validation specifies the path where the mismatch was found.

Runtime validation Process tab (workflow) display example

Workflow conditions

The workflow conditions include the capability to set a condition for the HTTP response status code. (Refer to https://http.dev/status and https://en.wikipedia.org/wiki/List_of_HTTP_status_codes); both links contain the same information but from different sources).

You can set a condition based on the HTTP status code received in the API response

The list of available workflow conditions contains an option to specify the HTTP response status code as a condition. The title of the option is Response code and the description is HTTP Response code.

The Response code option is displayed to the user in conditions only if the process integration is defined one step above it in the workflow hierarchy. Otherwise, if the process integration is not defined above it, the response code option does not display in the conditions.

The HTTP response status code in the workflow conditions include these settings:

  • Operator

    • Equals (the response code is equal to the value in the condition)

    • Not Equal (the response code is not equal to the value in the condition)

    • Less than (the response code number is less than the value in the condition)

    • Greater than (the response code number is greater than the value in the condition)

    • Less than or equal (the response code number is less than or equal to the value in the condition)

    • Greater than or equal (the response code number is greater than or equal to the value in the condition)

  • Value (the value of the HTTP response code, for example, 300, 400, 500, or other value)

Related topics