Working with Variables in Extensions
Most Application Extensions need to use data that is created or maintained in a Flow.
For example you might want to create an Extension that:
gets the user's current location and displays it on a live map; or
sets a security token which is sent from the website running the Flow.
You use the following X‑Platform APIs to enable your Extensions to work directly with Flow variables:
getVariable: Gets the value of a Flow variable so its value can be used in the Application Extension.
setVariable: Sets the value of a Flow variable. The value is updated in the Flow when the user proceeds to the next Flow step.
setVariablesAsync: Sets the value of a Flow variable array. The value is updated immediately for use in the current Flow step.
Details and usage examples are provided below.
getVariable API
This API gets the value of any user or Variable. Simple types, Object types, Collections and enumerated (Enum) types are supported. The variable is retrieved from the server when the API is called, using an asynchronous method.
Sample syntax:
ctx.getVariable('textVar', function(data) {
//success
console.log('tested var:', data);
}, function(xhr) {
//failure
});In the example above, the value of the variable called textVar is written to the console. The failure handler is optional, or you may replace it with your own handler.
Sample syntax for Enum variable type:
ctx.getVariables(['ColorChoice'], function(data) {
console.log('ColorChoice from getVariables = ', data);
});
//getVar from extension
ctx.getVariable('ColorChoice', function(data) {
console.log('ColorChoice from getVariable :', data);
}, function(xhr) {
console.log('failed :');
});
console.log('failed :');
});In the example above, the value of the Enum variable array ColorChoice is written to the console. The failure handler is optional, or you may replace it with your own handler.
setVariable API
This API sets the value of any user or Variable. Simple types, objects, Collections and enumerated (Enum) types are supported. The value of the variable is updated when the end user clicks a Next or Done Flow step. If the method fails, the Flow continues without updating the value.
Sample syntax:
var newValue = "abcdefg"
ctx.setVariable('textVar', newValue);In the example above, a new value for the variable is defined, and then the value of the variable (textVar) is set to the new value.
Should a user proceed to the next Flow step but then click Back, a variable that was updated by setVariable will be reset to the its prior value.
setVariablesAsync API
This API sets the value of any user or Variable array without waiting for the next Flow step. Simple types, objects, Collections and enumerated (Enum) types are supported. The value is updated immediately for use in the current Flow step. If the method fails, the Flow continues without updating the value.
Sample syntax:
//set the vars using success (and fail) callbacks
ctx.setVariablesAsync({
userVar: 'user from ext',
textVar: 'text from ext'
}, function() {
//get the vars to test the value change.
ctx.getVariables(['userVar', 'textVar'], function(data) {
console.log('values after set', data);
});
}, function() {
console.log('set failed, please check logs for more info');
});
});
});In the example above, a new array is defined, and then retrieved.
Note
In some scenarios, if a user clicks Back after setVariablesAsync has been called, the updated values will not be reset, unlike standard variable reset behavior which occurs using setVariable.
Using Variables in Extensions: Examples
The following sections present simple examples that demonstrate how to manipulate objects (Custom Variable types) and collections. Each section provides one example for getVariable and one example for setVariable.
Working with Variables in a Simple Collection
The following example shows how to get the value of the first item in a simple collection (mySimpleCollection) and write that value to the console.
ctx.getVariable('mySimpleCollection', function(value) {
console.log(value[0]);
}, function() {
//handle error
}); The next example shows how to update the values of the variables in a simple collection. In this case, the new values are item1 and item2.
ctx.setVariable('mySimpleCollection', ["item1", "item2"]);Working with Object Fields
The examples in this section involve a Custom Variable type that contains a name field and an age field.
In the first example, we get the value of the name field, and use it to write a personalized greeting to the console.
ctx.getVariable('Object Name', function(person) {
console.log('Hello, ' + person.name);
}, function() {
//handle error
});The next example shows how to update the values of the object fields. In this case, the new values are Sami and 40.
ctx.setVariable('Object Name', {name: 'Sami', age: 40})Working with Object Collections
This section shows how to manipulate variables in a collection of objects. The following examples involve a collection (Employees Collection ) of two employees objects. Each object contains a name field and an age field.
In the first example, we get the name of the first employee in the collection and write it to the console.
ctx.getVariable('Employees Collection', function(employees) {
console.log(employees[0].name);
}, function() {
//handle error
})In the next example, we define new values for the fields in the object collection, and then update the Employees Collection with these new values.
var employees = [{
name: 'Julia',
age: 30
},{
name: 'name',
age: 31
}];
ctx.setVariable('Employees Collection', employees);