Launch From a 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 ti ti-settings 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 ti ti-settings 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 ti ti-settings icon in the grid. This feature is enabled by default for grids in Rock, so you’ll see the ti ti-settings 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.

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 ti ti-settings 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.

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.

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.