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. 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: 

• Understand Variables

• Learn about Handling files in your workflow

What is a web service?

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.

What is JSON?

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

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

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

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

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.

3. In URL, type your SharePoint URL or select a variable that holds your request URL.
4. Select a Request type.
5. In Request headers, type your request headers or insert a variable that stores the headers of your HTTP request.
6. 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:

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.

   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.

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.

      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:

   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.

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:

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:
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:
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.

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

Accept: application/json;odata=verbose

Content-Type: application/json;odata=verbose