Writing Correlation Scripts

In general, a correlation query should meet the requirements of most deployments. However, if you need a more powerful correlation mechanism than a simple query can provide, you can write a correlation script with additional logic. Correlation scripts can be useful if your query needs extra processing, such as fuzzy-logic matching or out-of-band verification with a third-party service over REST. Correlation scripts are generally more complex than correlation queries, and impose no restrictions on the methods used to find matching objects.

A correlation script must execute a query and return the result of that query. The result of a correlation script is a list of maps, each of which contains a candidate _id value. If no match is found, the script returns a zero-length list. If exactly one match is found, the script returns a single-element list. If there are multiple ambiguous matches, the script returns a list with multiple elements. There is no assumption that the matching target record or records can be found by a simple query on the target system. All of the work required to find matching records is left to the script.

To invoke a correlation script, use one of the following properties:

correlationQuery

Returns a Map whose values specify the QueryFilter for the sync engine to execute.

correlationScript

Returns a List<Map> whose value is a list of correlated objects from the target.

You can invoke a correlation script inline, or using a script file. For example:

"correlationScript" : {
    "type": "text/javascript",
    "file": "myCustomCorrelationScript.js"
}

"correlationScript" : {
    "type": "text/javascript",
    "source": " var resultData = openidm.query("system/ldap/account", myQuery); return resultData.result;"
}

The following example shows a correlation script that uses link qualifiers. The script returns resultData.result—a list of maps, each of which has an _id entry. These entries will be the values that are used for correlation.

Correlation Script Using Link Qualifiers

(function () {
    var query, resultData;
    switch (linkQualifier) {
        case "test":
            logger.info("linkQualifier = test");
	        query = {'_queryFilter': 'uid eq \"' + source.userName + '-test\"'};
            break;
        case "user":
            logger.info("linkQualifier = user");
	        query = {'_queryFilter': 'uid eq \"' + source.userName + '\"'};
            break;
        case "default":
            logger.info("linkQualifier = default");
	        query = {'_queryFilter': 'uid eq \"' + source.userName + '\"'};
            break;
        default:
            logger.info("No linkQualifier provided.");
	        break;
    }
    var resultData = openidm.query("system/ldap/account", query);
    logger.info("found " + resultData.result.length + " results for link qualifier " + linkQualifier)
    for (i=0;i<resultData.result.length;i++) {
        logger.info("found target: " + resultData.result[i]._id);
    }
    return resultData.result;
} ());

Configure a Correlation Script Using the Admin UI

From the navigation bar, click Configure > Mappings.
On the Mappings page, select the mapping to correlate.
From the Mapping Detail page, select the Association tab, and expand Association Rules.
Expand the Association Rules area, click the drop-down menu, and select Correlation Script.
From the Type drop-down menu, select JavaScript or Groovy.
To enter the correlation script, do one of the following:
- To use an inline script, select Inline Script, and enter the script.
- To use a script file, select File Path, and enter the script path.
Tip
To create a correlation script, use the details from the source object to find the matching record in the target system. If you are using link qualifiers to match a single source record to multiple target records, you must also use the value of the linkQualifier variable within your correlation script to find the target ID that applies for that qualifier.
To save the script as part of the mapping, click Save.

Writing Correlation Scripts

Tip