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.

1

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.

2

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.

3

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.

4

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

5

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.

6

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 our Inquiry example, 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 inquiry example there are activities for the initial entry of the request that process steps 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 on 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 user 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.

1 Workflow Type Navigation:

Shows workflow categories and the workflows 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. You should make this as detailed as possible since it acts as documentation for your workflow.

4 Activities:

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

5 Copy:

Many workflows are similar. To help you create new workflows that are similar to ones you already use, Rock allows you to make a copy of an existing workflow 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 and edit security. Security will determine who is able to view a workflow as well as manage (via the Edit permission) a workflow.

Editing A Workflow

Clicking the Edit button takes you to the edit screen for that workflow. 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.

6 Workflow 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:

Workflows are grouped into categories for organization.

8 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.

9 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-users.

10 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).

Advanced Settings

The next section is the Advanced Settings section.

The Advanced Settings section of the Workflow Configuration has some useful options, including the Completed Workflow Retention Period field. This is where you can specify how many days you want to keep a 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. Using the Completed Workflow Retention Period option allows you to routinely and automatically clean up your workflows. If you never want the workflow to be removed, leave the field blank.

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.

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 ().

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 activated at the beginning of a workflow. If this is set to 'True', the activities header will be shown in green to help you quickly identify startup activities.

5 Security:

Security on a workflow activity helps with activities that must interact with a user (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.

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 to complete it. Assignment only comes into play for activities that must interact with a user (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. Each of these action types are discussed below.

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 criteria 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 unfamilar 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.

Default Action Types

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

Workflow Entry Block

Many workflows will start with a user 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 a user.

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 user doesn’t even know that they are interacting with a workflow.

Person Profile Actions

You may have noticed that there is a menu 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 user 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.

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 Rock.Job.CompleteWorkflows 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.

User Entry 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.

1

The Form Header is a great place to introduce the purpose of your form and any background knowledge that might be needed. As a Rock user, 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...

2

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

3

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

4

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 your users 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 user'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 user, its form will be shown. This is a very powerful feature because it allows you to build complex interactions with the user.

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

1

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

2

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 user who clicked on the form but then left. Now that the user has entered information and executed a command, we will persist it.

3

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

4

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.

1

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

2

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.

Managing Workflows

On the workflow entry screens you may have noticed a Manage link next 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.

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. 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 it's settings. Let's take a tour around this page showing each feature.

Details Tab

The details tab gives you on overview on 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 them 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 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 accidently 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 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 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 user 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.

1

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 user clicks on the form but never enters anything.

2

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.

3

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 below.

Workflow Activities

Finally, we'll define the activities and actions for our workflow. The activities for this workflow are show 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 user's position request details. Some of these details will depend on whether they are asking for a full-time or part-time request.

1

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

2

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

3

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

4

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

5

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

6

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

7

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

8

Our final action activates the HR Entry action to handle the next step. This action is set to mark the 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.

1

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.

2

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.

1

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

2

Then we add an entry 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.

1

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

2

Next, we email the requester with the approval response.

3

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

4

Finally, we mark the workflow as complete.

Workflow Tips

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

• 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.

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 is launched 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.

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 /IT Request

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.

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 User Entry 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 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 Settings. 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": "jonedmiston@ccvonline.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's security role has access to edit workflow types.

Workflow Navigation Page

The workflow navigation page 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.

1

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

2

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

3

If the logged in individual has List View 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 user must be authorized to View the workflow type in order to enter information.
• The first active action form that user is assigned to will be displayed.
• The user must also be authorized to either Edit the block, or View the activity type.

Workflow List

The Workflow List block requires that a user must be authorized to Edit workflow type 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 user must be authorized to View the workflow in order to view read-only details.
• The user must be authorized to Edit the block, or Edit the workflow, in order to edit the workflow.

My Workflows

The My Workflow block has the following security settings.

1

The user must be authorized to View the workflow type.

2

Displays workflows for any activity that meets the following criteria :

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

3

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

4

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

Workflow Entry

The Workflow Entry block checks for a WorkflowId or WorkflowGuid parameter. If found, it will load the existing workflow. If parameters are not included, or 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 user selected the included action.

The out-of-the-box workflow entry page is configured with the route of http:///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 each of the different field types for attributes and a description of how its value is stored. 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 paramater such as:
http://rock.yourchurch.com/Webhooks/LaunchWorkflow.ashx?WorkflowTypeId=12
You could then provide the following template for your Process Request.

{% assign workflowTypeId = QueryString['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 Atttribute 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 require 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 }}

Text to Workflow Configuration

Text to Workflow is a defined type, so it’s located at Admin Tools > General Settings > Defined Types. Click the + button to create a new Text to Workflow defined value.

1 Value

This is the phone number people will text the keyword to in order to launch the workflow. This should be in the form of +16235524427 for Twilio.

2 Keyword Expression

This is the keyword people will text and that will launch the workflow. For instance, to match the keyword ‘neighborhood’ you could use the expression 'nei.*' (without the quotes). If you leave this field blank, Rock will match any request. Note that the first matching keyword will be processed and the remaining defined values will not be considered. It's a good idea to create a general catchall expression at the bottom of your defined types list to process any items that didn't match up with previous keywords.

3 Workflow Type

This is where you choose which workflow will be launched when the keyword expression is received.

4 Workflow Name Template

This Lava-enabled field is where you can create a string to use as the workflow name. For example, Request From {{FromPerson.FullName}} ({{FromPhone}}) See the listing below of available Lava merge fields.

5 Workflow Attributes

You can set Lava-enabled attributes and values for use in your Text to Workflow defined type, such as the name of the person who texted the keyword. See the listing below of available Lava merge fields.

The Workflow Attributes are Lava-enabled and give you a lot of useful options for how to execute your text to workflow.

Workflow Configuration

The next step is to set up your workflow. Again, the possibilities here are endless. It all depends on what you're trying to accomplish and how creative you want to be. For more information, see Configuring a Worfklow Type above. When configuring your workflow, there are a few things to keep in mind.

Getting the Person Attribute into Your Workflow

There are a couple of ways to identify the owner of the mobile number that sent the incoming keyword prompt. One way is to query using the ‘Run SQL’ action. Or you could use {{ FromPerson }} in a Lava merge field if all you want is the owner’s name as a text attribute. If you want a full Person Attribute, though, you can load the workflow initiator into your workflow attribute using the “Set Attribute to Initiator” action.

https://[YourExternalRockAddress]/Webhooks/TextToWorkflowTwilio.ashx

Troubleshooting

Sometimes things don’t go as planned. Mistakes and errors happen. Here are some common configuration issues that can happen, as well as some things to keep in mind as you set up and use Text to Workflow.