Introduction

On SAML claims based SharePoint web Applications, SharePoint Groups to User resolution is not available out of the box without custom resolvers. Hence the workflows would obviously not able to send emails to individual users upon task creation. Moreover it can assign tasks only to groups and not to individual users as long as Groups are associated with role claims. The sample Custom SharePoint 2013 Approval Workflow provided here would help in filling that gap with the help of a role resolver service. This workflow is intended to be used on SAML Token based authenticated web applications.  The workflow leverages a custom Role Resolver activity (included in solution) which is capable of resolving the users based on the role claims by calling a WCF service. Based on the user information resolved for the given SharePoint group, the tasks will be assigned and the emails can be sent upon assignment and  cancellation.

SharePoint 2013 doesnt provide any out of the box Approval or Publishing Approval Workflows as like 2010. Moreover the workflow has been completly re architectured in 2013 based on CSOM. The Custom workflow sample provides an option of enabling workflows on any list with a custom association form to configure input parameters and task alert email parameters. The sample also provides multilingual capabilities. Moreover the publishing approval workflow can be enabled on publishing sites by enabling just one feature. provides an additional option of configuring the global settings thru a common configuration list.

Description

Upon deployment, the solution enables the following 5 features.

  1. Custom Approval Workflows Infrastructure (Site Collection Scoped)
  2. Custom Approval Workflow Activities (Web Scoped)
  3. Custom Approval Workflows Infrastructure (Web Scoped)
  4. Configure Publishing Approval Workflow - For SAML Based Authentication (Web Scoped)
  5. Configure Publishing Approval Workflow - For Windows Based Authentication (Web Scoped)

Custom Approval Workflow Activities (Web Scoped)

The feature deploys the a custom activity named "Resolve Group Members". The activity is responsible for resolving the group names to user information. The activity basically accepts the SharePoint Groups (collection) or a Role Name (for direct resolution instead of parsing the group for role name), calls the WCF Service (URL configurable thru Workflow Global Settings) to resolve the role names to user information and return the same to the calling workflow.

Thanks to Anuj Jain for his help on developing this activity and Role Resolver.

Custom Approval Workflows Infrastructure (Web Scoped)

If you would like to enable workflow on a non-publishing site, this is the only feature you need to activate. The feature basically deploys 2 workflows (1. Approval 2. ApprovalSAML), associated resources and forms. Upon activation you will be able to see the workflow listed on any list workflow settings.

Approval Workflow

This workflow is intended to be used for Windows Based Web Application, where the user names will be resolved based on the approvers input parameter.

Approval WorkflowSAML

This workflow is intended to be used on Web Applications enabled with SAML Token based authentication. As the SharePoint Group to User resolution is not available out of the box, the workflow will not send emails upon task creation. hence this needs to be achieved thru role resolvers. As part of the workflow, the custom activity named "Resolve Group Members"  (deployed by custom workflow activities infrastructure) will perform this SharePoint Group Name to Users resolution and ensure the resolved users are added to the web in content. Upon user resolution the Composite Task activity on the workflow will be supplied with list of user for which the task needs to be created, which will enable us to achieve the usual workflow behavior of task creation and notifications.

During association the workflow does provides an association page 2, where it does provide an option to fill the following parameters.

  1. Approvers
  2. Due duration (days)
  3. Option to end on document change
  4. Option to End on First Approval
  5. Task Title
  6. Task Assignment Email Subject
  7. Task Assignment Email Body
  8. Task Cancellation Email Subject
  9. Task Cancellation Email Body
  10. Task Overdue Email Subject
  11. Task Overdue Email Body

During first time configuration the fields will be filled with default values. If you would like to change the values, please ensure you dont remove the place holders from the default values.

Upon submission the workflow will be configured on the given list.

Important Note:

Upon assocation, the following manul steps are required for the workflow to work as expected.

  1. Enable "Worklfow 2013 Task" Content Type on Workflow Task list associated with the workflow.
  2. Activate the web scoped feature "Workflows can use app permissions"
  3. Enable permission for the workflow to access the content on the sharepoint.

Custom Approval Workflows Infrastructure (Site Collection Scoped)
Required only when you need to enable publishing workflows. Can be activated only on the Root site collection. Upon activation, the feature deploys a "Workflow Global Settings" list with the following items.

  • ApprovalWorkflowApproversSharePointGroup - Approvers|Administrators
    • use this entry to configure the default approvers group associated with the publishing approval. The values can be | (or) or & (And) splitted. Can have multiple values. however doesnt support mixed splitters. (both | and &)
  • ApprovalWorkflowDefaultDurationDays - 7
    • Default number of duration days.
  • EnablePublishingApprovalWorkflowOnLists - Pages,Images,Documents
    • Lists on Publlishing site for which the approval workflow needs to be enabled.
  • RoleReolverUri - http://localhost/RoleResolverService.svc/Users
    • The URL of Role Resolver Service to be called to get the SharePoint groups resolved to users information.
  • UserTokenPrefix - i:0e.t|Partners|
    • The user token prefix to be used while ensuring the users on the given web after role resolution. The sample provided illustrates UPN (i:0e.t) as primary claim and Partners as Trusted Identity provider name. (PowerShell Command to get the list of possible Claim type encodings Get-SPClaimTypeEncoding)

Configure Publishing Approval Workflow - For Windows Based Authentication (Web Scoped)
This feature configures publishing approval workflows as per the above configuration settings on a publishing site. Upon activation the feature perfroms the following actions on the web.

  1. Associates the workflow on Pages, Images and Document Libraries.
  2. Uses the email templates from resource files.
  3. Since Sharepoint 2013 supports triggering of workflow only on Item Added, Updated or Manul, there is no option of triggering the workflow on Item Major checkins, hence the approval action can be handled only thru the event recivers.
    • Associates the following event receivers on the lists to handle all the possible scenarios of approval actions.
      • Item Updating
      • Item Updated
      • Item CheckedIn
    • Approval Actions Supported
      • Approval Override (Direct Approval/Reject) thru ribbon (cancells the in progress workflow)
      • Cancel Approval (Cancells the inprogress workflow)
      • Approval/Rejection thru workflow task.
  4. Activates the dependency feature -  "Workflows can use app permissions"
  5. Enables Trust to the workflow - (Automation of enabling permission for the workflow to access the sharepoint)

More Information

Workflow Services WCF Service

The solution includes a WCF service which provides some management capabilities like approval/Rejection. As the 2013 workflows are CSOM based these actions are not possible directly from the workflow. hence those capabilities are acheived thru the server based services.

Role Resolver WCF Service

The solution includes a sample Role Resolver WCF service that provides the user role resolution for the given SharePoint group. The WCF service can accept the following parameters and returns user information as a collection, in JSON format (as expected by the Role Resolver workflow activity).

Input Parameters:

  1. claim
  2. rowLimit (to prevent result count flooding)
  3. workflowId (doesnt do anything, just included incase if we need to implement a business logic in role resolver code)

Output:

  1. UserInfo collection
    1. UPN
    2. Name
    3. Email

Jquery (OpenSource) - Work with your Legal Dept

The solution leverages Jquery to perform some operations on the association form to provide enhanced features.
However the script files are not included as part of the solution.

For the solution, in order to work/behave as expected the following Jquery .js files need to be included in the solution path \layouts\customapprovalworkflow\scripts\ before compilation and deployment.

  1. jquery-1.8.2.js
  2. jquery-1.8.2.min.js

Please check with your legal department before enabling the jquery scripts on the end user solution.

Contributors

  1. Anuj Jain - Consultant - Global Delivery

Last edited Sep 18, 2013 at 7:15 AM by thirumurugan, version 4