SharePoint Designer 2013 Workflows and POST REST API

Following on from my last post of using GET REST API in workflows, this post will show how you can create an item in a list using the POST REST API.

Creating a list Item using REST API.

Using the same list as before, on my SharePoint site, I have a list. The list is nothing special, it’s just an example of some data.

Title: String
Person: User field
Colour: Choice field

You wouldn’t do this in real world scenario, but my demo will demonstrate when you run the workflow on any item, it will just create a new item in the list.

A better real world scenario might be when an item is added to this list, some of the information needs to be copied and created in another list, or when an item is changed a workflow fires to copy the information to another list similar to a history list.

Creating the workflow

In SharePoint Designer, I have gone to my list, and created a new workflow.

• First, we need to add a Dictionary Item. This is so we can create a header for our HTTP Call. Type in “Dictionary“
  and then in the options to choose from select Build Dictionary.
  
  Click on “this”.
  
  A dialog will appear, and it is here we need to add two headers.

Name	Type	Value
accept	String	application/json;odata=verbose
content-type	String	application/json;odata=verbose

Click on Variable:dictionary, and create a new variable called Headers.

• We need to create another Dictionary now, this is to store the “type”. When you create an item with REST API, you need to provide the __metadata with the ListItemEntityType. Typically this item is SP.Data.[ListName]Item. However, to be absolutely sure, you can use this REST API call in the browser to find out.

   

  https://<tenant>/sites/<Site>/_api/web/lists/getbytitle('	<listTitle>')/ListItemEntityTypeFullName
  

Name	Type	Value
type	String	SP.Data.DemoListItem

• One more dictionary needs to be created, this is the RequestContent for the POST Call.

Name	Type	Value
__metadata	Dictionary	Variable:EntityType
Title	String	New Item
Colour	String	Blue
PersonId	String	Current Item:Created By (return field as: User Id Number)

When you create this, ensure that __metadata has 2 underscores in front of it.
All fields are the internal names.

User fields all have an Id field with it, in my case the Person field has a PersonId field, it is this that I set with another User Id.

Choice fields just accept a valid string.

Taxonomy fields are a little different, see section below.

• Now we can call a HTTP web service. Underneath the dictionary, start typing “http” and press enter to insert Call HTTP Web Service.
  Click on “this” to open up the dialog box, and then click on the … for the string builder dialog box.
  
  I like to use as much dynamic values as possible so my URL in here looks like the following:

  [%Workflow Context:Current Site URL%]/_api/web/lists/getbytitle('[%Workflow Context:List Name%]')/items
  

  Set the HTTP method to HTTP POST.
  

  After entering the URL and setting the Method, click the dropdown at the far right on the line in SPD and select properties. Set the RequestHeaders to the Dictionary Variable:Headers you made in the first step. Set the RequestContent to the dictionary Variable:NewItemMetadata. Set the ResponseContent to a new variable, and the ResponseStatusCode to a new variable. Click OK.
  

  The ResponseContent will be populated with the results, and the ResponseStatusCode will be populated with Created if successful, or a different value if something went wrong.

• After the Web service call, I add an If Statement, to test that the variable responseCode equals to Created.
  
• I log success to the history list.
• In the else statement of if “responseCode equals Created” I grab the error message from the ResponseContent dictionary and output the value to an error message. Then I display the error message in the history list. To grab the error the dictionary path is error/message/value

  

• Don’t forget to Transition to Stage “End of Workflow” at the end.

  

Publish your workflow.

When I run the workflow against any list item, after a moment a new entry is added to the list.

Updating Taxonomy/managed metadata column in POST REST API calls.

To be able to update a Taxonomy column in a list you would need to create the following 2 dictionary’s first, then assign 2^nd dictionary to the column.

TaxonomyMetadata Dictionary

Name	Type	Value
type	String	SP.Taxonomy.TaxonomyFieldValue

TaxonomyValue Dictionary

Name	Type	Value
__metadata	Dictionary	TaxonomyMetadata Dictionary
Label	String	<Label value>
TermGuid	String	<TermGuid>
WssId	String	-1

<Label Value> – the actual value of the taxonomy term
<TermGuid> – The guid of the taxonomy term found in the termstore.
The WssId can always be -1 as SharePoint can work that out itself, but it requires a value.

PostRequestContent

Name	Type	Value
__metadata	Dictionary	Variable:EntityType
Title	String	New Item
<TaxonomyColumnInternalName>	Dictionary	Variable:TaxonomyValue Dictionary

It is the final dictionary above that you would set in the web service call as the RequestContent.

SharePoint Designer 2013 Workflows and GET REST API

SharePoint Workflows have been around for a long time, and with Microsoft flow now firmly taking hold the need for SharePoint workflows might be less. However, I recently had to work with SharePoint Workflows and learnt a few things around using REST API and I wanted to share my knowledge.

Reading a list/Item using REST API.

On my SharePoint site, I have a list. The list is nothing special, it’s just an example of some data.

Title: String
Person: User field
Colour: Choice field

All I’m going to do in the workflow, is when it is run, it will grab the items in the list, and then display the results in the history list. The point of this demo is to show how to make REST API calls and grab/loop through data.

Creating the workflow

In SharePoint Designer, I have gone to my list, and created a new workflow.

• First, we need to add a Dictionary Item. This is so we can create a header for our HTTP Call. Type in “Dictionary“
  and then in the options to choose from select Build Dictionary.
  
  Click on “this”.
  
  A dialog will appear, and it is here we need to add two headers.

Name	Type	Value
accept	String	application/json;odata=verbose
content-type	String	application/json;odata=verbose

Click on Variable:dictionary, and create a new variable called Headers.

Because SPD is a pain, it has already created a variable called dictionary, if you click on Local Variables from the ribbon, you can delete this variable. This will ensure you keep only the variables you are using within your workflow and save confusion later. Always give your variables sensible names, just as if you were writing code.

• Now we can call a HTTP web service. Underneath the dictionary, start typing “http” and press enter to insert Call HTTP Web Service.
  Click on “this” to open up the dialog box, and then click on the … for the string builder dialog box.
  
  I like to use as much dynamic values as possible so my URL in here looks like the following:

  [%Workflow Context:Current Site URL%]/_api/web/lists/getbytitle('[%Workflow Context:List Name%]')/items?$select=Title,Colour,Person/Title,Person/Name,Person/EMail&$expand=Person
  

  In the above API call I’m bringing back additional information about the Person from the person column. See at the end of this post about bringing back other information on a person column.

  After entering the URL, click the dropdown at the far right on the line in SPD and select properties. Set the RequestHeaders to the Dictionary you made in the first step. Set the ResponseContent to a new variable, and the ResponseStatusCode to a new variable. Click OK.
  

  The ResponseContent will be populated with the results, and the ResponseStatusCode will be populated with OK if successful, or a different value if something went wrong.

• After the Web service call, I add an If Statement, to test that the variable responseCode equals to OK.
  
• Now we want to grab the results. So now we will grab a dictionary item. Type “Get” and press enter to insert Get an Item from a Dictionary.
  Click “item by name or path” and type “d/results”
  Click “dictionary” and select “ResponseContent”
  Click “item” and create a new variable. This variable is a dictionary too that will contain the individual items. I’ve called mine DemoList.
  
• We need to count the number of items in the new dictionary variable. I do this to ensure that we have returned items.
  Type “Count” and press enter to insert count items in a dictionary.

  Click “dictionary” and select variable “DemoList”.
  Can leave output Variable to count.
  

• Put another If statement, and check that Count is greater than 0.
  
• We now need to create a variable that will be our indexloop.
  
• Add a loop with a condition. (Alternatively, we could have skipped the last step and added a “loop n times” instead).
  Set the condition to read. “The contents of this loop will run repeatedly while: Variable: indexloop is less than Variable: count

  

• Now I’m going to get the values of Title, Colour, Person/Title and Person/Name from the DemoList dictionary.
  Type “Get” and press enter to insert Get an Item from a Dictionary
  Click “item by name or path” and type “([%Variable: indexloop%)/Title”

  Click “dictionary” and select “DemoList”
  Click “item” and create a new variable.

  Repeat this for all the parameters.
  

• Still inside the loop underneath gathering the parameters we need to raise the index variable by one.
  Type “Calc” then press enter to insert Do Calculations
  Click first “value” and select the Variable: “indexloop”

  Click second “value” and set to 1.

  Set the output to a number variable. I called mine NewIndex
  

• Now you need to set the variable NewIndex to indexloop.
  
• Lastly, for demo purpose, I’m logging the results I’ve got to the history list. This logging to history lists is still within the loop.
  Type “Log” then press Enter to insert log to History List.
  Then I’m just logging out the variables I’ve captured.
  
• Don’t forget to Transition to Stage “End of Workflow” at the end.

  

Publish your workflow.

When I run the workflow against any list item I see the following results in my History List.

Bringing back additional Person Data in REST API calls.

To bring back a person column data (or a lookup column), you need to expand it in a REST API call, you also need to include the values you want to bring back from the expanded column. A list of all possible values you can bring back for a user column can be found if you type the following in a browser (after already signing into SharePoint that is).

https://<tenant>/sites/<site>/_api/web/lists/getbytitle('<ListTitle>')/items(1)/<UserFieldInternalNameColumn>

*I’m using XV – XML Viewer chrome extension for the layout.

Building Your SharePoint 2013 development machine on Windows Server 2012 – Part 9 – Configuring Workflow

UPDATE: SharePoint 2016 development machine

I am doing a collection of blog posts, you can access the other parts of this post below.

• Part 1 – Introduction
• Part 2 – Setting up and configuring Host Computer using Hyper V and a Wireless Network
• Part 3 – Building a base disk to use for differencing disks.
  • Installing Windows Server 2012
  • Installing SQL 2012
  • Installing Office 2013
  • Installing Visual Studio
  • Setting up the Menu
  • Syspreping
• Part 4 – Installing Active Directory
• Part 5 – Configuring SQL 2012 ready for SharePoint 2013 and Kerberos.
• Part 6 – Installing SharePoint 2013
• Part 7 – Configuring Hosting Apps
• Part 8 – Configuring My Sites and User Profiles
• Part 9 – Configuring Workflow
• Part 10 – Setting up Visual Studio

Install SharePoint Designer 2013

I have noticed in my blog I haven’t yet told you to install SharePoint Designer 2013. There is a good reason to install it now, because I can use it to prove if you have correctly configured Workflow Manger with SharePoint. SharePoint Designer 2013 is a free tool from Microsoft.

1. Download SharePoint Designer 2013 32bit from the Microsoft site http://www.microsoft.com/en-GB/download/details.aspx?id=35491
2. Once downloaded run the file sharepointdesigner_32bit.exe.
3. Accept the License terms and click Continue
4. Click Install Now.
5. Once installed, I’d recommend performing a Windows Update. From the Start Menu type Windows Update, open up the application and run any updates required. Reboot if necessary.

Check to see Workflow settings in SharePoint Designer.

1. From the start menu, type SharePoint Designer and open the application.
2. Once SharePoint Designer has opened, click Open Site.
3. Type the URL http://dev.cannonfodder.local click Open.
4. If prompted, enter your credentials User: Cannonfodder\Administrator Password:Pa55w0rd.
5. From the Navigation menu, select Workflows
    
6. On the ribbon menu, select List Workflow > Documents.
   
    
7. In the Create List Workflow dialog, at the bottom you will see a dropdown box for Choose the platform to build your workflow on. Only SharePoint 2010 will be listed.  
8. Close down SharePoint Designer.
   

Configuring Workflow Manager

First we need to create a Workflow account.

1. In the Start Menu, type Active Directory Users and Computers. Select the application.
2. Expand the tree in the left hand pane to see the Users OU. Select the Users OU.
   
3. Right Click on User and select New > User. Create a new user called SP_Workflow. Set the Full Name and Log on name to SP_Worflow. Click Next.
   
4. In the password dialog screen, enter the following and click Next.
   1. Password and Confirm Password as: Pa55w0rd
   2. Untick User must change password at next logon.
   3. Leave User cannot change password as unticked.
   4. Tick Password never expires
   5. Leave Account is disabled as unticked.
   6. Click Next. Then click Finish.

Setting up SQL with the correct Security Accounts.

1. From the start menu, type SQL Server Management Studio and open up the application
2. In SQL Server click Connect. (This should be to SQL2012 database instance).
3. In the left hand menu expand Security. Right click Logins. And select New Login…
4. In the Login – New dialog box, click the Search button.
5. Type SP_Workflow in the Enter the object name to select, and click Check Names. This will resolve the name. Click OK.
6. In the left hand panel select Server Roles.
7. Tick both securityadmin and dbcreator then click OK.
8. Close down SQL Server Management Studio

Giving SP_Workflow administrative rights.

1. From the start menu, type Active Directory Users and Computers and open up the application.
2. In the left hand panel, expand Active Directory users and Computer > cannonfodder.local > Builtin.
3. In the right hand panel, right click Administrators and select Properties.
4. In the members tab, click Add.
5. Type SP_Workflow in the Enter the object names to select box, click Check Names, then click OK.
6. Click OK to the Administrators Properties dialog box, and close Active Directory Users and Computers.
   

Installing Workflow Manager

1. Go to the URL http://www.microsoft.com/web/downloads/platform.aspx and download the latest Microsoft Web Platform Installer.
2. Once downloaded run the file WebPlatformInstaller_amd64_en-US.msi
3. Accept the license terms and click Install.
   
4. Once installed, you can open from the start menu by typing Web Platform.
5. Once loaded, type Workflow in the top right search box and press Enter. Find Workflow Manager 1.0 and click Install.
6. On the Prequisites page, click I Accept.
7. Once installer has complete, Click Continue and then Finish to start the configuration process.

Configuring Workflow Manager

1. From the Start menu, type Workflow Manager Configuration and open the application.
2. On the Welcome Page, click Configure Workflow Manager with Default Settings (Recommended).
   
3. On the New Farm Configuration Page set the SQL server Instance to SQL2012
4. Set the User ID to SP_Workflow@cannonfodder.local and the password to Pa55w0rd
5. Tick the Allow Workflow management over HTTP on this computer.
6. Click the Test Connection button to ensure your credentials work.
7. In the Certificate Generation Key and Confirm Certificate Generation key enter Pa55w0rd into both textboxes.
8. At the bottom right of the dialog box click the right arrow button to proceed to next screen.
9. A summary will appear. You can either click the tick icon at the bottom right to continue, or Get PowerShell Commands to obtain the powershell scripts to run later. In this instance, click the tick icon.
   (Please note the screen shot was taken during my first attempted, I used the wrong RunAs Account)
   
10. Once the process has completed everything should have been configured.
    

Connecting Workflow to SharePoint 2013.

1. From the start menu, type Workflow manager powershell and open the application.
2. Type

    Get-WFFarm | ft HttpPort 

3. Take note of this port (12291), as this is the port number that you will connect SharePoint 2013 to the Workflow Manager 1.0 farm.
   
4. Close Workflow Manager PowerShell.
5. From the start menu, type SharePoint 2013 Management Shell and open the application.
6. Type

    Register-SPWorkflowService –SPSite "http://intranet.cannonfodder.local" –WorkflowHostUri "http://cannonfodderser:12291" –AllowOAuthHttp 

7. Once you get the command prompt appearing again your SharePoint 2013 farm in now connected to the Workflow Manager 1.0 farm.
   

Check to see Workflow settings are working in SharePoint Designer.

1. From the start menu, type SharePoint Designer and open the application.
   
2. Once SharePoint Designer has opened, click Open Site.
3. Type the URL http://dev.cannonfodder.local click Open.
4. If prompted, enter your credentials User: Cannonfodder\Administrator Password:Pa55w0rd
5. From the Navigation menu, select Workflows
   
6. On the ribbon menu, select List Workflow > Documents.
7. In the Create List Workflow dialog, at the bottom you will see a dropdown box for Choose the platform to build your workflow on. Both SharePoint 2010 and SharePoint 2013 should be listed if the Workflow is set up correctly.
8. Close down SharePoint Designer.