Polling monitor events

A polling monitor is a mechanism to retrieve information from online services on a scheduled basis, in situations where support for a webhook event flow isn't available or desired.

As specific events occur on the remote service, they're tracked and recorded. Then, when a scheduled polling monitor flow executes, Okta queries the remote service and retrieves all the information recorded since the last time the remote service was called.

This mechanism is commonly used to automate processes and keep different systems in sync without requiring constant manual intervention.

Polling monitor overview

Configuring a polling monitor flow consists of several general steps:

  1. Set up the polling monitor. The polling monitor composes a GET request that calls a specific API resource using a time-based filter that updates after every scheduled execution.

    For example, an Okta admin might set up a polling monitor to receive daily notifications about new employees that their company has added in Workday.

  2. Set a stored increment value, called a cursor. This stored value is updated at each execution of the scheduled polling monitor. In Okta Workflows, this stored value, usually a time stamp, is updated and accessed using a Cursor function card. Each time the flow composes the GET request, it uses this value to fetch the records from the remote service. See the Cursor function card for implementation details.

  3. Schedule the event trigger. Polling monitors use the same configuration dialog as a scheduled flow. You can set your polling monitor to call the remote service with any frequency from 5 minutes up to 30 days.

  4. Retrieve the payload. Okta sends the GET request containing the filtered query to the remote service, which returns a payload of records that occurred within the given time frame.

  5. Process the payload. The receiving app processes the records returned by the GET request. It parses the JSON payload and completes the event flow.

    When handling payloads, there are two processing aspects to consider:

    • Request aggregation. Incoming payloads are received as a collected batch of items.

    • Batched request processing. Although the incoming payloads arrive as a collected batch, the event flow can process each item individually or handle the entire batch as one item.

    See Enable run mode for polling monitors.

Use cases

The easiest implementation of a polling monitor event is to use a saved time stamp as part of the query to the remote service's API. This method returns all records that were created or updated since that saved time stamp.

If a time stamp query isn't supported, you may have to retrieve all records and manually filter the collection. Also, for more intricate scenarios, for example tracking deleted users, you may need a complex cursor object that retains extra metadata between executions of the polling monitor.

Created records

In this use case, the filter query sent to the API contains a starting date (the previous execution time stamp) and an end date (the current execution time stamp). The API returns all records added by the remote service over the specified time period.

Your polling monitor flow would look similar to the following example. The startDate is the previous execution time stamp, which is pulled from the Cursor. The endDate is the current time. These values are added to a Compose card to make the query string. The string is sent to a Construct card that creates the query input for the Call Flow card.

The query returns the records as a batch object in the body of the Call Flow card, which is passed to the Return Objects card. The Cursor card is updated with the new time stamp for use in the next execution of the polling monitor event.

Updated records

Similar to polling for created records, if the API supports filtering using a lastUpdated time stamp, then you can specify the before and after time stamps to find updated users.

The only difference in the flow for this use case is that the Compose function card string uses updated instead of created for the query.

When executed, your polling monitor fetches all user changes since the last update.

Deleted records

A more advanced scenario is using a polling monitor to track users deleted on the remote service. The following example explains one way of handling this use case using the cursor as an object to store user information along with a time stamp for tracking executions.

A cursor has a 10 KB size limit. Using cursors to store large amounts of data may cause errors that require your users to reactivate their flow and reset the cursor.

When configuring this Polling Monitor event card, the outputs for the card are set as a static output group object. Each user in a returned Deleted User object is defined with their User ID as a text value:

The API query polls the /v1/users endpoint to return a list of objects containing all current users on the remote system. After that information is returned, the flow performs the following steps:

  1. The list of returned users in the body of the API query is passed to a Pluck function card.

  2. The Pluck card uses the ID key within the users list, returning a list of current user ID values as output. This currentUserList contains only the users that are active in the remote system.

  3. The cursor object (dragged from the flow's Polling Monitor card) also contains a list of users at the userList location. This Cursor Properties object is input for an Object - Get function card. This function card generates a list object called previous list of IDs that contains all the previously known users on the remote system.

  4. For the comparison operation, the flow compares the difference between the previous list of IDs and the current list of IDs. Those IDs that aren't found in the current list are sent into a new list called Deleted User IDs. This output list is comprised of all the ID values that are no longer on the remote system.

  5. Next, the flow creates an object to pass to the Flow Control - Cursor card. The Object - Construct function card takes as input both the current time stamp and the newly minted list of current users.

  6. The output object is then passed to the Properties field of the Cursor card. The cursor object is saved as metadata for the next execution of this polling monitor.

  7. However, the Deleted User IDs list has to be formatted as a list of objects to be returned to the polling monitor user. To do so, the flow includes a List - Map function card. The care invokes a small helper flow called Reshape Deleted Users for each entry in the Deleted User IDs list.

    The Reshape Deleted Users helper flow processes each item in the Deleted User IDs list. Each ID value that is passed to the flow is sent to an Object - Construct card. This creates a unique object for each user, with the format { "User ID" : "ID" }.

  8. As each entry in the Deleted User IDs list is processed, the flow adds it to the Reshaped Outputs list of objects.

  9. When the helper flow is done, the Reshaped Outputs list of objects gets passed to the Flow Control - Return Outputs card. This matches the defined output on the Polling Monitor card and completes the execution of the polling monitor. The user receives the expected list of users deleted from the remote service.