Demystifying SP2013 Workflow AppStep

A SharePoint 2013 workflow essentially can run as two different accounts.  The current user, or AppStep (which runs the action as the Workflow App account).

You will need to activate this feature.

But this is not where these notes end.

SP2013 AppStep is not the same as SP2010 Impersonation Step

In SP2010, when you use impersonation step, you gain additional activities, and because SP2010 doesn't have the concept of different permissions impersonations - essentially those activities lets you perform the action with elevated privileges in the code.

In SP2013, everything is an App.  That includes workflows.  So, when you activate this feature, you gain:

• Ability to have App Step in your workflow designer (SharePoint Designer or Visual Studio .NET)
• App Step runs the actions inside with App Permissions, and this is important: the App only has Read and Write.  It does not have full control or manage or any other fancy pants abilities.
• When App Step updates the list item, you get a nice message on the list item that says Updated by Workflow on behalf of (user).

The power of HttpSend

You can of course call all the fancy new SP2013 REST API in your workflow.  http://msdn.microsoft.com/en-us/library/office/dn268594(v=office.15).aspx  - This gives your workflow a lot of power.  You can do this either as the current user or in the App account context.

Fabian and Chris has documented a number of really great articles on this.

• http://www.fabiangwilliams.com/2013/09/06/help-unable-to-create-list-using-sharepoint-2013-rest-api-in-spd2013/
• http://blogs.architectingconnectedsystems.com/blogs/cjg/archive/2013/09/07/Configure-Workflow-Manager-to-create-lists.aspx

Andrew Connell also has a great segment on Plural Sight on REST services.

• http://www.pluralsight.com/training/Courses/TableOfContents/sharepoint-2013-workflow-web-services

There are ways to increase that permission level

If you are on-premises, there is a powershell command to grant the Workflow App account additional permissions.

Set-SPAppPrincipalPermission

• http://blogs.architectingconnectedsystems.com/blogs/cjg/archive/2013/09/07/Configure-Workflow-Manager-to-create-lists.aspx

If you are on Office 365, there is a hidden URL that lets you re-apply a permission mask to the Workflow Account.

/_layouts/15/appinv.aspx

• http://msdn.microsoft.com/en-us/library/office/jj822159(v=office.15).aspx

Apps for SharePoint

Of course, the way Microsoft wants you to build workflows in the cloud would not be via a hidden URL.

The best way (but somewhat tricky at the moment, as tooling gets better this story will improve) is to build SP2013 workflows within an App for SharePoint.  The workflow is deployed in the App web, and has the same permissions that the user grants to the App web.  You can request additional permissions as you package your App and those will be available to the Workflow as well.

So this is fantastic for building self contained apps where lists, list definitions, javascript forms and SP2013 Workflows all tie together to form a small bit of functionality.

But having workflows in the App Web means that it can't be added to existing document libraries or lists or sites in the host web.  So there are a number of scenarios where Apps for SharePoint doesn't work that well.  I have been using SP2013's Sandbox Solutions for this purpose.  But Sandbox Solution Packages doesn't have its own App permissions (and thus you'll need to see the previous point about how to elevate that afterwards).

Integrated Workflow Apps

Microsoft has begun to talk about the new Integrated Workflow Apps in more detail.

The new syntax available for Integrated Workflow Apps will basically allow you to install workflow packaged as an App for SharePoint, but instead of deploying the Workflow to the App web, it will be deployed and made available on the Host Web. 

But tooling will need to improve in a future VS.NET update.  This is something I want to blog again later as more details are available.  But for now, there's a great link here.

• http://www.vrdmn.com/2014/09/integrated-workflow-apps-deploy.html

There are a few pieces of the puzzle missing, and one may need to build additional javascript based UI to deploy assets (lists and workflow associations) to the host web.  But I'm loving the choices and I think SP2013 Workflows is moving in a fantastic direction.

SP2013 Workflows and WSPublishState does not exist

Column 'WSPublishState' does not exist. It may have been deleted by another user.

This is a quick blog of something that troubled me for nearly an afternoon.

Scenario

• SP2013 workflow
• Packaged as Sandbox Solution with list definitions in Visual Studio

The errors happen during Feature activation.  Both from within Visual Studio's Deploy as well as via Site Settings - Activate Feature.  The feature activation fails because WSPublishState column doesn't exist.

Resolution

I fixed this by splitting the list definition and workflow definitions into different features.  This leads me to ponder if there is a conflict caused by the list, workflow and workflow association being created all within the same feature.

Nintex Workflow Inline Function to check if SPFile is locked

IsDocumentWritable

Nintex Workflow has a fairly useful function "IsDocumentWritable" that checks if the current item that the workflow is running on is writable.

There is a small problem, it only checks if the file is Checked Out (SPFile.CheckedOutType) and not if the file was locked, say by a Desktop Client Application.

Add Nintex Workflow Inline Function

We can add a simple Nintex Workflow inline function to get the behaviour we wanted:

I followed Vadim's excellent blog entry: http://www.vadimtabakman.com/nintex-workflow-developing-a-custom-inline-function.aspx

/*
* & 'C:\Program Files\Nintex\Nintex Workflow 2010\NWAdmin.exe' -o AddInlineFunction -functionalias "fn-IsFileLocked" -assembly "MY_DLL, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f7c41d4a6ea1fb3" -namespace "MYNamespace" -typename "MYInlineFunctions" -method "IsFileLocked" -description "Checks if file is locked." -usage "fn-IsFileLocked(itemPath)"
*/

public static bool IsFileLocked(string itemPath)
{
    bool result = false;
    try
    {
        SPSecurity.RunWithElevatedPrivileges(() =>
        {

            using (SPSite site = new SPSite(itemPath))
            {
                using (SPWeb web = site.OpenWeb())
                {
                    SPFile file = web.GetFile(itemPath);
                    if (!file.Exists)
                    {
                        return;
                    }

                    // true if checked out

                    result = file.LockType != SPFile.SPLockType.None;
                    return;
                }
            }
        });
    }
    catch (Exception ex)
    {
    }
    return result;
}

You can call this method from within Nintex Workflow Designer.

Using SharePoint Designer 2013 Workflow to copy file via REST on Office 365

This is a bit of trial and error, but works very well at the end, so I want to publish this and share the syntax.

Related References:

• http://blogs.msdn.com/b/sharepointdesigner/archive/2012/09/05/how-to-work-with-web-service-using-call-http-web-service-action.aspx HyongGuk Kim / Microsoft shows how to call a GET REST service
• http://www.fiechter.eu/blog/Lists/Posts/Post.aspx?ID=37&mobile=0 Adrian Fiechter explains how to call a GET service with Request Headers

I will tackle the next step.  How do you call a POST REST service, with the CopyTo function on SPFile.  http://msdn.microsoft.com/en-us/library/ms455020.aspx

The flexibility is that you can easily tweak the urls and essentially allow your workflow to copy files anywhere.

Step 1.  Understand the correct URL

• https://sharepointgurus365.sharepoint.com/sites/john/  the Office 365 site.
• https://sharepointgurus365.sharepoint.com/sites/john/_api/web/folders/GetByUrl('Shared%20Documents')/ the Shared Documents library.
• https://sharepointgurus365.sharepoint.com/sites/john/_api/web/folders/GetByUrl('Shared%20Documents')/Files/getbyurl('top1.png') the file: /sites/john/Shared%20Documents/top1.png
• https://sharepointgurus365.sharepoint.com/sites/john/_api/web/folders/GetByUrl('Shared%20Documents')/Files/getbyurl('top1.png')/copyTo(strNewUrl='/sites/john/Shared%20Documents/top2.png',bOverWrite=true)  This calls the CopyTo method on the file, destination is top2.png, overwrite is true.

Put this into your browser's address bar (this executes a GET request):

No good.  Need POST.

Step 2.  Make that SharePoint Designer 2013 Workflow

1. First step, with the POST call, we need to add a Request Header for Accept: application/json; odata=verbose
   Put this in a dictionary variable.
   
   
   
2. Second step.  Call Web Service!
   
   
   You need to set up Request Headers as well.  This has to be done via the Properties, since it's not a link that's shown.  Set this to the dictionary created in the previous step.
   This step is the same as mentioned in Adrian Fiechter's blog.
   
   
   
3. You should capture the ResponseContent, and add an additional action to log it to History
   The Stage ends.  Go to End of Workflow.
   
   
   
   
4. The whole thing, in 3 lines:
   
   
   
   

Step 3.  Run it.

Here's me starting the workflow on the top1.png file.

The top1.png is copied to top2.png!  Interestingly, it's copied the Call Workflow "workflow status" column.  Both links (which is a lookup field) go to the same workflow.

This is the workflow history. 

Notice that the CopyTo method returned void (null) in this case.  Should there be an error, you'll see it logged here.

That's all!  Hope you find these steps useful.