Flow variable or contact variable: how to decide

April 14, 2016

We’ve seen quite a number of RapidPro users who struggle to understand the difference between RapidPro variables. There are Contact variables, Flow variables, Step variables, Channel variables, Date variables and Extra variables.

In this post we will try to explain the difference between the main variables used in RapidPro: Contact and Flow variables.

First let us try describe the two variables:

  • @contact references the contact interacting with the flow. In most cases, this is the active contact - the person whose responses are being handled by the workflow. For example @contact.gender refers to the contact’s gender.
  • @flow variables refer to values collected at each RuleSet within a flow. @flow variables only reference values collected by the flow in which they're called. This allows you to refer to previously collected values or update contact fields with a value sent by a contact.

When do you use a flow variable and when a contact variable?

Let us look at how these variables work in simple flow:

In this flow we ask contacts 2 simple questions:

1. The first question is what their favourite colour is. Once we get a response, we want to add it to their contact profile (under Contacts) for future reference, e.g. if we want to target flows to users with a specific colour preference. We do do this by saving the response to the favourite colour question in the contact field called Favourite Colour:

2. The second question is what will they eat today. As you see in the flow above , we don’t save the response to this question in the contact profile as it is not relevant to have it there; what you will eat today may change tomorrow anyway.

So how does RapidPro handle these responses?

In the diagram below we simplified the actions taking place in RapidPro to handle the data captured by our flow.

How RapidPro handles data

Note that the numbering below corresponds with the yellow coloured numbers in the diagram.

1. Once a contact (in this example Peter) responds to the favourite colour question, the response is immediately saved as a flow result.

2. With the Update Contact action, we also save the response in Peter’s contact field Favourite Colour. Once saved there, we can always reference to it in any other flow when we are interacting with Peter by using variable @contact.favourite_colour.

3. The response to the food question is saved as a flow result. Since we don’t save it as a contact field, it cannot be referenced in a future flow or used to target specific users (disclaimer: provided we don’t for instance start the contact in another flow, but that’s a story for another day).

In the last message we send a message to Peter displaying some information:

4. @contact.name references the contact’s name, in this case Peter. This information is retrieved from Contacts where it has been saved by a previous flow.

5. @contact.favourite_colour refers to Peter’s Favourite Colour. This information is also retrieved from Contacts where it was saved earlier in the current flow.

6. @flow.food refers to what Peter is going to eat today. This information was collected earlier in the flow.

As soon as the contact exists a flow, we cannot reference flow results anymore (again: provided we don’t for example start another flow and use the captured results in the next flow). The only way to access flow results is if we save them as contact fields - using the action Update Contact - such as name, age, location, favourite colour, etc.

Not being able to reference flow results doesn't mean you can access them:

7. You can view flows results in RapidPro or download them. Or you can expose the data to an external application through the RapidPro API.

We hope this post has been useful. In case of questions or comments you can reach us at join@rapidpro.io. Or join the RapidPro User Forum.