Web Request - BETA

Use the Web request stage to retrieve information to use within a bot, or drive change in an external system. The stage is executed from Ivanti Neurons Platform and is run once per device that passes through the stage. It can interact with 3rd party REST APIs, and is supported against unauthenticated and authenticated APIs.

How to configure the Web Request stage

1. On the Create bot page, add a Web Request stage to a bot and open the Stage settings.
2. From the Select Credential drop-down, select the credential if the web request requires authentication. If you need to create new credentials, click Add credentials to open the Credentials store. Basic API and API Key authentication are currently supported. If no credentials are required, leave the default setting No authentication.
3. Under Headers toggle Show auto-generated headers to On if you want to view the auto-generated headers. The headers are in-line with the target API requirements, for further details refer to the 3rd party documentation.
   • Key: Enter the header key for the web request.
   • Value: Enter the header value for the web request.
4. Select the Method. This is the HTTP Method that will be used to access the target API. The supported methods are: GET, POST, PUT, PATCH, and DELETE.
5. Enter the API Address. The address must be internet accessible.
   If you are passing values in from another stage or bot input, and the destination API accepts a JSON payload, click Edit JSON body to open the Json editor. Select the values you want to include (the Web Request stage must be connected to any previous stages in order for information to be passed through).
   
6. Choose the appropriate Output mode to reflect the response from the API. If you selected an HTTP Method of GET most common will be JSON.
7. Click Test and get response to do an immediate call to the API.
   If the JSON body contained variables from earlier stages you will be prompted to enter example data.
8. The Example Response is populated from the Test and get response action.
   Once you have verified the response you can determine whether the results are singular (unique fields per endpoint) or an array (multiple values for a given field per endpoint).
9. If the results are an array, you need to toggle On the Mapping array.
   When the stage is in mapping array mode, the stage will display the 'multiple' badge meaning that to use the results in most other stages you will need to use a 'For-each' block to execute the contents for each result.
   • Enter the Path to array.
10. Once the Mapping array toggle is On, complete the following Field Map attributes:
    • Path inside of array element:The path to the object in the JSON response. This may just be the name on its own, but if the object is nested the path needs to be denoted in dot syntax e.g. level1.level2.myfield
      Singular example:
      {"configuration": {startup_events": {"updates": "some value"}}}
      Path to updates would be: configuration.startup_events.updates
      Array example:
      {"users": [{display_info": {"name": "John"}}]}
      Path to array would be: users
      Path within array would be: display_info.name
    • Type: This needs to match the format of the value being read so that the correct filters/behavior can be applied in future stages.
    • Mapped label: This is the friendly name for the field that will show up on the token picker and filters in subsequent stages.

Once the Mapping array attributes have been selected, click Test mapping to test the mappings against the Example Response, this makes sure the mappings are correct.