A Sample Workflow

Let's take a look at a sample workflow to get an idea of what's possible. In our sample, the fictitious "Rock Solid Church" has implemented a human resources process to help manage new position approvals. With this process in place let's say that Ted Decker wants to get approval to hire a part-time event planner. Let's walk through the workflow that has been defined.

1Request

Ted starts the process by entering his request into the system. Many of these requests would be started by going to Tools > Workflows, but you can add new workflow pages anywhere you'd like in the navigation. On the first entry screen, Ted selected the option of needing a Part-Time position. The workflow took that into consideration and immediately asked him to complete an additional entry screen specifically for part-time submissions that asks for the number of hours needed for the position.

2Sent

After all of the entry screens have been completed, the workflow sends an email to the designated human resources worker, in this case Alisha Marble.

3Additional Info

After clicking a link from the email, Alisha completes an entry form to add additional human resources fields like salary range and who will need to approve the position. Keep in mind this is a simple example. You could automate the selection of the approver if you'd like. In our example Alisha has selected the church's senior pastor Pete Foster.

4Approve/Deny

The workflow now sends Pete an email regarding the position. From the email, Pete can click to approve or deny the position.

5Notes

In our example, Pete has chosen to click the link to approve the request using the Rock website. This allows him to add further notes.

6Emails

With the request approved, emails are sent to both Ted to let him know the good news and Alisha so that she can start the needed human resources paperwork.

This is just a quick example of one workflow. We'll look behind the scenes of this specific workflow later in the chapter Building a Simple Workflow.

Workflow Types vs. Workflows

Let's start with a little vocabulary. Workflow Types are the configuration patterns that a specific Workflow will use to execute. As an example, you might configure an HR Position Approval workflow type that an employee uses to initiate an IT Director Position Request workflow.

Attributes

Attributes are the data elements your workflow needs to be able to process. For the External Inquiry example workflow type that ships with Rock, we'll need information about the requester (name, email address, phone) as well as the topic, message and campus. Once we have the input from the guest, we'll also need attributes that store the person being assigned to the inquiry as well as any notes that they enter.

Attributes can represent many types of data including text, numbers, images, locations, a person, date and more.

Activities

Activities are groupings of actions that function together to complete a unit of work. How many activities you use in a particular workflow is part science and part art, but in most cases, there is not a right answer. In general, though, think of activities as phases of your workflow. In our External Inquiry example there is an activity for the initial entry of the request, and activities for each category of the inquiry (pastoral inquiry, website inquiry, finance inquiry, etc.)

When you configure your workflow, you'll set certain activities to Activate at the start of the workflow. These activities can then activate other activities depending on the nature of the input and workflow logic.

While most attributes will be defined for the entire workflow, it is also possible to define attributes that are specific to an activity. This allows for activities to have their own set of data items.

Actions

Activities are made up of Actions. Actions are the smallest unit of work in a workflow. Don't let their size fool you though. Like ants, they may be small, but they can move large objects by working together. Some examples of what actions can do are:

• Send an email.
• Set the value of an attribute.
• Present the person with a form to enter data.
• Run a SQL query.
• Activate a new activity.

Status

Every instance of a workflow has a Status. There's nothing magical about the status. In fact, it's just a text field that's updated by the actions as they process through the workflow. A well-crafted workflow uses the status field to help communicate the stage the workflow is in. For instance, a work request workflow might use statuses like Pending, Open, or Closed.

Viewing A Workflow Type

On the Workflow Configuration detail screen, you can view important information about your workflow type.

1 Workflow Type Navigation

Shows workflow categories and the workflow types in each category. While you can nest categories, it's best to keep your structure relatively flat.

2 Name

The name of the workflow type.

3 Description

The description of the workflow type. You should make this as detailed as possible since it acts as documentation for your workflow type.

4 Activities

This lists each of the activities configured in the workflow type. For each activity it also lists their actions. This section is a form of auto-documentation if you provide clear names and descriptions for your activities and actions.

5 Copy

Many workflow types are similar. To help you create new workflow types that are similar to ones you already use, Rock allows you to make a copy of an existing workflow type to use as a starting point for creating a new one.

6 Action Buttons

Here you can launch the workflow, view a list of workflow instances, edit security and export the workflow type. Security will determine who is able to view a workflow as well as manage (via the Edit permission) a workflow type.

7 Change Log

Workflow types can change over time and might be worked on by more than one person. Use the Change Log to add notes about what was changed by clicking the button. Keeping a good change log will help your future self, as well as others, understand what changes have been made and can be very valuable for troubleshooting.

Editing A Workflow Type

Clicking the Edit button takes you to the edit screen for that workflow type. This screen is made up of several sections, which are explained below.

Details

The first section is the Details section. Let's take a look at what it includes.

1 Name

The name associated with the workflow type.

2 Active

Determines if the workflow type is active. This is helpful if you'd like to prevent new workflows from being created but would like to keep the workflow type around to view previous workflow instances.

3 Automatically Persisted

We’ll discuss persisted vs. non-persisted workflows in detail below. Just know this is where you set the persistence type.

4 Description

While you may be tempted to skip over the description, we highly recommend that you enter a detailed description of your workflow covering when it should be used and its basic functionality.

5 Work Term

The term you will use to describe an instance of the workflow. For example, an IT work request may use the term Request while our inquiry example would use Inquiry.

6Workflow Number Prefix

While every workflow will have a unique system ID, Rock also generates a workflow instance ID for the type. This makes for more logical and consistent IDs. The Workflow Number prefix allows you to optionally add an alpha-number prefix to the workflow instance ID. So instead of having an ID of, say, 00001 you can have something like POS0001.

7 Category

Workflow types are grouped into categories for organization.

8 Icon CSS Class

You can provide a CSS icon to help distinguish your workflow type from others. By default, Rock supports the Font Awesome icon set. These icons should be in the form fa fa-[icon name] as pictured in the example.

Advanced Settings

The next section is the Advanced Settings section.

1 Processing Interval

Persisted workflows that are still active are run on a routine basis to see if there are any actions that can be completed. How often your workflow is run depends on this setting. To reduce the overhead on your server, you'll want to set this interval wisely.

2 Logging Level

Logging is used to help debug (find logic errors) in your workflows. You can set the logging level to match the verboseness you need (None is nothing while Action is pretty much everything).

3 Maximum Workflow Age

For a variety of reasons, some workflows can hang around without ever being completed. This setting lets you automatically complete workflows that are older than the number of days provided, based on the date the workflow was created. Especially when used with the Completed Workflow Retention Period (see next item below) this can help keep your list of workflows clean and tidy.

4 Completed Workflow Retention Period

This is where you can specify how many days you want to keep a completed workflow before it's deleted. Over time your list of workflows will grow, including some workflows you'll only need for a limited amount of time. By default, workflows are never deleted, so you might find your list getting cluttered. Setting a value here allows you to routinely and automatically clean up your workflows. If you never want the workflow to be removed, leave this field blank.

5 Log Retention Period

This setting only applies if you've provided a Logging Level value other than "None". Because logs take up space, and because they're mostly used temporarily for debugging purposes, you probably want to clean them out once they're no longer needed. Logs will be deleted if they are older than the time period you provide here.

6 No Action Message

You can customize the message that's displayed in scenarios where a workflow of this type is active but does not have an active entry form. There's generally no need to make changes here.

7 Summary View

This template is used to display the workflow Summary when viewing workflow details. For the most part you shouldn't need to make changes here, but keep in mind that any changes you do make will only apply to the workflow type being edited.

Attributes

Next is the Attributes section.

Attributes are the data elements your workflow needs to be able to process. In this section you configure each of these elements and define the types of data they will store (i.e., text, numbers, dates, people, groups, etc.)

While it might be tempting to rush and define your attributes quickly by providing only a name and field type, it's wise to slow down and provide a good description of how the attribute will be used in the workflow. Trust us, you'll thank yourself later. Also, consider if a default value would make sense in your workflow.

Save Time

Sometimes adding a good default value for your attribute can save steps in your workflow as you will only need to set the value of an attribute if a change is needed.

Activities/Actions

Finally, there is the Activities section.

Activities and actions are the meat and potatoes of workflows. They control the flow logic that your workflow will use when it's processed. While we'll be talking about activities and actions in detail later, know that this is where you'll configure them for your workflow types.

Tip

Be sure to check out the Workflow Control section in the Workflow Actions Documentation for more details.

As you build more complex workflows you might start to get confused about which box is an activity and which is an action. Just remember activities have a group of cubes () next to their titles while actions have a single cube ().

Import/Export Details

Now we all know that workflows can be complex and very specific to your organization. In the event that you have a workflow that isn’t so custom, this ability can be a game changer for those in the Rock community. Below is a general overview of the Export/Import page.

1 Workflow Type

This dropdown will populate with all of the currently available workflows. Navigate through the options to find yours to export.

2 File

If you are the one receiving a workflow, click the upload button to find the .json file to Import.

3 Category

Choose the desired category the imported workflow will load to.

4 Test Only

You can avoid any surprises that might come up during your import by first importing in Test Only mode. This will run through the import process without actually importing the workflow so you can spot issues in advance.

Activation

Activities won't run until they are activated by the workflow engine. There are two ways that an activity is activated:

1. Start-up: You can configure certain activities to be activated when a workflow starts.
2. Action Activation: If an activity is not activated at start-up, then it must be activated by an action on an activity that was.

Simply defining an activity doesn't guarantee that it will ever be executed. If it is not activated with the start of a workflow and no action ever activates it, it will never run.

Configuring Activities

When you add a new activity to a workflow type, you'll see a new blank activity panel. The configuration options are shown below:

1 Name

Be sure to give your activity a descriptive name. If this was a flow chart on paper, the name would be the text in the box.

2 Description

Don't cheat yourself by providing a short description. It's often helpful to outline both the purpose of the activity and the flow logic that will be needed to execute.

3 Active

This tells the workflow if this activity is active in the configuration. While this isn't used very often, it can be helpful if you need to temporally disable an activity from running.

4 Activated With Workflow

This defines whether the activity will be automatically activated at the beginning of a workflow. If this option is enabled, the activity's icon and border will be shown in green to help you quickly identify it as a startup activity.

5 Security

Security on a workflow activity helps with activities that must interact with a person (mainly through entry forms). More on entry forms can be found below. Note: The security icon for an activity will not appear until after the workflow has been saved.

6 Attributes

Activities can have their own attributes. When they're needed, they're configured here. More on when to use activity attributes is discussed in the next section.

7 Actions

This is where you'll define the actions that make up your activity. The order of the actions is important because they will execute in the order you provide. For more details see the Actions chapter below.

Activity Attributes

Like workflow attributes, activity attributes allow you to store the data needed to execute your workflow. Many workflows can get by with using just workflow attributes. But there will be times when a specific activity is run more than once. If you'd like to keep track of data for each execution, you'll need to define activity attributes. The data in these attributes is only available within the specific activity instance.

As an example, say you had an activity that seeks approval for a purchase order. As a part of the approval, you might want to allow the approver to enter notes about their decision. You'd also like your workflow to allow the approval step to be re-run until an approval is received (for instance the approver may deny it at first, it goes back to the requester who edits it and then re-submits it for approval). If the approval note was stored as a workflow attribute, it would be overwritten each time the approval activity is run. When defined as an activity attribute, each instance of the activity would have its own instance of the note attribute.

Assignment

Activities can be assigned to a specific person or group. While security determines who's allowed to view or edit an activity, the assignment describes who is responsible for completing it. Assignment only comes into play for activities that must interact with a person (mainly through entry forms). Assignments help workflows prompt the right people to enter the data that is needed. We'll touch more on assignments in the Working With Entry Forms chapter.

Action Configuration

While each action type will have configuration settings unique to its purpose, all actions do share some similar configuration settings. Let's look at these common settings. They can be found by clicking on an activity in a workflow configuration.

1 Name

The name is used to help describe the task the action is performing within the activity.

2 Action Is Completed On Success

This tells the workflow engine if the action should be marked as completed when it runs successfully. For most actions you'll want to be sure this is set to 'True'. But there may be times when you want an action to be performed every time the workflow is processed.

3 Activity Is Completed On Success

This setting tells the workflow engine to mark the entire activity as complete if the action successfully runs. This has the effect of keeping all following actions from running. If you are familiar with programming logic, this is similar to a break statement.

4 Action Type

This is where you configure what type of action you want to perform. There are many different types of actions, each with their own function. We have each type of action documented for you in the Workflow Actions Documentation.

5 Assign Message

The message that is displayed based on the Action Type selected.

6 Person Picker

The person picker is here because of the selected action type. Different fields will appear in this area depending on the type of action that's been chosen.

Action Filters

We learned about ways we can control the flow of actions inside an activity in the previous section. Action Filters provide us with another powerful way of controlling the flow logic of a workflow. They allow you to only run an action if the value of an attribute meets a criterion you define.

When an action has a filter configured, the filter icon will display in yellow to help you know that a filter is present.

Although most of the filter match criteria are self-explanatory, the Regular Expression is possibly unfamiliar to you. Simply put, a regular expression is a sequence of characters that define a search pattern and using them you can achieve powerful text matching. For example, if you wanted to match a prayer request text for the phrases "suicide", "SUICIDE", "kill himself", "kill herself", or "kill myself" you could use a regular expression value of (?i)(suicide|kill (h|m)(\S+)(\s*)self). You can find a Microsoft Regular Expression Quick Reference online and use a tool like https://www.debuggex.com/ for testing your new creations.

Sometimes, a workflow action might not be able to finish its job. This could happen because the "Run If" conditions needed to run the action aren't met. To help your workflow run smoother in this case, you may consider enabling the Complete Action If Criteria Unmet option. When you turn this on for a specific action, Rock will automatically mark the action as "Completed" even if the conditions aren't met. This way, you won't have to worry about unfinished business.

Note, when an action is auto-completed, Rock will keep a record of it in the workflow log. The log will show that the action couldn't be finished but was marked as complete.

Default Action Types

For a listing of Rock's workflow actions, see the Workflow Actions Documentation. There we outline a number of actions that come with Rock, providing tips on when and how to use them. Screenshots of the settings are also provided.

Workflow Entry Block

Many workflows will start with a person filling out a form. This is certainly the case with workflows like IT requests, facility operations requests, HR approvals, etc. There are a couple of ways you can launch these types of workflows.

Workflow Category Browser

Rock ships with a workflow entry page under Tools > Workflows. This page displays a list of workflow categories with the ability to expand the category to view its workflows. Clicking on a workflow will launch it and show its first entry screen. You can configure which categories are displayed by modifying the block's settings. Category and workflow security will also be used to personalize the display to the specific rights of the person viewing the page.

Direct Workflow Entry

There may be times when you'd like to place a specific page in the navigation that takes you directly to a workflow entry screen. An example of this is the Contact Us page on the external website. This page has been configured with the Workflow Entry block. One of the block settings of this block type allows you to define a specific workflow type to launch when the page loads. This is a great way to include links to important workflows into your internal and external sites. The magic of this technique is that the person doesn’t even know that they are interacting with a workflow.

Workflow Entry Block Settings

Above we noted that you can configure the Workflow Entry block's settings to set a specific workflow to launch when the block is accessed. Let's take a closer look at that setting as well as the other block settings available for Workflow Entry.

1 Name

This is simply the name of the block, which you can customize if you wish.

2 Workflow Type

Here is where you can specify a workflow type for the block. Whenever the block is accessed, the workflow type you select will automatically launch and you'll be brought to an entry form. This is how the Contact Us example described above is configured.

3 Show Summary View

Most of the time you'll want to keep this set to "No". Enabling this will display a summary of the workflow, showing who initiated it and when, instead of the messages that typically display after the workflow has been submitted/completed.

4 Block Title Template

You can customize the title of the block using the power of Lava. By default, the Work Term configured for the workflow type is displayed.

5 Block Title Icon CSS Class

If you want to display a specific icon at the top of the block you can add it here. Otherwise by default the icon associated with the workflow type will be used.

6 Disable Passing WorkflowId

By default, a WorkflowId in the URL can be used to select the workflow that should appear in this block. However, you can disable this, allowing only a workflow GUID to be passed.

7 Disable Passing WorkflowTypeId

This is similar to the above setting, but applies to Workflow Type Id. By default, a WorkflowTypeId in the URL can be used to select the type of workflow being launched from this block. You can disable this, allowing only a workflow type GUID to be passed.

8 Log Interactions

You can log an interaction when the person first views a workflow form, and when the last form is completed. Logging interactions for both can give you insight into how long a form takes to fill out, or how many people start the form but don't finish.

Person Profile Actions

You may have noticed that there is a button on the Person Profile page labeled Actions. On this menu there is an item entitled Person Data Error. Clicking on this menu item launches a workflow that allows the person to report any data integrity issues to the proper team. You can easily add your own workflows to this list.

The first step is to create your new workflow. Be sure one of your first actions uses the Set Attribute From Entity. This takes the person whose record is being viewed and places them in a workflow attribute (this attribute should be of type Person). Your workflow can then add any processing logic from there.

Once your workflow is defined, you can add the workflow to the action menu. This is done by editing the block settings back on the Person Profile page. There you'll see a setting for selecting workflows to add. Workflow security will be considered when building the list so you can make sure that only certain people are able to launch the workflow.

Entity Triggers

Have you ever thought: "Gee, I wish I could do something every time someone saves a person in the database." Well, with Rock you can! Entity triggers can be configured under Admin Tools > General Settings > Workflow Triggers.

1 Trigger Type

You must select when the trigger will be fired. See notes below on the difference between pre and post events.

2 Active

Determines if the workflow trigger is currently active. This is helpful if you want to temporarily suspend the trigger but don't want to delete it.

3 Entity Type

Select the entity type you'd like to add the trigger to (e.g., Person, Group, etc.)

4 Entity Type Qualifier Column / Value (Optional)

There are times when you will only want to run your trigger in certain situations. For instance, you may want to run a post-save trigger when groups of group type Serving Team are saved. In this case you would set the Qualifier Column to GroupTypeId and the Qualifier Value to 23 (the GroupTypeId for Serving Teams). These settings allow you to simplify your workflows for specific use cases.

5 Workflow Type

Select the workflow type you want to launch. Be sure that this workflow saves the passed entity to an attribute so that it has access to the value being saved or deleted.

6 Workflow Name

This setting provides a workflow name for the workflows that are created.

Launch Workflow from Grid

Have you ever wanted to run a workflow for each item on a grid? Perhaps you need to send every person in a data view into an on-boarding process. Or maybe you want to send them an email asking for them to complete a form. If you can write a workflow for it, you can launch it right from a grid.

When you’re looking at a grid, all you have to do is click the button to launch a workflow for each item listed. Let’s look at an example using the Group Viewer page to launch workflows for the members of a group.

Clicking the icon pictured above will take you to the Workflow Launch page pictured below.

When you arrive at the Workflow Launch page you will see that each of the items (in this case, group members) are listed at the top. This lets you check to make sure you have the correct information and the right items.

Beneath the list of items, you’ll notice the Workflow Type picker. Use this to select the type of workflow to launch, then click the Launch button. Keep in mind that a new workflow will be launched for each item listed above the picker. In our group member example, four new workflows will be launched. Also remember that the workflow we're launching in this example is configured to work with group members (as opposed to person records).

You’ll notice above that after clicking the Launch button, you can choose to Launch Another Workflow without leaving the page. This makes it easy to quickly launch multiple workflows for the same set of items.

Extending Workflow Launches

Hopefully you’re already seeing tremendous power of launching workflows from grids. Now, let’s look at how you can extend this feature even further.

In the above Group Viewer example, we launched workflows for group members by clicking the icon in the grid. This feature is enabled by default for grids in Rock, so you’ll see the in other places and it will work the same way. But you might not want all of your grids to allow workflow launches. Or you might want to force a specific workflow to be launched instead of having a person choose from the picker. You can configure all this, and more, using the options described below.

Disable Workflow Launcher

We'll start with the most basic setting. If you want to turn off the launcher for a grid, all you have to do is access the Custom Grid Options in the grid’s block settings. Expand the Custom Actions area and set Enable Workflow Launcher to “No”.

This setting only applies to the workflow launcher that ships with Rock, as described in the above section. Custom actions (see below) are not impacted by this setting, even if those actions will launch a workflow.

Workflow Launch Block

The workflow launcher takes you to a page with a workflow launch block. This block is the bridge that connects the items in the grid to the workflows you want to launch for those items. Administrators can change the block settings to customize different aspects of the process.

1 Name

The name of the block can be changed here.

2 Workflow Types

You can specify which workflow types are able to be launched by adding them to this list. The Custom Actions section below describes a different way to restrict the workflow types on this block, so be sure to check that out before using this field.

3 Allow Multiple Workflow Launches

If set to yes, this allows launching multiple different types of workflows for the same set of selected items. After one is launched, the block will allow the individual to select another type to be launched.

4 Panel Title

The title that’s displayed in the block panel can be customized here.

5 Panel Title Icon CSS Class

By default, the icon is displayed, but you can change it here.

6 Default Number of Items to Show

This setting controls the number of items that will be shown on the launch screen. If the number of items in the grid is higher than this number, a count will be displayed showing how many aren’t visible.

The workflow launch block is programmed to look for a Workflow Type Id in the URL. If it finds one, then the block will automatically lock the workflow picker to that workflow type, and it can’t be changed by the person. This is like specifying a workflow type in the block’s settings, except the block will dynamically change according to the query string in the URL. We’ll show you what this looks like in the Custom Action Routes section below.

Custom Actions

Now let’s talk about the doors that open with Custom Actions. Custom actions work like the workflow launcher example described above. An icon gets added to the grid (like the icon) and then a person can click it to start your custom action. The key is that this isn’t limited to group members or workflows. Custom actions can take items from any grid and use them wherever you need. In the below example we'll take a look at adding custom actions to a data view results grid.

Custom actions are added in the grid’s block settings, in the same Custom Grid Options area as the Enable Workflow Launcher setting described above. Click the Add Actions button to create a new custom action.

1 Route

The route you provide drives your custom action. People will be taken to the page provided when they initiate your custom action from the grid. If you want to launch a workflow for each grid item, the route should point to a page with a workflow launch block. We’ll talk more about this field below.

2 Icon CSS Class

This is where you choose the icon that appears in the grid. People will click this icon to initiate your custom action.

3 Help Text

When a person hovers over the icon in the grid, this text will appear to indicate what action will be taken.

Using the configuration pictured above, the grid containing people from the data view now has a new icon for the new action.

Custom Action Routes

As noted above, there’s more to the Route configuration than just taking the person to a different page. In the example configuration above, the route is /page/630?WorkflowTypeId=16. Let’s break that down.

The first part of this action’s route takes the person to a new page, which is /page/630 in this example. We’ve added a workflow launch block to that page, so that’s all we need for this route to work for launching workflows. In this case, a route of /page/630 would result in a custom action that’s very similar, maybe identical, to the workflow launch process described in the prior section.

To take it a step further, don’t forget that the workflow launch block checks for a workflow type in the URL. If it finds a workflow type, then it will lock the workflow picker to that type. All you need to do is add a query string parameter in the format of ?WorkflowTypeId=xx to your route, and the block will automatically pick it up.

Populating Workflow Attribute Values

The workflow launch block will take any of the parameters that are in the query string and pass them into the workflow's matching attributes. So, if you have a group attribute in your workflow, you can pass the group's Id by including ?GroupId=12 in the route.

The example route we used above has an added parameter of ?WorkflowTypeId=16. This tells the block to allow only the “Photo Request” workflow type.

This custom action now provides a dedicated icon people can use to launch only “Photo Request” workflows. Remember, the block itself hasn’t changed. It’s only locked to photo requests in this case because of the route in our custom action.

Keeping that in mind, you can add new icons to launch different types of workflows using the same target page and the same block. In addition to photo requests, you might add a new custom action for assessment requests, giving you an icon for each on the grid as pictured below.

Note in the screenshot above that both routes point to the same page, and the same workflow launch block. Adding the workflow type to the Route means that the icon will launch only photo requests, while the icon will launch only assessment requests.

Working with Launched Workflows

In the above sections we’ve only been using workflow types that ship with Rock, launched from Group Member and Data View grids. But you can use these features with other workflows, and with other grids.

When you’re building a workflow to launch from a grid, it’s important to know what types of items, or entities, the grid contains. The examples in prior sections were working with Group Member and Person entities because those are the types of entities contained in those grids. Other grids may have different entities, like groups or financial transactions.

The key is knowing that the entity is passed from the grid to the workflow. That means the grid needs to know the type of entity it’s working with, but it also means your workflow needs to be designed to work with that type of entity. The best way to do that is to use the Attribute Set from Entity action, to capture each entity from the grid and assign it to a workflow attribute.

You can see above that the group member from the grid will be assigned to the workflow's "Group Member" attribute. Now the entity can be referenced directly in the workflow, and you can use it in other actions. Remember, a workflow is launched for each entity in the grid. We're only processing a single group member in this workflow, not the set of group members.

Auto Closing Workflows

Have you ever wanted to give up on something? Well, this could be the case with certain types of workflows. In situations where it's no longer sensible to continue running a workflow, you now have an option to clear the slate. The Complete Workflows job can be added in the Jobs Administration screen. You can configure it to run against one or more workflow types that are older than a certain number of minutes. Alternatively, if you leave the Expiration Age setting empty, it will complete all workflows when the job is run. This can be useful if you schedule the job to run at certain times of the year. You can also provide a custom Close Status (such as 'Expired') to know at a glance why the workflow was completed when you are reviewing them at a later date.

Form Action

To help us understand this action better, let’s go back to the simple HR Position Request example from earlier, specifically the first entry form that Ted used to start the request. Below is a screenshot of the entry form action used in that workflow.

1Purpose

The Form Header is a great place to introduce the purpose of your form and any background knowledge that might be needed. As someone who uses Rock, we know you won’t make the mistake of writing a dry and impersonalized message. Instead, we're sure you'll remember to use Lava merge fields like {{ CurrentPerson.NickName }} to make your form feel personalized. That's just how you roll...

2Attributes

Next, you'll pick which Workflow / Activity attributes you want the person to complete. For each, you can select whether the fields are: Visible, Editable and/or Required.

3Logic

You can click the button next to any of the form fields to apply conditional logic. This allows you to configure this field to show or hide based on the value of other fields. For more details see the Conditional Logic section below.

4Form Footer

The footer text is a great place to add information about what will happen next in the process.

5Commands

Finally, you can add different Commands to the form. These commands cause the entry form to be submitted and different parts of the workflow to be activated. We'll talk more about commands next.

Entry Form Commands

Commands allow people filling out the form to execute different logic based on their selections. For instance, on an approval entry you might add two commands of Approve or Deny. Depending on which command is selected, different activities and/or actions can be run. There are two different ways commands can trigger logic. Let’s consider both in detail.

Entry Form Chaining

In our sample HR workflow, you'll remember that the initial entry form asked if the position was full-time or part-time. Depending on the person's selection, they were taken to a new entry form based on their input. This is a feature called entry form chaining. When the command on the first form is executed, the workflow is activated and processed. If any action in the workflow assigns a new entry form action for the current person, its form will be shown. This is a very powerful feature because it allows you to build complex interactions with the person.

Let's look at how the sample position request form was configured for chaining.

1Entry Form

Our initial entry form, which included the attribute of Full-time or Part-time.

2Non-persisted

The workflow was initially configured to be non-persisted. This was to keep the workflow from being saved in the database in the case of a person who clicked on the form but then left. Now that the person has entered information and executed a command, we will persist it.

3Requester

Next, we set the requester for the workflow and also provide a workflow name.

4Second Entry Form

Now we're ready to show the second entry form, depending on their input. Each of these entry forms is configured with action filters that limit them to only be run if the position type is either full-time or part-time. As you can see here, using action filters with entry forms can be very powerful.

Instead of using action filters, we could have launched separate activities to get the details for each position type, one for full-time and one for part-time. In this case though, the action filters seemed a better option.

Emailing From the Entry Form

In many cases you'll want to email an individual to let them know that a workflow needs their entry before continuing. While you're welcome to configure the Email Send action to do this, there is a short-cut built into the Entry Form action.

1Notification Email

You can select a pre-configured email template to use for the email.

2Include Actions in Email

You can also select whether the commands you've configured should be included in the email. This allows the recipient to execute various commands right from their email client.

Buttons

Buttons on entry forms have several capabilities. Learning to extend them can help you build even more power into your workflows.

Using Person Entry

Often, one of primary reasons for using the Form action is to collect information about the person who is filling out the form. For instance, you might want their name, email address and phone number. This kind of information is requested so often that Rock has a feature to automate adding these kinds of questions to your form. As if that weren’t enough, this feature will also create a record in Rock if the person doesn’t already have one. If the person is in Rock, this will find their record and it can be used to update their information.

Unlike other items on your form, you don’t need to create workflow attributes for these questions. As described below, all you need to do is Enable Person Entry and pick what you want to ask the person for. Let’s take a look.

1Enable Person Entry

The rest of the fields described here will only appear if Enable Person Entry has been selected. If your form doesn’t need to ask for a person’s information, then this should remain disabled.

2Person Form HTML

Just like the Form Header and Form Footer, you can add HTML to the top (Pre-HTML) and bottom (Post-HTML) of the Person Entry fields. This is a great way to visually separate these questions from other items on the form.

3Autofill Current Person

If Rock knows who the person is (e.g., because they’re logged in), selecting this option will automatically fill in the Person Entry fields for them. That means the person filling out the form doesn’t have to give you information you already have. This is also a great way to fill in gaps in your data. For instance, if Rock has an email address for the person but not a phone number, then the person’s email address will be filled in for them, but they’ll still need to enter a phone number manually.

4Hide if Current Person Known

Selecting this option can help simplify your form by hiding all the Person Entry fields if Rock already knows who the person is. However, it also means that the person loses the opportunity to update their information. Either way, keep in mind that selecting this option doesn’t always mean the Person Entry fields will be hidden. For instance, if you set the Address field to be Required, and if the person doesn’t have an address in Rock, then the Person Entry fields will still be shown. This ensures the Required information can be collected.

5Record Status

Like the Connection Status, you can choose what Record Status a new person should have. This only applies to new records that are created.

6Connection Status

The person filling out the form may be new to Rock. In that case, the Connection Status you select here will be applied to the person’s record when it’s created.

7Show Campus

If selected, a Campus field will be available on the form. The campus field will be required and can be changed by the person.

8Campus Type/Status

If you have Show Campus enabled, you can use these fields to restrict which campuses are available for selection by the person filling out the form. For instance, you might use these to limit the options to Physical campuses that are Open.

9Person Entry Fields

This is where you get to select which Person Entry fields you want on your form. For instance, if you don’t want the person’s Address, then you can Hide that field entirely. You can also choose to make each field either Required or Optional based on your needs.

10SMS Opt-In

Allows the Registrant to permit or deny permission to be contacted via text messages at their mobile number. The Options for this field are Hide, Optional or Required.

11Address Type

Only one Address Type will appear on the form, and this is where you’ll select which one it should be. If the Address field is set to “Hide” then this setting won’t be referenced.

12Spouse Entry

Enabling this option will provide a duplicate set of Person Entry fields on the form for the person’s spouse. If “Optional” is selected, then the person will be given a Show Spouse checkbox on the form that they can click to show these additional fields. If “Required” is selected, then the spouse fields will always be shown on the form. Except for the First Name and Last Name, which are always required, the Person Entry fields for Spouse respect the Hide, Optional or Required settings of each other field. In other words, you can set Spouse Entry to be “Required” but the other fields for things like Email or Birthdate will still be hidden, optional or required according to your setup.

13Spouse Label

Sometimes it will make more sense to say “husband” or “wife” instead of “spouse”. You can change what "Spouse" is called on the form by providing a different label here. Just keep in mind that the spouse fields are only intended for spouses, regardless of what you call them. Changing the Spouse Label to “Child” doesn’t mean the form is now collecting information on the person’s child. If you want the person to provide information for anyone other than their spouse, you’ll have to add those fields to your form outside of the Person Entry Configuration area by adding workflow attributes.

14Person, Spouse and Family Attributes

You can store the person, their spouse and/or their family in a workflow attribute using these fields. The Person and Spouse attributes should be of type “Person”, while the Family attribute would be of type “Group”. Storing this information in workflow attributes lets you easily reference the people or family later in the workflow. This works for both new records and for existing records that are matched according to the information provided in the form.

15Race

You can choose to collect a person's race, which describes their physical traits and characteristics.

16Ethnicity

You can also choose to collect a person's ethnicity, which is a cultural identifier.

Conditional Logic

Each of your form's fields can have conditional logic applied. This lets you show or hide the field based on how the person answers other questions in the form. Let's take a look at how this can work in the Position Approval example workflow we've been using.

Let's say we only want the Number of Hours field to appear for the person if the position Type is "Part-Time". All we need to do is click the icon for Number of Hours to add this condition.

In the screen that pops up, you'll need to click Add Criteria to start adding the logic for your condition. You have several options available.

1 Show/Hide

You can choose to either Show or Hide the field when the criteria you provide are met. By default, this is set to Show, which means the field will be hidden unless the condition is satisfied.

2 All/Any

You can have multiple criteria for your condition. This field determines if All of the criteria need to be met, or if Any one of them can be met, for the condition to be satisfied.

3 Entry Form Fields

This drop-down contains a list of the other fields on your form. This is how you indicate that an answer to one field has an effect on the field you're working with. In this example we're checking the Type field to determine whether or not to show the Number of Hours field. Only fields within the current form are available for adding criteria.

4 Field Criteria

What you see here will change depending on the entry form field you picked. This is where you define which answers should satisfy the criteria. In this example we only want the Number of Hours field to appear if the Type is Part-time. Here we see checkboxes because the Type field is a single-select attribute.

5 Delete

Click the button to delete a single criteria row from the condition.

6 Add Criteria

You can add as many criteria as needed by clicking this button. You may want to have more than one criterion in cases where a person's answers to multiple fields should determine whether or not this field is shown.

When a logical condition has been added to an entry form field, the will turn orange as pictured below. Now the Number of Hours field will only be shown to the person filling out the form if they selected Part-time as the position Type.

Getting Started

There's nothing you need to do in advance to start using the Form Builder. You can start creating and using forms right away. In this section we'll walk you through the basic parts of the Form Builder and some of the options you have for your forms. Later we'll cover the details of adding fields to your forms for people to fill out.

Your first step will be to navigate to Tools > Form Builder. There you'll be able to create a new form or access an existing one. But there's more you can do on this page besides looking for or creating forms.

1 Form Categories

If these categories look familiar, it's because they're the same categories used by workflow types. After all, each form you create becomes a new workflow type. From here you can select a category to see all the forms in that category, or you can add new categories to the list.

2 Edit Category

For the selected category you can adjust security, edit its name or delete it entirely. Just remember the changes you make here will also be reflected on the Workflow Configuration page. Categories can't be deleted if they contain any forms or workflow types.

3 Create New Form

To get started on a new form all you need to do is click the button.

4 Forms

This is the list of forms in the selected category. For each form you'll see its name, who created it, when it was created and how many times the form has been submitted. Hovering your mouse over the form will provide links to different areas of the form's configuration. From here you can also delete or copy the form.

Creating a New Form

Let's start with the basics of creating a new form. First, we'll cover how to create a form, and then we'll go over the different parts of the form that you'll be working with.

1 Name

Be sure to give your form a good name. A solid name will make the form's intent clear and will help distinguish it from other forms. The name of the form is for internal use only and will not be visible to the person filling it out.

2 Description

Like the name, the description is for internal use and will not be shown to the person filling out the form. Do your future self a favor and create a description that indicates how, where and why the form will be used.

3 Template

You can optionally create your new form from a pre-configured template. For more details see the Form Builder Templates section below.

4 Category

The category will be filled in for you, but you can change it here if needed.

After clicking the Start Building button pictured above, you'll be brought to the main Form Builder page pictured below. This is where you'll actually design your form.

As pictured above, you'll see four areas on your new form. There are areas for the form's header, a Person Entry form, your form's fields and the form footer. Each of these areas can be customized by clicking the or icons along the right of each area. We'll look at each of these areas individually below.

Form Header/Footer

You can optionally add content to your form's header or footer area. This content will appear above (header) and below (footer) the rest of your form, as it's shown on the screen.

Person Entry Form

If you've ever worked with the Form workflow action, then you might already be familiar with the Person Entry form. This is a mini form that collects a person's information and will match the person to a record in your system or create a new record if needed. In the workflow type that gets created, the result of the information gathered here will be stored in a Person attribute. In most cases you'll probably want to use the Person Entry form, but it can be disabled by toggling the Enable Person Entry setting on the main Form Builder panel.

1 Autofill Current Person

If Rock knows who the person is (e.g., because they’re logged in), selecting this option will automatically fill in the Person Entry fields for them. That means the person filling out the form doesn’t have to provide information you already have. This is also a great way to fill in gaps in your data.

2 Hide if Current Person Known

Selecting this option helps simplify your form by hiding all the Person Entry fields if Rock already knows who the person is. Keep in mind that selecting this option doesn’t always mean the Person Entry fields will be hidden. For instance, if you set the Address field to be Required, and if the person doesn’t have an address in Rock, then the Person Entry fields will still be shown. This ensures the Required information can be collected.

3 Record/Connection Status

The person filling out the form may be new to Rock. In that case, the Connection Status and Record Status you select here will be applied to the person’s record when it’s created.

4 Show Campus

If selected, a campus field will be available on the form. The campus field will be required and can be changed by the person.

5 Campus Type/Status

If you have Show Campus enabled, you can use these fields to restrict which campuses are available for selection by the person filling out the form. For instance, you might use these to limit the options to Physical campuses that are Open.

6 Person Entry Fields

This is where you get to select which Person Entry fields you want on your form. For instance, if you don’t want the person’s Address, then you can Hide that field entirely. You can also choose to make each field either Required or Optional based on your needs.

Sections

A section is where you can group the fields that make up your form. You can have a single section or multiple sections. Each section has its own settings that you can use to add content and styling to your form, which we'll look at below.

1 Title

You can give your section a title. The title will appear in large font above the description (if one exists) and above the form fields contained in the section. This is a great way to label/classify the fields within the section.

2 Description

The description appears below the title in a smaller font. This is where you can give a little extra detail about the fields in the section or provide instructions for the person filling out the form.

3 Show Heading Separator

Enabling this will simply add a horizontal rule (a line) below the title and description, visually separating them from the section's fields. This option is here purely for aesthetic reasons, to help your form look its best.

4 Type

This indicates the type of section this is. You can choose No Style, which has the same effect as not making a Type selection at all. This means the fields in this section will appear to simply be on the page, not contained within any visual grouping. The Well option, on the other hand, will enclose your fields in a lightly bordered background. This is a great way to visually break up multiple sections and can give your form a cleaner and more professional feel.

5 Conditionals

You can choose to show or hide the entire section, and the fields within it, based on the person's answers to fields in other sections. This is perfect for cases where you want to ask a series of questions only if the person answers an earlier question a certain way.

Those are the settings for the form section itself. Next, we'll look at adding fields to the section for people to fill out.

Adding Form Fields

Now that you're familiar with the different parts of the form you're ready to start adding fields. Fields are pieces of input that the person filling out the form is asked to provide. Fields are added to the form by clicking them from the left of the page and dragging them into a section on the right. For instance, you might add a Boolean field if you want the person to answer a simple Yes/No question. You might add a Text or Memo field if you want the person to provide a typed answer to a question. There are many field options for gathering different types of data from the person. Let's look at adding some fields to a form.

1 Section

This is how you add new sections to your form, giving you new areas to add fields to.

2 Common Fields

As the name implies, these are the fields that you'll probably use most often. If you've ever worked with attributes before then you've probably seen some of these fields in use. Each field has its own settings, which we'll talk about a little later.

3 Additional Fields

Click here to expand the Additional Fields list. These fields can be added to your form just like the Common Fields, but they're hidden initially simply because they're used less often.

4 Enable Person Entry

Here you can enable or disable the Person Entry form. It's likely that you'll want this enabled most of the time to identify the person who is filling out the form.

5 Campus Set From

You have three options for setting the campus.

1. Current Person: Use the campus of the current person who is logged in while using the form.
2. Workflow Person: Use the campus associated with the Person attribute.
3. Query String: Use the campus from the Campus query string parameter, which could be the campus Id or Guid.

6 Form Fields

This is where the fields from the left get placed onto your form, into a section. After a field has been placed you can (and should) adjust its configuration, which we'll cover below.

Adjusting Field Settings

There are many types of fields you can add to your form, and each of them has unique settings that are specific to the field. For instance, if you use a Single-Select then you'll need to provide a list of values that the person can choose from. We won't cover every possible field and its configuration in this document, but there are elements that all fields on your form share.

1 Name

The Name of the field appears on the form and is visible to the person. More often than not you'll want to change the name of the field to make it relevant to what you're asking the person for.

2 Description

If you add a Description, it will create a tooltip icon () next to the field name. The person filling out the form can hover their mouse over the icon to see the description you've added. This is a great way to provide instructions or clarification for the person filling out the form.

3 Unique Properties

This area will change depending on the field. Some fields have multiple configurable properties, while others will simply have an optional Default Value.

4 Conditionals

You can add logic to the field so that it is shown or hidden depending on the person's answers to other questions on the form. For instance, you might only want to show a Baptism Date field if the person indicates they have been baptized.

5 Format

The Column Span setting lets you control the width of the field on the form. Reducing the width of multiple fields lets you display those fields horizontally rather than vertically. You might also use this so that narrow fields (like Date or Integer) don't take up the full width of the form.

Here you can also indicate whether the field should be Required, and you can choose to hide the field's label (i.e., Name).

6 Advanced

If needed, you can adjust the field's Key value. This can be important when you're using the field in other workflow actions. Here you can also choose to Show on Results Grid, which will display the value of the field in the Workflow List when viewing submissions.

Let's pause for a moment to talk a little bit more about the Column Span setting referenced above. The width of your form is broken up into 12 equal sized columns. So, adding a field that is 12 columns wide means that the field will be the full width of the form. If you want multiple fields on the same line/row, you can reduce the widths of the fields. For instance, a field that is six columns wide can be on the same line as another field that is six columns wide. In that case both fields would be half the width of the form. Or you could have four fields that are each three columns wide, allowing all four fields to be on the same line. The key is remembering you have 12 columns total to work with.

Navigating the Form Builder

Each form has settings that are broken down into five areas. These areas can be accessed by clicking the corresponding tab near the top of the page when editing a form, or by clicking on an area when viewing the list of forms under Tools > Form Builder. So far, we've only been focusing on one of those areas, the Form Builder itself. Now let's take a look at some of the other features and functions that are available in the other areas.

Submissions

This is where you'll find a filterable list of the form's submissions. Clicking on one of the rows will bring you to the Workflow Detail page for that submission. The grid actions let you do powerful things, like launch a workflow for each submission.

Communications

After a form has been submitted you have two options for sending automatic emails. You can send a Confirmation Email to the person who submitted the form, and you can send a Notification Email to recipients of your choosing. In either case you have the option of using a pre-configured Email Template or a custom email that you create on the page.

The Notification Email is a little unique. Here you have the option of sending the email to a Campus Topic Address. Campus Topics and the associated email addresses are configured for each campus under Admin Tools > General Settings > Campuses.

Settings

The settings area is divided into two parts, General Settings and Completion Settings. You won't make changes here very often, but you should be familiar with some of the options available to you.

1 Name/Description

Here you can edit the name and description of your form. These are initially set when the form is first created. Don't skimp of these fields, as a clear name and description can help you and others identify exactly what this form is for.

2 Template

If you built your form from a template, then the name of the template will appear here. You can apply a template to a form that was created without one, but best practice is to initially create the form using the template. You may need to refresh the form for changes to the template to apply. For more details see the Form Builder Templates section below.

3 Category

You can change the category for this form by selecting one from this field. By default, it will be the category that was selected when the form was initially created.

4 Is Login Required

Enable this if the person must be logged in to complete the form.

5 Form Entry Starts/Ends

People will not be able to access the form outside of the date range provided here. The start date is inclusive, so setting this to January 1st would allow people to access the form on January 1st. The end date is not inclusive, so providing an end date of December 31st means people won't be able to access it after December 30th.

6 Completion Settings

When the person submits the form, you have two options for what happens next. You can provide a message that will be shown to the person on the screen, or you can redirect the person to the URL provided.

Analytics

The Analytics page lets you see, for a selected timeframe, how many times the form has been viewed and how many times it has been submitted. There is also a Conversion Rate indicator, showing the percentage of people who viewed the form and then proceeded to complete it.

As noted near the top of the block, these statistics are only collected if the Workflow Entry block hosting the form is configured a certain way. Within the Workflow Entry block's settings, you'll need to enable Log Interaction when Form is Viewed and Log Interaction when Form is Completed to gather these statistics.

Form Builder Templates

Often, you'll have multiple forms that share similar configurations. For instance, you might want a consistent header across several forms, or you might want all of your forms to include specific Person Entry fields. That's where Form Templates come in, saving you time by letting you create a template and then apply that template to your forms. On top of that, the settings you define in your template can't be changed by a person editing the form, so you can rest assured that your template configuration will be applied exactly as intended.

To create or edit form templates, navigate to Admin Tools > General Settings > Form Builder Templates. Pictured below is an example template showing the different options you have. These are the same settings, and have the same functions, as the form settings described in previous sections above.

1 Name/Description

Be sure to provide a good name and description. When selecting a template to use for a form, only the template's name is visible.

2 Is Login Required

Enable this if all forms using this template should require a login.

3 Form Headers and Footers

Adding these to your template is a great way to ensure a consistent look across forms. While the headers and footers provided on the template cannot be modified when editing the form, the form will have additional editable header and footer areas that can be edited.

4 Person Entry Settings

Typically, you'll want to gather information about the person filling out the form, so it makes sense to set up Person Entry at the template level. This also ensures the same data is being collected across forms.

5 Confirmation Email

You can define settings for the confirmation email at the template level, ensuring that people who complete the forms get a consistent confirmation message. Like other template settings, the Confirmation Email can't be changed on the form itself, but you'll still be able to configure the Notification Email.

6 Completion Settings

This is another area where you can ensure a consistent experience when a form is submitted. The same options that are available on the form are available here, allowing you to either display a message or redirect the person to a new page.

Managing Workflows

On the workflow entry screens you may have noticed a Manage link to the right of the workflow name. You’ll only see this link if you have Edit access to the workflow type.

Clicking this link will take you to a grid of all the workflows for this workflow type. This grid allows you to filter the workflows by several different criteria including:

• Workflow Name
• Initiator
• Status Text
• Activation Date (the date it was launched)
• Completion Date
• State (is it currently active or completed)

Clicking on a workflow will show you its details.

You might have noticed the Delete button near the bottom of the grid in the screen pictured above. You can select one or more workflows from the list and use this button to delete them all at once. Keep in mind that because deleting workflows can take some time, the delete is performed in the background.

Viewing Workflow Details

After clicking a workflow from the grid above you’ll see the details of the workflow instance. From here you can see the state of all of the workflow attributes as well as all the activities that are in process or have completed.

1 Workflow Summary

This area shows the name, initiator and the activation date and time. These values can be updated in the edit mode.

2 Workflow Status

The header also includes the workflow type and status of the current workflow.

3 Workflow Attributes

Next you will see a listing of all of the workflow attributes and their values. In edit mode you can change any of these attributes.

4 Edit Button

The edit button allows you to change any of the properties, attributes or activities of the workflow.

5 Notes

See notes specific to this workflow.

Editing Workflow Details

Viewing the workflow details page gives you a clear view about the status of a specific workflow with the ability to edit any of its settings. Let's take a tour around this page showing each feature.

Details Tab

The details tab gives you an overview of the state of the workflow.

1 Workflow Summary

This area shows the name, initiator and the activation date and time. These values can now be updated in the edit mode.

2 Workflow Attributes

Next you will see a listing of all of the workflow attributes with the ability to edit their values if needed.

Activities Tab

The activities tab shows a listing of each activity that was activated through the life cycle of the workflow.

1 Activity Name / Description

2 Activity Completion Status

3 Assigned to Person / Group

This will show the currently assigned person or group. From this screen you can modify these values if you need to.

4 Completion Flag

You can manually mark the activity as complete if needed. While you could also mark an activity back to Uncomplete it will most likely be marked complete again by the workflow engine the next time it runs unless you alter the completion status of some of the activity's actions also.

5 Action List

Each action defined by the activity type is listed on this grid. You can see the last time the action was processed as well as its completion status and date. If you would like to re-run an action, you can choose to uncheck its completion checkbox. As long as the activity is still active, this action will be re-run. You can also mark an action as complete. This is helpful if your workflow accidentally gets stuck on an action due to improper configuration.

My Workflows

The tools described above are great for working on workflows of a specific workflow type. However, there are times you just want to see the workflows that are assigned to you or that you have initiated. You can track active workflows that are related to you under Tools > My Workflows.

1 Initiated By Me / Assigned To Me

This toggle allows you to filter the workflows by:

• Initiated By Me: Those that you started. For example, if you opened an IT Request it would be listed here.
• Assigned To Me: These are the active workflows that are assigned to you. This includes workflows that are assigned to a group that you are a member of. Using this toggle is a great way for you to track your work and what needs your attention.

2 Active Types / All Types

This toggle determines which workflow types will be displayed.

• Active Types: This will only show workflow types that have active items related to you. Using this option helps to reduce the clutter and noise by showing only workflow types that need your attention.
• All Types: This will display all workflow types you have security to view.

3 Workflow Types

Below the toggles you'll see a listing of all the workflows you have security to view. If a workflow has active requests that you’re related to, a small number will appear at the top of the workflow type showing a count of the related workflows.

4 Workflow Grid

When you click on a workflow type it will list the workflows that are related to you. Selecting one of them will take you to the workflow details screen.

Mini My Workflows

You'll notice that there is a miniature version of My Workflows on the homepage. This acts as a reminder to the individual of their task list as well as providing a quick link to the workflow.

This block has several settings that allow you to customize it. These settings include:

• The ability to filter the results to a specific category(s)
• To include child categories
• To show only workflows you are assigned to
• To show only workflows you initiated
• The markup that is displayed can also be fully customized using HTML and Lava.

Using these settings, along with the power of HTML/Lava, you can reformat this block several different ways. Some organizations might even move it into the main zone on the page to give it more space.

Non-Persisted Workflows

Non-persisted workflows are executed but the attribute values are never written down (or in tech terms never written to the database). They exist only in the computer's temporary storage and go away when done. These types of workflows are great when the entire workflow will be processed immediately and will then be completed.

The check-in workflow is a non-persisted workflow. After the check-in process is complete there is no need to store all of the workflow attributes that helped the system pick the right room for the individual. Many of the entity trigger workflows may turn out to be non-persisted. These workflows will be used to make quick decisions about the nature of an update to the data. Keeping the workflow around won't provide benefits in most cases.

Persisted Workflows

Persisted workflows write their state and status down. This allows them to run over long periods of time without forgetting their status. Most workflows that individuals interact with will be persisted (e.g., IT Requests, Facility Requests, HR processes, etc.). This allows the workflow to live for hours, days or even years.

Persisted workflows should also be used when a history of what occurred is important. These types of workflows allow you to go back and see what happened when.

Morphing Persistence

Just because a workflow starts out as a non-persisted workflow doesn't mean it has to stay that way. There is a workflow action called "Workflow Persist" that will change the current workflow to a persisted workflow. This is commonly used with workflow types that start with an entry form.

Picture this - a person comes to the first entry screen of a workflow and then changes their mind and closes the page. What happens? In a persisted workflow the loading of the entry screen started a new workflow that is now stored in the database. In a non-persisted workflow, nothing happens. Because of this, it's common for entry workflows to start as non-persisted and then change to persisted after the first entry screen is completed.

Workflow Details

Workflow types are configured under Admin Tools > General Settings > Workflow Configuration. After adding the workflow, we'll complete the detail section.

1Non-Persisted

Note that this workflow is not automatically persisted. Workflows that start with an entry form are usually configured this way to keep workflows from being added to the database when the person clicks on the form but never enters anything.

2Icon

Note that we have also given our workflow a custom icon so that it stands out a bit. These are simply FontAwesome CSS classes. See the FontAwesome site for a listing of all the icons.

3Logging

We've set our logging level to Action so we can see everything that is going on under the hood.

Workflow Attributes

Next, we will define all the attributes for our workflow. The attributes for the position request workflow are pictured below. Make note of the different field types for these attributes, as this workflow uses several of them.

Workflow Activities

Finally, we'll define the activities and actions for our workflow. The activities for this workflow are shown below. Note how the Initial Entry activity is in green. This means that it's configured to activate when the workflow is initially activated.

Let's walk through each activity now to look at its actions. We won't look at each setting of each action, but we'll give you an idea of the purpose of each.

Initial Entry

The purpose of this activity is to get the person's position request details. Some of these details will depend on whether they are asking for a full-time or part-time request.

1Entry Form

Initial entry form that asks for details about the position. One of these fields, Type, will allow the person to note if the position is full-time or part-time.

2Persist

Next, we persist the workflow, now that the person has entered information, so that we can maintain the values over time.

3Requester

We can now set the requester for the workflow with the current person who just entered the form.

4Name

Another setup step is to provide the workflow with a name. This name will be used on the various grid displays.

5More Information

Now we'll start asking for more information. This next action will get further details if the person requested a full-time position. Note that an action filter limits this entry form to only be displayed when the person selected full-time as the position type.

6Full Time

The next step sets the position hours to 40 if the person selected full-time, using action filters.

7Part Time

This action collects information for part-time positions. It also uses filter actions to only display when appropriate.

8HR Entry

Our final action activates the HR Entry activity to handle the next step. This action is set to mark the current activity as complete when it runs.

HR Entry

This activity is responsible for getting additional details from the human resources department. It has the following actions.

1Assign

The first action assigns the activity to Alisha Marble, the human resources representative for the organization. This tells the workflow who is responsible for entering the human resources information.

2HR Entry

The next and final action is the human resources entry screen. This entry form is set to email the assigned person when the action is active. This saves us from having to add our own email action. The command on this entry form is set to activate the next step, which is the approval process.

Approval Process

This activity is responsible for getting the approval for the position. Achieving this might be easier than you thought. Consider these actions.

1Approver

Just like the HR Entry, we assign this activity to the approver who was entered by human resources.

2Approval Information

Then we add an entry form to get the approval information. This form has two commands: one for Approve and the other for Deny. Each of these commands launches an activity to process actions for each response. This entry form also has to be configured to send an email. This email has the Include Actions In Email enabled, which allows the individual to approve or deny the request right from the email.

Approved / Denied Activities

These activities are configured pretty much the same way, so we'll look at them together.

1Approve or Deny

The first action marks the request as either approved or denied.

2Response to Requester

Next, we email the requester with the approval response.

3Response to HR

Then, we send an email to the human resources representative so that they are aware of the approval state.

4Complete

Finally, we mark the workflow as complete.

Workflow Tips

Below are some tips to keep in mind when creating new workflows.

• There are different ways to use workflows to send emails to groups. One approach is to set up an attribute that defines the group, then add an Email Send action type pointed to the attribute. Below is an example of what that would look like.

  

  1 Field Type

  Be sure the Field Type is set to "Group" so you can select the group you need.

  2 Default Value

  Use the drop-down to select the group that should receive the email.

  

  1 Action Type

  Select "Email Send" to have the workflow send an email.

  2 Attribute Value (Send To Email Address)

  The attribute that was configured above can now be selected from the drop-down menu. This will send an email to the "Children's Volunteers" group, according to the workflow attribute setup.

• While not required in all cases, it's wise to have your last action set the activity as complete when it's done. If you don't set this, all of the actions will need to be complete before the activity is marked complete. And if you're using action filters, this might not always occur.
• Don't forget that you can activate a workflow from a workflow. If there's something small that isn't working quite right in your big workflow, consider creating a small helper workflow to get the job done.
• There are many resources to help you build the workflow you need. Aside from the Workflow Actions Documentation, other guides may give insight into building the right workflow the right way. For example, our Engagement manual has an entire chapter on Connection Workflows.

Unattended Check-in

You’ll notice the check-in workflow on the Workflow Configuration screen. This is the workflow that runs Rock's check-in system. Unless you know exactly what you’re doing, we recommend that you do not alter this workflow.

Person Data Error

The Person Data Error workflow is an example of a workflow that launches from the action menu on the Person Details screen. It allows your organization's staff to note any issues with the data that they might not know how to fix. This is a great pattern to use when you go to create your own person profile actions.

Photo Request

This is another example of a workflow that launches from the action menu on the Person Profile page. After ensuring the person hasn't opted out, this workflow type will present a form to the person who launched it, where a custom message can be provided. The custom message, and a link to upload a photo, will be emailed to the person. The email also contains opt-out and unsubscribe options for the person.

Request Assessment

This workflow also launches from the action menu on the Person Profile page. The purpose of this workflow type is to send an email to a person to request that they take one or more of Rock's assessments. The person who initiates the workflow is asked which assessments should be requested and has the option of providing a custom message that will be included in the email.

External Inquiry

This workflow is used on the Contact Us page of the external website. It's meant to help direct your guest's questions to the correct staff. It also helps to provide accountability that your guest's questions will be answered in a prompt timeframe.

Facilities Request / IT Support

These two workflows act as a request ticketing system for your facilities and information technology teams. Using them allows your staff to report issues or request new services.

Profile Change Request

A workflow of this type will be launched from the My Account page on the external site when a person clicks the Request Additional Changes button. The person will type their request and submit it, at which point the workflow will alert an assigned staff member or volunteer via email. The staff member or volunteer can then provide a resolution for the item, which will be emailed to the initial requester to notify them that the change has been made.

Adding Notes From the Workflow Details

When looking at the details of a workflow you'll notice that you have the option to add notes. This is a great way to be able to provide context or additional information at any time (even after a workflow has been completed).

Adding Notes From Entry Forms

Another way to add notes is from entry forms. You'll notice on the Form action there is a setting to Enable Note Entry. When it's set, you'll see the note entry form next to the selected form fields.

Adding Notes From Workflow Actions

The final way to add workflow notes is using workflow actions. This allows you, the workflow author, to automatically create notes about the workflow processes.

1 Note

This is the text of the note. Be sure to use Lava for extra power.

2 Note Type

When you add notes using actions, you can style the note in several different ways with Note Types. These note types are defined under Admin Tools > General Settings > Defined Types > Workflow Note Types.

3 Is Alert

Setting this property will cause the note to always be at the top and highlighted with the alert styling.

Attributes

Attributes are the most commonly accessed merge fields for workflows. Let's dig in to see how we can add strength to our workflows using the power of Lava and workflow attributes.

Any attribute value can be referenced using the notation {{ Workflow | Attribute:'AttributeKey' }}. By default, the attribute key is the name of the attribute with all of the spaces removed, although you can provide your attribute with a different key if you wish. So, if you want to display the value stored in the Attribute Position Title, you’d use {{ Workflow | Attribute:'PositionTitle' }}.

Referencing an attribute will always return the formatted value of the attribute. For example, if the Requester attribute was a Person type attribute, the {{ Workflow | Attribute:'Requester' }} merge field would return the full name of the person.

{% assign CurrentPerson = Workflow | Attribute:'Admin','Object' %}
{% assign years = Workflow | Attribute:'Requester','Object' | Attribute:'BackgroundCheckDate','Object' | DateDiff:'Now', 'Y' %}
{% if years and years < 2 %}True{% else %}False{% endif %}

{% assign isStep1Ready = Activity | Attribute:'Step1Ready' %}
{% assign isStep2Ready = Activity | Attribute:'Step2Ready' %}
{% if isStep1Ready == 'Yes' and isStep2Ready == 'Yes' %}True{% else %}False{% endif %}

Workflow

The workflow item represents the current workflow instance. The following merge fields are available:

Workflow = {
    "Id":,
    "Guid":,	
    "Name":,
    ""Description":
    "Status":
    "WorkflowType = {
        "Id":,
        "Guid":
        "Name":,
        "Description":
        "Order":
        "WorkTerm":
        "Category": = { 
            "Name": 
            "Description": 
        }
    }
    "Activities":[]
    "ActivityTypes": []
}

Current Activity

The activity merge object has the following fields available.

Activity = {
    "Id":,
    "Guid":,	
    "AssignedPersonAliasId":,
    "AssignedGroupId":,
    "ActivatedDateTime":
    "WorkflowId":,
    "Workflow":,
    "ActivityType = {
        "Id":,
        "Guid":
        "Name":,
        "Description":
        "Order":
        "ActionTypes": []
    }
}

Current Action

The action has the following merge fields available.

Action = {
    "Id":,
    "Guid":,	
    "ActivityTypeId":,
    "ActivityType":,
    "ActionType = {
        "Id":,
        "Guid":
        "Name":,
        "Order":
    }
}

Global Attributes

Rock’s global attributes are also available for actions that support Lava. You can get a full list of these attributes under Admin Tools > General Settings > Global Attributes. These attributes can be accessed through Lava using:

{{ 'Global' | Attribute:'[AttributeKey]' }}

Additional Merge Fields

{
    "FirstName": "Alisha",
    "NickName": "Alisha",
    "MiddleName": "Mary",
    "LastName": "Marble",
    "IsDeceased": false,
    "PhotoId": 56,
    "BirthDay": 10,
    "BirthMonth": 10,
    "BirthYear": 1961,
    "Gender": 2,
    "AnniversaryDate": "1980-04-09T00:00:00",
    "GraduationDate": null,
    "Email": "alisha@rocksolidchurchdemo.com",
    "IsEmailActive": true,
    "EmailNote": null,
    "EmailPreference": 0,
    "ReviewReasonNote": null,
    "InactiveReasonNote": null,
    "SystemNote": null,
    "PrimaryAliasId": 1,
    "FullName": "Alisha Marble",
    "BirthdayDayOfWeek": "Friday",
    "BirthdayDayOfWeekShort": "Fri",
    "PhotoUrl": "/GetImage.ashx?id=56",
    "BirthDate": "1961-10-10T00:00:00",
    "Age": 52,
    "DaysToBirthday": 45,
    "Grade": null,
    "GradeFormatted": "",
    "CreatedDateTime": null,
    "ModifiedDateTime": "2014-08-26T21:28:56.99",
    "CreatedByPersonAliasId": null,
    "ModifiedByPersonAliasId": 1,
    "Id": 1,
    "Guid": "ad28da19-4af1-408f-9090-2672f8376f27",
    "UrlEncodedKey": "EAAAACE88i304vQJcwoNWW6P7fZ!2bSxiGgjyCooBFy4H332mMnPJoySCsXjQXVMJF87MynUFCAKPz4gIs1RshCy3dL7M!3d",
    "ConnectionStatusValue": {
        "Value": "Member",
    },
    "MaritalStatusValue": {
        "Value": "Married",
    },
    "PhoneNumbers": [
    {
        "NumberTypeValue": {
            "Value": "Mobile",
        },
        "CountryCode": "1",
        "Number": "5555555555",
        "NumberFormatted": "(555) 555-5555",
        "IsMessagingEnabled": true,
        "IsUnlisted": false,
        "NumberFormattedWithCountryCode": "+1 (555) 555-5555",
    }],
    "RecordStatusReasonValue": null,
    "RecordStatusValue": {
        "Value": "Active",
    },
    "SuffixValue": {
        "Value": "Ph.D.",
    },
    "TitleValue": {
        "Value": "Mrs."
    }
}

Editing A Workflow Type

To be able to add or edit a workflow type, you’ll need Edit access to the workflow configuration page
(Admin Tools > General Settings > Workflow Configuration)
and the Workflow Type Detail block on it. Currently, only the Rock Administrator security role has access to edit workflow types.

Workflow Navigation Page

The workflow navigation page (Tools > Workflows) is a great place for your staff to start and manage workflows. Below is a summary of the security needed to interact with the various components of this page.

1View Permission

One must have View permission to the workflow category in order for it to display. The category also must be selected in the block settings to be shown.

2View Access

Once the category is displayed, the current person must also have view access to the workflow type in order for it to be displayed on the list.

3View List

If the logged in individual has View List access to the workflow type, they'll also see the link to be able to view the active/completed workflows of this type.

Workflow Entry and URL Links

The following security is required for the Workflow Entry block:

• The person must be authorized to View the workflow type in order to enter information.
• The first active action form that the person is assigned to will be displayed.
• The person must also be authorized to either Edit the block or View the activity type.

Workflow List

The Workflow List block requires that a person must be authorized to Edit workflow types in order to view a list or add/edit/delete a workflow.

Workflow Detail

The following security is required on the Workflow Detail block:

• The person must be authorized to View the workflow in order to view read-only details.
• The person must be authorized to Edit the block, or Edit the workflow, in order to edit the workflow.

My Workflows

The My Workflows block has the following security settings.

1Authorized

The person must be authorized to View the workflow type.

2Criteria

Displays workflows for any activity that meets the following criteria:

• Workflow type is active
• Activity is active and has an active form
• The person must be authorized to View the activity

3Assigned

If viewing Assigned to, the person must be assigned to the activity

4Initiated

If viewing Initiated by, the workflow must have been initiated by the person.

Workflow Entry

The Workflow Entry block checks for a WorkflowId or WorkflowGuid parameter in the URL. If found, it will load the existing workflow. If parameters are not included, or a workflow is not found, a new workflow is created (in this case, a WorkflowTypeId query string parameter is required). Either way, the workflow is processed, and the block will look for the first active form action on the first active activity.

If a command query string parameter is included, the block will immediately process the form, assuming the person selected the included action.

The out-of-the-box workflow entry page is configured with the route of http://yourservername/WorkflowEntry/17. Note that in this case, 17 is the WorkflowTypeId.

Attribute Values

When working with workflows and attributes, it's helpful (actually it's pretty much essential) to know how those attributes store their values. Below is a list of a few commonly used attribute field types, with a description of how the value is stored internally.

The full list of field types can be found in our Workflows & Lava documentation.

When creating workflow actions that update an attribute value, make sure to reference this list so that your attribute values get set correctly.

Configuring a Webhook to a Workflow

You configure the linkage from a webhook to a workflow using a Defined Value. These are configured under
Admin Tools > General Settings > Defined Types > Workflow Webhook.
Each webhook that comes in will go through this list to determine which workflow types to launch. That determination is made by evaluating the Lava in the Process Request attribute of the Defined Value. If the Lava returns 'True' a workflow of that type will be started.

All of the Defined Values will be considered for each webhook that is called. All of the defined values whose Process Request Lava returns 'True' will run. It's important that this template is very discerning in making sure that only the correct workflow types are launched. One way to simplify this matching is to use query string parameters in the URL you define in your webhook. The default URL you provide for the webhook is:
http://rock.yourchurch.com/Webhooks/LaunchWorkflow.ashx
To help in your matching you could tack on a query string parameter such as:
http://rock.yourchurch.com/Webhooks/LaunchWorkflow.ashx?WorkflowTypeId=12
You could then provide the following template for your Process Request.

{% assign workflowTypeId = 'Global' | PageParameter:'WorkflowTypeId' %} {% if workflowTypeId == '12' %} True {% else %} False {% endif %}

This makes the selection of the workflow type very easy.

Ok, we've now discussed how to select the workflow type to launch. Now let's look at ways we can pass information to those workflows. You'll first notice that you can configure a Lava template for setting the Workflow Name. This allows you to customize the name on each run based on information from the webhook call.

You can also list attribute keys from the workflow and provide Lava templates for setting their values. The challenge here is knowing what data is available to you. The Defined Type screen has a feature that shows/hides these available fields. The basic items are:

• Url
• RawUrl
• Method
• QueryString
• RemoteAddress
• RemoteName
• ServerName
• RawBody
• Headers
• Cookies

Each of these items can have a lot of child properties. The documentation on the Defined Type screen shows some of these details, but the actual values will change greatly based on the calling service. We recommend that you start by setting various test attributes with items like 'RawBody' to see what is available.

While you can put Lava into the Workflow Attribute configuration on the Defined Value it's recommended that a majority of that logic be done inside of the workflow using the RawBody. The Lava on the Defined Value can't contain special characters like a | that are required in Lava filters.

Example
For instance if you passed the RawBody into the workflow using the attribute key of 'Body', then the Lava below could be used to access properties of the body.

{% assign body = Workflow | Attribute:'Body' | FromJSON -%} {{ body.propertyname }}

Workflow Configuration for SMS Pipeline

As you've learned throughout this guide, there are lots of different ways to configure your workflow types. The example below is not intended to be a set of instructions that you must follow exactly for your workflow to function. We'll go over other options a little later. For now, we'll walk through an example just to explain the features.

First, keep in mind that the pipeline can send the information it has to your workflow automatically. For instance, your workflow configuration doesn’t require an action to identify the person. You’ll still need workflow attributes to store that information, so that’s where we’ll start. In this example we’ve set up only a few attributes that the pipeline can populate. See below for the full list.

These attributes allow the person, their phone number and the content of their SMS text message to be sent directly to the workflow. From there, you can perform any number of Actions or Activities using those attributes.

In the example pictured below, we’ll add a Person Note that contains the person’s name and the text of the SMS message they sent.

As you can see in the above example, your workflow configuration for pipelines won’t be very different from other kinds of workflows. Actions and Attributes are set up and used in the same ways. However, there is some configuration you’ll need within the SMS Pipeline itself to make it all work. We’ll cover that in the next section.

Working with the SMS Pipeline

After your workflow has been configured, you're ready to add it to the SMS Pipeline. In this section we'll highlight the pipeline configuration related to workflows.

For information on SMS Pipelines in general, see the SMS Pipeline chapter of our Communicating with Rock guide.

Pictured below is a basic example of a workflow configuration in the pipeline. Keep in mind the workflow configuration that was described in the prior section, because it will be referenced here.

1 Workflow Type

This is the workflow type that we want to launch for an SMS message.

2 Pass Nameless Person

You can disable this setting to prevent Nameless People records from being sent to your workflow. We’ll talk more about working with Nameless People below.

3 Workflow Name Template

This field lets you dynamically assign the name of each launched workflow, for each SMS message received. In this example, the workflow name would be "SMS From Ted Decker" if Ted Decker sent the message.

4 Workflow Attributes

This is where you can feed information from the SMS message directly into your workflow. You'll use the Key value of the workflow's attribute in the first field. In the second field you'll add the Lava that identifies how you want to fill in that attribute's value.

As described above, your pipeline configuration can send attribute values directly to your workflow's attributes. In the next section, we'll look at the details of how this works and the different attributes you can set.

Using Attribute Set to Initiator

There are some reasons why you might want to have the workflow find values for its attributes instead of sending them from the pipeline. The first consideration is maintenance. The workflow attributes and the pipeline configuration must be kept in sync to work properly. Using the Attribute Set to Initiator approach instead, you don't have to worry about changes to the pipeline impacting your workflow's functionality as long as your workflow accounts for different scenarios.

The above point leads to the second consideration, which is flexibility. Using a method like Attribute Set to Initiator means the workflow can be launched from a variety of different sources. It will be more difficult to use the workflow in other contexts if it's designed to rely on specific data from the pipeline.

1 Attribute Set to Initiator

The person who sent the SMS message is the initiator. By assigning the initiator to the "Person" attribute, we now have the person’s record in the workflow.

2 Attribute Set Value

Here we'll use some Lava to get the name of the person we identified above. We'll use the name in the next workflow action (see below) to see if the person has a record in Rock.

Let's pause here for a moment to mention Nameless People. When an SMS message is received, Rock will automatically try to identify the person. If the person isn't in Rock, a Nameless Person record is created. This special type of record gives Rock a way to keep track of the person even though all we have is their phone number. For more details, see the Nameless People section of our Communicating with Rock guide.

The next workflow action, pictured below, is where we'll check for a Nameless Person. Your workflow options are limited if you don’t have a person’s record to work with. However, that doesn’t mean your process needs to exclude Nameless People. For instance, you can send the person a link to create a profile as pictured in the example below.

1 Action Filter

This workflow action filter checks the name of the initiator, which we obtained in the prior action. If the person's name is "Nameless Person" then we know the sender of the SMS message doesn't have a record in Rock.

2 Send SMS Message

In this case, we'll send an SMS message to the person. We can do that because the Nameless Person record contains the phone number the person used to send their original message.

3 Message Attribute

The content of the SMS message the person receives is maintained as a workflow attribute in this example. The message encourages the person to visit the website to create a profile, so we'll know who they are going forward.

If it's not a Nameless Person record, then the workflow action described above wouldn't run. Instead, we now know the workflow has a complete person record in-hand. You can use that information to perform any other actions or activities you need. At this point in the workflow configuration, we've left the pipeline behind. From here, the same tools and features described earlier in this guide can be used to build the rest of your workflow according to your needs.