How To

How do I migrate links created by OpenIDM 2.x to OpenIDM 3?

Last updated Jan 5, 2021

The purpose of this article is to provide a sample script, which allows you to migrate existing links within OpenIDM 2.x to the new format required in OpenIDM 3.


This article has been archived and is no longer maintained by ForgeRock.

Background information

As of OpenIDM 3, IDs for external systems (for example, in the links table) are no longer URL encoded. This means system object _ids in an existing links table will not be recognized by an OpenIDM 3 reconciliation process. 

In order to preserve existing links within the repository on OpenIDM 2.x installations, a migration script has been created which decodes the existing OpenIDM 2.x format links and rewrites them to be compatible with OpenIDM 3.

Migrating links


As with any migration, we strongly recommend testing the script in your own development or test environment before applying to production.

The following script can be implemented as a custom endpoint and invoked via REST in order to migrate the links within your existing repository:


{     "file" : "script/decodeLinks.js",     "type" : "text/javascript" }


(function () { var _ = require("lib/lodash"), linkQry = openidm.query("repo/link", {"_queryId": "query-all", "fields": "*"}), syncConfig ="config/sync"), linkTypes = {}, results = []; _.each(syncConfig.mappings, function (m) { if (!_.has(m, "links")) { linkTypes[] = { "source": m.source, "target": }; } }); _.each(linkQry.result, function (r) { var needsUpdate = false; if (!_.has(linkTypes, r.linkType)) { return; } if (linkTypes[r.linkType].source.match(/^system\//)) { needsUpdate = true; r.firstId = decodeURIComponent(r.firstId); } if (linkTypes[r.linkType].target.match(/^system\//)) { needsUpdate = true; r.secondId = decodeURIComponent(r.secondId); } if (needsUpdate) { results.push(openidm.update("repo/link/" + r._id, r._rev, r)); } }); return results; }());

For example, you can invoke this script with a REST call such as:

$ curl --cacert localcert.crt -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: password" -X GET "https://localhost:8443/openidm/endpoint/decodeLinks/*"

See Also

OpenIDM Installation Guide › Migrating to OpenIDM 3.0.0

How do I upgrade from OpenIDM 2.x to OpenIDM 3.x?

How do I migrate to OpenIDM 4.x from an earlier release?

Related Training


Related Issue Tracker IDs

OPENIDM-2091 (Migration script for encoded ids in the links table)

Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.