Skip Ribbon Commands
Skip to main content

Adrian Fiechter

Jan 19
SharePoint 2013: HTTP Web Service Action / Use Managed Metadata as Text in Workflow

The amazing new workflow engine for SharePoint 2013 is one of the most powerful things I have ever seen. Compared to the previous version it's fun to use and design workflows with the this engine, and the results are actually matching with your expectation. There is only one simple case, where the result was not exactly what was expected. When a user creates a workflow and access the list item from the workflow, the managed metadata fields are returning only the identifier of the term set. From a technical perspective this makes sense as those identifiers are used to lookup the correct item from the termstore. Anyway from an end-user perspective that looks somehow confusing.

This blog post explains on the example of extracting a managed metadata field the use of the following actions:

  • Build Dictonary
  • Call HTTP Web Service
  • Get item from Dictonary
  • Log to History

In addition it shows shortly how to explore the SharePoint 2013 objects from the browser.

Problem:

Inside a workflow we need to be able to have a condition based on the text value entered into a managed metadata field. Instead of using the termset identifier, the user designing the workflow wants to see the text value.

Solution:

The newly introduced HTTP web service action gives you a very powerful way to solve problems like this. To solve exactly this issue a HTTP web service action is and the values are loaded from the SharePoint server. The following example shows how this can be done.

Precondition and Limitation:

The SharePoint 2013 workflow with the workflow manager has to be installed on your farm. More information: http://msdn.microsoft.com/en-us/library/jj163276.aspx

When you are using this solution please be careful with renaming managed metadata, as this could affect your workflow. In addition the solution create one additional call back to you SharePoint server, but this shouldn't affect the performance. Finally the proposed solution doesn't support multi value managed metadata fields.

Example:

Identify URL to request the object

  1. Firstly you have to evaluate the correct URL for your list item. To do that open https://<sitecollection url>/_api/web/lists/

    Note: If you see something like the following image, please read the blog post: http://www.fiechter.eu/Lists/Posts/Post.aspx?ID=36&mobile=0

     

  2. In the browser search for the list name. For example here the list name is "Workflow Demo". When you have found it, collapse the items above.

     

  3. Search for the id tag a little bit higher and copy the url to access the list found under the id tag

     

  4. The url should look like https://<site collection url>/_api/Web/Lists(guid'a5ad9815-3a06-4689-b288-97bad99e0c21')

    Note: If you don't want to use the GUID you can also use the display name of your list:

    https://<site collection url>/_api/Web/lists/getByTitle('Workflow%20Demo')

     

  5. Create one example item inside the list

     

  6. Extend the url with /items(1) to access the item with the id=1 https://<site collection url>/_api/Web/Lists(guid'a5ad9815-3a06-4689-b288-97bad99e0c21')/items(1). Access the new url and try to find your managed metadata field. In this example the field is called "Category"

    Attention: Please ensure that the field is not a multi value field!

     

     

  7. Finally you have to extend the url with Category/Label to access the field value: https://<site collection url>/hr/demosite/_api/Web/Lists(guid'a5ad9815-3a06-4689-b288-97bad99e0c21')/items(1)/Category/Label. By accessing the url you should see something like this:

  8. Now you have identified the url to request the label of your managed metadata field.

Create the workflow that extracts the value

  1. Create a new list workflow and open it in SharePoint Designer.

     

  2. At the beginning we have to define the http request header, to avoid the following error: {"error":{"code":"-1, Microsoft.SharePoint.Client.ClientServiceException","message":{"lang":"en-US","value":"The HTTP header ACCEPT is missing or its value is invalid."}}}. The header can be created by the action "build dictionary". Add a new "Build Dictionary" action

     

  3. Select this on the new dictionary

     

  4. Add a new item with the name "Accept" and the value "application/json;odata=verbose"

     

  5. Add a new action called "Call HTTP Web Service"

     

  6. Select this on the activity

     

  7. To construct the workflow url correctly we open the url builder

     

  8. Click on "Add or change lookup" and add the current site url

     

  9. Afterwards add /_api/Web/Lists(guid'

     

  10. Click again on "Add or change lookup" and add the ListName

     

  11. Afterwards add ')/Items(

     

  12. Click again on "Add or change lookup" and add the item id

     

  13. Afterwards add )/Category/Label (Replace category with the field name you have identified). The final URL should look like the following. Then you can press ok.

     

  14. Ensure that the request method is HTTP Get and click again Ok.

     

  15. To get some result from SharePoint the request header has to be added by selecting the action and afterwards "Advanced Properties" from the ribbon.

     

  16. Assign the dictionary that you have built before, to the request header

     

  17. As last, you have to ensure that you can use the value returned from the http request. To do that, click on "response" under Response content and select Create a new variable.

     

  18. The new variable is called ManagedMetadataValueEncoded and from type dictionary

     

  19. As there is always a possibility to do something wrong, this is a good time to add a logging entry. For that click "Action -> Log to history list".

    Note: As this entry is more fore debugging purpose, you should remove it before delivering the workflow to your end-users.

     

  20. Select "message"

     

  21. Enter "Return value from HTTP Service:"

     

  22. Then click "Add or Change Lookup"

     

  23. Click ok

     

  24. To extract from the return value, the real value in the field add an action "Get an item from a Dictionary"

     

  25. Enter "d/Label" in the field "item by name or path"

     

  26. Under from select the "ManagedMetadataValueEncoded"

     

  27. At the end you need to assign an output variable from the type string. For that select output and "Create a new variable"

     

  28. Call the variable "ManagedMetadataValue"

     

  29. To log the final value add again a "Log to history list" action

     

  30. Select "message"

     

  31. Enter "Extracted Managed Metadata Value:"

     

  32. Then click "Add or Change Lookup"

     

  33. Click ok

     

  34. Terminate the workflow

  35. Select End of Workflow

That's itJ, afterwards you can create your conditions based on the value inside the ManagedMetadataValue variable. To ensure that it works, start the workflow from your list and see the results, by clicking the instance:

 

To summarize here is the complete workflow created.

The workflow creates the request header, sends a request to the SharePoint server and extracts the field value of your managed metadata from the response.

More information:

REST API for SharePoint 2013: http://msdn.microsoft.com/en-us/library/fp142385.aspx