Pro Office 365 Development, Second Edition (2014)

APPENDIX B. SharePoint Designer’s Text-Based Workflow Editor

In Chapter 4, you created a workflow in SharePoint Designer using the Visual Designer view. We showed a brief glimpse of the Text-Based Designer view. Once you get used to the Text-Based view, you may find it to be a more efficient tool for authoring the workflow details. In this appendix, we’ll provide a basic overview of the Text-Based editor.

Creating the Workflow Editor Components

The basic building blocks of a declarative workflow are actions and conditions. Actions are the things a workflow does and conditions define the rules that determine when certain actions are performed. These are often combined into stages and steps that help organize the workflow in logical blocks. There are also some special components such as loops and parallel blocks that you can use to control the program.

· Actions – the things a workflow does such as update a list or send an e-mail.

· Conditions – these allow you to perform different processing based on the data or previous outcomes.

· Stages and steps – these enable you to organize a workflow into smaller blocks.

· Special components – provide advanced execution such as loops and parallel processing.

Note The workflow platform has been completely redesigned in SharePoint 2013. Both 2010 and 2013 workflows are supported but they cannot work together. The actions shown here are for 2013 workflow. If you create a 2010 workflow, the list of actions and conditions will be different.

Actions

Actions are the things your workflow will do, such as create a task, send an e-mail, or update a variable. Figure B-1 shows a partial list of the actions that are available to you.

Figure B-1. Available actions

Note This figure shows only a partial list of the actions available to you. Refer to Chapter 4 for more information about workflow elements.

These actions correlate with the stencil shapes that you used in Visio. The actions are grouped into categories to help you find the one you need. The first group, called Recent Actions, contains the actions you have used recently. These same actions are also listed in their normal groups. Listing them here makes it easier for you to find actions that you use frequently.

Conditions

Conditions give you the ability to execute actions based on the outcome of previous actions or input parameters. For example, if an item was approved, you may want to perform different actions than if it was rejected. Figure B-2 shows the list of conditions that you can use.

Figure B-2. Available conditions

When you insert a condition, the designer creates a line in the workflow starting with If and followed by the condition. Subsequent actions are indented to show that they are performed only if the condition is true. You can also add an Else block, which will be executed if the condition is false.

Stages and Steps

We explained stages in Chapter 4. Within a stage, steps are used to further divide your workflow into smaller blocks that are easy to visualize. When you create a new workflow, the initial implementation contains Stage 1. You can add all of your actions and conditions into this stage. However, for longer workflows, creating additional stages and steps will make your workflow easier to read. Steps can also be nested so a single step can contain other substeps. However, stages cannot be nested.

Special Components

Figure B-3 shows the buttons available on the ribbon for inserting elements.

Figure B-3. Insert section in the Workflows ribbon

We’ve explained the Condition, Action, Stage, and Step buttons, but there are a few more buttons that provide some interesting features. A Loop action allows you to execute one or more actions repeatedly. You can either repeat a fixed number of iterations or until a specified condition is true. A sample action is shown in Figure B-4.

Figure B-4. A Loop action with condition

The Else Branch button will create an Else block for an existing condition. Clicking this button while on a condition will create the corresponding Else block.

The Parallel Block button allows you to create a group of actions that are performed in parallel, although not necessarily simultaneously. The default logic is to perform actions sequentially (one at a time). As you start entering actions, you’ll notice that the wording on the workflow will indicate how the actions are executed. For example, the second action will be prefixed with the word "then", implying that the second action is started after the first action is completed. However, in parallel blocks, the word "and" is used, indicating they are being started at the same time.

The App Step button creates a new step, just like the Step button, with one important difference. The actions performed in this step are run using the privileges of the registered app. Normally, a workflow is run with the permissions of the user that initiated the workflow. The App Step is used when the workflow must update a list that some users may not have access to to avoid getting access denied errors.

To create an App Step action, you must first enable this feature. Go to the Site Settings page and then click the Manage Site Features link. Scroll to the bottom of this list and find the Workflow can use app permissions feature, shown in Figure B-5. Click theActivate button to enable the feature. You will also need to register the app and configure its privileges. For more information, check out the article at http://msdn.microsoft.com/en-us/library/office/jj822159(v=office.15).aspx.

Figure B-5. Enabling the App Step feature

Using the Editor Features

When you design a workflow, you’ll add actions, conditions, and steps to your workflow and then configure them. The workflow editor provides some nice features to help you add the necessary components and then to specify how they are to function.

Using the Insertion Point

You will quickly notice the flashing orange bar, which indicates the insertion point. This indicates where actions, conditions, or steps will be inserted when you click one of the buttons in the ribbon. The flashing orange bar indicates the current insertion point. You can move the insertion point by hovering the mouse pointer over where you want to insert an action, condition, or step. If this is a suitable location, a solid faint orange bar will appear where the mouse pointer is, as demonstrated in Figure B-6.

Figure B-6. Moving the insertion point

The flashing orange bar (insertion point) is inside Stage 1. If you hover the mouse just below Stage 1, a faint orange bar will appear. If you click it, it will start flashing, indicating that this is now the current insertion point. You can generally move the insertion point to any of the following:

· Between existing actions (to insert a new action or condition).

· After the actions for a condition (to create an Else branch).

· After the last action in a step (to add an action or condition).

· Between existing steps (to insert a new step).

· After the last step (to add a new step).

· Before, after, or between stages to add a new stage.

When you click the insertion point, it will open a search box where you can search for the desired action or condition. For example, click the insertion point, and enter email. The designer should look like the one shown in Figure B-7.

Figure B-7. Searching for the e-mail action

Tip You don’t have to click the current insertion point. If you just start typing, it will automatically open up the search box.

This is a really handy feature! As you started typing and entered em, it would show that it found 12 actions or conditions. If you press Enter at that point, it would list them for you to select one. By the time you typed ema, the search was narrowed down to a single result, and it told you to press Enter to select the matching action. So, by only typing ema and pressing Enter, you can add an action to send an e-mail.

Defining Parameters

Most actions and conditions have parameters that you can specify to control its execution. In the Send an Email action, for example, you’ll need to specify who the e-mail will go to as well as the subject and body of the e-mail. Parameters in an action or condition are underlined and are displayed as links, as shown in Figure B-8.

Figure B-8. The Send an Email action with an undefined parameter

When you click one of these parameter links, the display will change to allow you to specify a value for the parameter. The controls that are made available to you will vary depending on the type of parameter. For most simple parameters, the display will look like Figure B-9.

Figure B-9. Editor changed to accept input

The link has changed into a text box and two buttons. This provides three ways for this information to be entered. For fixed text, you can simply type it in the text box. If you want to use a column, parameter, or variable defined in SharePoint, use the lookup (fx) button to provide aLookup dialog box, as shown in Figure B-10.

Figure B-10. The Lookup dialog box

This third option is to click the button with the ellipses. Click this button, and the String Builder dialog box will appear. This allows you to combine static text along with dynamic data stored in SharePoint. To add dynamic data, put the cursor where you want the data inserted and click the Add or Change Lookup button. This will display the same Lookup dialog, as shown in Figure B-11.

Figure B-11. Using the String Builder dialog box

Complex parameters will display a dialog box that allows you to define multiple values. The these users link in the Send an Email action, for example, will display the Define E-mail Message dialog box shown in Figure B-12. This is used to specify the recipients as well as the subject and body of the e-mail.

Figure B-12. The Define E-mail Message dialog box

Summary

Workflows that are created with the text-based editor are identical to the ones created using the visual designer. You have the same actions, conditions, and other components available to you. You can also switch back and forth between editors. For example, you can start a workflow using Visio, edit it with the text-based editor, and then finish up with Visio. The text-based editor may take a little getting used to but you might find it more efficient to work in.