Create a data stream action to get user activity from a 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 user activity 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

About this task

Monitor user activity to find software subscriptions that your company is paying for but are not being used. You can reclaim these unused subscriptions to reduce your company's software expenses.

Before creating the data stream action, decide how you want to define meaningful user activity. Meaningful activity can be a combination of user actions. Create a separate data stream action for each user activity metric. For example, the base system Webex Meetings integration defines meaningful activity as hosting a meeting. It uses one data stream action to get the dates of the most recently hosted meetings for all users. If you also wanted the Webex Meetings integration to include logging in as meaningful activity, you would create a second data stream action to get the most recent login times for all users.

Your data stream action to get users may return a user activity metric such as last login time. In this case, you don't need to create a data stream action to get user activity or a subflow to get user activity unless you want to define additional user activity metrics. Make sure that your subflow to get users sets this user activity metric as the Last activity input in the Upsert User Subscription action.

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 User Activity.
    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. In the Inputs section of the Action Outline, click Create Input.
  6. Add a look back time input.
    Table 2. Inputs
    Label Name Type Mandatory
    Look back time look_back_time Date/Time Yes
  7. If the API that you're working with requires user authentication for requests, 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.

  8. Click Request in the Action Outline.
  9. On the form, fill in the fields.
    Table 3. 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.
  10. Click Pagination Setup step in the Action Outline.
  11. 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.
  12. 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, convert the value to an integer, perform any required operations, then convert it back to a string.
  13. Click SOAP step or REST step in the Action Outline depending on the option that you selected for how you will get data.
  14. If you selected SOAP, fill in the form as shown.
    Table 4. 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 meaningful user activity. For example, the base system Webex Meetings integration defines meaningful user activity as hosting a meeting so that it uses the LstsummaryMeeting request to get a list of all meetings. 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 meaningful user activities, a start date set as the Look back time input, and your variables from the pagination setup step.
    Note: For an example of a SOAP envelope, see the Get User Activity data stream action used in the Webex Update User Activity subflow.
  15. If you selected REST, fill in the form as shown.
    Table 5. 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.
    Add another parameter for the start date so that the request returns results from the start date to the current date. Set the value as the Look back time input.
    Note: Make sure the Look back time input date/time variable is correctly formatted for the API that you're working with. If you need to reformat or convert to another data type such as a string, you can do this in the action preprocessing script step.

    The following image shows a completed example of the REST step. This example is from the Get Audit Log data stream action used in the Jira Update User Activity subflow.

    REST step
  16. Click Parsing in the Action Outline.
  17. On the form, fill in the fields.
    Table 6. Parsing form
    Field Value
    How will you identify each record JSON/XML Splitter
    How will you parse each item into an object Script Parser
  18. Click Splitter step in the Action Outline.
  19. On the form, fill in the fields.
    Table 7. Splitter step form
    Field Value
    Source Format Select XML or JSON depending on the format returned by the API response.
    Item Path Absolute path to a meaningful activity 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/meeting
    • Example JSON item path: $.data.meeting
  20. Click Outputs in the Action Outline.
  21. Click Create Output and edit the variable as shown.
    Table 8. Action Output
    Label Name Type Mandatory
    targetObject targetObject Object No
  22. Add child items for targetObject to store the user email and the date of meaningful activity.
    For example, an XML response might look like this.
    <message>​
  <body>​
    <meeting>
      <meetingID>​12345</meetingID>​
      <startDate>​08/13/2019 20:08:16</startDate>​
      <hostEmail>​email@email.com</hostEmail>​
    </meeting>​
    <meeting>
      ...
    </meeting>
  </body>​
</message>
    For this response, add the child items as shown.
    Table 9. Child items for targetObject
    Label Name Type Mandatory
    email email String No
    last_activity last_activity String No
  23. In the Action Outline, click Script Parser step.
  24. Create a targetObject output object for each meaningful activity element in the response and then map each the activity date and user email to the targetObject child items.

    The parser script is executed for each user element.

    Note: These examples show the types of elements that could be contained in a response. Don't 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.email = xmlDoc.getNodeText('/meeting/hostEmail');
    outputs.targetObject.last_activity = xmlDoc.getNodeText('/meeting/startDate');
})(inputs, outputs)
    Example script that parses a JSON response. 
    (function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.email = record.hostEmail;
    outputs.targetObject.last_activity = record.startDate;
})(inputs, outputs)
  25. 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.
  26. After verifying that the data stream action is working as expected, click Publish.