Transfer List Component¶

Overview¶

The Transfer List component can dynamically generate, at design time, a list of objects and allow a user to select one or more objects. It is used in conjunction with a List Object Component on a previous page (step) of the activity to define the list of objects. This example shows a transfer list being used in the Cloud Studio LDAP connector Add Entry activity:

Transfer-list example from Cloud Studio LDAP connector

Component JSON¶

As the list-object component that precedes this transfer list is an essential part of its operation, this JSON fragment includes both the list-object and the transfer-list components:

"addEntry": {
   "displayName": "Add Entry",
   "properties": [
      {
         "name": "list-object-page",
         "type": "pagination",
         "children": [
            {
               "name": "list-object",
               "displayName": "Select Structural Class",
               "type": "list-object",
               "use": {
                  "ui": {
                     "selectObjectLabel": "Selected Structural Class: ",
                     "tableHeaders": [
                        "Name"
                     ],
                     "tableItems": [
                        "name"
                     ]
                  },
                  "discoveryType": "provided",
                  "orientation": "output",
                  "documentIdPath": "this"
               }
            },
            {
               "name": "continue",
               "displayName": "Continue on error",
               "type": "boolean",
               "defaultValue": false,
               "validators": [
                  {
                     "name": "required"
                  }
               ]
            }
         ]
      },
      {
         "name": "transfer-list-page",
         "type": "pagination",
         "children": [
            {
               "name": "transfer-list",
               "displayName": "Select Auxiliary Class",
               "type": "transfer-list",
               "widgetHint": "component:connector/transfer-list",
               "use": {
                  "ui": {
                     "mainTitle": "Object Classes",
                     "leftSubTitle": "Available Auxiliary Classes",
                     "rightSubTitle": "Selected Auxiliary Classes",
                     "showDefaultTypeIcons": false
                  }
               },
               "validators": [
                  {
                     "name": "min",
                     "args": [
                        0
                     ]
                  }
               ]
            }
         ]
      }
   ]
}

In the JSON describing the transfer-list, these properties can be configured:

type: The transfer list component type must be "transfer-list".
mainTitle: Title for the transfer list.
leftSubTitle: Subtitle above the left list.
rightSubTitle: Subtitle above the right list.
showDefaultTypeIcons: If true, LDAP object type icons are displayed.
args: Defines the minimum number of fields that must be selected in order to make the component valid. Can be [0] which allows for no selection to be valid and allow the user to continue to the following step.

Component Discovery¶

The connector is expected to provide the list of objects. This is provided in a manner similar to how the List Object component discovers its object list and the same method (getObjectList) in the activity is called. To distinguish the call to this method when called for a transfer list that follows a list object, switch the return value based on the page name of the step that is called. As shown in this example, the page name is resolved and then used to switch the formation of the object list:

@Override
public List<DiscoverableObject> getObjectList(
    DiscoverContextRequest<DiscoverableObjectRequest> objectListRequest) throws DiscoveryException {
  logger.info("Getting objectList for Activity: " + getName());
  List<DiscoverableObject> objectList = new ArrayList<DiscoverableObject>();
  try {
    LdapConnection ldapConnection = (LdapConnection) objectListRequest.getConnection();
    List<Properties> properties = objectListRequest.getRequest().getSelectionPath();
    String page = null;
    for (Properties property : properties) {
      if (property.getKey().equalsIgnoreCase(PROPERTY_NAME)) {
        page = property.getValue().toString();
        break;
      }
    }

    switch (page) {
      case LIST_OBJECT:
        objectList = ldapConnection.getObjectList(ObjectClassTypeEnum.STRUCTURAL);
        break;
      case TRANSFER_LIST:
        objectList = ldapConnection.getObjectList(ObjectClassTypeEnum.AUXILIARY);
        break;
    }
  } catch (Exception ex) {
    ex.printStackTrace();
    String msg = Messages.getMessage(Messages.LDAP_CODE06_MSG,
        new Object[] {getName(), ex.getLocalizedMessage()});
    throw new DiscoveryException(Messages.LDAP_CODE06, msg, ex);
  }
  return objectList;
}

Component Output¶

The transfer list returns to the connector its output in the form of a JSON string. This string must be converted back into an object before it can used. This is accomplished in the execute() method of the activity:

@Override
public void execute(ExecutionContext context) throws Exception {
  Map<String, String> functionalParam = context.getFunctionParameters();
  String transferList = functionalParam.get(TRANSFER_LIST);
  JSONObject transferListJsonObject;
  JSONArray selectedNameJsonArray;
  . . .
  try {
    transferListJsonObject = new JSONObject(transferList);
    selectedNameJsonArray = transferListJsonObject.getJSONArray(SELECTED_NAMES);
  } catch (JSONException e) {
    transferList = transferList.substring(transferList.indexOf('['), (transferList.indexOf(']') + 1));
    selectedNameJsonArray = new JSONArray(transferList.replaceAll("\\\\", ""));
  }
  . . .