SPD WF 2013: 5 Things you wish you knew before using it #Azure #SharePoint2013

Wondering what you can get from SharePoint Workflow 2013 , which is a completely new beast?
I assumed that you have already read all WF 2013 perks that MSDN promises you.

My goal here is to give more a reality check - what you will discover while building workflow 2013 in SharePoint designer (SPD).

1. You can't access user profile. ex. to get a user's department.
You need use interop to call WF2010 that in turn accesses User Profiles list

2. Dictionary sometimes is cumbersome to use when you want to unite multiple stand-alone variables, even though MSDN uses this case to justify use of the new type - Dictionary
2.1. you can't add an item to the dictionary after the dictionary is created. all dictionary pairs should be created and assigned at the same time;
2.2. you can't retrieve dictionary key without assigning it the output variable, which clutters the variable list anyway.

3. Sometimes Workflow is failed to be open in SPD in SharePoint Online.
"Windows Workflow Foundation, part of .Net Framework 3.0, must be installed to use this feature"

To fix it:
3.1. Apply SharePoint Designer 2013 hotfix package (Spd-x-none.msp): April 8, 2014
     , spdcore2013-kb2727100
     3.2. Clear SPD Cache

4. Re-Publish workflow won't update WF version from the first time. You have to hit publish (at least in my env) twice to deliver a new WF to the site.

5. If (or rather when) your newly developed WF failed with internal status - suspended. The error is not informative even though it's verbose

When to use an timer job rather than a Workflow

A time ago a I have put short and useful note :When to use an Event Handler rather than a Workflow

Now, I want to create another "copy-paste" from one of the book that I m reading (Microsoft SharePoint 2010 Administrator's ) on the topic " Workflow and timer job when to use it":

Timer jobs can be used instead of so called "system" workflow ( that automate processes  that interact with the content and data stored in SharePoint). The major differences between timer job and system workflow:
 - Timer jobs can be activated and managed by farm administrators only;
 - End users can't control execution;

So rule of thumb: If the end users do not need to control the process, then choose timer jobs; otherwise, choose system workflow

• Does any user interaction occur?
  
• Will the process run for a long time (more than a second or two)?
  
• Will the process need to pause to wait for another process to complete a task?
  
• Will the process be run many times (more than 25 or 30) concurrently?

If the answer is "Yes" for any of these questions, you should build a workflow; if "No" for all, consider an event receiver. There are certainly some exceptions, but in general these rules apply. (Workflow Scalability and Performance in Windows SharePoint Services 3.0)

SPD Workflow Tasks: email notification customization

[What you have]:

   You have a SharePoint Designed Workflow with action "Collect Data from a User"\"Assign a Form to a Group"\"Assign a To-do Item". The task list has email notification turned on.

[What you want]:

  You want change the default task email notification from the task list.

[What you want to know]:

WSS stores predefined alert templates under {sharepoint root\hive*}\TEMPLATE\XML
alerttemplates.xml

                * - If you use SharePoint on a daily basis, you are probably familiar with the SharePoint hive. In SharePoint 2010, the hive is called the SharePoint root.

 

    If you turn the notification on the Task list: Tasks -> Settings -> Advanced settings -> E-mail Notification; every time the task gets assigned -the email gets sent to the "Assigned to" person.
    The type of such notification is described in alerttemplates.xml:

 <AlertTemplate Type="List"  Name="SPAlertTemplateType.AssignedToNotification">
  
Here the piece where the text of the email is defined:
                        <IfSubString>
                        <Expr1>0x010801</Expr1>
                        <Expr2><GetVar Name="RawValue#ContentTypeId" /></Expr2>
                        <Then><GetVar Name="RawValue#EmailBody"/></Then>
                        <Else>

The meaning of this CAML piece is following:

   - "RawValue#" - I couldn't find any decent documentation about this value. But my experiment has shown that "RawValue" is the FieldCollection of the SPItem - "Task".

   - CAML gets the ContentTypeId of the task, check if  the content type id has a substring "0x010801"
Why "0x010801"? - There are predefined content types in SharePoint, all  custom content types are inherited from the basic one. The all basic content types are in the file {root folder\hive}\TEMPLATE\FEATURES\ctypes.xml. 
        The content type with ID 0x010801 is a workflow task.
   <ContentType ID="0x010801"
        Name="$Resources:WorkflowTask"
        Group="_Hidden"
        Hidden="TRUE"
        Description="$Resources:WorkflowTaskCTDesc"
        Version="0">
        <FieldRefs>
            <FieldRef ID="{58ddda52-c2a3-4650-9178-3bbc1f6e36da}" Name="Link" />
            <FieldRef ID="{16b6952f-3ce6-45e0-8f4e-42dac6e12441}" Name="OffsiteParticipant" />
            <FieldRef ID="{4a799ba5-f449-4796-b43e-aa5186c3c414}" Name="OffsiteParticipantReason" />
            <FieldRef ID="{18e1c6fa-ae37-4102-890a-cfb0974ef494}" Name="WorkflowOutcome" />
            <FieldRef ID="{e506d6ca-c2da-4164-b858-306f1c41c9ec}" Name="WorkflowName" />
            <FieldRef ID="{ae069f25-3ac2-4256-b9c3-15dbc15da0e0}" Name="GUID" />
            <FieldRef ID="{8d96aa48-9dff-46cf-8538-84c747ffa877}" Name="TaskType" />
            <FieldRef ID="{17ca3a22-fdfe-46eb-99b5-9646baed3f16}" Name="FormURN" />
            <FieldRef ID="{78eae64a-f5f2-49af-b416-3247b76f46a1}" Name="FormData" />
            <FieldRef ID="{8cbb9252-1035-4156-9c35-f54e9056c65a}" Name="EmailBody" />
            <FieldRef ID="{47f68c3b-8930-406f-bde2-4a8c669ee87c}" Name="HasCustomEmailBody" />
            <FieldRef ID="{cb2413f2-7de9-4afc-8587-1ca3f563f624}" Name="SendEmailNotification" />
            <FieldRef ID="{4d2444c2-0e97-476c-a2a3-e9e4a9c73009}" Name="PendingModTime" />
            <FieldRef ID="{35363960-d998-4aad-b7e8-058dfe2c669e}" Name="Completed" />
            <FieldRef ID="{1bfee788-69b7-4765-b109-d4d9c31d1ac1}" Name="WorkflowListId" />
            <FieldRef ID="{8e234c69-02b0-42d9-8046-d5f49bf0174f}" Name="WorkflowItemId" />
            <FieldRef ID="{1c5518e2-1e99-49fe-bfc6-1a8de3ba16e2}" Name="ExtendedProperties" />
        </FieldRefs>
    </ContentType>

That means the Alert "AssignedToNotification" checks if the task's content type is inherited from the workflow task. All instances of SPD WF tasks are childs of 0x010801. 
 - If the tasks has a derived workflow task content type, the email body is formed from the  field "EmailBody"  of the task list item.

 I have looked at the content of the field "EmailBody" and it looks like this:
<HTML>
  <HEAD>
    <STYLE>
TABLE.mail
{
    border-collapse:collapse; width:100%;
    font: 8pt Tahoma;
}

TD.header { background:#F8F8F9; border:1px solid #E8EAEC;              padding: 12pt 10px 20px 10px; font: 16pt Verdana}
TD.body { border-top:1px solid #E8EAEC; border-bottom:1px solid #E8EAEC; padding: 12pt 10px 24pt 10px; }
TD.footer { border-top:1px solid #E8EAEC; border-bottom:1px solid #9CA3AD; padding: 4pt 10px 4pt 10px; }
A { color:#003399; text-decoration:none; }
A:visited { color:#aa00aa; }.bodytext
{
    font: 8pt Tahoma;
    color: #000000;
}

    </STYLE>
  </HEAD>
  <BODY class=bodytext>
    <TABLE class=mail cellspacing=0 dir=ltr>
      <TR class=header>
        <TD class=header>Task assigned by SharePOint ETL User on 4/23/2010.<br></TD>
      </TR>
      <TR class=body>
        <TD class=body></TD>
      </TR>
      <TR class=footer><TD class=footer>To complete this task:<br><ol><li>Review <a href="http://webapp/sitecol/subsite1/subsite1_1/Lists/Discussion/DiscussionView.aspx?ID=380">Veronica M. Jackson</a>.</li><li>Perform the specific activities required for t
his task.</li><li><!--[if gte mso 12]>Use the <b>Edit this task</b> button to mark the task as completed. (If you cannot update this task, you might not have access to it. Click <a href="http:///webapp/sitecol/subsite1/subsite1_1//Lists/Tasks/DispForm.aspx?I
D=379">here</a> to request access.)<![endif]--><![if !(gte mso 12)]><a href="/webapp/sitecol/subsite1/subsite1_1//Lists/Tasks/DispForm.aspx?ID=379">Edit this task</a> to mark the task as completed.<![endif]></li></ol></TD></TR>

    </TABLE>
   
  </BODY>
</HTML>

I don't know for sure what puts the value in the "EmailBody" field. But I have a feeling that is OWSSVR.dll

[What you want to do]:

As I can see, here is 2 solutions:

1. Create a copy of alerttemplate.xml and change the CAML query there  - replace <GetVar Name="RawValue#EmailBody"/> with what you want to see in the email, and run the stsadm command:
stsadm -o updatealerttemplates -url {sitecollection url} -f {custom alerttemplate} –lcid 1033   http://technet.microsoft.com/en-us/library/dd278299%28v=office.12%29.aspx
   Consideration:The alert template is applied on the whole site collection. That means that you will change the email notification body for the whole site collection.

2. If you want to change the email body only for particular SPD WF tasks - you want to implement custom event handler on the task list .
    example:
  public override void ItemAdding(SPItemEventProperties properties)
        {
                var emailBody = properties.AfterProperties["EmailBody"];
                if(emailBody!=null)
                {
                    properties.AfterProperties["EmailBody"] = getNewEmailBody(emailBody.ToString(),properties.AfterProperties["Title"].ToString());
  
                }         
        } 
   
[What you want to consider]:
For some scenarios - you can avoid the deep diving into alert templates changing - and make use of the SPD WF action: "Send an Email".

SPD Workflow: Custom action won't work

Yeah... The SPD WF is still in use in my project..

There are several benefits of using them:
 - easy to tailor to users' needs on the fly.
 - easy to understand by non-developers
  - can be done by non-developers.

There are (of course , as everything is in life)  minuses:
 - it's not transferable to another environment (but with extra effort-  it's possible  - explanation is here a hard-coded list id replacement )
 - it's not so flexible as a coded workflow
 - there is now way to debug it as easily as a coded workflow.

For some reason we use the SPD Workflow with custom written actions.
 Even  you are done with the step of writing the custom action. The second step - "using of the custom action" can be frustrating.
Based on my experience - the most common issue with the custom action in  the Sharepoint Designer Workflow is - it's appeared in the drop down list "Actions" , when you select  - it doesn't appear in the workflow.

That's my favorite one) - you won't find any trace of the errors in any logs.

I have found the concise and really helpful "how-to" fix the mysterious issues in the SPD WF - Common Pitfalls in SharePoint Designer Custom Actions

• When you select a custom activity from the Actions drop-down, nothing happens
• Usual suspect: the class name and assembly reference do not match in ACTIONS file and DLL. Please check that your class reference in the Action tag in the ACTIONS file exactly matches your DLL full name.
• Not so usual suspect: SPD has a cached reference of your old DLL. Exit SPD, delete ApplicationData\Microsoft\WebSite Cache\ folder and restart SPD.
• Even less usual suspect: You've correctly placed the ACTIONS file and the activity DLL, but you haven't added an authorizedType element into your web application web.config file. Add the correct entry (you can check the whole process here) and try again.
• When you bind a property to a value, it doesn't get set
• Usual suspect: the demoted property name in your DLL and in ACTIONS file do not match. Please check that all your properties in the code exactly match the Parameters section elements in your ACTIONS file.

 P.S. Thank you Edin - I didn't find the way to say "thank you" on the your blog. I hope you wouldn't  mind to be referenced from my blog.

When to use an Event Handler rather than a Workflow

In general, you will want to create an event handler rather than a workflow when you need to attach small bits of code that will run immediately before or after a list event has occured.
 As a rule of thumb, if your event handler must perform more than one or two operations (for example, updating some fields, validation data, or sending an email), you should consider using a workflow rather than an event handler.

Quoted from nice and easy to read book
SharePoint 2007 Development Recipes: A Problem-Solution Approach (Expert's Voice in Sharepoint)

Code-based workflow: how to debug

A great article explains how to debug a code-based wf

To get a trace from WF engine change the web.config:

<system.diagnostics>

       <switches>

              <add name=“System.Workflow LogToTraceListeners“ value=“1“ />

              <add name=“System.Workflow.Runtime.Hosting“ value=“All“ />

              <add name=“System.Workflow.Runtime“ value=“All“ />

              <add name=“System.Workflow.Runtime.Tracking“ value=“All“ />

              <add name=“System.Workflow.Activities“ value=“All“ />

       switches>

       <trace autoflush=“true“ indentsize=“4“>

              <listeners>

                     <add name=“customListener“

               type=“System.Diagnostics.TextWriterTraceListener“

               initializeData=“WFTrace.log“ />

              listeners>

       trace>

system.diagnostics>

Sharepoint code based workflow: OnTaskCreated error

After starting a workflow that uses OnTaskCreated you receive an error message:

Engine RunWorkflow: System.Workflow.Activities.EventDeliveryFailedException: Event "OnTaskCreated" on interface type "Microsoft.SharePoint.Workflow.ITaskService" for instance id "" cannot be delivered. ---> System.NullReferenceException: Object reference not set to an instance of an object. 

Huh, seems familiar? The only suggestion that Microsoft is making: do not use this event.

 After you start a workflow on a server that is running SharePoint Services 3.0, you receive an error message that states an error has occurred in the workflow

SharePoint Workflow Development on 64 bit Environment

Error creating workflow project in Visual Studio for MOSS x64 

That was a big suprise to know that I can't develop sharepoint workflow in Visual Studio 2008 on 64x.

But the great news is that you still can enjoy it if you make use of WSPBuilder extension - WSPBuilder

SPD WF Action Wait until by default 5 minutes

As you may have already discovered the action like "Wait until"\"Pause" don't work precisely as you setup them. Even you setup to wait only one minute, workflow by default will resume itself after 5-6 minutes.
Why is that?
It is because of the job-workflow schedule on the farm and by default this job runs every 5 minutes to brush up the running workflows.
So, if you are not satisfied with such behavior you can change it!

This is the simple stsadm command to check the current schedule:
stsadm -o getproperty -pn job-workflow -url http://test/apps

And this the command to save your time while you waiting for wf awaking:
stsadm -o setproperty -pn job-workflow -pv "every 2 minutes between 0 and 59" -url http://test/apps

Understanding and resolving the workflow task locking issue

A not so uncommon error that people encounter with SharePoint workflow is running into locked tasks. You know, the error that you get when working with workflow tasks, usually on your developer machine. You might get the error message "This task is currently locked by a running workflow and cannot be edited."

Information: This task is currently locked by a running workflow and cannot be edited.

Extremlly useful article to understand the lock task problem created by workflow.
In essence, be sure that you have healthy running an event handler attached to the item which also has a workflow.

And here is the result which causes the "locking" and hummer-way to fix it:
Locked Workflow

My investigation concluded that the task with locking issue "The file is currently checked out or locked for editing by another user"  can be identified by looking at the task property Level . If the item is locked - the value is

"Checkout"

Here is a powerful script  in PowerShell to free the tasks up that had been locked:

$tasklist=$web.Lists["Tasks"]
Foreach ($task in $tasklist.Items) 
  {If($task.Level -eq "Checkout") 
    {
      Write-Host $task.Id
      $tasklist.RootFolder.Files[$task.Url].UndoCheckOut() 
    }
  }