SharePoint Online - Call a SharePoint web service

Use the SharePoint Online - Call a SharePoint web service action A tool for building the processes, logic, and direction within workflows. Actions are the steps the workflow performs to complete a process. to make REST API calls to SharePoint Online. You can configure the action to return the response content in an output variable. The format of the response header is always JSON, whereas, the response content can either be JSON or XML, depending on the configuration of the request headers.

For example, if your workflow requires retrieving information about a SharePoint Online list item, the SharePoint Online - Call a SharePoint web service action makes a HTTP Get request to SharePoint Online through the SharePoint platform API. SharePoint then returns details about the specified SharePoint Online list item. See Step-by-step example: Make a HTTP Get request to retrieve information about a SharePoint Online list item and extract a property.

You may also want to update a list item in a SharePoint Online list; the SharePoint Online - Call a SharePoint web service action makes a HTTP Post request to SharePoint Online through the SharePoint platform API. SharePoint then updates the list. See Step-by-step example: Make a HTTP Post request to update the title of a SharePoint Online list item.

For more information about the SharePoint Online connector, go to SharePoint Online.

Note: The Call a SharePoint web service action is a generic action and there is no error handling. Instead, any error response content is passed to the action output. It is recommended that you design an error handling process around this action when using it. For example, delayed retries to handle the 429 Too Many Requests error.

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 SharePoint Online - Call a SharePoint web service action

The steps required to configure the action are given below. The required and optional configuration fields are described in the SharePoint Online - Call a SharePoint web service action fields and selections.

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

  2. Select a Connection. If you do not have a connection, see Add a connection.

    Note: 

    Only the connections created with the List and libraries authentication method are available in the drop-down list.

    For more information about authentication methods for SharePoint Online connections, see Authentication methods for SharePoint Online connections.

  1. In URL, type your SharePoint URL or select a variable that holds your request URL.
  2. Select a Request type.
  3. In Request headers, type your request headers or insert a variable that stores the headers of your HTTP request.
  4. In Request content, type your request content or insert a variable that stores the content of your HTTP request.

Step-by-step example: Make a HTTP Get request to retrieve information about a SharePoint Online list item and extract a property

This example retrieves the information about a SharePoint Online list item and extracts a property from SharePoint's response content. We will use the Query JSON action to extract the property value from SharePoint Online - Call a SharePoint web service's JSON-based output. To verify the retrieved information, we will add Log to instance details actions to the workflow.

In the Designer page:

  1. Add the  SharePoint Online - Call a SharePoint web service action to the workflow.
  2. Select or create a Connection.
  3. In URL, type your SharePoint URL or select a variable that holds your request URL, using the following format:
    4. https://SharePoint URL path/_api/web/lists('List ID')/Items(Item ID)

    For example:

    https://anyname.sharepoint.com/sites/foldername/_api/web/lists('ab12345c-d123-456e-f78a-9012bc34567d')/Items(1)
  4. In the Request type field, select HTTP Get.
  5. In the Output section, click the Result field to add a variable.
    1. In the Insert variables panel, make sure SharePoint Online is selected, and then click Create variable.

      2. The Create variable panel appears.

    2. In the Name field, type SPGetOuput.
    3. Click Create & Insert.
  6. Use the default Request header displayed in the Request header field.
    7. Accept: application/json;odata=verbose
    Content-Type: application/json;odata=verbose
  7. Add the Log to instance details action to the workflow, and configure the action:
    1. In the Message field, click Insert to insert a variable.
    2. In the Insert variables pane, click SharePoint Online.
    3. Expand SPGetOutput.
    4. Insert Response content.
  8. Add the Query JSON action to the workflow, and configure the action:
    1. In the JSON source field, insert a variable from the SharePoint output.
      1. Click Insert.

        2. The Insert variables panel appears.

      2. Click SharePoint Online, and then expand SPGetOutput.
      3. Insert Response content.
    2. In the JSONPath Expression field, enter the following code:

      3. Copy

      $['d']['__metadata']['type']
    3. In the Store first result field, add a variable called itemType.
  9. Add the Log to instance details action to the workflow, and configure the action:
    1. In the Message field, click Insert to insert a variable.
    2. In the Insert variables pane, click Workflow.
    3. Insert itemType.
  10. Publish the workflow and check the result in the Instances page.

    11. The output for the first Log to instance details action should show the retrieved details about the SharePoint list item that you specified in the URL. The second Log to instance details action should show the value of the property that is extracted from the Response content. You can further add more actions to your workflow to use or modify the retrieved details.

    For information on the format of the URL path, request headers, or request content, see the Microsoft SharePoint API documentation.

Step-by-step example: Make a HTTP Post request to update the title of a SharePoint Online list item

This example updates the title of the first item in a SharePoint Online list.

In the Designer page:

  1. Add the  SharePoint Online - Call a SharePoint web service action to the workflow.
  2. Select or create a Connection.
  3. In URL, type your SharePoint URL or select a variable that holds your request URL, using the following format:
    4. https://SharePoint URL path/_api/web/lists('List ID')/Items(Item ID)

    For example:

    https://anyname.sharepoint.com/sites/foldername/_api/web/lists('ab12345c-d123-456e-f78a-9012bc34567d')/Items(1)
  4. In the Request type field, select HTTP Post.
  5. In the Request headers field, enter the following headers:
    6. Copy 
    Accept: application/json;odata=verbose
    Content-Type: application/json;odata=verbose
    If-Match: *
    X-HTTP-Method: MERGE
    Note: 

    • For the If-Match property, we'll use "*" to match and update any version of the specified list item. The version of the list item would no longer be checked. For more information on using If-Match, see the If-Match documentation.

    • X-HTTP-Method is included only in requests that use HTTP Post to perform other operations, such as Merge, Delete, or Put. For more information, see the Properties used in REST requests.

  6. In the Request content field, enter the following payload:
    7. Copy 
    {
    "__metadata":
    {
    "type": "List item type"},
    "Title": "UpdatedTitle"
    }

    Note: List item type depends on your SharePoint Online list. For example, "SP.Data.TestListItem".

  7. Test or publish your workflow, and check your SharePoint Online list.

    8. The title of the first item in the list should be displayed as UpdatedTitle.

    For information on the format of the URL path, request headers, or request content, see the Microsoft SharePoint API documentation.

 

SharePoint Online - Call a SharePoint web service action fields and selections

Section

Field

Description

Variable
Unlabeled

Connection Credentials and other settings that enables workflows to communicate with external systems, services, or applications. It's required to pass data between the workflow and the indicated service, which could be a cloud service, business application, or content store.

The SharePoint Online connection to use.

To refresh the available connections, click .

 (n/a)
  URL

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

For example:

https://anyname.sharepoint.com/sites/foldername/_api/web/lists('ab12345c-d123-456e-f78a-9012bc34567d')/Items(1)

For more information on constructing REST URLs to access SharePoint resources, see the Microsoft SharePoint API documentation.

 Text, Decimal, Integer, Boolean, DateTime
  Request type

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

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

For more information, see the HTTP commands with the SharePoint REST service. 

 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.

A default value is provided in the Request headers field. JSON is used in the Accept and Content-Type properties, by default, but you can also change it to XML.

Accept: application/json;odata=verbose
Content-Type: application/json;odata=verbose
 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
Output Result

Stores the result of the action as an object with the following variables:

  • Response status code: Integer variable that contains the HTTP response status code.
  • Response status code description:Text variable that contains the description of the HTTP response status code.
  • Response headers: Text variable that contains the headers of SharePoint's response.
  • Response content: Text variable that contains the content of SharePoint's response.
 Object