How to use Split Steps in RapidPro

Oct. 13, 2015


Introduction

Split Steps are rules that "split," or direct, a Contact down a specific path in a Flow based on a Contact Field variable, Flow Field variable, Expression or Message Form variable. Split Steps are grey as opposed to blue Action Steps, indicating they move the Contact along without waiting for a response. They can be placed at any point in a Flow.
 
In the example below, you’ll note that upon starting the Flow the Contact is directed to the appropriate Step based on the settlement value present in their Contact Profile. If they’re a resident of the Ubumwe settlement and that location value is present in their Contact Profile, they’ll receive resource recommendations based on that location value. The same goes for the Batsinda settlement. 


Split by Contact Field

This options helps you to direct a Contact down the flow based on a piece of information already stored in their Contact Profile (e.g. gender or location). To use the Split by Contact Field option you can do the following: 

1. Navigate to the Flow tab and select or create the Flow you'd like to modify. 

2. Create a Connection to a new Step to open the Step Editor. If you're creating a new Flow, the Step Editor opens when you click the "Create Message" box. 

3. Navigate the Split Editor.

Note: When creating a Step, you may see the screen pictured below. This is called the Action Editor. You'll need to click the split icon in the top right corner of the Action Editor to navigate to the Split Editor. The Step Editor comprises both of these editors, as they can be used to create either an Action Step or Split Step. 

ActionBox

The Step Editor flips from the Action Editor to the Split Editor pictured below. 

Split by steps box


3. Click on the "Split by contact field" option. 

Split by contact field box


4. Select the Contact Field you'd like to use to split the Contact. In the example pictured below, we've selected the "Settlement" Contact Field.

Note: As we've done below, you'll need to specify the Field value options by writing them out. In this example we split by gender. The "Save result as" input doesn't apply to Split Steps. 

Split by gender box


5. In the Flow Editor, the example Split Step looks like: 

Split by contact field flow example

Split by Flow Field

A Flow Field differs from a Contact Field in that it explicitly pertains to values collected within a Flow during a Run. These values are collected via Response Rules designated via the Split Editor. 

In the example pictured below, "Water Source" is a Flow Field that can be referenced via a Step later in the Flow.


split by water source

To create a Split Step that directs a Contact based on a Flow Field Value: 

1. Navigate to the Flow tab and select or create the Flow you'd like to modify. 

2. Create a Connection to a new Step to open the Step Editor. If you're creating a new Flow, the Step Editor opens when you click the "Create Message" box. 

3. Navigate the Split Editor.

Note: When creating a Step, you may see the screen pictured below. This is called the Action Editor. You'll need to click the split icon in the top right corner of the Action Editor to navigate to the Split Editor. The Step Editor comprises both of these editors. 

The Step Editor flips from the Action Editor to the Split Editor pictured below. 

Split Editor


3. Click on the "Split by flow field" option. 

Split by water source


4. Select the Flow Field you'd like to use to split the Flow. 

In the example pictured above, we've selected the "Water Source" Flow Field. In this example we're creating a Split Step to which a Contact is directed if they indicated in a previous Step that their water source is either "Well" or "Stream" and also indicated in a next Step that they don't boil their water. These two responses indicate that the Contact is at risk for infection, and the Flow Field Split Step allows us to distinguish these individuals in order to provide situation-specific information to help them reduce risk. This process is illustrated in the flow below.

Example flow for split by flow field


Split by Message Form

Message Forms are a sequence of values delimited (separated) by space or plus signs. They allow you to collect data in a custom structure and validate it using Split Steps containing Response Rules. 

As an example, you might record the birth of a child by soliciting messages in the following format: 

birth [gender]+[name]+[mother's birth year], which could yield the result "birth f+Noel+1985".


In the case above, the term "birth" acts as a Keyword Trigger, initiating the Flow. 

To create a Flow that collects and evaluates the Message Form in the example above: 

1. Click the "gear" icon and select the "Edit" option in the drop-down menu to create the "birth" Keyword Trigger that will direct Message Forms to this Flow. 


2. Begin the Flow by creating a Split Step with an open-ended Response Rule to collect the Message Forms directed to this Flow via the "birth" Keyword Trigger and save the result as "Message."

3a. Remove the keyword trigger to isolate the submission as the flow variable @flow.message (Split by Message Form RuleSets may only evaluated flow variables). To do so, create a RuleSet that splits the initial message by expression. In the example pictured below, we apply the @(REMOVE_FIRST_WORD()) function to the incoming message (referenced using @step.value). The resulting expression should read@(REMOVE_FIRST_WORD(step.value)). 

3b. Save the resulting flow variable as "Fields" to yield only the values delimited by a plus sign. To review, the values we'll submit will follow the format [gender]+[name]+[mother's birth year]. Each bracket value is assigned its own field.Gender is the first field, name the second and mother's birth year the third.


4. Add a "Split by message form" Split Step that splits the first message field delimited by a plus sign. In this example, it's gender. Create a Response Rule for each gender that categorizes the short form values "m" or "f" as their long form counterparts, and save the resulting Flow Field as "Gender." 


5. Add a "Send an SMS response" Action Step that addresses incorrectly formatted "Gender" values and asks the Contact to resubmit. Because this Step is a dead-end, the Contact will exit the Flow after receiving the message. 


5 (a). In the example pictured below, we've formatted the error message to repeat the Contact's form submission using the @flow.fields variable and ask for another submission. Being that the Contact will exit the Flow at this Step, they'll need to resubmit the Message Form using the Keyword Trigger "birth." 


6. Add a second "Split by message form" Split Step that splits the second field value delimited by a plus. This time, it's the name of the child. Create an "is not empty" Response Rule that ensures the second field in the Message Form has a value, categorize it as "Has Name" and save the resulting Flow Field as "Name."


7. Add a "Send an SMS response" Action Step that addresses incorrectly formatted "Name" values and asks the Contact to resubmit. Do so by editing the previous error message format to include "Missing name field." Because this Step is a dead-end, the Contact will exit the Flow after receiving the message and will need to resubmit the Message Form using the Keyword Trigger "birth." 


8. Add a third "Split by message form" Split Step that splits the third field value delimited by a plus. This time, it's the mother's birth year. Add a "has a number between" Response Rule that ensures the second field in the Message Form has a valid birth year value and save the resulting Flow Field as "Birth Year."


9. Add a "Send an SMS response" Action Step that addresses invalid "Birth Year" values and asks the Contact to resubmit. Do so by editing the previous error message format to include "Invalid Birth Year." Because this Step is a dead-end, the Contact will exit the Flow after receiving the message and will need to resubmit the Message Form using the Keyword Trigger "birth." 


10. Finish the Flow by adding a "Send an SMS response" Action Step that confirms the Message Form submission by referencing the Flow Field values submitted by the Contact. 


To the Contact, Message Form submission will appear as simple as the exchange pictured in the example below.


The resulting Flow should look similar to the example pictured below.