Four gotchas of SharePoint workflow deployment – Specification

Every successful workflow deployment needs a specification requirement. It provides an explicit set of requirements to be clearly defined. Everyone already knows this mantra but many still run into critical issues with workflow. One of the main reasons that make workflow messed up is an unclear requirement. Even people wearing business analyst (BA) do nothing but listen to what their clients need. They don’t know how much a specification should have for workflow development. As a result, developers who are responsible for building workflow are often stuck.

In this article, we will look into how much of information you need when developing specification requirement documentation for SharePoint workflow deployment. If you are a business analyst who has to sit down with your client to define workflow requirement, then this article is written for you.

Many of you may realize that your clients just provide flow diagram and a few paragraphs describing how the workflow works then nothing else. They actually don’t know how much of information they need to provide you until you turn on the light in their brain.

Workflow characteristic

The main focus of a workflow is always its flow that depicts essential steps actors need to do to complete a process. But there is additional information for a workflow:

  • Current business challenges: to define the features to solve the existing challenges, this information need to be taken into account.
  • Process owner: this is the one who is responsible for reviewing and approving the workflow. For example, the owner of HR On-boarding process is often the HR manager. This information is to let you know after kick-off meeting, you will have to work with them.
  • Goals/Objectives: many forget thinking about this. Your workflow wouldn’t be acknowledged successful without its objectives. For example, the complimentary product order solution allows the HR department to be able to create and manage the list of complimentary products. The goal is a starting point for further questions to define functional requirements in more details.
  • The people who benefits from the workflow: if you don’t know this information, I’m wondering how you can collect ideas or requirements from them. This is also to let you know that you will have to ask the client about group permission as well.
  • A brief description of the process

Take a look at the sample:

“Every month Contoso offers complimentary goods for its employees. The total budget for each employee may vary depending on the financial resources (A brief description). Currently the Human Resources department (HR) has identified the following issues (Current business challenges) in the complimentary product program at Contoso each month:

  • The HR department must collect and total up ordered complimentary goods every month. It takes time to extract the report
  • There is no automatic calculation tool that allows employees in ordering goods. They have to manually calculate their choices in accordance with the total budget.
  • Email storage increase every month.

The complimentary product order (CPO) solution provided by ABC provides the following main features (Objectives):

  • A central portal where employees at Contoso (Who benefits) can use to pick up provided goods.
  • The HR department (Process owner) will be able to create and manage the list of complimentary products. They can create, read, update or delete (CRUD) products offered for employees each month. The total price each month is adjustable as well.
  • The system provides the automatic calculation to let employees know whether total price of their choices is out or not.

SharePoint workflow specification

 In my experience, every workflow has the following characteristics:


Lots of questions and ideas come up after you get the information above. Without it, everything seems to be ambiguous. What to define now? With general information and objectives above, as an experienced SharePoint professional, you may think about a portal in which there is a form where people will have to open to fill out information for given goods. In this point, what information do they need to fill specifically? You will then be provided an Excel file in almost cases. With this Excel file, define the content types:

  • Complimentary Product request content type
  • Good/Product content type
  • Budget content type

There are additional columns in the table above you may consider to add for more complex structure

  • Dependent field
  • Dependent required field
  • Dependent content type
  • Index display name
  • Read-only (Yes/No)

After defining clearly data input, you then work with the process owner to clarify security:

  • Authentication
  • Authorization

Based on the people who benefit from the workflow, you can plan for authentication. The people who use the workflow may be external users that are not managed in Active Directory. In this case, the solution would be to use whether customer form-based authentication, or 3rd party tools.

The authorization is the permission matrix of who can do what in the workflow. First, define participants and groups you need. See the following example:

“The business workflow includes the following participants:

  • Requestor: who fill out information in given request form
  • Line manager: who receives the request then decide whether it’s approved or not.
  • Signer: who receives the request then decide whether it’s approved or not. They then digitally sign if the request is approved.
  • Administrator: who compares original and scanned documentation to make sure both entirely match each other. “

You can create a permission worksheet like the following:

View this reference for more about planning permission levels and groups.

If your workflow has approval process, it’s recommended to be a separate approval permission matrix. It’s to let your developers clearly understand who approves at which steps.

Carefully plan for authorization. It’s to avoid well-known issues in workflow security. Your workflow sometimes may be stopped because the next approver doesn’t have access to it.

With flow design, read this article

With use case, write down what the workflow runs in each step. See the following example:


This use case starts when a requestor accesses the portal. The requestor enters username and password that is provided by the Active Directory system. With external requestor, they are provided by custom membership provider. The actor will then get authenticated to the portal


The portal has a request form that provides blank fields for the requestor. The requestor fills out information in the form.”

Finally, look into designing user experience for the workflow. The mockup shows the client how the workflow looks like and how they interact with it. The final article of the series will cover sort of UI/UX tricks for workflow.


This article gives you information required for every workflow basically in SharePoint. Without it, your developers will run into lots of issues that may block the progress. If you have any other tips, please feel free to leave the comment in this article. I would be very happy to learn from you.

Related articles:


Leave a Reply

© 2018 The Soldier of Fortune.