How to execute a SP2013 REST API request with Nintex Workflow

cju
Scout
45 91 81.5K

How to execute a SP2013 REST API request with Nintex Workflow

With all the Nintex Workflow actions, we can achieve lots of great workflows. Sometimes, we'd like to build more complicated, technical, reusable workflows. For these workflows, we need more actions and possibilities that can be achieved by calling SharePoint ASMX web services or SP2013 REST API requests.

As the ASMX web services are deprecated in SharePoint 2013 and SharePoint Online, it is recommended to use SP2013 REST API instead when it is possible (not all functionalities of the ASMX web services are available in SP2013 REST API).

I'd like to help you building your SP2013 REST API requests.

There are two categories of SP2013 REST API requests :

  • POST : to update, create or remove information in SharePoint,
  • GET : to retrieve information from SharePoint.

The process to execute these two types of requests is different.

How to execute a GET request

To execute a GET request, a "Web request" action only is needed. The configuration of the action should look like this :

REST_API_Request_GET.png

It is possible to select a text variable in the "Store result in" field to get the response of the request and then use a "Query XML" action to extract the information needed.

How to execute a POST request

The execution of a POST request is more complex. A request digest is first needed in order to pass the security information to the server when sending the POST request.

To get the request digest, the following "Web request" action should be executed :

REST_API_Request_Digest.png

A text variable has to be selected in the "Store result in" field.

Then the request digest has to be extracted from the response of the request.

To extract this information, a "Query XML" action has to be configured to execute the following XPath query :

//*[local-name()='FormDigestValue']

QueryXML_extract_request_digest.png

Once the request digest is stored in a variable, it is possible to execute the POST request via a "Web request" configured like the following :

REST_API_Request_POST.png

Example : How to update a list item using REST API

Before executing the POST request used to update a list item, the request digest and the list item entity type full name are needed.

To get the request digest, follow the steps explained above.

To get the list item entity type full name, execute the following "Web request" action (where "txtListName" is the title of the list where the list item to update is) :

rest_api_get_listitementitytypefullname.png

The next step is to extract the list item entity type full name from the response of the above request using the following XPath query :

//*[local-name()='ListItemEntityTypeFullName']

The last step is to execute the POST request with the following "Web request" action (where "numID" is the id of the item to update) :

rest_api_update_item.png

I hope that this will help the community !

Caroline Jung

91 Comments
cju
Scout

Sorry I haven't read the last version of your post .

Have you tried to get and then upload the file content using this web request:

http://site url/_api/web/lists/getbytitle('list title')/items(item id)
/AttachmentFiles('file name')/$value
leannarh
Novice

Thank you for the quick response, Caroline. I think I am getting close with the documents you have sent me, but I am really new to REST (I hadn’t even heard of it before last Friday). How do I “translate” this into the Web Request action of a Nintex workflow? How do I get “content-length”?

cju
Scout

Actually this web request works without "content-length" header.

Do you use Nintex for O365 or for SharePoint?

leannarh
Novice

We are using Nintex for SharePoint.

I used the links you sent to retrieve the attachment using the /$value, and saved it to a string variable. When I tried to do the POST Web request using that variable and the /$value, it gave me an error that the Uri string is too long. When I retrieve the attachment, should I be saving it to a string variable or doing something else with it when it is returned?

I can’t tell you how much I appreciate you helping me with this. Thank you!

cju
Scout

If you get an error regarding a too long url, then you need to increase the maxUrlLength attribute of httpRuntime element in the web.config of the SharePoint web application executing your workflow (if the workflow is scheduled it's the

OWSTIMER.EXE.config instead of the web.config): https://msdn.microsoft.com/en-us/library/e1f13641(v=vs.100).aspx.

The string variable should be ok to store the attachment content.

Hope this helps

damienveler
Novice

Hey,

Thanks a lot for this post.

Any idea to call a API with a OAuth authentication ?

Thanks,

Damien

cju
Scout

Hi Damien,

Here's a link to a blog that can help you on that:

https://community.nintex.com/community/build-your-own/nintex-for-office-365/blog/2017/02/09/working-...

Hope this helps

kjhawkins
Novice

Caroline, I have read this thread with great interest.  I've have been trying to get the "accept-language" header value in workflow using the Web Call action with no success.  We need to use the result to set the language for labels on task forms and notifications.  I must be missing something simple.  My response contains no reference to the "accept-language" header.

Any suggestions?

-Ken

cju
Scout

Hi Ken,

It seems that SharePoint REST API calls don't return any accept-language header.

What do you want to do exactly? Maybe we can find a workaround...

kjhawkins
Novice

Thanks Caroline, but we decided to scrap the function involved.

Regards,

Ken

rashmikoti
Novice

Hi Caroline,

Thank you for the nice blog. I have followed all the steps to update a document in library. The REST API call to fetch the item  was excuted without any error. But I don't see that column s are updated. No error in the logs as well.

The body looks like as follows. None of the column is updated.

 '__metadata' : { 'type' : '{WorkflowVariable:ListName}'},
     'Textcolumn' : 'Complete',
'choicecolumn' : 'No',
'Date Column' : '{Common:CurrentDate}'
}

Any help?

cju
Scout

Hi Rashmi,

Can you share the url that you're using to perform the request?

rashmikoti
Novice

Hi Caroline,

I am looking for help to understand the chekcout, update and checkin REST API calls for a document in the document library.

1. I want to know how do we overide the checkout. I am using a site collection workflow. Does the just checkout REST API call will override the checkout?

2. I am checking out the document and updating the metadata using update REST API and checkin using REST API.

But I don't see the meta data is getting updated.

If I use only UPDATE REST API without any checkout and checkin, it works - metadata gets updated

Any idea about this behavior. What should I be doing to update the metadata along with checkout and checkin. I should be able to update the document from the workflow even if it is already checked out.

Thanks

Rashmi

cju
Scout

Hi Rashmi,

Unfortunately, I haven't worked so far with check-in and check-out REST API calls.

I'm afraid I can't help you a lot with that.

Did you finally get a solution?

rashmikoti
Novice

Hi Caroline,

I was able to resolve the check out and check in requirements using REST API calls. Here is the example for the REST API URL,

Checkout -

{WorkflowVariable:WebURL}/_api/web/GetFileByServerRelativeUrl('/sites/WorkflowVariable:ServerRealtiveURLofPage}')/CheckOut()

Update Item by REST API

Checkin - {WorkflowVariable:WebURL}/_api/web/GetFileByServerRelativeUrl'/sites/WorkflowVariable:ServerRealtiveURLofPage}')/CheckIn(checkintype=1)

cju
Scout

Great

Thanks for sharing this !

akramt
Novice

Hi Caroline,

I'm getting an issue during GET operation stating : Workflow Status

Error performing web request. The underlying connection was closed: An unexpected error occurred on a send.

Below is the screen shot of the configuration which I did to achieve the same.

Please let me know what I'm doing wrong here.

Regards,

Akram

cju
Scout

Hi Akram,

I think that this error is related to server/network configuration. If you try to execute this request directly from the SharePoint server, I think that you will get the same error.

Does the SharePoint farm have multiple front servers? If yes, is there a load balancer?

The better way to solve this issue is to check with an administrator in the event viewer of the SharePoint server if there are more details.

Hope this helps,

Caroline

mariofialho
Novice

Hi Caroline,  I am working on a web request to the REST API that will update a Hyperlink Column.  I went through all of the steps that both you and Tomasz laid out SAML Request, Response Message, but there's no BinaryRequestToken element in the response.  

SAML RESPONSE

SAML RESPONSE

So I tried grabbing the innerXML from the X509SKI element instead.  Sent that in and get the Response Headers back.  The I log them all out to find the Cookie Header (which accoring to Tomaz is Index Item #6) and it's not there. Is this solution still valid?

 

Thanks,

Mario

cju
Scout

Hi Mario,

I'm afraid I can't help with that but I'm sure that ‌ can

TomaszPoszytek

What env. are you working in? I see a SPO term in your screenshots, so possibly this is O365

This is not a BinaryRequestToken, but BinarySecurityToken:

Try to post your SAML Request Security Token using Postman for example, to see the response. I just did it and I've been received that token.

Also using Postman you will have the possibility to preview, whether this way of authentication is even allowed - I have access to three tenants, on two of them this is disallowed. Possibly because of some policy settings or MFA.

Regards,

Tomasz

mariofialho
Novice

Thanks Tomasz,

The client has a dedicated Office 365 tenant and they indeed have MFA enabled. Thanks for the reply I will pass this along.

Mario

vijay_kampu
Novice

Hi Caroline,

I need your help please. I wanted to update the datefield, but its throwing some error

{
"__metadata": { "type": getItemTypeForListName(listName) },
"Title": "firsdt",

"ApplicatinDate" : "{ItemProperty:ApplicationDate}"

}

i tried converting iso format and assign it, but in vein

{
"__metadata": { "type": getItemTypeForListName(listName) },
"Title": "firsdt",

"ApplicatinDate" : "{WorkflowVariable:ISOConvertedDate}"

}

getting below error

Error performing web request. <?xml version="1.0" encoding="utf-8"?><m:error xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"><m:code>-1, Microsoft.SharePoint.Client.InvalidClientQueryException</m:code><m:message xml:lang="en-US">I

Pelase suggest to me how to save date field and person or group

vijay_kampu
Novice

Url i am using is : 

Web URL/_api/web/lists/getbytitle('txtListName')/items

I am able to save other fields except date and person group

cju
Scout

Hi Vijay,

Can you send me the complete error message? In the workflow, you can send you an email with the error message in the body and set the body to be in plain text instead of rich text.

To update a date column, the json should look like this :

'StartDate':'2014-01-29T08:00:00Z'

Can you send me the value of the variable "ISOConvertedDate"?

vijay_kampu
Novice

Thank you , there was a syntax error

cju
Scout

I'm glad that you could solve your issue

cholslin
Apprentice

This is a fantastic article and should be bookmarked in every SharePoint developer's Nintex Community profile. Thanks for the guidance, Caroline!

cju
Scout

Thanks for the comment Christian ! I'm glad if this article can help

amiri_b
Novice

Dear Caroline Jung‌, I need your help.

I 'm using REST API to add permission to a user on an item within a list. I have successfully removed the inheritance with a post request to :

https://URL/ts/_api/web/lists/getByTitle('Timesheet Reports')/items(32)/breakroleinheritance(copyRoleAssignments=true,clearSubscopes=true)‍

However, when I try to add new item level permission to the item with the bellow context:

https://URL/_api/web/lists/getByTitle('Timesheet Reports')/items(32)/roleassignments/addroleassignment(principalid=9;roledefid=1073741826)

‍‍

where principalid=9 is the "ID" for the user (not group) retrieved from :

https://URL/_api/web/siteusers

 

I'll get the bellow error in response :

This XML file does not appear to have any style information associated with it. The document tree is shown below.
<m:error xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<m:code>
-1, Microsoft.SharePoint.Client.InvalidClientQueryException
</m:code>
<m:message xml:lang="en-US">
The expression "web/lists/getByTitle('Timesheet Reports')/items(32)/roleassignments/addroleassignment(principalid=9;roledefid=1073741826)" is not valid.
</m:message>
</m:error>‍‍‍‍‍‍‍‍‍

Please advice.

Updates >>

Issue was related to bad syntax. I was using ; instead of ,

kmccool
Scholar

I'm using PowerShell to get the list of items that haven't been modified in a while and emailing the last modifier asking them if they want to delete stale items. (We're doing a massive SharePoint cleanup project)

I would like a workflow to delete the item using the web request POST action but am troubleshooting atm.

Is it normal to have the date/time stamp on then end of my Digest Value?

Thanks

Kassie

amiri_b
Novice

Dear Kassie,

Digest value always ends with a time stamp, and the timestam is usually half an hour valid.

Your problem should be somewhere else.

kmccool
Scholar

Ok, thanks to this post, I've got the auto delete working with the web request for our SharePoint cleanup project.

Now I need to move items to an archive library if the user selects to send the document to records. Is there a method I could use to move a document to the archive list? I would use the copy action but these items are all housed in different library locations on the site collection, they are just listed on this clean up list.  

Any ideas for me?

Thanks

Kassie

amiri_b
Novice

Dear Kassie McCool‌, if you mean the list in which it's items should cleaned up, contains document address, then you could simply read the address in workflow (with a variable) and use it in the copy action to copy it to the archive library. then simply delete the document from the original library.

then your workflow should have this actions in order:  ( I couldn't take snapshots so I just type the logic  )

Run If (condition should be "if the user selected the archive option")

Set Variable (read the address in a variable)

Copy Item (Copy the item with the address in variable as source to archive destination library)

Delete Item (use variable as source to delete the Source Item)

}

kmccool
Scholar

Thanks for the reply behy.

I'm on 2013 on prem. Not sure if we're on different versions, but my Copy item action does not allow me to customize the source value with a variable value.

Or are you saying to use these methods in my web call?

Thanks

Kassie

amiri_b
Novice

You're right Kassie McCool‌, variable is not an option. also you're not able to copy/paste items across sites. you're only able to do that within the same site.

is it in the same site? I mean source and target.

kmccool
Scholar

They are on the same site. I was kind of hoping to do this as a web request. I found some info on SharePoint folder moves but I don't want to move a folder, just a document.

Here's what I have so far. I popped off the folder portion of the syntax but it isn't working yet.

https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee658974(v=offic...

I'm sure I'll get there. Just have to keep working on it.

thanks

Kassie

kjhawkins
Novice

I don't know if it will help in your case, but here is what I have used to move a document within the same library:

kmccool
Scholar

Thanks for the reply Ken.

This is getting me pretty close. I found almost the same solution from Vadim Tabakman‌'s blog post here and added a header as he suggested.

I am still having trouble getting it to work. I'm getting an error in my result, "Error performing web request. The underlying connection was closed: The connection was closed unexpectedly." After reviewing the error logs, I found this error: "Catastrophic failure (Exception from HRESULT: 0x8000FFFF (E_UNEXPECTED))"

I'm not the admin for our server so I have little troubleshooting ability from that side.

If there's any advice you could give on how to get this up and running I would appreciate it.

Thank you

Kassie

 

emmmhaa
Scholar

Hi Caroline,

I want to update a date field. I copied and changed a working web request to update users in the same workflow.
The result is a 400 Http status.
Do you have any idea what I am doing wrong?
Here is a log extract:

Message body: {'__metadata':{'type':'SP.Data.Dokumente_x0020_TR_x0020_HFItem'},'wf_TR_DBearbeiterStart':{'results':[2019-06-07T00:00:00Z]}}

varDBearbeiterStartResult: 400

 

Best regards Micha

emmmhaa
Scholar

Solution: {'__metadata':{'type':'SP.Data.Dokumente_x0020_TR_x0020_HFItem'},'wf_TR_DBearbeiterStart':'2019-06-11T00:00:00Z'}