How and why to execute lookup through JavaScript

How and why to execute lookup through JavaScript

Lookup is the backbone of building data integrated user interface using AgilePoint eForms. A common need for many applications is to retrieve data from external sources. Ex. database, APIs, etc. The data on the user form (UI) can come from multiple sources. The AgilePoint form designer ‘eForms’ makes it very convenient to configure and consume lookups on the form. The lookup trigger can be based on various conditions/rules, which makes it possible to have a cascading type of lookup. However, there are use cases where data returned by the source needs to be massaged before it can be rendered/shown on the form. Ideally, if the source of the data is coming in the expected format then out-of-the-box configuration and execution options would suffice the need.

In the case of data massaging needs, the ‘executeLookup’ helper JavaScript method comes handy. Here is a scenario we can use to implement the concept. We would like to show a list of employees in a drop-down in a certain format where employee full name is associated with employee title. Ex. “John Rider – Project Manager”. For the implementation of this concept we can leverage AgilePoint’s API called GetRegisterUsers. This get API returns list of list of all the registered users in the AgilePoint system. Here are the steps to follow.

1. Create an auto-lookup, which calls GetRegisterUsers REST API. (I assume you know auto-lookup configuration, if not, please leave the comments). Just to complete the auto-lookup configuration, the API response needs to be bound a control. In this case, you can use the same target drop-down control you would like to populate with the users.
2. Drag and drop a button control on the form – this control is used to trigger the executeLookup eForm Helper method, concatinate full name and title, and bind the concatinated data back to the drop-down control using an another eForm Helper method called bindDataToCollectionControls. Please use button control’s “JavaScript Function” property under “Advanced” category to execute the “getUserData” function.

function getUserData() {
    var options = {};
    options.lookupName = 'GetRegisteredUsers';
    options.lookupType = eFormHelper.constants.lookuptype.namevalue;

    eFormHelper.executeLookup(options, function(result) {
        console.log(result.isSuccess);
        var users = [];

        result.data.forEach(function(value, index, array) {
            var user = {};
            user.Value = value.Value;
            user.Name = value.Value + ' - ' + value.Name; // concatinate full name with title
            users.push(user);
        });

        var userOptions = {};
        userOptions.fieldId = 'UserList'; // dropdown name
        userOptions.value = users;
        eFormHelper.bindDataToCollectionControls(userOptions);

    });
}