gonzalo.marcos@nintex.com

Using the Office 365 REST API to create lists from your Nintex Workflow

Blog Post created by gonzalo.marcos@nintex.com on Aug 9, 2018

The Office 365 REST API provides a very useful way to interact with SharePoint data from any system able to create REST API requests. And one of those systems is our beloved Nintex Workflow for Office 365. In this post, we'll see how to use the Office 365 REST API to create SharePoint lists from a Nintex Workflow.

As in every REST API request, the first thing you need to do is to have a look at the reference documentation of that API, to understand the list of requests available and the values you need to provide for those requests. In our case, you can start with the SharePoint REST API documentation in this link.

Now, let's focus on the request we want to create. The following example, taken from the previous link, shows how to create a list:

 

 

With that, we know exactly all the information we need to get for our request. Creating a RESTful HTTP request in Nintex Workflow is easy if we know how to get that information, we just need to go through these 5 steps:

  1. Create the Workflow variables
  2. Build the Dictionary Variables
  3. Set the End Point URL
  4. Create the Web Service Call
  5. Parse the Response received

Those steps lead us to the following Workflow Design:

Let's go step by step and see it in more detail for our example:

 

1. Create the Workflow Variables

We will create Dictionary variables for the Headers and the Body of the request and response. We also need variables for the Endpoint URL of the API resource and the Status Code of the response we'll get from our request. The metadataObject variable is a Dictionary that we need for an object to be included in our Request Body (we'll see it later in this post).

 

 

2. Build the Dictionary Variables

  • Request Headers: 

     In our example we need to create headers for Accept and Content-Type to specify JSON as the format we'll be sending the request and the format we want to get the response. The rest of the Headers are not needed for a request coming from the workflow.

     

 

  • Request Body: 

     

    In this Dictionary variable, we just need to provide the key-value pairs that specify the title and description of our new list. What is very handy in here is that these values can be dynamic and we can, as in this example, pick up the values from an initial form. We can also specify the list template to use with the BaseTemplate parameter. In this linkyou can find the list of Template IDs. In my example, I'm going to go for a Document Template and provide the ID = 101

 

 

Notice that the first key-value pair, __metadata, is defined as an object in the API Reference Documentation. That's why we need, in a previous step, define another Dictionary variable, which I called metadataObject, and use it in the Request Body Dictionary. Here's how we define the __metadata object:

 

 

  • Response Body: 

    For the response body, we don't have to build the Dictionary. This variable will be where we'll be storing the JSON object of the response.

 

3. Set the End Point URL

My recommendation, when building up REST API requests in a workflow is to create a workflow variable for the URL of the end point we're making the request, especially if the URL will contain dynamic values for the base URL, path and query parameters. And that's the case of our example with the RequestEndPoint variable. So, drag and drop a Set WF variable action to the canvas and use the Workflow Context on the right-hand side to pick up the URL of the Current site. After that, add the rest of the URL manually, as in the picture below:

 

4. Create the Web Service Call

At this point of our design, we've got all the elements needed to create our RESTful HTTP request. So, drag and drop the Call HTTP Web Service action and use the variables we've set up for the different parameters of the action. Make sure you choose POST as the HTTP method of your request. Your action should look like this:

 

 

5. Parse the Response received

I'm not including it in this workflow design, but after our web service call, we could include more actions to parse the values received in our ReponseBody Dictionary variable. That would be useful to check if our call was successful or to retrieve values like the list URL created. But I'll leave it to you to complete it.

 

So, as you can see, using the Office 365 REST API is not that difficult if you understand well the information you need for your request. I really encourage you to explore it and see what you can do from your Nintex Workflows. Hope it's been useful!

Outcomes