Call a web service

Use the Call a web service action A tool for building the processes, logic, and direction within workflows. to make HTTP requests and API calls. You can output the response content, response headers, and response status code as variables. The response content is returned in JSON format.

For example, let's say you have a change management workflow for business processes, and those business processes also have corresponding workflows. When a business process (and therefore a workflow for that business process) requires a change, someone fills a Nintex form to request the change which kicks off the change management workflow.

When a change to the business process is approved in the change management workflow, the Call a web service action makes a HTTP post request to the Nintex platform API, which deactivates the workflow for the business process which requires the change. The workflow designer can then make the required changes to the workflow without any new instances of the workflow running. See Step-by-step example: Make an HTTP Post request to Nintex Automation Cloud to deactivate a workflow

Another example to use the Call a web service action is to retrieve current weather information of a specific city by making an API call to a third-party API platform such as OpenWeatherMap. See Step-by-step example: Make an API call to the OpenWeatherMap API to retrieve weather information.

Before you begin:

In the simplest form possible, a web service can be defined as a means of communication between two machines over a network, exchanging machine-readable file formats such as JSON.

In Nintex Automation Cloud, you can integrate web services in your workflows by using the Call a web service action. For example, you have a workflow that requires retrieving the current weather information of a specific location. By using a third-party API platform such as OpenWeatherMap, you can access current weather data to fulfill your workflow requirements. See Step-by-step example: Make an API call to the OpenWeatherMap API to retrieve weather information.

For more information about web service, see Web Service wiki.

JSON is JavaScript Object Notation, a flexible syntax for storing textual information in a structured way. It is one of the primary standards for transmitting information across the internet.

JSON is built of:

  • Key-value pairs, where a key is matched by a colon to a specific value, like "title" : "Gone with the Wind".
  • Objects, where multiple key-value pairs are grouped together as a unit between a set of curly braces {}.
  • Arrays, where a set of objects or key-value pairs are grouped into a list between a set of square brackets [].

Objects and arrays can be nested inside of each other, creating an extremely flexible data structure:


{ 
  "products": {
    "food": [ 
      { 
        "category": "fruit",
        "name": "apple",
        "type": "Red Delicious",
        "price": 2.95
      },
      { 
        "category": "deli",
        "name": "fish",
        "type": "salmon",
        "price": 7.99
      }
    ],
    "homewares": {
      "item" : "towel",
      "color": "blue",
      "size" : "bath",
      "price": 12.95
    }
  }
}

Jump to:

Configure the Call a web service action

  1. Add the action to the workflow and open the action configuration panel. For more information, see Add an action to the workflow.

  2. In URL, type your request URL or select a variable that holds your request URL.
  3. Select a Request type.
  4. In Request headers, type your request headers or insert a variable that stores the headers of your HTTP request.
  5. In Request content, type your request content or insert a variable that stores the content of your HTTP request.
  6. Select or create variables for Response content, Response headers, and Response status code. You can use these variables later in your workflow.

    7. Note: You can use the Response content variable in a Query JSON action to extract information from the response content. See Query JSON for more information.

The following example deactivates a published workflow to prevent it from running.

Note: Use the Deactivate a workflow reference in the Nintex platform API documentation alongside these configuration steps.

In the Designer page:

  1. Add the Call a web service action to the workflow and open the action configuration panel. For more information, see Add an action to the workflow.

  2. Copy and paste the following POST URL in the URL field:
    3. Copy 
    https://us.nintex.io/workflows/v1/designs/workflow_id/deactivate
    • workflow_id: Unique identifier of the workflow that you want to deactivate. You can find this ID as one of the workflow instance variables of your workflow. From the toolbar, click Variables > Context > Workflow ID. See Workflow instance variable for more information.

    Note: This POST URL is listed In the Deactivate a workflow reference in the Nintex platform API documentation.

  3. Select HTTP Post for the Request type.
  4. Type the following in the Request header field:
    5. Copy 
    accept: application/json
authorization: bearer <personal access token>
content-type: application/json
    • personal access token: Token used to authenticate calls made to your Nintex Automation Cloud tenant. On the top navigation bar of your Nintex Automation Cloud tenant, click Settings > Apps and tokens. See Apps and tokens for more information.

This example retrieves the current weather information of a city you specify in the GET URL. The response content of the API call is returned in JSON format.

Note: Use the OpenWeatherMap APi guide alongside these steps.

  1. Add the Call a web service action to the workflow and open the action configuration panel. For more information, see Add an action to the workflow.

  2. Copy and paste the following URL into the URL field.
    3. Copy 
    https://api.openweathermap.org/data/2.5/weather?q=‍Location&APPID=AppID
    • Location: the city where the current weather information will be retrieved.
    • AppID: the API key provided when you sign up for an OpenWeatherMap account. This API key allows you authenticated use of OpenWeatherMap APIs.
  3. Select HTTP Get for the Request type.
  4. In Response content, select or create a variable to hold the response content of the API call.

    5. Note: You can use this variable in a Query JSON action to extract information from the response content. For example, you want to extract the Weather description, which is shown in the following code as "scattered clouds", use the variable as the JSON source and then type $.weather[0].description as the JSONPath expression. See Query JSON for more information.

    The following code is an example of a response from an OpenWeatherMap API call about the weather of London at a specified time:

    {
    "coord": {
      "lon": -0.13,
      "lat": 51.51
    },
    "weather": [
        {
          "id": 801,
          "main": "Clouds",
          "description": "scattered clouds",
          "icon": "02d"
        }
      ],
      "base": "stations",
      "main": {
          "temp": 281.62,
          "pressure": 1023,
          "humidity": 71,
          "temp_min": 278.71,
          "temp_max": 284.82
      },
      "visibility": 10000,
      "wind": {
          "speed": 3.1,
          "deg": 230
      },
      "clouds": {
          "all": 18
    },
      "dt": 1567405267,
      "sys": {
          "type": 1,
          "id": 1414,
          "message": 0.0113,
          "country": "GB",
          "sunrise": 1567401255,
          "sunset": 1567450013
      },
         "timezone": 3600,
         "id": 2643743,
         "name": "London",
         "cod": 200
}

Call a web service action fields and selections

Field

Description

Variable
URL

Uniform Resource Locator (URL) used to call a web service. Accepts any combination of typed text and inserted variables.

 Text, Decimal, Integer, Boolean, DateTime
Request type

The method of HTTP request to be performed on an identified resource.

  • HTTP Get: requests to retrieve data.
  • HTTP Put: requests to store an entity under the supplied URI (Unified Resource Identifier).
  • HTTP Post: requests that the server accept your data.
  • HTTP Patch: requests to apply partial modifications to a resource.
  • HTTP Delete: requests to delete a specified resource.

Learn more about HTTP request methods.

n/a
Request headers HTTP header to be used in the request. The HTTP header does not relate to the content of the message and only provides additional information about the request or itself to the server. Accepts any combination of typed text and inserted variables. Text, Decimal, Integer, Boolean, DateTime, Collection
Request content The message content of your HTTP request. Accepts any combination of typed text and inserted variables. Text, Decimal, Integer, Boolean, DateTime, Collection

Response content

Content of the server's response. Accepts an inserted variable.

 Text, Decimal, Integer, Boolean, DateTime

Response headers

Headers of the server's response. Accepts an inserted variable.

Text

Response status code

Code that indicates the result of the HTTP request. It is issued by the server in response to a client's (i.e. your) request. Accepts an inserted variable.

Learn more about the different types of status codes.

Text, Integer