Create a data stream action to get a list of user subscriptions from the SaaS application.

Before you begin

If you're using an existing ServiceNow® Integration Hub spoke, find out if it has a data stream action to get a list of users that you can use instead of creating one.

For more information about data stream actions, see Data Stream actions.

Role required: flow_designer or admin

Procedure

  1. Navigate to All > Flow Designer > Designer.
  2. Click New and then select Data Stream.
  3. On the form, fill in the fields.
    Table 1. Action Properties form
    FieldValue
    Name Name of your choice. For example, Get Users.
    Accessible From All application scopes.
    Category Leave this field empty.
    Protection None.
    Application Spoke app to integrate with the SaaS application. This spoke app can be an existing Integration Hub spoke or a new spoke that you created.
    In-Flow Annotation Leave this field empty.
    Description Description of your choice.
  4. Click Submit.
  5. If the API that you're working with requires user authentication for requests, click Inputs in the Action Outline and add inputs for authentication.
    Examples of common user authentication inputs are admin user id and site name. See the documentation for your chosen API to learn about the requirements for user authentication in your specific case. If the API requires an access token, a Credential Value variable is automatically created later. You don't need to add an access token as an input.

    When you use your completed data stream action in a subflow, you define what values to pass as these inputs.

  6. Click Request in the Action Outline.
  7. On the form, fill in the fields.
    Table 2. Request form
    Field Value
    How will you get data Choose either REST Step or SOAP step. Your choice depends on the API for the SaaS application that you're integrating with.
    Enable pagination Selected.
    Run a script before each request Not selected.
  8. Click Pagination Setup step in the Action Outline.
  9. Define pagination variables based on the query parameters used by the SaaS API.

    If you're using offset-based pagination, use the Limit / Offset pagination template to preload the pagination configuration.

    Note: The value of the reserved getNextPage variable determines whether to request another page of results. As long as the getNextPage variable is true, the action continues to send requests for the next page.
  10. Write a Pagination Variables Script to update the pagination variables.

    The script runs on each request. If you're using a pagination template, adjust the preloaded script as needed.

    The following image shows a completed example of the pagination setup step. This example is from the Get Users data stream action used in the Webex Download Subscriptions subflow.

    Pagination Setup step
    Note: Pagination variables only support the string data type. To perform math operations, you must convert the value to an integer, perform any required operations, then convert it back to a string.
  11. Click SOAP step or REST step in the Action Outline depending on the option that you selected for how you will get data.
  12. If you selected SOAP step, fill in the form as shown.
    Table 3. SOAP step form
    Field Value
    Connection Details
    Connection Use Connection Alias.
    Connection Alias Connection alias that you created when you created the integration profile. If you have not yet created an integration profile, follow the steps to create a custom integration profile with a connection alias.
    Endpoint This value is automatically populated when you select the connection alias. It's set to the Connection URL from the HTTP(s) Connection record linked to the alias.
    Request Details
    Build Envelope Manually.
    SOAP Action API request to get a list of all users. See the documentation for your chosen API to select the appropriate request.
    SOAP Envelope XML request message to get a list of all users. See the documentation for your chosen API to learn how to write an XML request message. In general, the header should have your input variables for user authentication as well as the Credential Value variable as the access token. The body should include the request to get a list of all users and your variables from the pagination setup step.
    Note: For an example of a SOAP envelope, see the Get Users data stream action used in the Webex Download Subscriptions subflow.
  13. If you selected REST step, fill in the form as shown.
    Table 4. REST step form
    Field Value
    Connection Details
    Connection Use Connection Alias.
    Connection Alias Connection alias that you created when you created the integration profile. If you have not yet created an integration profile, follow the steps to create a custom integration profile with a connection alias.
    Base URL This value is automatically populated when you select the connection alias. It's set to the Connection URL from the HTTP(s) Connection record linked to the alias.
    Request Details
    Build Request Manually.
    Resource Path Path to the resource. This value gets appended to the Base URL. See the documentation for the API that you're working with to learn how to construct the resource path.
    HTTP Method GET.
    Query Parameters Add parameters for pagination. Set the values as the variables that you created in the pagination setup step.

    The following image shows a completed example of the REST step. This example is from the Get Jira Users data stream action used in the Jira Download Subscriptions subflow.

    REST step
  14. Click Parsing in the Action Outline.
  15. On the form, fill in the fields.
    Table 5. Parsing form
    Field Value
    How will you identify each record JSON/XML Splitter
    How will you parse each item into an object Script Parser
  16. Click Splitter step in the Action Outline.
  17. On the form, fill in the fields.
    Table 6. Splitter step
    Field Value
    Source Format Select XML or JSON, depending on the format returned by the API response.
    Item Path Absolute path to a user element in the response message. See the documentation for the API that you're working with for information about the format of the response message.
    • Example XML item path: /message/body/user
    • Example JSON item path: $.data.user
  18. Click Outputs in the Action Outline.
  19. Click Create Output and edit the variable as shown.
    Table 7. Action Output
    Label Name Type Mandatory
    targetObject targetObject Object No
  20. Add child items for targetObject based on the user child elements returned in the response message.
    For example, an XML response might look like this.
    <message>​
  <body>​
    <user>
      <userID>​12345</userID>​
      ​<email>​email@email.com</email>​
      <firstName>​Jane</firstName>​
      <lastName>​Doe</lastName>​
      <lastLoginTime>​08/13/2019 20:08:16</lastLoginTime>​
      <active>​TRUE</active>​
    </user>​
    <user>
      ...
    </user>
  </body>​
</message>
    For this response, add the child items as shown.
    Table 8. Child items for targetObject
    LabelNameTypeMandatory
    userID userID String No
    email email String No
    firstName firstName String No
    lastName lastName String No
    lastLoginTime lastLoginTime String No
    active active True/False No
  21. Click Script Parser step in the Action Outline.
  22. Create a targetObject output object for each user element in the response and then map each user child element to a targetObject child item.

    The parser script is executed for each user element.

    Note: These examples show the types of elements that are generally contained in a response to a get users request. Do not directly copy these scripts. Use element names from the documentation for the API that you're working with.
    Example script that parses an XML response. 
    (function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.userID = xmlDoc.getNodeText('/user/userID');
    outputs.targetObject.email = xmlDoc.getNodeText('/user/email');
    outputs.targetObject.firstName = xmlDoc.getNodeText('/user/firstName');
    outputs.targetObject.lastName = xmlDoc.getNodeText('/user/lastName');
    outputs.targetObject.lastLoginTime = xmlDoc.getNodeText('/user/lastLoginTime');
    outputs.targetObject.active = xmlDoc.getNodeText('/user/active');
})(inputs, outputs)
    Example script that parses a JSON response. 
    (function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.userID = record.userID;
    outputs.targetObject.email = record.email;
    outputs.targetObject.firstName = record.firstName;
    outputs.targetObject.lastName = record.lastName;
    outputs.targetObject.lastLoginTime = record.lastLoginTime;
    outputs.targetObject.active = record.active;
})(inputs, outputs)
  23. To test your data stream action, click Test.
    1. View the test results and system logs for details about any errors.
      To view system logs, navigate to System Logs > System Log > All.
    2. If your data stream action has errors, make sure that you're using the correct endpoints and that the API requests and responses are structured as expected.
  24. After verifying that the data stream action is working as expected, click Publish.