Create a 'send web request' step

In Jira Service Management’s virtual service agent, conversation flows are made up of a series of steps. The send web request step type allows you to automatically send a request to a server, and get web pages or resources in return. Read about the other step types.

Create a ‘send web request’ step

1. Go to the conversation flow you want to add a send web request step to. Find out how to build a conversation flow.

2. To see which fields and values are available for this send web request step, open the Fields and values available for this step expand at the bottom of the panel. Fields and values can be referenced in the Web request URL, Headers, and Body fields using curly braces, for example, {{field}}.

3. Enter a Title.

4. Select an HTTP method. The setting for this depends on the URL your web request is set up to use. Commonly used settings include:

   • GET: typically used to retrieve data

   • POST: typically used to add data

   • PUT: typically used to set data

   • DELETE: typically used to delete data

5. Enter a Web request URL.

6. Enter a Request timeout (in seconds). In the event of a timeout, the conversation will continue down the ELSE branch.

7. If desired, enter one or more Headers.

   • As an example, if you needed to get authorization, you could use Authorization in the Name field, and Bearer API_token_here in the Value field.

   • To ‘hide’ a header value, select the Hidden checkbox. Once saved, a hidden header value will appear as dots (····) instead of its actual value. This means it can be used for API tokens or secret keys that shouldn’t be shared with other people.

8. Select a Body content type.

   • text/plain means your Body field contains plain text (no special markup/text format).

   • application/json means your Body field contains JSON.

   • application/xml means your Body field contains XML.

9. If desired, enter a Body.

   • Data in this field will be sent as the body of the web request, if applicable for your use case.

10. Enter a variable name in Response variable. The response body types currently supported are JSON and plain text.

    • This variable can be used in send message and send web request steps later in this conversation flow.

    • When you use a response variable to capture a web request's response, you can directly access the following components:

      • Status code: Use {{responseVariableName.status}} to access the HTTP status code, such as 200, 403, or 500.

      • Headers: Access specific headers using {{responseVariableName.headers.Header-Name}}.

      • Body: For JSON responses, use {{responseVariableName.body}} to access the JSON object. Navigate to specific properties using path notation, such as {{responseVariableName.body.propertyName}}. For plain text responses, use {{responseVariableName.body}} to access the entire response body as a string.

    • If the response body includes a list or is formatted as a JSON array, you could access individual elements using the following accessor properties:

      • first: To retrieve the first element, use {{responseVariableName.body.arrayPropertyName.first}} if the array is a property, or {{responseVariableName.body.first}} if the entire response is an array.

      • last: To access the last element, use {{responseVariableName.body.arrayPropertyName.last}} for an array property, or {{responseVariableName.body.last}} if the response itself is an array.

      • indexed: For specific elements, use {{responseVariableName.body.arrayPropertyName.indexed.N}} if it's a property, or {{responseVariableName.body.indexed.N}} for the entire response, where N is the 0-based index.

      • size: To find out the number of elements, use {{responseVariableName.body.arrayPropertyName.size}} for a property, or {{responseVariableName.body.size}} if the array is the entire response.

11. Add your desired Conditions. To add more conditions, select + Add condition.

    • One ELSE condition is required.

    • Each condition will create a new branch in this conversation flow.

    • The variables available for conditions are status (for example, 200, 403, or 500), body (the content returned in the response), and headers (the headers returned in the response).

Example conditions

To understand the syntax of conditions, we’ve created some examples:

• status == 200 matches a response with status 200, but not any other status.

• status ~ 2?? matches a response with any status that starts with 2 (for example, 200, 201 and so on, but not 300, 400, and so on).

• not status ~ 2?? matches a response if it does not have a status between 200 and 299.

• body ~ "success" matches a response that contains the string "success" inside the response body

• status == 200 and body ~ "success" matches a response with status 200 and a body containing the string "success"

• headers.Content-Type == "application/json" matches a response with the Content type header set to application/json

• not (status != 200 and body ~ "*ERROR*") matches if the status is 200 or the body does not contain “ERROR”

• body ~ /^$/ matches if the body is empty

• body ~ /^[A-Za-z]+$/ matches if the body contains only alphabetical characters.

• not body ~ /"remaining": 0/ matches if the body does not contain the string ““remaining”: 0”

Note: We support regex for body and headers, but not status. Therefore, this is invalid: status ~ /4[0-9]{2}/

JSON and inequalities

Keep in mind that the virtual service agent does not support inequalities, or JSON in the conditions.

For example, suppose you had the following response body: { "remaining": 2 }

It would mean that the following condition is invalid: body.remaining > 0

We recommend using regex to find the appropriate value in the JSON. A valid condition (equivalent to what the above condition is doing) would be: body ~ /^"remaining": ([0-9]+(?:[\.][0-9]*)?|\.[0-9]+)$/

This would match if the body contains the string "remaining": $ (where $ is a non-zero positive whole number or decimal value).

Use the response variable to improve a conversation flow

Let’s say you’re creating a conversation flow that allows customers to book a desk at their local office, and they respond to an ask for information step by saying that they work in the Sydney office.

You could set up a send web request step that sends a web request to a URL created for booking desks at your company’s offices around the world, and reference it using the syntax provided when you got the “Sydney” response in the ask for information step:

If the response from the web request matches one of your success conditions (for example, status ~ 2??), you could then have the virtual service agent inform the customer (using the send message step type) that their desk has been booked.

Imagine that the API for booking a desk returns a JSON response with the following structure upon a successful booking:

In this case, you could use the response variable to:

• Define a response variable: In the send web request step, define a response variable called bookingResponse to store the API response.

• Access specific data: After storing the response, you can use it to access specific pieces of information. For example, you could use bookingResponse.body.bookingId to extract the booking ID.

  • Access list elements: If the response includes a list of available desks, you could access specific desks or iterate over them:

    • You could use {{bookingResponse.body.availableDesks.first}} to get the first available desk, which would be "Desk 2".

    • If you want to inform the customer about all available desks, you could display each desk by iterating over the list using a simple template syntax:

      1 2 3 {{#bookingResponse.body.availableDesks}} - {{.}} {{/bookingResponse.body.availableDesks}}

      This will iterate over each desk and output them in a list format.

• Customize messages for the customer: In a subsequent send message step, you could reference the booking ID to provide a personalized message to the user. For example: "Your desk has been successfully booked at the Sydney office. Your booking ID is {{bookingResponse.body.bookingId}}."

• Handle different outcomes: By checking bookingResponse.status, you could adapt the conversation flow based on whether the booking was a success or not. For example, if the status is "failed", you could let the customer know and then provide other options (like escalation or another attempt to book).

• Utilize response headers: Let’s say the response contains the following headers:

  • 1 2 X-RateLimit-Remaining: 150 X-Request-ID: abc123

  • You could use the X-Request-ID header in a subsequent web request for tracking purposes. For example, if you wanted to log or verify the transaction in another system, you could set up another send web request step that includes the X-Request-ID in its headers to allow your team to track these actions across different systems. Below is a request example for subsequent web request:

    1 2 3 4 { "action": "logTransaction", "requestId": "{{bookingResponse.headers.X-Request-ID}}" }