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 Jacada Interact 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 system variable. Simple types, objects, 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 system 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 its prior value.

setVariablesAsync API

This API sets the value of any user or system 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);

 

 

Revision:

Comments