Start monitoring today and get 20% off on your first invoice. Available on all Uptrends plans.

Uptrends' Multi-Step API monitoring allows you to execute multiple sequential HTTP requests on your API, where incoming data gets parsed, saved to variables, or checked for the presence of specific content. In certain cases, however, the incoming data will need its values transformed or mapped, to make sense of it more easily. Examples include the XML and JSON encoding and decoding functions described in our custom integrations setup guide. In addition to these predetermined functions, Uptrends allows you to set User-defined functions. These functions can be used to convert variable values (acquired in a previous step, or from a system variable provided by Uptrends) to a new value.

Available types of user-defined functions

Currently we offer two types of user-defined functions:

  • Regular Expression: this function type allows you to apply a regular expression (RegEx) to your previously created variables. This is useful for extracting specific sections of the response data (such as extracting an authentication code from a Location redirect-header).
  • Mapping: the mapping function type allows you to automatically replace certain values in the response with specific other values. For example, if one endpoint uses the terms 'error'/'ok' (such as Uptrends' own API) while the next one you'll be interacting with expects the terms 'incident'/'healthy', you can use a mapping function to automatically adjust these values to the correct equivalents.

Creating User-defined functions

You can set up a user-defined integration in either the Steps tab of your Multi-Step API monitors, or in the Customizations tab of your (custom) integrations.

Note: A user-defined function is specific to the Multi-Step API monitor or custom integration for which you set it up, and does not carry over to other monitors or integrations.
  1. In the Steps tab of one of your Multi-Step API monitors or the Customizations tab of your (custom) integrations, you can find the User defined functions header near the bottom of the page.
  2. Click the + Add function button to start defining a new function.
  3. Select the appropriate function type: Mapping or Regular expression, and give the function an appropriate name - we recommend something simple and without spaces, as you'll need to refer to it later on.
    1. In case of a mapping function, add the individual mappings you require. The mapping function will translate the "From" values to the corresponding "To" values.
    2. For a regular expression function, specify the RegEx as required. The Regex is matched against the input text, and can be used to extract a specific part of that input.

You can add additional functions by repeating these steps, if necessary.

An example of a mapping function

Using your functions

To use your newly defined User-defined function(s), you'll have to wrap the variable(s) on which the function should act in the function reference like {{userDefinedFunction({{variableReference}})}}. As an example, let's look at a mapping function whose purpose is to translate incoming response data from 'Error' to 'Incident', from 'Warning' to 'Unhealthy, and from 'Ok' to 'Healthy', so that the endpoint called in the following step gets sent the terms it understands. In this example:

  • A user-defined function as shown in the image above was created, called errorMapping.
  • The endpoint sends a JSON response containing a field 'Status', which has a value of either 'Error', 'Warning', or 'Ok'.
  • In the following step, we intend to forward that status data to a different API. This new API doesn't understand the terms used, however, and requires values of 'Incident', 'Unhealthy' or 'Ok' instead.

To use the errorMapping function to automatically translate the status value into the correct terms, follow these steps:

  1. Extract the value of the 'Status' field from the response data, as you normally would (see our Multi-Step monitoring variables set-up guide). In this example, the resulting variable is named statusRaw. As described, this variable will contain 'Error'/'Warning'/'Ok'.
  2. To apply the user-defined function, first click the Add variable button.
  3. Set the variable source (the drop-down list on the left) to Execute function.
  4. For the function expression, wrap the variable reference in the function as decribed above: {{errorMapping({{statusRaw}})}}
  5. The resulting value will be either 'Incident' , 'Unhealthy', or 'Healthy', depending on what the value of the statusRaw variable was. In the Variable name textfield, specify a name for the output value.

How to use your mapping functionNow we've created a new value, status, whose value is either 'Incident' , 'Unhealthy', or 'Healthy'. In following steps, we can refer to this variable in the regular was (e.g. using the {{status}} notation. In this example, we've used a Mapping function, but it should be noted that the steps for a RegEx function are identical.