UserData

Allowing for the centralised store of message content, the UserData enables content and text to be handled in one location and shared between any/all recipes.

For example, a name or phone number change in a process would be easily handled in one place ensuring all quoted names and numbers were changed.

Using UserData values also allows you to share the same message between multiple recipes, reducing duplication.


        "type": "SendMessageAction",
        "data": {
            "messageText": "${userData['join']}",
            "connectionName": "routing.rules",
            "recipients": {
                "addresses": [
                    "Alex"
                ]
            }
        }

...

    "UserData": {
        "Join": "Welcome to our programme!  Please SMS 'help' to +254 555-555-555 to get further instructions",
        "Help": "Help: gets this list. Join: joins our group. Leave: removes yourself from the group"
    }

Description A single UserData entry consists of a Variable and a Message. The Variable is the name, or key, that the Message can be referenced as. It is the shorthand for the content. Either can be any mix of letters and numbers.

In the example above a Send SMS Action is referencing a ‘Join’ UserData entry. When this Actions is executed a message will be sent to ‘Alex’ with the text ‘Welcome to our programme! Please SMS ‘help’ to +254 555-555-555 to get further instructions’ as the Variable ‘${userData['join']}’ is replaced by its corresponding Message.

The UserData above has two entries, one for ‘Join’ and one for ‘Help’. Each of these can be referenced in any recipe using the notation ${userData['VARIABLE']} where the expression will be swapped for the corresponding Message content.

To aid in the communication of the purpose of a user data entry, each entry has two additional properties; description and user friendly name. The value of these properties is best explained with the aid of an example.

Assume you have a user data entry whose key is organization. Organization may mean many different things to different people. This is where the additional properties provide clarity of intent and purpose. Suitable values of the properties below may be:

User Friendly name: Who do you work for?
Description: Enter the name of the company you work for.

User data types

There are four types of user data.

Text: This is a user data type whose value is a String. An example of such an entry is one whose key is ‘city’ and value is ‘Nairobi’.
Long text: This is a user data type whose value is a String. The difference between Long text and text is with Long text a magic wand from which Flang expressions can be selected is provided when populating the Value of the user data.
Contact Selector: The value of this user data type is a contact. The ‘Manage User Data’ section provides a contact selector allowing you to select a contact for the user data value.
Date Picker: This is a user data type whose value is a DateTime. Clicking on its value field or calendar icon next to it, reveals a date picker which allows you to choose a date and time of your choice.
Multi-selector dropdown: This user data type allows you to create a drop down list. To create a user data entry of this type, we may fill in the following values in the form.

Key: cars
User Friendly Name: which car do you like?
Description: Enter the car you would like.
Value: BMW
Mercedes
Kiira
Note that each of the entries for the value are on a new line.

You can supply values for the multi-selector dropdown by using a flang expression that will result into a string with values separated by newline characters.
For example, if we want to create a drop down with values from 1 to 10, you can use the following flang expression.

${(1..10).collect().join("\n")}

A multi-selector dropdown containing all the available contacts whose mobile number begins with "+245" can be as follows

${Contact.findAll{ contact -> contact.mobile.startsWith('+254') }.contacts*.name.join("\n"}}

You can mix both flang and non flang entries in the available value options of the drop down.

Default value: The default selected value for the drop down. This also supports flang. Using the above example flang expression, if we wanted the option 2 to be the default selection, we can either use the value "2" or the flang expression ${1 + 1}. The default selected value containing flang, however, will be overwritten once a value is selected and the flang will now be replaced with the value selected.

User data and activities

When creating user data you have the option to specify if when used in an activity, the user is allowed to provide avalue for the user data type or not.

This is done by checking/unckecking the option Set when Activity created? when creating/editing the user data entry.

When creating a collection, the when you check the option Set when Activity created? then in the activity that user data entry can be edited otherwise it can’t.

It is also important to note the various user data types appear in the activities as followings.

Text: Appears as a text box.
Long text: Appears as a text area with a magic wand from which flang expression can be selected at the side.
Contact Selector:Dropdown containing contacts, groups as smart groups
Multi-selector dropdown: A dropdown containing the values specified whilst creating the user data entry in the parent collection.

Catching nulls

If your userData variable may sometimes be empty when you reference it - for example an optional input field - then FLang will return '[Missing UserData key: VARIABLE]' as the result. If you want to avoid this and simply have FLang return an empty string then use userData.properties instead:

${userData.properties['optional-keywords']}

Links

Actions and Fallback Actions

Parameters A key value pair of Strings in the JSON format. The Message has a maximum length of 1600 characters.

UserData

0 Comments