As noted in Appendix E, "REST API Reference", Representational State Transfer (REST) is a software architecture style for exposing resources, using the technologies and protocols of the World Wide Web.

REST interfaces are commonly tested with a curl command. Many of these commands are used in this document. They work with the standard ports associated with Java EE communications, 8080 and 8443.

To run curl over the secure port, 8443, you must include either the --insecure option, or follow the instructions shown in Section 16.2.2, "Restrict REST Access to the HTTPS Port". You can use those instructions with the self-signed certificate generated when OpenIDM starts, or with a *.crt file provided by a certificate authority.

In many cases in this guide, curl commands to the secure port are depicted with a --cacert self-signed.crt option. Instructions for creating that self-signed.crt file are shown in Section 16.2.2, "Restrict REST Access to the HTTPS Port".

By default you start and stop OpenIDM in interactive mode.

The startup script starts OpenIDM, and opens an OSGi console with a -> prompt where you can issue console commands.

To stop OpenIDM interactively in the OSGi console, enter the shutdown command.

-> shutdown

To stop OpenIDM running as a background process, use the shutdown.sh script.

$ ./shutdown.sh
./shutdown.sh
Stopping OpenIDM (454)

If you start OpenIDM in the background, and the job stops immediately after startup, see Section 23.1, "OpenIDM Stopped in Background".

To disable ConsoleHandler logging, see Chapter 10, "Configuring Server Logs".

By default, OpenIDM starts up with the configuration and script files that are located in the openidm/conf and openidm/script directories, and with the binaries that are in the default install location. You can launch OpenIDM with a different configuration and set of script files, and even with a different set of binaries, in order to test a new configuration, manage multiple different OpenIDM projects, or to run one of the included samples.

The startup.sh script enables you to specify the following elements of a running OpenIDM instance.

By default, properties files are loaded in the following order, and property values are resolved in the reverse order:

If both system and boot properties define the same attribute, the property substitution process locates the attribute in boot.properties and does not attempt to locate the property in system.properties.

You can use variable substitution in any .json configuration file with the install, working and project locations described previously. The following properties can be substituted:

Property substitution takes the following syntax:

&{launcher.property}

For example, to specify the location of the OrientDB database, you can set the dbUrl property in repo.orientdb.json as follows:

"dbUrl" : "local:&{launcher.working.location}/db/openidm",
     

The database location is then relative to a working location defined in the startup configuration.

Note that property substitution does not work for connector reference properties. So, for example, the following configuration would not be valid:

"connectorRef" : {
    "connectorName" : "&{connectorName}",
    "bundleName" : "org.forgerock.openicf.connectors.ldap-connector",
    "bundleVersion" : "&{LDAP.BundleVersion}"
    ...
  

The "connectorName" must be the precise string from the connector configuration. If you need to specify multiple connector version numbers, use a range of versions, for example:

"connectorRef" : {
    "connectorName" : "org.identityconnectors.ldap.LdapConnector",
    "bundleName" : "org.forgerock.openicf.connectors.ldap-connector",
    "bundleVersion" : "[1.4.0.0,2.0.0.0)",
    ...
  

OpenIDM includes a customizable information service that provides detailed information about a running OpenIDM instance. The information can be accessed over the REST interface, under the context https://localhost:8443/openidm/info.

By default, OpenIDM provides the following information:

You can extend or override the default information that is provided by creating your own script file and its corresponding configuration file in openidm/conf/info-name.json. Custom script files can be located anywhere, although a best practice is to place them in openidm/script/info. A sample customized script file for extending the default ping service is provided in openidm/samples/infoservice/script/info/customping.js. The corresponding configuration file is provided in openidm/samples/infoservice/conf/info-customping.json.

The configuration file has the following syntax:

{
    "infocontext" : "ping",
    "type" : "text/javascript",
    "file" : "script/info/customping.js"
} 
  

The parameters in the configuration file are as follows:

Additional properties can be passed to the script as depicted in this configuration file (openidm/samples/infoservice/conf/info-name.json).

Script files in openidm/samples/infoservice/script/info/ have access to the following objects:

Due to the highly modular, configurable nature of OpenIDM, it is often difficult to assess whether a system has started up successfully, or whether the system is ready and stable after dynamic configuration changes have been made.

OpenIDM provides a configurable health check service that verifies that the required modules and services for an operational system are up and running. During system startup, OpenIDM checks that these modules and services are available and reports on whether any requirements for an operational system have not been met. If dynamic configuration changes are made, OpenIDM rechecks that the required modules and services are functioning so that system operation is monitored on an ongoing basis.

The health check service reports on the state of the OpenIDM system and outputs this state to the console and to the log files. The system can be in one of the following states:

OpenIDM checks all required modules and services. Examples of those services are shown here.

Required Modules (examples)

"org.forgerock.openicf.framework.connector-framework"
"org.forgerock.openicf.framework.connector-framework-internal"
"org.forgerock.openicf.framework.connector-framework-osgi"
"org.forgerock.openidm.audit"
"org.forgerock.openidm.core"
"org.forgerock.openidm.enhanced-config"
"org.forgerock.openidm.external-email"

   ...

"org.forgerock.openidm.system"
"org.forgerock.openidm.ui"
"org.forgerock.openidm.util"
"org.forgerock.commons.org.forgerock.json.resource"
"org.forgerock.commons.org.forgerock.json.resource.restlet"
"org.forgerock.commons.org.forgerock.restlet"
"org.forgerock.commons.org.forgerock.util"
"org.forgerock.openidm.security-jetty"
"org.forgerock.openidm.jetty-fragment"
"org.forgerock.openidm.quartz-fragment"
"org.ops4j.pax.web.pax-web-extender-whiteboard"
"org.forgerock.openidm.scheduler"
"org.ops4j.pax.web.pax-web-jetty-bundle"
"org.forgerock.openidm.repo-jdbc"
"org.forgerock.openidm.repo-orientdb"
"org.forgerock.openidm.config"
"org.forgerock.openidm.crypto"  
  

Required Services (examples)

"org.forgerock.openidm.config"
"org.forgerock.openidm.provisioner"
"org.forgerock.openidm.provisioner.openicf.connectorinfoprovider"
"org.forgerock.openidm.external.rest"
"org.forgerock.openidm.audit"
"org.forgerock.openidm.policy"
"org.forgerock.openidm.managed"
"org.forgerock.openidm.script"
"org.forgerock.openidm.crypto"
"org.forgerock.openidm.recon"
"org.forgerock.openidm.info"
"org.forgerock.openidm.router"
"org.forgerock.openidm.scheduler"
"org.forgerock.openidm.scope"
"org.forgerock.openidm.taskscanner"
     

You can replace this list, or add to it, by adding the following lines to the openidm/conf/boot/boot.properties file:

By default, OpenIDM gives the system ten seconds to start up all the required bundles and services, before the system readiness is assessed. Note that this is not the total start time, but the time required to complete the service startup after the framework has started. You can change this default by setting the value of the servicestartmax property (in miliseconds) in the openidm/conf/boot/boot.properties file. This example sets the startup time to five seconds.

openidm.healthservice.servicestartmax=5000

The health check service works in tandem with the scriptable information service. For more information see Section 2.3, "Obtaining Information About an OpenIDM Instance".

Do not use the health check service to monitor the status of external resources, such as LDAP servers, or external databases. Rather, monitor these resources over the REST interface, as described in Section 11.7, "Checking the Status of External Systems Over REST".

On a running OpenIDM instance, you can list the installed modules and their states by typing the following command in the Felix administration console. (The output will vary by configuration.)

-> scr list 
      
   Id   State          Name
[  12] [active       ] org.forgerock.openidm.endpoint
[  13] [active       ] org.forgerock.openidm.endpoint
[  14] [active       ] org.forgerock.openidm.endpoint
[  15] [active       ] org.forgerock.openidm.endpoint
[  16] [active       ] org.forgerock.openidm.endpoint

      ...

[  34] [active       ] org.forgerock.openidm.taskscanner
[  20] [active       ] org.forgerock.openidm.external.rest
[   6] [active       ] org.forgerock.openidm.router
[  33] [active       ] org.forgerock.openidm.scheduler
[  19] [unsatisfied  ] org.forgerock.openidm.external.email
[  11] [active       ] org.forgerock.openidm.sync
[  25] [active       ] org.forgerock.openidm.policy
[   8] [active       ] org.forgerock.openidm.script
[  10] [active       ] org.forgerock.openidm.recon
[   4] [active       ] org.forgerock.openidm.http.contextregistrator
[   1] [active       ] org.forgerock.openidm.config
[  18] [active       ] org.forgerock.openidm.endpointservice
[  30] [unsatisfied  ] org.forgerock.openidm.servletfilter
[  24] [active       ] org.forgerock.openidm.infoservice
[  21] [active       ] org.forgerock.openidm.authentication
->

To display additional information about a particular module or service, run the following command, substituting the Id of that module from the preceding list.

-> scr info Id

The following example displays additional information about the router service:

-> scr info 6 
      
ID: 6
Name: org.forgerock.openidm.router
Bundle: org.forgerock.openidm.core (41)
State: active
Default State: enabled
Activation: immediate
Configuration Policy: optional
Activate Method: activate (declared in the descriptor)
Deactivate Method: deactivate (declared in the descriptor)
Modified Method: modified
Services: org.forgerock.json.resource.JsonResource
Service Type: service
Reference: ref_JsonResourceRouterService_ScopeFactory
    Satisfied: satisfied
    Service Name: org.forgerock.openidm.scope.ScopeFactory
    Multiple: single
    Optional: mandatory
    Policy: dynamic
Properties:
    component.id = 6
    component.name = org.forgerock.openidm.router
    felix.fileinstall.filename = file:/openidm/samples/sample1/conf/router.json
    jsonconfig = {
    "filters" : [
        {
            "onRequest" : {
                "type" : "text/javascript",
                "file" : "bin/defaults/script/router-authz.js"
            }
        },
        {
            "onRequest" : {
                "type" : "text/javascript",
                "file" : "bin/defaults/script/policyFilter.js"
            },
            "methods" : [
                "create",
                "update"
            ]
        }
    ]
}
    openidm.restlet.path = /
    service.description = OpenIDM internal JSON resource router
    service.pid = org.forgerock.openidm.router
    service.vendor = ForgeRock AS 
->

To debug custom libraries, you can start OpenIDM with the option to use the Java Platform Debugger Architecture (JPDA).

OpenIDM provides a script that generates an initialization script to run OpenIDM as a service on Linux systems. You can start the script as the root user, or configure it to start during the boot process.

When OpenIDM runs as a service, logs are written to the directory in which OpenIDM was installed.

The configexport subcommand exports all configuration objects to a specified location, enabling you to reuse a system configuration in another environment. For example, you can test a configuration in a development environment, then export it and import it into a production environment. This subcommand also enables you to inspect the active configuration of an OpenIDM instance.

OpenIDM must be running when you execute this command.

Usage is as follows:

$ ./cli.sh configexport --user username:passsword export-location
  

For example:

$ ./cli.sh configexport --user openidm-admin:openidm-admin /tmp/conf

On Windows systems, the export-location must be provided in quotation marks, for example:

C:\openidm\cli.bat configexport --user openidm-admin:openidm-admin "C:\temp\openidm"

Configuration objects are exported, as .json files, to the specified directory. The command creates the directory if needed. Configuration files that are present in this directory are renamed as backup files, with a timestamp, for example, audit.json.2014-02-19T12-00-28.bkp, and are not overwritten. The following configuration objects are exported:

The configimport subcommand imports configuration objects from the specified directory, enabling you to reuse a system configuration from another environment. For example, you can test a configuration in a development environment, then export it and import it into a production environment.

The command updates the existing configuration from the import-location over the OpenIDM REST interface. By default, if configuration objects are present in the import-location and not in the existing configuration, these objects are added. If configuration objects are present in the existing location but not in the import-location, these objects are left untouched in the existing configuration.

If you include the --replaceAll parameter, the command wipes out the existing configuration and replaces it with the configuration in the import-location. Objects in the existing configuration that are not present in the import-location are deleted.

Usage is as follows:

$ ./cli.sh configimport --user username:password [--replaceAll] import-location
  

For example:

$ ./cli.sh configimport --user openidm-admin:openidm-admin --replaceAll /tmp/conf
  

On Windows systems, the import-location must be provided in quotation marks, for example:

C:\openidm\cli.bat configimport --user openidm-admin:openidm-admin --replaceAll "C:\temp\openidm"

Configuration objects are imported, as .json files, from the specified directory to the conf directory. The configuration objects that are imported are outlined in the corresponding export command, described in the previous section.

The configureconnector subcommand generates a configuration for an OpenICF connector.

Usage is as follows:

$ ./cli.sh configureconnector --user username:password connector-name
  

Select the type of connector that you want to configure. The following example configures a new XML connector.

$ ./cli.sh configureconnector --user openidm-admin:openidm-admin myXmlConnector
 Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
0. CSV File Connector version 1.1.0.2
1. Database Table Connector version 1.1.0.1
2. Scripted Poolable Groovy Connector version 1.4.1.0
3. Scripted Groovy Connector version 1.4.1.0
4. Scripted CREST Connector version 1.4.1.0
5. Scripted SQL Connector version 1.4.1.0
6. Scripted REST Connector version 1.4.1.0
7. LDAP Connector version 1.4.0.1
8. XML Connector version 1.1.0.2
9. Exit
Select [0..9]: 8
Edit the configuration file and run the command again. The configuration was 
saved to /openidm/temp/provisioner.openicf-myXmlConnector.json

The basic configuration is saved in a file named /openidm/temp/provisioner.openicf-connector-name.json. Edit the configurationProperties parameter in this file to complete the connector configuration. For an XML connector, you can use the schema definitions in sample 1 for an example configuration.

  "configurationProperties" : {
    "xmlFilePath" : "samples/sample1/data/resource-schema-1.xsd",
    "createFileIfNotExists" : false,
    "xsdFilePath" : "samples/sample1/data/resource-schema-extension.xsd",
    "xsdIcfFilePath" : "samples/sample1/data/xmlConnectorData.xml"
  },  
  

For more information about the connector configuration properties, see Section 11.3, "Configuring Connectors".

When you have modified the file, run the configureconnector command again so that OpenIDM can pick up the new connector configuration.

$ ./cli.sh configureconnector --user openidm-admin:openidm-admin myXmlConnector
Executing ./cli.sh...
Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
Configuration was found and read from: /path/to/openidm/temp/provisioner.openicf-myXmlConnector.json
  

You can now copy the new provisioner.openicf-myXmlConnector.json file to the conf/ subdirectory.

You can also configure connectors over the REST interface. For more information, see Section 11.6, "Creating Default Connector Configurations".

The encrypt subcommand encrypts an input string, or JSON object, provided at the command line. This subcommand can be used to encrypt passwords, or other sensitive data, to be stored in the OpenIDM repository. The encrypted value is output to standard output and provides details of the cryptography key that is used to encrypt the data.

Usage is as follows:

$ ./cli.sh encrypt [-j] string
  

The -j option specifies that the string to be encrypted is a JSON object. If you do not enter the string as part of the command, the command prompts for the string to be encrypted. If you enter the string as part of the command, any special characters, for example quotation marks, must be escaped.

The following example encrypts a normal string value:

$ ./cli.sh encrypt mypassword  
  
Executing ./cli.sh
Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
Activating cryptography service of type: JCEKS provider:  location: security/keystore.jceks
Available cryptography key: openidm-sym-default
Available cryptography key: openidm-localhost
CryptoService is initialized with 2 keys.
-----BEGIN ENCRYPTED VALUE-----
{
  "$crypto" : {
    "value" : {
      "iv" : "M2913T5ZADlC2ip2imeOyg==",
      "data" : "DZAAAM1nKjQM1qpLwh3BgA==",
      "cipher" : "AES/CBC/PKCS5Padding",
      "key" : "openidm-sym-default"
    },
    "type" : "x-simple-encryption"
  }
}
------END ENCRYPTED VALUE------ 
  

The following example encrypts a JSON object. The input string must be a valid JSON object.

$ ./cli.sh encrypt -j {\"password\":\"myPassw0rd\"}

Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
Activating cryptography service of type: JCEKS provider:  location: security/keystore.jceks
Available cryptography key: openidm-sym-default
Available cryptography key: openidm-localhost
CryptoService is initialized with 2 keys.
-----BEGIN ENCRYPTED VALUE-----
{
  "$crypto" : {
    "value" : {
      "iv" : "M2913T5ZADlC2ip2imeOyg==",
      "data" : "DZAAAM1nKjQM1qpLwh3BgA==",
      "cipher" : "AES/CBC/PKCS5Padding",
      "key" : "openidm-sym-default"
    },
    "type" : "x-simple-encryption"
  }
}
------END ENCRYPTED VALUE------  
  

The following example prompts for a JSON object to be encrypted. In this case, you need not escape the special characters.

$ ./cli.sh encrypt -j

Using boot properties at /path/to/openidm/conf/boot/boot.properties
Enter the Json value

> Press ctrl-D to finish input
Start data input:
{"password":"myPassw0rd"}
^D        

Activating cryptography service of type: JCEKS provider:  location: security/keystore.jceks
Available cryptography key: openidm-sym-default
Available cryptography key: openidm-localhost
CryptoService is initialized with 2 keys.
-----BEGIN ENCRYPTED VALUE-----
{
  "$crypto" : {
    "value" : {
      "iv" : "6e0RK8/4F1EK5FzSZHwNYQ==",
      "data" : "gwHSdDTmzmUXeD6Gtfn6JFC8cAUiksiAGfvzTsdnAqQ=",
      "cipher" : "AES/CBC/PKCS5Padding",
      "key" : "openidm-sym-default"
    },
    "type" : "x-simple-encryption"
  }
}
------END ENCRYPTED VALUE------
  

The keytool subcommand exports or imports secret key values.

The Java keytool command enables you to export and import public keys and certificates, but not secret or symmetric keys. The OpenIDM keytool subcommand provides this functionality.

Usage is as follows:

./cli.sh keytool [--export, --import] alias
  

For example, to export the default OpenIDM symmetric key, run the following command:

$ ./cli.sh keytool --export openidm-sym-default
   
Using boot properties at /openidm/conf/boot/boot.properties
Use KeyStore from: /openidm/security/keystore.jceks
Please enter the password: 
[OK] Secret key entry with algorithm AES
AES:606d80ae316be58e94439f91ad8ce1c0  
  

The default keystore password is changeit. You should change this password after installation.

To import a new secret key named my-new-key, run the following command:

$ ./cli.sh keytool --import my-new-key   
   
Using boot properties at /openidm/conf/boot/boot.properties
Use KeyStore from: /openidm/security/keystore.jceks
Please enter the password: 
Enter the key: 
AES:606d80ae316be58e94439f91ad8ce1c0 
  

If a secret key of that name already exists, OpenIDM returns the following error:

"KeyStore contains a key with this alias"

The validate subcommand validates all .json configuration files in the openidm/conf/ directory.

Usage is as follows:

$ ./cli.sh validate   
   
Executing ./cli.sh
Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
...................................................................
[Validating] Load JSON configuration files from:
[Validating] 	/path/to/openidm/conf
[Validating] audit.json .................................. SUCCESS
[Validating] authentication.json ......................... SUCCESS

    ...

[Validating] sync.json ................................... SUCCESS
[Validating] ui-configuration.json ....................... SUCCESS
[Validating] ui-countries.json ........................... SUCCESS
[Validating] ui-secquestions.json ........................ SUCCESS
[Validating] workflow.json ............................... SUCCESS
  

You can set up a basic configuration for OpenIDM with the Administrative User Interface (Admin UI).

Through the Admin UI, you can connect to resources, configure attribute mapping, and set up managed objects, reconciled on a defined schedule.

You can customize the configuration of connectors, managed objects, mapping between resources, and more. You can add and edit properties to be synchronized, configure correlation queries, and enable LiveSync.

To access the initial Admin UI screen, navigate to https://localhost:8443/admin.

The information that appears in the initial Admin UI screen depends on how you started OpenIDM. For example, if you start OpenIDM with one of the OpenIDM samples (see Chapter 3, "More OpenIDM Samples" in the Installation Guide), your first Resources screen will display connectors and managed objects as configured in the selected sample.

As shown in the initial screen, the Admin UI supports connecting to external resources (see Chapter 11, "Connecting to External Resources") and managing users, groups, and roles (see Chapter 8, "Managing Users, Groups, and Roles").

Scroll up and down the Admin UI screen. Review configured connectors and managed objects. The screenshots in this section assume that you have started OpenIDM with the configuration for Sample 2b (Section 3.4, "Sample 2b - LDAP Two Way" in the Installation Guide).

Connectors are used to communicate with remote resources, such as a database, an identity store, or another organized data store.

Once you connect one or more data stores and managed objects, you can create a mapping between two resources. You can then configure property mapping between those resources, for later synchronization.

4.1.1. Administering Connectors from the UI

You can include several different connectors in an OpenIDM configuration. Select the option to create a new connector. Try some of the different connector types in the screen that appears. Observe as the Admin UI changes the configuration options to match the requirements of the connector type.

Remember, every connector serves as a conduit to an external data store.

If you are not sure what to enter in a specific Add Connector text box, review the list of connectors supported with OpenIDM (Section 11.5, "Connectors Supported With OpenIDM 3.1"). You should be able to find guidance and or examples on how each supported connector is configured.

For additional guidance, review sample connector files in the samples/provisioners/ subdirectory.

Once you fill in all required text boxes, the Admin UI allows you to validate the connector configuration.

4.1.2. Administering Managed Objects from the UI

You can set up Managed Objects in a similar way to how you set up connectors. Typically, OpenIDM uses managed objects as described in Chapter 8, "Managing Users, Groups, and Roles".

To access the details of a Managed Object, go to the Resources screen. Select the Edit icon associated with the Managed Object that you want to change, such as user, group, or role.

4.1.3. Configuring a Resource Mapping from the UI

You may have multiple connectors and managed objects. You can configure a mapping between any two of these resources. Connectors represent an external data store, as specified in Section 11.3, "Configuring Connectors". In contrast, managed objects represents a data store internal to OpenIDM.

Resource mapping requires a source and a target. Generally, each resource includes properties such as username, address, surname, and title. Resource mapping can go beyond user information to other types of data.

Once you create a mapping, you can identify properties that you wish to control in the target. With this part of the Admin UI, you can configure how OpenIDM uses matching properties in the source.

The following screenshot illustrates a property mapping between two resources. Every resource includes identifiers for each attribute. For example, different resources may use one of the following identifiers for usernames: un, uid, user, sAMAccountName, and account. For more information on property mappings, see Section 12.3.2, "Synchronization Mappings File".

The bold black line is used solely by the UI to determine what data is shown from these data stores. It does not affect reconciliation. In the Admin UI, you can change the location of the line, or move a property above or below the line.

4.1.4. Configuring Reconciliation from the UI

Reconciliation changes data on a target system to match the corresponding data on a source system. You can customize how OpenIDM performs reconciliation in several ways.

4.1.4.1. Correlation Options

OpenIDM can match existing records on the target system to records on the source system. This matching is known as correlation.

Before activating reconciliation, you may choose to configure various correlation options, including reconciliation query filters, individual record validation, association rules, and data association management.

For more information on correlation, see Section 12.17, "Correlation Queries".

You can add reconciliation query filters, with queries on the source and target objects. For more information, see Section 7.3.4, "Constructing Queries". You can set up queries on properties such as userName and parameters such as Smith.

You can add individual record validation scripts, based on the validSource and validTarget script objects. For more information on these objects, see Section D.1, "Object-Mapping Objects". With these scripts, you can set up criteria for OpenIDM to validate source and target objects for reconciliation.

You can set up correlation queries (Section 12.17, "Correlation Queries") with an expression builder or with a JavaScript or Groovy-based script.

When a reconciliation operation finds a matching target entry, the process creates a link between the source and the target entries. This is also known as a Data Association. Data associations serve two purposes - they speed up future reconciliation operations, and they serve as a record of the relationship between a source and a target entry.

You can set up such data associations for individual entries, as well as different situations shown in Section 12.13.1, "Synchronization Situations".

4.1.4.2. Reconciliation Options

Before activating reconciliation, you may choose to configure situational policies, situational event scripts, and reconciliation scripts.

You may want to configure situational policies. By default, the policies associated with mappings are set to "read-only". As such, OpenIDM does not change anything on the target system, unless you make changes to situational policies.

With situational policies, you can define actions relevant for situations shown in the screenshot below. For a full list of available policies, see Section 12.13, "Synchronization Situations and Actions".

To access the following screen, select the Mapping of your choice and select edit. In the sub-tabs that appear, select Reconciliation.

You can configure situational event scripts. Each of the script events shown onCreate, onDelete, onLink, onUnlink, and onUpdate, can help you with constructing attributes. For more information, see Section 12.3.5, "Constructing and Manipulating Attributes".

You can configure scripts that are triggered on reconciliation, as part of the dataflow configuration (see Section 12.18, "Advanced Data Flow Configuration".

You can choose to test the overall process with a single record reconciliation. In other words, you need not test these policies and scripts against the entire data set. For example, you can restrict reconciliation to a specific ID (see Section 12.6, "Restricting Reconciliation to a Specific ID").

Finally, you should set up a schedule, as described in Section 12.19.1, "Configuring Scheduled Synchronization".

You can also configure LiveSync, which captures the changes that happen on a remote system, and then pushes those changes to OpenIDM.

For more information on Reconciliation and LiveSync, see Section 12.1, "Types of Synchronization".

You can manage reconciliation and liveSync with the embedded Quartz scheduler. For more information, see Chapter 13, "Scheduling Tasks and Events".

Once you've set up Reconciliation based on configured properties, correlation queries, and a synchronization schedule, you can start the synchronization process. Try it out! You'll see the results in the target data store.

Once you have taken the steps required to configure OpenIDM through the Admin UI, you can start the synchronization process from a source to a target. Once a synchronization is complete, you can review the results in this window.

4.1.5. Configuring Authentication Modules from the UI

You can also configure authentication modules from the Admin UI. To access those modules, click Settings.

The page shown here displays several available modules, based on the ForgeRock Common Authentication Framework. For more information on each module, see Section 15.3, "Supported Authentication Modules".

For all users, the User View UI includes a Dashboard tab, which lists any tasks assigned to the user who as logged in, processes available to be invoked, and any notifications for that user.

For the administrative user, (role openidm-admin), the User View UI also includes a Users tab, which provides an interface for user entries, if you have configured managed users in the OpenIDM repository.

To access the User View UI, install and start OpenIDM, then point your browser to https://localhost:8443/openidmui. If you have not installed a certificate that is trusted by a certificate authority, you are prompted with an "Untrusted Connection" warning the first time you log in to the UI.

The following image shows the Dashboard tab for the administrative user when no tasks, processes, or notifications are available.

The following image shows the Users tab, populated with two sample users, after a reconciliation associated with Sample 2b.

You can sort the list of users alphabetically, by any of the column values. Click on the column title to sort.

The Profile link enables the user to modify his username or password. The Change Security Data link, accessed from the top of the screen, or from the user's Profile page enables the user to change his password and, if this functionality has been enabled, to select a new security question.

Password changes are subject to the default password policy, as shown in the following password update screen.

For a regular user (role openidm-authorized), the Users tab is not displayed. By default, regular users cannot manage user accounts, except for certain aspects of their own accounts.

The following sections outline the configurable aspects of the User View UI.

4.3.1. Enabling Self-Registration

Self-registration (the ability for new users to create their own accounts) is disabled by default. To enable self-registration, set "selfRegistration" to true in the UI configuration file (conf/ui-configuration.json).

{
    "configuration" : {
        "selfRegistration" : true,
...    
    

When self-registration is enabled, a "Register your account" link is provided on the login page. When a user creates an account on the account registration page, a managed object is created in the OpenIDM repository. The default policies for managed objects are applied during account creation.

User objects created using self-registration automatically have the role openidm-authorized.

4.3.2. Configuring Security Questions

In the event that a user forgets his password, a password reset function enables registered users to reset their own passwords. To guard against unauthorized access, you can specify that users be prompted with one or more security questions when they request a password reset.

Security questions are disabled by default. To enable them, set "securityQuestions" to true in the UI configuration file (conf/ui-configuration.json).

{
    "configuration" : {
        "securityQuestions" : true,
...    
   

A default set of questions is provided, but you can add to these, or overwrite them. Specify the list of questions to be asked in the conf/ui-secquestions.json file.

Refresh your browser after this configuration change for the change to be picked up by the UI.

When security questions are enabled, the following panel is included on the self registration page.

In addition, a "Reset your password" link is provided on the login page. When a user attempts to reset her password, she is prompted for the response to the security question that she set up during registration.

Note

If security questions are enabled after a specific user has registered, that particular user will be unable to use the password reset functionality.

{
    "policyId" : "minimum-length",
    "params" : {
        "minLength" : 16
    }
},

4.3.4. Enabling Site Identification

To ensure that users are entering their details onto the correct site, you can enable site identification. Site identification provides a preventative measure against phishing.

With site identification enabled, a user is presented with a range of images from which he can select when he registers his account, and prompted to specify his own site phrase. The selected site image and phrase are displayed on login, to confirm that the user is logging in to the legitimate site.

To enable site identification, set "siteIdentification" to true in the UI configuration file (conf/ui-configuration.json).

{
    "configuration" : {
        "siteIdentification" : true,
...    
    

Refresh your browser after this configuration change for the change to be picked up by the UI.

When site identification is enabled, the following panel is included on the self registration page.

A default list of four images is presented for site identification. The images are defined in the siteImages property in the conf/ui-configuration.json file:

"siteImages" : [
"images/passphrase/mail.png",
"images/passphrase/user.png",
"images/passphrase/report.png",
"images/passphrase/twitter.png"
],
...    
   

You can change the default images, and include additional images, by placing image files in the ui/extension/images folder and modifying the siteImages property in the ui-configuration.json file to point to the new images. Refresh your browser for the change to take effect.

The following example assumes an image file named my-new-image.jpg, located in ui/extension/images.

"siteImages" : [
"images/passphrase/mail.png",
"images/passphrase/user.png",
"images/passphrase/report.png",
"images/passphrase/twitter.png",
"images/my-new-image.jpg"
],
...
   

Note that the default image files are located in ui/default/enduser/public/images/passphrase.

{
    "key" : "norway",
    "value" : "Norway",
    "states" : [
        {
            "key" : "akershus",
            "value" : "Akershus"
        },
        {
            "key" : "aust-agder",
            "value" : "Aust-Agder"
        },
        {
            "key" : "buskerud",
            "value" : "Buskerud"
        },
...
   

Only administrative users (with the role openidm-admin) can add, modify, and delete user accounts. Regular users can modify certain aspects of their own accounts.

The User View UI is integrated with the embedded Activiti worfklow engine, enabling users to interact with workflows. Available workflows are displayed under the Processes item on the Dashboard. In order for a workflow to be displayed here, the workflow definition file must be present in the openidm/workflow directory.

A sample workflow integration with the User View UI is provided in openidm/samples/workflow, and documented in Section 17.5.2, "Sample Workflow - Provisioning User Accounts". Follow the steps in that sample for an understanding of how the workflow integration works.

Access to workflows is based on OpenIDM roles, and is configured in the file conf/process-access.json. By default all users with the role openidm-authorized or openidm-admin can invoke any available workflow. The default process-access.json file is as follows:

{
    "workflowAccess" : [
        {
            "propertiesCheck" : {
                "property" : "_id",
                "matches" : ".*",
                "requiresRole" : "openidm-authorized"
            }
        },
        {
            "propertiesCheck" : {
                "property" : "_id",
                "matches" : ".*",
                "requiresRole" : "openidm-admin"
            }
        }
    ]
}  
  

To extend the process action definition file, identify the processes to which users should have access, and specify the qualifying user roles. For example, if you wanted to restrict access to a process definition whose ID was 567, to users with the role ldap you would add the following to the process-access.json file:

{
    "propertiesCheck" : {
        "property" : "_id",
        "matches" : "567",
        "requiresRole" : "ldap"
    }
}
  

You can customize the theme of the user interface with your own branding. One way to adjust the UI theme, is to edit the properties in the UI theme configuration file (/path/to/openidm/conf/ui-themeconfig.json). This file stores detailed color values, background image paths, and a number of other common styling options. Because the UI theme configuration file is part of the configuration store, it is shared by all nodes in a cluster. Changes made to this file do not have to be replicated manually across nodes.

To change theme elements that are not included in the UI theme configuration file, you can create a custom theme in the openidm/ui/extension directory. By default the user interface reads the stylesheets and images from the openidm/ui/default directory. Do not modify the files in this default directory as there is no guarantee that your changes will not be overwritten in the next OpenIDM release. Modifications made in the openidm/ui/extension directory can be maintained across product upgrades. The UI searches the extension directory first and applies any styles or images located in this directory. Note that files added to the extension directory must be manually copied between every node in a cluster.

If you want to update the view logic of the UI, you cannot simply add files to the extensions folder. It is assumed that if your deployment requires that level of control of the user interface, you are no longer going to want to be automatically upgraded with subsequent releases. As such, you need to take on the task of maintaining a fork of the UI.

$ grep "background-color" /path/to/openidm/conf/ui-themeconfig.json
"background-color" : "#ababab",
   

...
   "logo" : {
       "src" : "images/example-logo.png",
       "title" : "Example.com",
       "alt" : "Example.com",
       "height" : "80",
       "width" : "120"
   },
...

By default, the password reset mechanism is handled internally, in OpenIDM. You can reroute password reset in the event that a user has forgotten his password, by specifying an external URL to which password reset requests are sent. Note that this URL applies to the password reset link on the login page only, not to the security data change facility that is available after a user has logged in.

To set an external URL to handle password reset, set the passwordResetLink parameter in the UI configuration file (conf/ui-configuration.json) file. The following example sets the passwordResetLink to https://accounts.example.com/account/reset-password.

passwordResetLink: "https://accounts.example.com/reset-password"

The passwordResetLink parameter takes either an empty string as a value (which indicates that no external link is used) or a full URL to the external system that handles password reset requests.

By default, a UI session is invalidated when a user clicks on the Log out link. In certain situations your external applications might require a distinct logout URL to which users can be routed, to terminate their UI session.

The logout URL is #logout, appended to the UI URL, for example, https://localhost:8443/openidmui/index.html#logout/.

The logout URL effectively performs the same action as clicking on the Log out link of the UI.

By default, the UI is registered at a specific URL (context-root/openidmui). To override the default URL and specify your own path, edit the openidm/conf/ui.context-enduser.json file, setting the urlContextRoot property to the new URL. For example, to change the path to context-root/exampleui, edit the file as follows:

"urlContextRoot" : "/exampleui",

The UI is packaged as a separate bundle that can be disabled in the configuration before server startup. To disable the registration of the UI servlet, edit the openidm/conf/ui.context-enduser.json file, setting the enabled property to false:

"enabled" : false,

OpenIDM provides a specific configuration file for each supported JDBC repository, as well as example configurations for other repositories. These configuration files are located in /path/to/openidm/db/database and are named repo.jdbc.json. Copy the configuration file for your specific database type to /path/to/openidm/conf/.

The repository configuration file includes the connection details for the repository, a number of predefined queries, and a mapping between OpenIDM resources and the tables in the repository.

An excerpt from an example repository configuration follows.

{
    "connection" : {
        "dbType" : "MYSQL",
        "jndiName" : "",
        "driverClass" : "com.mysql.jdbc.Driver",
        "jdbcUrl" : "jdbc:mysql://localhost:3306/openidm?characterEncoding=utf8",
        "username" : "openidm",
        "password" : "openidm",
        "defaultCatalog" : "openidm",
        "maxBatchSize" : 100,
        "maxTxRetry" : 5,
        "enableConnectionPool" : true,
        "connectionTimeoutInMs" : 30000
    },
    "queries" : {...},
    "resourceMapping" : {...}
}
  

These two mapping strategies are discussed in the following sections.

5.2.1. Using Generic Mappings

Generic mapping speeds up development, and can make system maintenance more flexible by providing a more stable database structure. However, generic mapping can have a performance impact and does not take full advantage of the database facilities (such as validation within the database and flexible indexing). In addition, queries can be more difficult to set up.

In a generic table, the entire object content is stored in a single large-character field named "fullobject" in the "mainTable" for the object. To search on specific fields, you can read them by referring to them in the corresponding properties table for that object. The disadvantage of generic objects is that, because every property you might like to filter by is stored in a separate table, you must join to that table each time you need to filter by anything.

The following diagram shows a pared down database structure for the default generic table, and indicates the relationship between the main table and the corresponding properties table for each object.

These separate tables can make the query syntax particularly complex. For example, a simple query to return user entries based on a user name would need to be implemented as follows:

SELECT fullobject FROM ${_dbSchema}.${_mainTable} obj INNER JOIN ${_dbSchema}.${_propTable} prop
    ON obj.id = prop.${_mainTable}_id INNER JOIN ${_dbSchema}.objecttypes objtype
    ON objtype.id = obj.objecttypes_id WHERE prop.propkey='/userName' AND prop.propvalue = ${uid}
    AND objtype.objecttype = ${_resource}",
   

The query can be broken down as follows:

• Select the full object from the main table

  SELECT fullobject FROM ${_dbSchema}.${_mainTable} obj
       

• Join to the properties table and locate the object with the corresponding ID.

  INNER JOIN ${_dbSchema}.${_propTable} prop  ON obj.id = prop.${_mainTable}_id
       

• Join to the object types table to restrict returned entries to objects of a specific type. For example, you might want to restrict returned entries to managed/user objects, or managed/role objects.

  INNER JOIN ${_dbSchema}.objecttypes objtype ON objtype.id = obj.objecttypes_id
       

• Filter records by the userName property, where the userName is equal to the specified uid and the object type is the specified type (in this case, managed/user objects).

  WHERE prop.propkey='/userName'
  AND prop.propvalue = ${uid}
  AND objtype.objecttype = ${_resource}",
       

  The value of the uid field is provided as part of the query call, for example:

  openidm.query("managed/user", { "_queryId": "for-userName", "uid": "jdoe" });
       

Tables for user definable objects use a generic mapping by default.

The following sample generic mapping object illustrates how managed/ objects are stored in a generic table.

  "genericMapping" : {
      "managed/*" : {
          "mainTable" : "managedobjects",
          "propertiesTable" : "managedobjectproperties",
          "searchableDefault" : true,
          "properties" : {
              "/picture" : {
                  "searchable" : false
              }
          }
      }
  },
   

"mainTable" (string, mandatory)

Indicates the main table in which data is stored for this resource.

The complete object is stored in the fullobject column of this table. The table includes an entityType foreign key, that is used to distinguish the different objects stored within the table. In addition, the revision of each stored object is tracked, in the rev column of the table, enabling multi version concurrency control (MVCC). For more information, see Section C.1.6.3, "Manipulating Managed Objects Programmatically".

"propertiesTable" (string, mandatory)

Indicates the properties table, used for searches.

The contents of the properties table is a defined subset of the properties, copied from the character large object (CLOB) that is stored in the fullobject column of the main table. The properties are stored in a one-to-many style separate table. The set of properties stored here is determined by the properties that are defined as "searchable".

The stored set of searchable properties makes these values available as discrete rows that can be accessed with SQL queries, specifically, with WHERE clauses. It is not otherwise possible to query specific properties of the full object.

The properties table includes the following columns:

• ${_mainTable}_id corresponds to the id of the full object in the main table, for example, manageobjects_id, or genericobjects_id.

• propkey is the name of the searchable property, stored in JSON pointer format (for example /mail. For more information about JSON pointer syntax, see RFC 6901.

• proptype is the data type of the property, for example java.lang.String. The property type is obtained from the Class associated with the value.

• propvalue is the value of property, extracted from the full object that is stored in the main table.

  Regardless of the property data type, this value is stored as a string, so queries against it should treat it as such.

"searchableDefault" (boolean, optional)

Specifies whether all properties of the resource should be searchable by default. Properties that are searchable are stored and indexed. You can override the default for individual properties in the "properties" element of the mapping. The preceding example indicates that all properties are searchable, with the exception of the "picture" property.

For large, complex objects, having all properties searchable implies a substantial performance impact. In such a case, a separate insert statement is made in the properties table for each element in the object, every time the object is updated. Also, because these are indexed fields, the recreation of these properties incurs a cost in the maintenance of the index. You should therefore enable "searchable" only for those properties that must be used as part of a WHERE clause in a query.

"properties"

Lists any individual properties for which the searchable default should be overridden.

Note that if an object was originally created with a subset of "searchable" properties, changing this subset (by adding a new "searchable" property in the configuration, for example) will not cause the existing values to be updated in the properties table for that object. To add the new property to the properties table for that object, you must update or recreate the object.

"genericMapping" : {
    "managed/user" : {
        "mainTable" : "manageduserobjects",
        "propertiesTable" : "manageduserobjectproperties",
        "searchableDefault" : false,
        "properties" : {
            "/userName" : {
            "searchable" : true
            }
        }
    }
},
   

"explicitMapping" : {
    "internal/user" : {
        "table" : "internaluser",
        "objectToColumn" : {
            "_id" : "objectid",
            "_rev" : "rev",
            "password" : "pwd",
            "roles" : "roles"
        }
    },
    ...
}
   

To configure SSL with a JDBC repository, you need to import the CA certificate file for the server into the OpenIDM truststore. That certificate file could have a name like ca-cert.pem. If you have a different genuine or self-signed certificate file, substitute accordingly.

To import the CA certificate file into the OpenIDM truststore, use the keytool command native to the Java environment, typically located in the /path/to/jre-version/bin directory. On some UNIX-based systems, /usr/bin/keytool may link to that command.

The OpenIDM repository is accessible over the REST interface, at the openidm/repo endpoint.

In general, you must ensure that external calls to the openidm/repo endpoint are protected. Native queries and free-form command actions on this endpoint are disallowed by default, as the endpoint is vulnerable to injection attacks. For more information, see Section 5.4.2, "Running Queries and Commands on the Repository".

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/repo?_action=updateDbCredentials&user=admin&password=newPassword"

"commands" : {
"delete-notifications-by-id" : "DELETE FROM ui_notification WHERE receiverId = ${username}"
...
}, 

openidm.action("repo/ui/notification", "command", {},
{ "commandId" : "delete-notifications-by-id", "userName" : "scarter"});

OpenIDM exposes internal configuration objects in JSON format. Configuration elements can be either single instance or multiple instance for an OpenIDM installation.

Out of the box, OpenIDM is configured to make it easy to install and evaluate. Specific configuration changes are required before you deploy OpenIDM in a production environment.

# openidm.fileinstall.enabled=false

OpenIDM exposes configuration objects under the /openidm/config context path.

You can list the configuration on the local host by performing a GET https://localhost:8443/openidm/config. The following example shows excerpts of the default configuration for an OpenIDM instance started with Sample 1.

$ curl \
 --request GET \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --cacert self-signed.crt \
 https://localhost:8443/openidm/config
   {
   "configurations": [
      {
         "factoryPid": "servletfilter",
         "pid": "servletfilter.ec099f08-bfd4-4ab4-8537-78e5b956c7cc",
         "_id": "servletfilter/gzip"
      },
      {
         "factoryPid": null,
         "pid": "router",
         "_id": "router"
      },

   ...

      {
         "factoryPid": "endpoint",
         "pid": "endpoint.7e9ec068-bb4a-4fa0-ae15-1706bb4a3a07",
         "_id": "endpoint/jqgrid"
      },
      {
         "factoryPid": "endpoint",
         "pid": "endpoint.47978983-0411-425d-8f53-4022175e146a",
         "_id": "endpoint/gettasksview"
      },

   ...

      {
         "factoryPid": "ui",
         "pid": "ui.b10eb4cb-83e3-4a4b-9d29-d91d90eb3053",
         "_id": "ui/countries"
      },
      {
         "factoryPid": "process",
         "pid": "process.9863529c-60e0-42e3-b5d5-c5c704016e95",
         "_id": "process/access"
      }
   ]
}

Single instance configuration objects are located under openidm/config/object-name. The following example shows the default audit configuration.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/config/audit"
{
   "eventTypes": {
     "recon": {},
     "activity": {
       "filter": {
         "actions": [
           "create",
           "update",
           "delete",
           "patch",
           "action"
         ]
       },
       "passwordFields": [
         "password"
       ],
       "watchedFields": []
     }
   },
   "exceptionFormatter": {
     "file": "bin/defaults/script/audit/stacktraceFormatter.js",
     "type": "text/javascript"
   },
   "logTo": [
     {
       "recordDelimiter": ";",
       "logType": "csv",
       "location": "audit"
     },
     {
       "useForQueries": true,
       "logType": "repository"
     }
   ]
}   

Multiple instance configuration objects are found under openidm/config/object-name/instance-name.

The following example shows the configuration for the XML connector provisioner, based on the first IDM sample described in Chapter 2, "First OpenIDM Sample" in the Installation Guide.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/config/provisioner.openicf/xml"
{
    "operationTimeout": {
      "SCRIPT_ON_CONNECTOR": -1,
      "VALIDATE": -1,
      "SYNC": -1,
      "DELETE": -1,
      "TEST": -1,
      "UPDATE": -1,
      "CREATE": -1,
      "AUTHENTICATE": -1,
      "SEARCH": -1,
      "GET": -1,
      "SCRIPT_ON_RESOURCE": -1,
      "SCHEMA": -1
    },
    "connectorRef": {
      "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector",
      "bundleVersion": "1.1.0.2",
      "bundleName": "org.forgerock.openicf.connectors.xml-connector"
    },
    "connectorPoolingSupported": true,
    "syncFailureHandler": {
      "maxRetries": 5,
      "postRetryAction": "logged-ignore"
    },
    "configurationProperties": {
      "xsdFilePath": "samples/sample1/data/resource-schema-extension.xsd",
      "xsdIcfFilePath": "samples/sample1/data/resource-schema-1.xsd",
      "xmlFilePath": "samples/sample1/data/xmlConnectorData.xml"
    },
    "objectTypes": {
      "account": {
        "nativeType": "__ACCOUNT__",
        "$schema": "http://json-schema.org/draft-03/schema",
        "type": "object",
        "properties": {
          "securityAnswer": {
            "nativeType": "string",
            "nativeName": "securityAnswer",
            "required": true,
            "type": "string"
          },
          "securityQuestion": {
            "nativeType": "string",
            "nativeName": "securityQuestion",
            "required": true,
            "type": "string"
          },
          "password": {
            "nativeType": "string",
            "nativeName": "password",
            "type": "string"
          },
          "mobileTelephoneNumber": {
            "nativeType": "string",
            "nativeName": "mobileTelephoneNumber",
            "required": true,
            "type": "string"
          },
          "_id": {
            "nativeName": "__UID__",
            "type": "string"
          },
          "email": {
            "nativeType": "string",
            "nativeName": "email",
            "type": "string"
          },
          "description": {
            "nativeType": "string",
            "nativeName": "__DESCRIPTION__",
            "type": "string"
          },
          "name": {
            "nativeType": "string",
            "nativeName": "__NAME__",
            "required": true,
            "type": "string"
          },
          "roles": {
            "nativeType": "string",
            "nativeName": "roles",
            "required": false,
            "type": "string"
          },
          "lastname": {
            "nativeType": "string",
            "nativeName": "lastname",
            "required": true,
            "type": "string"
          },
          "firstname": {
            "nativeType": "string",
            "nativeName": "firstname",
            "type": "string"
          }
        },
        "id": "__ACCOUNT__"
      }
    },
    "operationOptions": {},
    "name": "xmlfile",
    "producerBufferSize": 100,
    "poolConfigOption": {
      "maxObjects": 10,
      "minEvictableIdleTimeMillis": 120000,
      "maxIdle": 10,
      "minIdle": 1,
      "maxWait": 150000
    }
  }

  

You can change the configuration over REST by using an HTTP PUT request to modify the required configuration object. Note that HTTP PATCH is not supported on the /config endpoint.

The following example modifies the router.json file to remove all filters, effectively bypassing any policy validation.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request PUT \
 --data '{
   "filters" : [
     {
       "onRequest" : {
         "type" : "text/javascript",
         "file" : "bin/defaults/script/router-authz.js"
       }
     }
   ]
   }' \
 "https://localhost:8443/openidm/config/router"
{
  "filters": [
    {
      "onRequest": {
        "file": "bin/defaults/script/router-authz.js",
        "type": "text/javascript"
      }
    }
  ]
} 

For more information about using the REST API to update objects, see Appendix E, "REST API Reference".

In an environment where you have more than one OpenIDM instance, you might require a configuration that is similar, but not identical, across the different OpenIDM hosts. OpenIDM supports variable replacement in its configuration which means that you can modify the effective configuration according to the requirements of a specific environment or OpenIDM instance.

When OpenIDM starts up, it combines the system configuration, which might contain specific environment variables, with the defined OpenIDM configuration properties. This combination makes up the effective configuration for that OpenIDM instance. By varying the environment properties, you can change specific configuration items that vary between OpenIDM instances or environments.

Property references are contained within the construct &{ }. When such references are found, OpenIDM replaces them with the appropriate property value, defined in the boot.properties file.

PROD.location=production
DEV.location=development

{
    "dbUrl" : "plocal:./db/&{&{environment}.location}-openidm",
    ...
}   

$ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Denvironment=PROD"
$ ./startup.sh

$ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Denvironment=DEV"
$ ./startup.sh

{
    "logTo" : [
        {
            "logType" : "csv",
            "location" : "&{user.home}/audit",
            "recordDelimiter" : ";"
        }
    ]
}
   

openidm.NO.ldap.port=2389
openidm.EN.ldap.port=3389
openidm.US.ldap.port=1389

"configurationProperties" :
   {
      "credentials" : "Passw0rd",
      "port" : "&{openidm.&{user.country}.ldap.port}",
      "principal" : "cn=Directory Manager",
      "baseContexts" :
         [
            "dc=example,dc=com"
         ],
      "host" : "localhost"
   }

You can customize OpenIDM to meet the specific requirements of your deployment by adding your own RESTful endpoints. Endpoints are configured in files named conf/endpoint-name.json, where name generally describes the purpose of the endpoint.

A sample custom endpoint configuration is provided in the openidm/samples/customendpoint directory. The use of this sample is described in Section 6.6.6, "Custom Endpoint Example". Custom endpoints in OpenIDM can be written either in JavaScript or Groovy. The sample includes three files:

Endpoint configuration files have a certain structure. They may cite scripts written in JavaScript or Groovy.

The cited scripts include defined request and context global variables.

{
  "file" : "echo.groovy",
  "type" : "groovy",
  "_file" : "echo.js",
  "_type" : "text/javascript"
}    

  "context" : "endpoint/echo",
     

{
  "context": "endpoint/linkedView/*",
  "type" : "text/javascript",
  "source" : "require('linkedView').fetch(request.resourceName);"
}
     

$ curl \
 --cacert self-signed.crt \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 --data { "name": "bob"} \
 "https://localhost:8443/openidm/endpoint/test?_action=myAction"

GET https://localhost:8443/openidm/endpoint/echo?queryId=query-all-ids&_para=foo

var x = "Sample return";
functioncall();
x   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/endpoint/echo?_queryId=query-all-ids"
     
     {
 "result" : [ {
     "method" : "query",
     "resourceName" : "",
     "pagedResultsCookie" : null,
     "pagedResultsOffset" : 0,
     "pageSize" : 0,
     "queryExpression" : null,
     "queryId" : "query-all-ids",
     "queryFilter" : "null",
     "parameters" : { },
     "context" : {
       "parent" : {
         "parent" : {
           "parent" : {
             "parent" : {
               "parent" : {
                 "parent" : null,
                 "contextName" : "root",
                 "rootContext" : true,
                 "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
               },
               "contextName" : "security",
               "authenticationId" : "openidm-admin",
               "authorizationId" : {
                 "id" : "openidm-admin",
                 "component" : "repo/internal/user",
                 "roles" : [ "openidm-admin", "openidm-authorized" ]
               },
               "rootContext" : false,
               "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
             },
             "headers" : {
               "X-OpenIDM-Username" : [ "openidm-admin" ],
               "Host" : [ "localhost:8443" ],
               "Accept" : [ "*/*" ],
               "X-OpenIDM-Password" : [ "openidm-admin" ],
               "User-Agent" : [ "curl/7.19.7 (x86_64-redhat-linux-gnu)
                 libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18
                 libssh2/1.4.2" ]
             },
             "parameters" : {
               "_queryId" : [ "query-all-ids" ],
               "_prettyPrint" : [ "true" ]
             },
             "external" : true,
             "contextName" : "http",
             "method" : "GET",
             "path" : "https://localhost:8443/openidm/endpoint/echo",
             "rootContext" : false,
             "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
           },
           "contextName" : "apiInfo",
           "apiVersion" : "2.3.1-SNAPSHOT",
           "apiName" : "org.forgerock.commons.json-resource-servlet",
           "rootContext" : false,
           "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
         },
         "contextName" : "server",
         "rootContext" : false,
         "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
       },
       "uriTemplateVariables" : { },
       "contextName" : "router",
       "matchedUri" : "endpoint/echo",
       "baseUri" : "endpoint/echo",
       "rootContext" : false,
       "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
     }
 } ],
 "resultCount" : 1,
 "pagedResultsCookie" : null,
 "remainingPagedResults" : -1
}  

You can set up custom configuration files in directories as defined in the openidm/conf/script.json file.

The following portion of the script.json file points to sources in installation and project directories. As described in Section 2.2, "Specifying the OpenIDM Startup Configuration", the launcher.project.location is the directory cited if you start OpenIDM with a specific project directory.

...
"sources" : {
  "default" : {
    "directory" : "&{launcher.install.location}/bin/defaults/script"
  },
  "install" : {
    "directory" : "&{launcher.install.location}"
  },
  "project" : {
    "directory" : "&{launcher.project.location}"
  },
  "project-script" : {
    "directory" : "&{launcher.project.location}/script"
  }
...

For example, if you start OpenIDM from the /path/to/openidm directory with the following command:

$ ./startup.sh -p /path/to/openidm/customconfig
   

The launcher.project.location directory would be /path/to/openidm/customconfig.

The script.json file also refers to a launcher.install.location directory, which is /path/to/openidm.

Thus, based on the way the script.json file is configured for project and project-script, you can add custom configuration and script files to the /path/to/openidm/customconfig and the /path/to/openidm/customconfig/script directories.

OpenIDM's uniform programming model means that all objects are queried and manipulated in the same way, using the Resource API. The URL or URI that is used to identify the target object for an operation depends on the object type. For an explanation of object types, see Appendix C, "Data Models and Objects Reference". For more information about scripts and the objects available to scripts, see Appendix F, "Scripting Reference".

You can use the Resource API to obtain managed objects, configuration objects, and repository objects, as follows:

val = openidm.read("managed/organization/mysampleorg")
val = openidm.read("config/custom/mylookuptable")
val = openidm.read("repo/custom/mylookuptable")
  

For information about constructing an object ID, see Section E.1, "URI Scheme".

You can update entire objects with the update() function, as follows.

openidm.update("managed/organization/mysampleorg", mymap)
openidm.update("config/custom/mylookuptable", mymap)
openidm.update("repo/custom/mylookuptable", mymap)
  

For managed objects, you can partially update an object with the patch() function.

openidm.patch("managed/organization/mysampleorg", rev, value)
  

The create(), delete(), and query() functions work the same way.

OpenIDM provides RESTful access to data objects via a REST API. To access objects over REST, you can use a browser-based REST client, such as the Simple REST Client for Chrome, or RESTClient for Firefox. Alternatively you can use the curl command-line utility.

For a comprehensive overview of the REST API, see Appendix E, "REST API Reference".

To obtain a managed object through the REST API, depending on your security settings and authentication configuration, perform an HTTP GET on the corresponding URL, for example https://localhost:8443/openidm/managed/organization/mysampleorg.

By default, the HTTP GET returns a JSON representation of the object.

OpenIDM supports an advanced query model that enables you to define queries, and to call them over the REST or Resource API. Three types of queries are supported, on both managed, and system objects:

Each of these mechanisms is discussed in the following sections.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/managed/user?_queryFilter=userName%20eq%20%22smith%22"

openidm.query("managed/user", { "_queryFilter" : '/userName eq "smith"' });

"query-all-ids" : "select _openidm_id from ${unquoted:_resource}"
   

?_queryId=query-all-ids
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/managed/user?_queryExpression=select+from+managed_user"
   

var params = {
    '_queryFilter' : 'givenName co "' + sourceCriteria + '" or ' + 'sn co "'
                     + sourceCriteria + '"'
};
var results = openidm.query("system/ScriptedSQL/account", params)
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET
 'https://localhost:8443/openidm/managed/user?_queryFilter=userName+eq+"Smith"'
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/system/ldap/account?_queryFilter=uid%20sw%20%22b%22&_pageSize=2"
   

{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 2,
  "result": [
    {
      "_id": "uid=bjensen,ou=People,dc=example,dc=com",
      "sn": "Jensen",
      "dn": "uid=bjensen,ou=People,dc=example,dc=com",
      "givenName": "Barbara",
      "description": "Created for OpenIDM",
      "cn": "Babara Jensen",
      "uid": "bjensen",
      "ldapGroups": [
        "cn=openidm2,ou=Groups,dc=example,dc=com"
      ],
      "mail": "bjensen@example.com",
      "telephoneNumber": "1-360-229-7105"
    },
    {
      "_id": "cn=bsmith,ou=People,dc=example,dc=com",
      "sn": "Smith",
      "dn": "cn=bsmith,ou=People,dc=example,dc=com",
      "givenName": "Bill",
      "description": null,
      "cn": "bsmith",
      "uid": "bsmith",
      "ldapGroups": [],
      "mail": "bsmith@example.com",
      "telephoneNumber": "0987362837"
    }
  ]
}   

"query-all-ids" : "select _openidm_id from ${unquoted:_resource} SKIP ${unquoted:_pagedResultsOffset} LIMIT ${unquoted:_pageSize}",

$ curl \
  --cacert self-signed.crt \
  --header "X-OpenIDM-Username: openidm-admin" \
  --header "X-OpenIDM-Password: openidm-admin" \
  --header "Content-Type: application/json" \
  --request GET \
  "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids&_pageSize=2&_pagedResultsOffset=3"
 {
   "remainingPagedResults": 2,
   "pagedResultsCookie": "5",
   "resultCount": 2,
   "result": [
     {
       "_rev": "0",
       "_id": "b980999e-aa5c-4655-b2a0-08731b64e0ba"
     },
     {
       "_rev": "0",
       "_id": "c72b9c00-1e2c-4139-9e7f-fb9fb822db96"
     }
   ]
 }  

$ 
'https://localhost:8443/openidm/system/ldap/account?_queryFilter=givenName+eq+"Dan"&_fields=givenName,sn&_sortKeys=sn'


{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 3,
  "result": [
    {
      "sn": "Cope",
      "givenName": "Dan"
    },
    {
      "sn": "Langdon",
      "givenName": "Dan"
    },
    {
      "sn": "Lanoway",
      "givenName": "Dan"
    }
  ]
}   
   

External users that are stored in OpenIDM's repository are referred to as managed users. For a JDBC repository, OpenIDM stores managed users in the managedobjects table. A second table, managedobjectproperties, serves as the index table. For an OrientDB repository, managed users are stored in the managed_user table.

OpenIDM provides RESTful access to managed users, at the context path /openidm/managed/user. For more information, see Section 1.3, "To Get Started With the OpenIDM REST Interface" in the Installation Guide.

OpenIDM provides support for a managed "group" object. For a JDBC repository, OpenIDM stores managed groups with all other managed objects, in the managedobjects table, and uses the managedobjectproperties for indexing. For an OrientDB repository, managed groups are stored in the managed_group table.

The managed group object is not provided by default. To use managed groups, add an object similar to the following to your conf/managed.json file:

{
    "name" : "group"
},
  

With this addition, OpenIDM provides RESTful access to managed groups, at the context path /openidm/managed/group.

For an example of a deployment that uses managed groups, see Section 3.6, "Sample 2d - Synchronizing LDAP Groups" in the Installation Guide.

The default managed object model includes a managed role object that can be manipulated in the same way as any other managed object.

This section refers to two distinct types of roles - direct (static) and indirect (dynamic) roles. Direct roles refer to roles that are specifically added to the user's "roles" attribute by an administrator operation. Indirect roles might be added to the user entry as a result of a script or rule that assigns the role. For example, a user might acquire a "sales-role" as a result of being in the "sales" organization.

A managed user's "roles" attribute takes an array as a value. Currently, only flat strings are supported in this array.

The "roles" attribute includes any specifically assigned roles, and any roles assigned internally by OpenIDM. So, the "roles" attribute of a particular user entry might appear as follows:

"roles" : [
    "name" : "managed/role/sample-role",
    "name" : "openidm-authorized"
]
  

A role value that includes a / character is considered to be a URL that points to the role details on the router, for example, managed/role/sample-role.

The following sections describe basic role manipulation - how roles are defined, assigned to users, and deleted. The entitlements or assignments supplied by roles are described in the subsequent section.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-None-Match: *" \
 --request PUT \
 --data '{
  "properties": {
    "description": "an example role"
  },
  "assignments": {
    "ldap": {
      "attributes": [
        {
          "name": "ldapGroups",
          "assignmentOperation": "mergeWithTarget",
          "unassignmentOperation": "removeFromTarget",
          "value": [
            "CN=employees,O=corp"
          ]
        }
      ],
      "onAssignment": {
        "file": "roles\/onAssignment_ldap.js",
        "type": "text\/javascript"
      },
      "onUnassignment": {
        "file": "roles\/onUnassignment_ldap.js",
        "type": "text\/javascript"
      }
    }
  }
}' \
 "https://localhost:8443/openidm/managed/role/newrole"
 
 {
   "assignments": {
     "ldap": {
       "attributes": [
         {
           "name": "ldapGroups",
           "unassignmentOperation": "removeFromTarget",
           "assignmentOperation": "mergeWithTarget",
           "value": [
             "CN=employees,O=corp"
           ]
         }
       ],
       "onAssignment": {
         "file": "roles/onAssignment_ldap.js",
         "type": "text/javascript"
       },
       "onUnassignment": {
         "file": "roles/onUnassignment_ldap.js",
         "type": "text/javascript"
       }
     }
   },
   "_id": "newrole",
   "properties": {
     "description": "an example role"
   },
   "_rev": "1"
 }
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/role/?_queryId=query-all-ids"
     
{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 1,
  "result": [
    {
      "_rev": "0",
      "_id": "newrole"
    }
  ]
}     
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-Match: *" \
 --request PATCH \
 --data '[
    {
        "operation": "add",
        "field": "/roles/-",
        "value": "managed/role/newrole"

    }
]' \
 "https://localhost:8443/openidm/managed/user/2e78fd22-a7cb-4585-9570-5f649e8abd25"
    
{
  "displayName": "Babara Jensen",
  "stateProvince": "",
  "userName": "bjensen",
  "postalAddress": "",
  "effectiveAssignments": {
    "ldap": {
      "attributes": [
        {
          "name": "ldapGroups",
          "unassignmentOperation": "removeFromTarget",
          "assignmentOperation": "mergeWithTarget",
          "assignedThrough": "managed/role/newrole",
          "value": [
            "CN=employees,O=corp"
          ]
        }
      ],
      "onAssignment": {
        "file": "roles/onAssignment_ldap.js",
        "type": "text/javascript"
      },
      "onUnassignment": {
        "file": "roles/onUnassignment_ldap.js",
        "type": "text/javascript"
      }
    }
  },
  "roles": [
    "openidm-authorized",
    "managed/role/newrole"
  ],
  "city": "",
  "effectiveRoles": [
    "openidm-authorized",
    "managed/role/newrole"
  ],
  "givenName": "Barbara",
  "lastPasswordAttempt": "Tue Oct 21 2014 16:01:22 GMT+0200 (SAST)",
  "address2": "",
  "passwordAttempts": "0",
  "sn": "Jensen",
  "mail": "bjensen@example.com",
  "country": "",
  "_rev": "2",
  "lastPasswordSet": "",
  "postalCode": "",
  "_id": "2e78fd22-a7cb-4585-9570-5f649e8abd25",
  "description": "Created for OpenIDM",
  "accountStatus": "active",
  "telephoneNumber": "1-360-229-7105"
}
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user?_queryId=get-users-of-direct-role&role=managed/role/newrole"
     
{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 1,
  "result": [
    {
      "effectiveAssignments": {
        "ldap": {
          "attributes": [
            {
              "name": "ldapGroups",
...
      "_id": "2e78fd22-a7cb-4585-9570-5f649e8abd25",
      "_rev": "2",
      "description": "Created for OpenIDM",
      "accountStatus": "active"
    }
  ]
}
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-Match: *" \
 --request PATCH \
 --data '[
    {
        "operation": "replace",
        "field": "/roles",
        "value": [
            "openidm-authorized"
        ]
    }
]' \
 "https://localhost:8443/openidm/managed/user/2e78fd22-a7cb-4585-9570-5f649e8abd25"

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request DELETE \
 "https://localhost:8443/openidm/managed/role/newrole"
{
  "properties": {
    "description": "an example role"
  },
  "assignments": {
    "ldap": {
      "attributes": [
        {
          "name": "ldapGroups",
          "unassignmentOperation": "removeFromTarget",
          "assignmentOperation": "mergeWithTarget",
          "value": [
            "CN=employees,O=corp"
          ]
        }
      ],
      "onAssignment": {
        "file": "roles/onAssignment_ldap.js",
        "type": "text/javascript"
      },
      "onUnassignment": {
        "file": "roles/onUnassignment_ldap.js",
        "type": "text/javascript"
      }
    }
  },
  "_rev": "1",
  "_id": "newrole"
}
    

{
  "message": "Cannot delete a role that is currently assigned",
  "reason": "Conflict",
  "code": 409
}

{
     "name": "samplerole",
     "_id": "samplerole",
     "assignments": {
         "ad": {
             "attributes": [
                 {
                     "name": "adSystems",
                     "value": [
                         "CN=fileshare,O=corp",
                         "CN=desktop,O=corp",
                         "CN=terminal,O=corp",
                         "CN=intranet,O=corp"
                     ],
                     "assignmentOperation": "mergeWithTarget",
                     "unassignmentOperation": "removeFromTarget"
                 }
             ]
         },
         "ldap": {
             "attributes": [
                 {
                     "name": "ldapGroups",
                     "value": [
                         "CN=employees,O=corp"
                     ],
                     "assignmentOperation": "mergeWithTarget",
                     "unassignmentOperation": "removeFromTarget"
                 },
                 {
                     "name": "employeeType",
                     "value": "employee"
                 }
             ],
             "onAssignment": {
                 "file": "roles/onAssignment_ldap.js",
                 "type": "text/javascript"
             },
             "onUnassignment": {
                 "file": "roles/onUnassignment_ldap.js",
                 "type": "text/javascript"
             }
         }
     }
}

 {
     "name" : "effectiveRoles",
     "type" : "virtual",
     "onRetrieve" : {
         "type" : "text/javascript",
         "file" : "roles/effectiveRoles.js",
         "rolesPropName" : "roles"
     }
 },
 {
     "name" : "effectiveAssignments",
     "type" : "virtual",
     "onRetrieve" : {
         "type" : "text/javascript",
         "file" : "roles/effectiveAssignments.js",
         "effectiveRolesPropName" : "effectiveRoles"
     }
 }
   

 {
    "_id":"i",
    "_rev":"1",
    "roles":[
       "openidm-authorized",
       "managed/role/sample-role"
    ],
    "effectiveRoles":[
       "openidm-authorized",
       "managed/role/sample-role"
    ],
    "effectiveAssignments":{
       "ldap":{
          "attributes":[
             {
                "value":[
                   "CN=employees,O=corp"
                ],
                "operation":"replaceTarget",
                "name":"ldapGroups",
                "assignedThrough":"managed/role/sample-role"
             },
             {
                "value":"employee",
                "name":"employeeType",
                "assignedThrough":"managed/role/sample-role"
             }
          ]
       },
       "ad":{
          "attributes":[
             {
                "value":[
                   "CN=fileshare,O=corp",
                   "CN=desktop,O=corp",
                   "CN=terminal,O=corp",
                   "CN=intranet,O=corp"
                ],
                "operation":"replaceTarget",
                "name":"adSystems",
                "assignedThrough":"managed/role/sample-role"
             }
          ]
       }
    }
 }

{
    "name" : "managedUser_systemLdapAccounts",
    "source" : "managed/user",
    "target" : "system/ldap/account",
    "links" : "systemLdapAccounts_managedUser",
    },
    "assignmentsToMap": [
        "ldap"
    ],
    ...
}   

{
     "name" : "role",
     "postCreate" : {
         "type" : "text/javascript",
         "file" : "roles/update-users-of-role.js"
     },
     "postUpdate" : {
         "type" : "text/javascript",
         "file" : "roles/update-users-of-role.js"
     },
     "postDelete" : {
         "type" : "text/javascript",
         "file" : "roles/update-users-of-role.js"
     }
}

The default policy is configured in two files:

...
{   "policyId" : "at-least-X-capitals",
    "policyExec" : "atLeastXCapitalLetters",
    "clientValidation": true,
    "validateOnlyIfPresent":true,
    "policyRequirements" : ["AT_LEAST_X_CAPITAL_LETTERS"]
},
...

policyFunctions.atLeastXCapitalLetters = function(fullObject, value, params, property) {
  var isRequired = _.find(this.failedPolicyRequirements, function (fpr) {
      return fpr.policyRequirement === "REQUIRED";
    }),
    isNonEmptyString = (typeof(value) === "string" && value.length),
    valuePassesRegexp = (function (v) {
      var test = isNonEmptyString ? v.match(/[(A-Z)]/g) : null;
      return test !== null && test.length >= params.numCaps;
    }(value));

  if ((isRequired || isNonEmptyString) && !valuePassesRegexp) {
    return [ { "policyRequirement" : "AT_LEAST_X_CAPITAL_LETTERS", "params" : {"numCaps": params.numCaps} } ];
  }

  return [];
}     
...     
      

{   "policyId" : "minimum-length",
    "policyExec" : "propertyMinLength",
    "clientValidation": true,
    "validateOnlyIfPresent": true,
    "policyRequirements" : ["MIN_LENGTH"]
}
      

function <name>(fullObject, value, params, propName) {	
	<implementation_logic>
}
        

function required(fullObject, value, params, propName) {
    if (value === undefined) {
        return [ { "policyRequirement" : "REQUIRED" } ];
    }
    return [];
}          
        

{
    "type" : "text/javascript",
    "file" : "bin/defaults/script/policy.js",
    "resources" : [
        {
            "resource" : "managed/user/*",
            "properties" : [
...
                {
                    "name" : "password",
                    "policies" : [
                        {
                            "policyId" : "required"
                        },
                        {
                            "policyId" : "not-empty"
                        },
                        {
                            "policyId" : "at-least-X-capitals",
                            "params" : {
                                "numCaps" : 1
                            }
                        },
                ...
           }
       ]
}     
       

...
    {
        "name" : "mobilePhones",
        "policies" : [
            {
                "policyId" : "required"
            },
            {
                "policyId" : "not-empty"
            }
        ]
    },
    {
        "name" : "mobilePhones[*]",
        "policies" : [
            {
                "policyId" : "not-empty"
            }
        ]
    }
...
       

You can extend the policy service by adding your own scripted policies in openidm/script and referencing them in the policy configuration file (conf/policy.json). Avoid manipulating the default policy script file (in bin/defaults/script) as doing so might result in interoperability issues in a future release. To reference additional policy scripts, set the "additionalFiles" property in conf/policy.json.

The following example creates a custom policy that rejects properties with null values. The policy is defined in a script named mypolicy.js.

var policy = {   "policyId" : "notNull",
       "policyExec" : "notNull",  
       "policyRequirements" : ["NOT_NULL"]
}

addPolicy(policy);

function notNull(fullObject, value, params, property) {
   if (value == null) {
       return [ {"policyRequirement": "NOT_NULL"}];
   }
   return [];
} 
    

The mypolicy.js policy is referenced in the policy.json configuration file as follows:

{
    "type" : "text/javascript",
    "file" : "bin/defaults/script/policy.js",
    "additionalFiles" : ["script/mypolicy.js"],
    "resources" : [
        {
...
    

You can also configure policies for managed object properties as part of the property definition in the conf/managed.json file. For example, the following extract of a managed.json file shows a policy configuration for the password property.

...
"properties" : [
    {
        "name" : "password",
        "encryption" : {
            "key" : "openidm-sym-default"
        },
        "scope" : "private"
        "policies" : [
            {
                "policyId" : "required"
            },
            {
                "policyId" : "not-empty"
            },
            {
                "policyId" : "at-least-X-capitals",
                "params" : {
                "numCaps" : 1
                }
            }
        ]
    },
...
   

Policy enforcement refers to the automatic validation of data in the repository when it is created, updated, or patched. In certain situations you might want to disable policy enforcement temporarily. You might, for example, want to import existing data that does not meet the validation requirements with the intention of cleaning up this data at a later stage.

You can disable policy enforcement by setting openidm.policy.enforcement.enabled to false in the conf/boot/boot.properties file. This setting disables policy enforcement in the back-end only, and has no impact on direct policy validation calls to the Policy Service (which the user interface makes to validate input fields). So, with policy enforcement disabled, data added directly over REST is not subject to validation, but data added with the UI is still subject to validation.

Disabling policy enforcement permanently in a production system is not recommended.

You can manage the policy service over the REST interface, by calling the REST endpoint https://localhost:8443/openidm/policy, as shown in the following examples.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/policy"

{
  "resources": [
    {
      "properties": [
      {
        "name": "_id",
        "policies": [
          {
            "policyFunction":
...
      

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/policy/managed/user/*"

{
   "properties": [
     {
        "name": "_id",
        "policies": [
            {
            "policyFunction": "
               "\n  function (fullObject, value, params, property) {
               \n    var i, join = function (arr, d) {

...
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{
  "sn":"Jones",
  "givenName":"Bob",
  "_id":"bjones",
  "telephoneNumber":"0827878921",
  "passPhrase":null,
  "mail":"bjones@example.com",
  "accountStatus":"active",
  "roles":"admin",
  "userName":"bjones@example.com",
  "password":"123"}' \
 "https://localhost:8443/openidm/policy/managed/user/bjones?_action=validateObject"
       
       
 {
   "failedPolicyRequirements": [
     {
       "property": "password",
       "policyRequirements": [
         {
           "params": {
             "numCaps": 1
           },
           "policyRequirement": "AT_LEAST_X_CAPITAL_LETTERS"
         }
       ]
     },
     {
       "property": "password",
       "policyRequirements": [
         {
           "params": {
             "minLength": 8
           },
           "policyRequirement": "MIN_LENGTH"
         }
       ]
     },
     {
       "property": "passPhrase",
       "policyRequirements": [
         {
           "params": {
             "minLength": 4
           },
           "policyRequirement": "MIN_LENGTH"
         }
       ]
     }
   ],
   "result": false
 }
      

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --cacert self-signed.crt \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{ "password" : "12345" }' \
 "https://localhost:8443/openidm/policy/managed/user/bjensen?_action=validateProperty"
       
{
    "result": false,
    "failedPolicyRequirements": [
        {
            "policyRequirements": [
                {
                    "policyRequirement": "AT_LEAST_X_CAPITAL_LETTERS",
                    "params": {
                        "numCaps": 1
                    }
                },
                {
                    "policyRequirement": "MIN_LENGTH",
                    "params": {
                        "minLength": 8
                    }
                }
            ],
            "property": "password"
        }
    ]
}                  
      

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{ "password" : "1NewPassword" }' \
 "https://localhost:8443/openidm/policy/managed/user/bjensen?_action=validateProperty"
       
       
{
    "failedPolicyRequirements": []
    "result": true,
}                      
      

The default configuration writes log messages in simple format to openidm/logs/openidm*.log files, rotating files when the size reaches 5 MB, and retaining up to 5 files. Also by default, OpenIDM writes all system and custom log messages to the files.

You can update the configuration to attach loggers to individual packages, setting the log level to one of the following values.

SEVERE (highest value)
WARNING
INFO
CONFIG
FINE
FINER
FINEST (lowest value)

If you use logger functions in your JavaScript scripts, you can set the log level for the scripts as follows:

org.forgerock.script.javascript.JavaScript.level=level

You can override the log level settings per script by using

org.forgerock.script.javascript.JavaScript.script-name.level

You can also disable logs if desired. For example, before starting OpenIDM, you can disable ConsoleHandler logging in the same openidm/conf/logging.properties file.

Just set java.util.logging.ConsoleHandler.level = OFF, and comment out other references to ConsoleHandler, as shown in the following excerpt.

   # ConsoleHandler: A simple handler for writing formatted records to System.err
   #handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler
   handlers=java.util.logging.FileHandler
   ...
   # --- ConsoleHandler ---
   # Default: java.util.logging.ConsoleHandler.level = INFO
   java.util.logging.ConsoleHandler.level = OFF
   #java.util.logging.ConsoleHandler.formatter = ...
   #java.util.logging.ConsoleHandler.filter=...

OpenICF provides a common interface to allow identity services access to the resources that contain user information. OpenIDM loads the OpenICF API as one of its OSGi modules. OpenICF uses connectors to separate the OpenIDM implementation from the dependencies of the resource to which OpenIDM is connecting. A specific connector is required for each remote resource. Connectors can run either locally or remotely.

Local connectors are loaded by OpenICF as regular bundles in the OSGi container. Remote connectors must be executed on a remote connector server. Most connectors can be run locally. However, a remote connector server is required when access libraries that cannot be included as part of the OpenIDM process are needed. If a resource, such as Microsoft Active Directory, does not provide a connection library that can be included inside the Java Virtual Machine, OpenICF can use the native .dll with a remote .NET connector server. In other words, OpenICF connects to Active Directory through a remote connector server that is implemented as a .NET service.

Connections to remote connector servers are configured in a single connector info provider configuration file, located in /path/to/openidm/conf.

Connectors themselves are configured through provisioner files. One provisioner file must exist for each connector. Provisioner files are named provisioner.openicf-name where name corresponds to the name of the connector, and are also located in the /path/to/openidm/conf directory.

A number of sample connector configurations are available in the openidm/samples/provisioners directory. To use these connectors, edit the configuration files as required, and copy them to the openidm/conf directory.

The following figure shows how OpenIDM connects to resources by using connectors and remote connector servers. The figure shows one local connector (LDAP) and two remote connectors (Scripted SQL and PowerShell). In this example, the remote Scripted SQL connector uses a remote Java connector server. The remote PowerShell connector always requires a remote .NET connector server.

When you configure a remote connector, you use the connector info provider service to connect through a remote connector server. The connector info provider service configuration is stored in the file openidm/conf/provisioner.openicf.connectorinfoprovider.json. A sample configuration file is provided in the openidm/samples/provisioners/ directory. To use this sample configuration, edit the file as required, and copy it to the openidm/conf directory.

The connector info provider service takes the following configuration:

{
  "connectorsLocation"     : string,
  "remoteConnectorServers" : [remoteConnectorServer objects]
}

{
  "name"               : "dotnet",
  "host"               : "127.0.0.1",
  "port"               : 8759,
  "heartbeatInterval"  : 60,
  "useSSL"             : false,
  "timeout"            : 0,
  "key"                : "Passw0rd"
}

To run remotely, the connector .jar itself must be copied to the openicf/bundles directory, on the remote machine.

Connectors are configured through the OpenICF provisioner service. Each connector configuration is stored in a file in the openidm/conf/ folder, and accessible over REST at the openidm/conf endpoint. Configuration files are named openidm/conf/provisioner.openicf-name where name corresponds to the name of the connector. A number of sample connectors are available in the openidm/samples/provisioners directory. To use these connectors, edit the configuration files as required, and copy them to the openidm/conf directory.

If you are creating your own connector configuration files, do not include additional dash characters ( - ) in the connector name, as this might cause problems with the OSGi parser. For example, the name provisioner.openicf-hrdb.json is fine. The name provisioner.openicf-hr-db.json is not.

The following example shows a connector configuration for an XML file resource.

{
 "name"                    : "xml",
 "connectorRef"            : connector-ref-object,
 "poolConfigOption"        : pool-config-option-object,
 "operationTimeout"        : operation-timeout-object,
 "configurationProperties" : configuration-properties-object,
 "objectTypes"             : object-types-object,
 "operationOptions"        : operation-options-object
}

The "name" property specifies the name of the system to which you are connecting. This name must be alphanumeric.

{
  "bundleName"       : "org.forgerock.openicf.connectors.xml-connector",
  "bundleVersion"    : "1.1.0.2",
  "connectorName"    : "org.forgerock.openicf.connectors.xml.XMLConnector",
  "connectorHostRef" : "host"
}

{
  "maxObjects"                 : 10,
  "maxIdle"                    : 10,
  "maxWait"                    : 150000,
  "minEvictableIdleTimeMillis" : 120000,
  "minIdle"                    : 1
}

{
  "CREATE"              : -1,
  "TEST"                : -1,
  "AUTHENTICATE"        : -1,
  "SEARCH"              : -1,
  "VALIDATE"            : -1,
  "GET"                 : -1,
  "UPDATE"              : -1,
  "DELETE"              : -1,
  "SCRIPT_ON_CONNECTOR" : -1,
  "SCRIPT_ON_RESOURCE"  : -1,
  "SYNC"                : -1,
  "SCHEMA"              : -1
}

"configurationProperties" : {
    "xsdIcfFilePath" : "&{launcher.project.location}/data/resource-schema-1.xsd",
    "xsdFilePath" : "&{launcher.project.location}/data/resource-schema-extension.xsd",
    "xmlFilePath" : "&{launcher.project.location}/data/xmlConnectorData.xml"
}

system/$systemName/$objectType

{
  "account" :
  {
    "$schema" : "http://json-schema.org/draft-03/schema",
    "id" : "__ACCOUNT__",
    "type" : "object",
    "nativeType" : "__ACCOUNT__",
    "properties" :
    {
      "name" :
      {
        "type" : "string",
        "nativeName" : "__NAME__",
        "nativeType" : "JAVA_TYPE_PRIMITIVE_LONG",
        "flags" :
        [
          "NOT_CREATABLE",
          "NOT_UPDATEABLE",
          "NOT_READABLE",
          "NOT_RETURNED_BY_DEFAULT"
        ]
      },
      "groups" :
      {
        "type" : "array",
        "items" :
        {
          "type" : "string",
          "nativeType" : "string"
        },
        "nativeName" : "__GROUPS__",
        "nativeType" : "string",
        "flags" :
        [
          "NOT_RETURNED_BY_DEFAULT"
        ]
      },                
      "givenName" : {
         "type" : "string",
         "nativeName" : "givenName",
         "nativeType" : "string"
         },
    }
  }
}

"objectTypes": {
    "allobjects": {
        "$schema": "http://json-schema.org/draft-03/schema",
        "id": "__ALL__",
        "type": "object",
        "nativeType": "__ALL__"
    },
...

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system/ldap?_action=liveSync"

"operationOptions" : {
  {
    "SYNC" :
    {
      "denied" : true,
      "onDeny" : "DO_NOTHING",
      "objectFeatures" :
      {
        "__ACCOUNT__" :
        {
          "denied" : true,
          "onDeny" : "THROW_EXCEPTION",
          "operationOptionInfo" :
          {
            "$schema" : "http://json-schema.org/draft-03/schema",
            "id" : "FIX_ME",
            "type" : "object",
            "properties" :
            {
              "_OperationOption-float" :
              {
                 "type" : "number",
                 "nativeType" : "JAVA_TYPE_PRIMITIVE_FLOAT"
              }
            }
          }
        },
        "__GROUP__" :
        {
          "denied" : false,
          "onDeny" : "DO_NOTHING"
        }
      }
    }
  }
...

Connectors that use the .NET framework must run remotely. Java connectors can run locally or remotely. Connectors that run remotely require a connector server to enable OpenIDM to access the connector.

This section describes the steps to install a .NET connector server and a remote Java Connector Server.

<add name="file"
    type="System.Diagnostics.TextWriterTraceListener"
    initializeData="C:\openicf\logs\connectorserver.log"
    traceOutputOptions="DateTime">
      <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information"/>
  </add>

OpenIDM 3.1 provides several connectors by default, in the path/to/openidm/connectors directory. Additional connectors can be downloaded from ForgeRock's Backstage site.

This section describes the connectors that are supported for use with OpenIDM 3.1, and provides instructions for installing and configuring these connectors. For instructions on building connector configurations interactively, see Section 11.6, "Creating Default Connector Configurations".

{
    "connectorRef": {
        "connectorHostRef": "#LOCAL",
        "bundleName": "org.forgerock.openicf.connectors.xml-connector",
        "bundleVersion": "1.1.0.2",
        "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
    }
}

{
    "configurationProperties": {
        "xsdIcfFilePath" : "&{launcher.project.location}/data/resource-schema-1.xsd",
        "xsdFilePath" : "&{launcher.project.location}/data/resource-schema-extension.xsd",
        "xmlFilePath" : "&{launcher.project.location}/data/xmlConnectorData.xml"
    }
}

$ cd path/to/openidm
 $ scp -r samples/sample1/data testuser@remote-host:/home/testuser/xml-sample
 testuser@remote-host's password:
 resource-schema-1.xsd                    100% 4083     4.0KB/s   00:00
 resource-schema-extension.xsd            100% 1351     1.3KB/s   00:00
 xmlConnectorData.xml                     100% 1648     1.6KB/s   00:00

$ cd path/to/openidm
 $ scp connectors/xml-connector-1.4.0.0.jar testuser@remote-host:/path/to/openicf/bundles
 testuser@172.16.203.97's password:
 xml-connector-1.4.0.0.jar                100% 4379KB   4.3MB/s   00:00

{
    "connectorRef": {
        "connectorHostRef": "#LOCAL",
        "connectorName": "org.identityconnectors.ldap.LdapConnector",
        "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
        "bundleVersion": "[1.4.0.0,2.0.0.0)"
    }
}

"configurationProperties" : {
    "host" : "localhost",
    "port" : 1389,
    "ssl" : false,
    "principal" : "cn=Directory Manager",
    "credentials" : "password",
    "baseContexts" : [
        "dc=example,dc=com"
    ],
    "baseContextsToSynchronize" : [
        "dc=example,dc=com"
    ],
    "accountSearchFilter" : null,
    "accountSynchronizationFilter" : null,
    "groupSearchFilter" : null,
    "groupSynchronizationFilter" : null,
    "passwordAttributeToSynchronize" : null,
    "synchronizePasswords" : false,
    "removeLogEntryObjectClassFromFilter" : true,
    "modifiersNamesToFilterOut" : [ ],
    "passwordDecryptionKey" : null,
    "changeLogBlockSize" : 100,
    "attributesToSynchronize" : [ ],
    "changeNumberAttribute" : "changeNumber",
    "passwordDecryptionInitializationVector" : null,
    "filterWithOrInsteadOfAnd" : false,
    "objectClassesToSynchronize" : [
        "inetOrgPerson"
    ],
    "vlvSortAttribute" : "uid",
    "passwordAttribute" : "userPassword",
    "useBlocks" : false,
    "maintainPosixGroupMembership" : false,
    "failover" : [ ],
    "readSchema" : true,
    "accountObjectClasses" : [
        "top",
        "person",
        "organizationalPerson",
        "inetOrgPerson"
    ],
    "accountUserNameAttributes" : [
        "uid"
    ],
    "groupMemberAttribute" : "uniqueMember",
    "passwordHashAlgorithm" : null,
    "usePagedResultControl" : false,
    "blockSize" : 100,
    "uidAttribute" : "dn",
    "maintainLdapGroupMembership" : false,
    "respectResourcePasswordPolicyChangeAfterReset" : false
},

# Set the truststore
javax.net.ssl.trustStore=/path/to/openidm/security/truststore
   

$ more /path/to/openidm/script/access.js
       ...
{
    "pattern"   : "system/ActiveDirectory",
    "roles"     : "openidm-admin",
    "methods" : "action",
    "actions"   : "script"
},     

     if ($loginName -ne $NULL) {
  [System.Reflection.Assembly]::LoadWithPartialName('Microsoft.SqlServer.SMO') | Out-Null
  $sqlSrv = New-Object ('Microsoft.SqlServer.Management.Smo.Server') ('WIN-C2MSQ8G1TCA')

  $login = New-Object -TypeName ('Microsoft.SqlServer.Management.Smo.Login') ($sqlSrv, $loginName)
  $login.LoginType = 'SqlLogin'
  $login.PasswordExpirationEnabled = $false
  $login.Create('Passw0rd')
  #  The next two lines are optional, and to give the new login a server role, optional
  $login.AddToRole('sysadmin')
  $login.Alter()
 } else {
  $Error_Message = [string]"Required variables 'loginName' is missing!"
     Write-Error $Error_Message
     throw $Error_Message
 }
     

 "systemActions" : [
     {
         "_scriptId" : "ConnectorScriptName",
         "actions" : [
             {
                 "systemType" : ".*ActiveDirectoryConnector",
                 "actionType" : "Shell",
                 "actionSource" : "@echo off \r\n echo %loginName%\r\n"
             },
             {
                 "systemType" : ".*ActiveDirectoryConnector",
                 "actionType" : "PowerShell",
                 "actionFile" : "script/createUser.ps1"
             }
         ]
     }
 ]
     

$ curl \
  --cacert self-signed.crt \
  --header "X-OpenIDM-Username: openidm-admin" \
  --header "X-OpenIDM-Password: openidm-admin" \
  --header "Content-Type: application/json" \
  --request POST \
  "https://localhost:8443/openidm/system/ActiveDirectory/?_action=script&scriptId=ConnectorScriptName&scriptExecuteMode=resource&loginName=myUser"

{
  "connectorRef": {
    "connectorHostRef": "#LOCAL",
    "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector",
    "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
    "bundleVersion": "1.1.0.2"
  }
}

{
    "configurationProperties": {
        "filePath": "data/hr.csv",
        "uniqueAttribute": "uid"
    }
}

"configurationProperties" : {
    "host" : "localhost",
    "port" : "3306",
    ...
    "database" : "HRDB",
    "autoCommit" : false,
    "reloadScriptOnExecution" : true,
    "createScriptFileName" : "&{launcher.project.location}/tools/CreateScript.groovy",
    ...
   

"configurationProperties" :
    {
       "quoting" : "",
       "host" : "localhost",
       "port" : "3306",
       "user" : "root",
       "password" : "",
       "database" : "contractordb",
       "table" : "people",
       "keyColumn" : "UNIQUE_ID",
       "passwordColumn" : "",
       "jdbcDriver" : "com.mysql.jdbc.Driver",
       "jdbcUrlTemplate" : "jdbc:mysql://%h:%p/%d",
       "enableEmptyString" : false,
       "rethrowAllSQLExceptions" : true,
       "nativeTimestamps" : true,
       "allNative" : false,
       "validConnectionQuery" : null,
       "changeLogColumn" : "CHANGE_TIMESTEMP",
       "datasource" : "",
       "jndiProperties" : null
    },

{
    "connectorHostRef": "#LOCAL",
    "connectorName": "org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector",
    "bundleName": "org.forgerock.openicf.connectors.googleapps-connector",
    "bundleVersion": "[1.4.0.0,2.0.0.0)"
}, 

"configurationProperties": {
    "domain": "",
    "clientId": "",
    "clientSecret": null,
    "refreshToken": null
}, 

Rather than creating provisioner files by hand, use the service that OpenIDM exposes through the REST interface to create basic connector configuration files, or use the cli.sh or cli.bat scripts to generate a basic connector configuration.

This section describes how to create connector configurations over the REST interface. For instructions on using the CLI to create connector configurations, see Section 3.3, "configureconnector".

List the available connectors by using the following command.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system?_action=availableConnectors"

The preceding command therefore returns the following output:

{
  "connectorRef": [
    {
      "bundleVersion": "1.1.0.2",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
      "displayName": "CSV File Connector",
      "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector"
    },
    {
      "bundleVersion": "1.1.0.1",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.databasetable-connector",
      "displayName": "Database Table Connector",
      "connectorName": "org.identityconnectors.databasetable.DatabaseTableConnector"
    },
    {
      "bundleVersion": "1.4.1.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.googleapps-connector",
      "displayName": "GoogleApps Connector",
      "connectorName": "org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector"
    },
    {
      "bundleVersion": "1.4.1.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "displayName": "Scripted Poolable Groovy Connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedPoolableConnector"
    },
    {
      "bundleVersion": "1.4.1.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "displayName": "Scripted Groovy Connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedConnector"
    },
    {
      "bundleVersion": "1.4.1.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "displayName": "Scripted CREST Connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedcrest.ScriptedCRESTConnector"
    },
    {
      "bundleVersion": "1.4.1.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "displayName": "Scripted SQL Connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"
    },
    {
      "bundleVersion": "1.4.1.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "displayName": "Scripted REST Connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"
    },
    {
      "bundleVersion": "1.4.0.1",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
      "displayName": "LDAP Connector",
      "connectorName": "org.identityconnectors.ldap.LdapConnector"
    },
    {
      "bundleVersion": "1.1.0.2",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.xml-connector",
      "displayName": "XML Connector",
      "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
    },
    {
      "bundleVersion": "{provisioner.salesforcemodule.version}",
      "systemType": "provisioner.salesforce",
      "bundleName": "org.forgerock.openidm.salesforce",
      "displayName": "Salesforce Connector",
      "connectorName": "org.forgerock.openidm.salesforce.Salesforce"
    }
  ]
}

To generate the core configuration, choose one of the available connectors by copying one of the JSON objects from the generated list into the body of the REST command, as shown below for the XML connector.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{"connectorRef":
 {"connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector",
 "displayName": "XML Connector",
 "bundleName": "org.forgerock.openicf.connectors.xml-connector",
 "bundleVersion": "1.1.0.2"}
 }' \
 "https://localhost:8443/openidm/system?_action=createCoreConfig"

This command returns a core connector configuration, similar to the following:

{
   "poolConfigOption": {
   "minIdle": 1,
   "minEvictableIdleTimeMillis": 120000,
   "maxWait": 150000,
   "maxIdle": 10,
   "maxObjects": 10
  },
   "resultsHandlerConfig": {
   "enableAttributesToGetSearchResultsHandler": true,
   "enableFilteredResultsHandler": true,
   "enableNormalizingResultsHandler": true
  },
  "operationTimeout": {
    "SCHEMA": -1,
    "SYNC": -1,
    "VALIDATE": -1,
    "SEARCH": -1,
    "AUTHENTICATE": -1,
    "CREATE": -1,
    "UPDATE": -1,
    "DELETE": -1,
    "TEST": -1,
    "SCRIPT_ON_CONNECTOR": -1,
    "SCRIPT_ON_RESOURCE": -1,
    "GET": -1,
    "RESOLVEUSERNAME": -1
  },
  "configurationProperties": {
   "xsdIcfFilePath": null,
   "xsdFilePath": null,
   "createFileIfNotExists": false,
   "xmlFilePath": null
  },
  "connectorRef": {
    "bundleVersion": "1.1.0.2",
    "bundleName": "org.forgerock.openicf.connectors.xml-connector",
    "displayName": "XML Connector",
    "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
  }
}

The configuration that is returned is not yet functional. Notice that it does not contain the required system-specific "configurationProperties", such as the host name and port for web based connectors, or the "xmlFilePath" for the XML file-based connector. In addition, the configuration does not include the complete list of "objectTypes" and "operationOptions".

To generate the final configuration, add values for the "configurationProperties" to the core configuration, and use the updated configuration as the body for the next command.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{
  "configurationProperties":
    {
      "xsdIcfFilePath" : "samples/sample1/data/resource-schema-1.xsd",
      "xsdFilePath" : "samples/sample1/data/resource-schema-extension.xsd",
      "xmlFilePath" : "samples/sample1/data/xmlConnectorData.xml",
      "createFileIfNotExists": false
  },
  "operationTimeout": {
    "SCHEMA": -1,
    "SYNC": -1,
    "VALIDATE": -1,
    "SEARCH": -1,
    "AUTHENTICATE": -1,
    "CREATE": -1,
    "UPDATE": -1,
    "DELETE": -1,
    "TEST": -1,
    "SCRIPT_ON_CONNECTOR": -1,
    "SCRIPT_ON_RESOURCE": -1,
    "GET": -1,
    "RESOLVEUSERNAME": -1
  },
  "resultsHandlerConfig": {
    "enableAttributesToGetSearchResultsHandler": true,
    "enableFilteredResultsHandler": true,
    "enableNormalizingResultsHandler": true
  },
  "poolConfigOption": {
    "minIdle": 1,
    "minEvictableIdleTimeMillis": 120000,
    "maxWait": 150000,
    "maxIdle": 10,
    "maxObjects": 10
  },
  "connectorRef": {
    "bundleVersion": "1.1.0.2",
    "bundleName": "org.forgerock.openicf.connectors.xml-connector",
    "displayName": "XML Connector",
    "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
  }
}' \
 "https://localhost:8443/openidm/system?_action=createFullConfig"

OpenIDM attempts to read the schema, if available, from the external resource in order to generate output. OpenIDM then iterates through schema objects and attributes, creating JSON representations for "objectTypes" and "operationOptions" for supported objects and operations.

The output includes the basic --data input, along with operationOptions and objectTypes.

Because OpenIDM produces a full property set for all attributes and all object types in the schema from the external resource, the resulting configuration can be large. For an LDAP server, OpenIDM can generate a configuration containing several tens of thousands of lines, for example. You might therefore want to reduce the schema to a minimum on the external resource before you run the createFullConfig command.

After a connection has been configured, external systems are accessible over the REST interface at the URL https://localhost:8443/openidm/system/connector-name. Aside from accessing the data objects within the external systems, you can test the availability of the systems themselves.

To list the external systems that are connected to an OpenIDM instance, use the test action on the URL https://localhost:8443/openidm/system/. The following example shows the connector configuration for an external LDAP system.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system?_action=test"
[
  {
    "ok": true,
    "connectorRef": {
      "bundleVersion": "[1.4.0.0,2.0.0.0)",
      "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
      "connectorName": "org.identityconnectors.ldap.LdapConnector"
    },
    "objectTypes": [
      "group",
      "account"
    ],
    "config": "config/provisioner.openicf/ldap",
    "enabled": true,
    "name": "ldap"
  }
]

The status of the system is provided by the ok parameter. If the connection is available, the value of this parameter is true.

To obtain the status for a single system, include the name of the connector in the URL, for example:

$ curl \
 --cacert self-signed.crt \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "https://localhost:8443/openidm/system/ldap?_action=test"
{
  "ok": true,
  "connectorRef": {
    "bundleVersion": "[1.4.0.0,2.0.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
    "connectorName": "org.identityconnectors.ldap.LdapConnector"
  },
  "objectTypes": [
    "group",
    "account"
  ],
  "config": "config/provisioner.openicf/ldap",
  "enabled": true,
  "name": "ldap"
}

If there is a problem with the connection, the "ok" parameter returns false, with an indication of the error. In the following example, the LDAP server named ldap, running on localhost:1389, is down.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system/ldap?_action=test"
{
  "ok": false,
  "error": "localhost:1389",
  "connectorRef": {
    "bundleVersion": "[1.4.0.0,2.0.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
    "connectorName": "org.identityconnectors.ldap.LdapConnector"
  },
  "objectTypes": [
    "group",
    "account"
  ],
  "config": "config/provisioner.openicf/ldap",
  "enabled": true,
  "name": "ldap"
}

To test the validity of a connector configuration, use the testConfig action and include the configuration in the command. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --data '{
    "name" : "xmlfile",
    "connectorRef" : {
        "bundleName" : "org.forgerock.openicf.connectors.xml-connector",
        "bundleVersion" : "1.1.0.2",
        "connectorName" : "org.forgerock.openicf.connectors.xml.XMLConnector"
    },
    "producerBufferSize" : 100,
    "connectorPoolingSupported" : true,
    "poolConfigOption" : {
        "maxObjects" : 10,
        "maxIdle" : 10,
        "maxWait" : 150000,
        "minEvictableIdleTimeMillis" : 120000,
        "minIdle" : 1
    },
    "operationTimeout" : {
        "CREATE" : -1,
        "TEST" : -1,
        "AUTHENTICATE" : -1,
        "SEARCH" : -1,
        "VALIDATE" : -1,
        "GET" : -1,
        "UPDATE" : -1,
        "DELETE" : -1,
        "SCRIPT_ON_CONNECTOR" : -1,
        "SCRIPT_ON_RESOURCE" : -1,
        "SYNC" : -1,
        "SCHEMA" : -1
    },
    "configurationProperties" : {
        "xsdIcfFilePath" : "samples/sample1/data/resource-schema-1.xsd",
        "xsdFilePath" : "samples/sample1/data/resource-schema-extension.xsd",
        "xmlFilePath" : "samples/sample1/data/xmlConnectorData.xml"
    },
    "syncFailureHandler" : {
        "maxRetries" : 5,
        "postRetryAction" : "logged-ignore"
    },
    "objectTypes" : {
        "account" : {
            "$schema" : "http://json-schema.org/draft-03/schema",
            "id" : "__ACCOUNT__",
            "type" : "object",
            "nativeType" : "__ACCOUNT__",
            "properties" : {
                "description" : {
                    "type" : "string",
                    "nativeName" : "__DESCRIPTION__",
                    "nativeType" : "string"
                },
                "firstname" : {
                    "type" : "string",
                    "nativeName" : "firstname",
                    "nativeType" : "string"
                },
                "email" : {
                    "type" : "string",
                    "nativeName" : "email",
                    "nativeType" : "string"
                },
                "_id" : {
                    "type" : "string",
                    "nativeName" : "__UID__"
                },
                "password" : {
                    "type" : "string",
                    "nativeName" : "password",
                    "nativeType" : "string"
                },
                "name" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "__NAME__",
                    "nativeType" : "string"
                },
                "lastname" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "lastname",
                    "nativeType" : "string"
                },
                "mobileTelephoneNumber" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "mobileTelephoneNumber",
                    "nativeType" : "string"
                },
                "securityQuestion" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "securityQuestion",
                    "nativeType" : "string"
                },
                "securityAnswer" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "securityAnswer",
                    "nativeType" : "string"
                },
                "roles" : {
                    "type" : "string",
                    "required" : false,
                    "nativeName" : "roles",
                    "nativeType" : "string"
                }
            }
        }
    },
    "operationOptions" : { }
}' \
 --request POST \
 "https://localhost:8443/openidm/system?_action=testConfig"
  

If the configuration is valid, the command returns "ok": true, for example:

{
   "ok": true,
   "name": "xmlfile"
}

If the configuration is not valid, the command returns an error, indicating the problem with the configuration. For example, the following result is returned when the LDAP connector configuration is missing a required property (in this case, the baseContexts to synchronize):

{
  "error": "org.identityconnectors.framework.common.exceptions.ConfigurationException:
           The list of base contexts cannot be empty",
  "name": "OpenDJ",
  "ok": false
} 

The testConfig action requires a running OpenIDM instance, as it uses the REST API, but does not require an active connector instance for the connector whose configuration you want to test.

You can add the attributes of your choice to a connector configuration file. Specifically, if you want to set up Property Level Extensions to one of the objectTypes such as account, use the format shown under Object Types.

You can configure connectors to enable provisioning of arbitrary property level extensions (such as image files) to system resources. For example, if you want to set up image files such as account avatars, open the appropriate provisioner file. Look for an account section similar to:

"account" : {
    "$schema" : "http://json-schema.org/draft-03/schema",
    "id" : "__ACCOUNT__",
    "type" : "object",
    "nativeType" : "__ACCOUNT__",
    "properties" : {
   

Under "properties", add one of the following code blocks. The first block works for a single photo encoded as a base64 string. The second block would address multiple photos encoded in the same way.

"attributeByteArray" : {
    "type" : "string",
    "nativeName" : "attributeByteArray",
    "nativeType" : "JAVA_TYPE_BYTE_ARRAY"
},
   

"attributeByteArrayMultivalue": {
    "type": "array",
    "items": {
        "type": "string",
        "nativeType": "JAVA_TYPE_BYTE_ARRAY"
    },
    "nativeName": "attributeByteArrayMultivalue"
},
   

Synchronization happens either when OpenIDM receives a change directly, or when OpenIDM discovers a change on an external resource.

For direct changes to OpenIDM, OpenIDM immediately pushes updates to all external resources configured to receive the updates. A direct change can originate not only as a write request through the REST interface, but also as an update resulting from reconciliation with another resource.

To determine what to synchronize, and how to carry out synchronization, OpenIDM relies on mappings configured in the /path/to/conf/sync.json file. LiveSync and implicit sync rely on the mappings configured once per OpenIDM server.

For reconciliation or LiveSync, you can schedule changes as described in Chapter 13, "Scheduling Tasks and Events".

Identity management software tends to favor either a meta-directory data model, where all data are mirrored in a central repository, or a virtual data model, where only a minimum set of attributes are stored centrally, and most are loaded on demand from the external resources in which they are stored. The meta-directory model offers fast access at the risk of getting outdated data. The virtual model guarantees fresh data, but pays for that guarantee in terms of performance.

OpenIDM leaves the data model choice up to you. You determine the right trade offs for a particular deployment. OpenIDM does not hard code any particular schema or set of attributes stored in the repository. Instead, you define how external system objects map onto managed objects, and OpenIDM dynamically updates the repository to store the managed object attributes that you configure.

You can, for example, choose to follow the data model defined in the Simple Cloud Identity Management (SCIM) specification. The following object represents a SCIM user.

{
    "userName": "james1",
    "familyName": "Berg",
    "givenName": "James",
    "email": [
        "james1@example.com"
    ],
    "description": "Created by OpenIDM REST.",
    "password": "asdfkj23",
    "displayName": "James Berg",
    "phoneNumber": "12345",
    "employeeNumber": "12345",
    "userType": "Contractor",
    "title": "Vice President",
    "active": true
}

Data flow for synchronization involves the following elements:

{
    "name": "MyLDAP",
    "objectTypes": {
        "account": {
            "lastName": {
                "type": "string",
                "required": true,
                "nativeName": "sn",
                "nativeType": "string"
            },
            "homePhone": {
                "type": "array",
                "items": {
                    "type": "string",
                    "nativeType": "string"
                },
                "nativeName": "homePhone",
                "nativeType": "string"
            }
        }
    }
}

12.3.2. Synchronization Mappings File

The synchronization mappings file (openidm/conf/sync.json) represents the core configuration for OpenIDM synchronization.

The sync.json file describes a set of mappings. Each mapping specifies how attributes from source objects correspond to attributes on target objects. The source and target indicate the direction for the data flow, so you must define a separate mapping for each data flow. For example, if you want data flows from an LDAP server to the repository and also from the repository to the LDAP server, you must define two separate mappings.

You identify external resource sources and targets as system/name/object-type, where name is the name used in the connector configuration file, and object-type is the object defined in the connector configuration file list of object types. For objects in OpenIDM's internal repository, you use managed/object-type, where object-type is defined in openidm/conf/managed.json. The name for the mapping by convention is set to a string of the form source_target, as shown in the following example.

{
    "mappings": [
        {
            "name": "systemLdapAccounts_managedUser",
            "source": "system/MyLDAP/account",
            "target": "managed/user",
            "properties": [
                {
                    "target": "sn",
                    "source": "lastName"
                },
                {
                    "target": "telephoneNumber",
                    "source": "homePhone"
                },
                {
                    "target": "phoneExtension",
                    "default": "0047"
                },
                {
                    "target": "mail",
                    "comment": "Set mail if non-empty.",
                    "source": "email",
                    "condition": {
                        "type": "text/javascript",
                        "source": "(object.email != null)"
                    }
                },
                {
                    "target": "displayName",
                    "source": "",
                    "transform": {
                        "type": "text/javascript",
                        "source": "source.lastName +', ' + source.firstName;"
                    }
                }
            ]
        }
    ]
}

In this example, the source is the external resource, MyLDAP, and the target is OpenIDM's repository, specifically the managed user objects. The properties reflect OpenIDM attribute names. For example, the mapping has the attribute lastName defined in the MyLDAP connector configuration file mapped to sn in the OpenIDM managed user object. Notice that the attribute names come from the connector configuration, rather than the external resource itself.

You can create attributes on the target as part of the mapping. In the preceding example, a phoneExtension attribute with a default value of 0047 is created on the target.

You can also use the "default" property to specify a value that should be assigned to the target property. When determining the value of the target property, any associated conditions are evaluated first, followed by the transform script, if present. The default value is applied (for update and create actions) if the "source" property and the "transform" script yield a null value. The default value overrides the target value, if one exists.

You can also set up conditions under which OpenIDM maps attributes as shown for the email attribute in the example. By default, OpenIDM synchronizes all attributes. In the example, the mail attribute is set only if the script for the condition returns true.

OpenIDM also enables you to transform attributes. In the example, the value of the displayName attribute is set using a combination of the lastName and firstName attribute values from the source. For transformations, the source property is optional. However, the source object is only available when you specify the source property. Therefore, in order to use source.lastName and source.firstName to calculate the displayName, the example specifies "source" : "".

To add a flow from the repository to MyLDAP, you would define a mapping with source managed/user and target system/MyLDAP/account, named for example managedUser_systemLdapAccounts.

The following image shows the paths to objects in the OpenIDM namespace.

OpenIDM stores managed objects in the repository, and exposes them under /openidm/managed. System objects on external resources are exposed under /openidm/system.

By default, OpenIDM synchronizes all objects that match those defined in the connector configuration for the resource. Many connectors allow you to limit the scope of objects that the connector accesses. For example, the LDAP connector allows you to specify base DNs and LDAP filters so that you do not need to access every entry in the directory. OpenIDM also allows you to filter what is considered a valid source or valid target for synchronization by using scripts. To apply these filters, use the validSource, and validTarget properties in your mapping.

validSource

A script that determines if a source object is valid to be mapped. The script yields a boolean value: true indicates that the source object is valid; false can be used to defer mapping until some condition is met. In the root scope, the source object is provided in the "source" property. If the script is not specified, then all source objects are considered valid.

{
    "validSource": {
        "type": "text/javascript",
        "source": "source.ldapPassword != null"
    }
}

validTarget

A script, used during reconciliation's second phase, that determines if a target object is valid to be mapped. The script yields a boolean value: true indicates that the target object is valid; false indicates that the target object should not be included in reconciliation. In the root scope, the source object is provided in the "target" property. If the script is not specified, then all target objects are considered valid for mapping.

{
    "validTarget": {
        "type": "text/javascript",
        "source": "target.employeeType == 'internal'"
    }
}

During synchronization, your scripts always have access to a source object and a target object. Examples already shown in this section use source.attributeName to retrieve attributes from the source objects. Your scripts can also write to target attributes using target.attributeName syntax.

{
    "onUpdate": {
        "type": "text/javascript",
        "source": "if (source.email != null) {target.mail = source.email;}"
    }
}

For more information about scripting, see Appendix F, "Scripting Reference".

If a source resource is empty, the default behavior is for a reconciliation operation to exit, without failure, and to log a warning, similar to the following:

2014-03-20 10:41:18:918 WARN Cannot perform reconciliation with an empty source
    object set, unless explicitly configured to allow it.
   

The reconciliation summary is also logged in the reconciliation audit log.

This behavior prevents reconciliation operations from accidentally deleting everything in a target resource. For example, in the event that a source system is unavailable but erroneously reporting its status as "up", the absence of source objects should not result in objects being removed on the target resource.

There might be situations in which you do want reconciliations of an empty source resource to proceed. In this case, you can override the default behavior by setting the "allowEmptySourceSet" property to true in the mapping. For example:

{
    "mappings" : [
        {
        "name" : "systemXmlfileAccounts_managedUser",
        "source" : "system/xmlfile/account",
        "allowEmptySourceSet" : true,
        ...
   

Reconciliation of an empty source effectively wipes out the target.

You can update mappings in the synchronization configuration file (sync.json) while the server is running, provided you do not update a mapping that is currently in use by a reconciliation process.

{
    "objects": [
        {
            "name": "user",
            ...
            "properties": [
                {
                    "name": "securityAnswer",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                },
                {
                    "name": "ssn",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                },
                {
                    "name": "password",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                }
            ],
            ...
          }
    ]
}

       "properties" : [
           {
               "name" : "securityAnswer",
               "encryption" : {
                   "key" : "openidm-sym-default"
               },
               "scope" : "private"
           },
           {
               "name" : "password",
               "encryption" : {
                   "key" : "openidm-sym-default"
               },
               "scope" : "private"
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '[
    {
    "operation":"replace",
    "field":"/givenName",
    "value":"Jon"
    }
 ]' \
 "https://localhost:8443/openidm/managed/user?_action=patch&_queryId=for-userName&uid=jdoe"
   

{
    "onCreate": {
        "type": "text/javascript",
        "source":
            "target.dn = 'uid=' + source.uid + ',ou=people,dc=example,dc=com'"
    }
}

{
    "mappings": [
        {
            "name": "systemMyLDAPAccounts_managedUser",
            "source": "system/MyLDAP/account",
            "target": "managed/user"
        },
        {
            "name": "managedUser_systemMyLDAPAccounts",
            "source": "managed/user",
            "target": "system/MyLDAP/account",
            "links": "systemMyLDAPAccounts_managedUser"
        }
    ]
}

You can trigger, cancel, and monitor reconciliation operations over REST, using the REST endpoint https://localhost:8443/openidm/recon.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser"

{"_id":"0890ad62-4738-4a3f-8b8e-f3c83bbf212e","state":"ACTIVE"}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser&waitForCompletion=true"
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/recon/0890ad62-4738-4a3f-8b8e-f3c83bbf212e"
     {
  "ended": "2014-03-06T07:00:32.094Z",
  "_id": "7a07c100-4f11-4d7e-bf8e-fa4594f99d58",
  "mapping": "systemLdapAccounts_managedUser",
  "state": "SUCCESS",
  "stage": "COMPLETED_SUCCESS",
  "stageDescription": "reconciliation completed.",
  "progress": {
     "links": {
       "created": 0,
       "existing": {
         "total": "1",
         "processed": 1
       }
     },
     "target": {
       "created": 0,
       "existing": {
         "total": "3",
         "processed": 3
       }
     },
     "source": {
       "existing": {
         "total": "1",
         "processed": 1
       }
     }
  },
  "situationSummary": {
     "UNASSIGNED": 2,
     "TARGET_IGNORED": 0,
     "SOURCE_IGNORED": 0,
     "MISSING": 0,
     "FOUND": 0,
     "AMBIGUOUS": 0,
     "UNQUALIFIED": 0,
     "CONFIRMED": 1,
     "SOURCE_MISSING": 0,
     "ABSENT": 0
  },
  "started": "2014-03-06T07:00:31.907Z"
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon/0890ad62-4738-4a3f-8b8e-f3c83bbf212e?_action=cancel"

{
     "status":"SUCCESS",
     "action":"cancel",
     "_id":"0890ad62-4738-4a3f-8b8e-f3c83bbf212e"
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/recon"
    

{
   "reconciliations": [
     {
       "ended": "2014-03-06T06:14:11.845Z",
       "_id": "4286510e-986a-4521-bfa4-8cd1e039a7f5",
       "mapping": "systemLdapAccounts_managedUser",
       "state": "SUCCESS",
       "stage": "COMPLETED_SUCCESS",
       "stageDescription": "reconciliation completed.",
       "progress": {
         "links": {
           "created": 1,
           "existing": {
           "total": "0",
           "processed": 0
         }
       },
       "target": {
         "created": 1,
         "existing": {
           "total": "2",
           "processed": 2
         }
       },
       "source": {
         "existing": {
           "total": "1",
           "processed": 1
         }
       }
     },
     "situationSummary": {
       "UNASSIGNED": 2,
       "TARGET_IGNORED": 0,
       "SOURCE_IGNORED": 0,
       "MISSING": 0,
       "FOUND": 0,
       "AMBIGUOUS": 0,
       "UNQUALIFIED": 0,
       "CONFIRMED": 0,
       "SOURCE_MISSING": 0,
       "ABSENT": 1
     },
     "started": "2014-03-06T06:14:04.722Z"
   },
 ]
}

{
    "_rev": "4",
    "_id": "SYSTEMLDAPACCOUNT",
    "connectorData": {
        "nativeType": "integer",
        "syncToken": 1
    }
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system/ldap/account?_action=liveSync&detailedFailure=true"

Every reconciliation operation performs a query on the source, and on the target resource, to determine which records should be reconciled. The default source and target queries are query-all-ids, which means that all records in both the source and the target are considered candidates for that reconciliation operation.

You can restrict reconciliation to specific entries by defining explicit source or target queries in the mapping configuration.

For example, to restrict reconciliation to only those records whose employeeType on the source resource is Permanent, you might specify a source query as follows:

"mappings" : [
     {
         "name" : "managedUser_systemLdapAccounts",
         "source" : "managed/user",
         "target" : "system/ldap/account",
         "sourceQuery" : : {
                "queryFilter" : "employeeType eq \"Permanent\""
            },
...

The format of the query can be any query type that is supported by the resource, and can include additional parameters, if applicable. OpenIDM 3.1 supports the following query types.

The source and target queries send the query to the resource that is defined for that source or target, by default. You can override the resource to which the query is sent by specifying a resourceName in the query. For example, to query a specific endpoint instead of the source resource, you might modify the preceding source query as follows:

"mappings" : [
    {
        "name" : "managedUser_systemLdapAccounts",
        "source" : "managed/user",
        "target" : "system/ldap/account",
        "sourceQuery" : {
            "resourceName" : "endpoint/scriptedQuery"
            "queryFilter" : "employeeType eq \"Permanent\""
        },
...

To override a source or target query that is defined in the mapping, you can specify the query when you call the reconciliation operation. For example, if you wanted to reconcile all employee entries, and not just the permanent employees, you would run the reconciliation operation as follows:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{"sourceQuery": {"_queryId" : "query-all-ids"}}' \
 "https://localhost:8443/openidm/recon?_action=recon&mapping=managedUser_systemLdapAccounts"

By default, a reconciliation operation runs both the source and target phase. To avoid queries on the target resource, set runTargetPhase to false in the mapping configuration (conf/sync.json file). For example, to prevent the target resource from being queried during the reconciliation operation configured in the previous example, amend the mapping configuration as follows:

{
    "mappings" : [
        {
            "name" : "systemLdapAccounts_managedUser",
            "source" : "system/ldap/account",
            "target" : "managed/user",
            "sourceQuery" : {
                "queryFilter" : "employeeType eq \"Permanent\""
            },
            "runTargetPhase" : false,
   ...  

"mappings" : [
    {
        "name" : "systemLdapAccounts_managedUser",
        "source" : "system/ldap/account",
        "target" : "managed/user",
        "sourceQuery" : {
            "_queryFilter" : "uid sw \"\""
        },
    ...

"mappings" : [
    {
        "name" : "systemLdapAccounts_managedUser",
        "source" : "system/ldap/account",
        "target" : "managed/user",
        "sourceQueryFullEntry" : true,
        "sourceQuery" : {
            "_queryFilter" : "uid sw \"\""
        },
    ...

In the same way that you can restrict reconciliation operations to specific records by using queries, you can specify an ID to restrict a reconciliation operation to a particular record.

To restrict reconciliation to a specific ID, use the reconById action, instead of the recon action when you call the reconciliation operation. Specify the ID with the ids parameter. Currently reconciling more than one ID with the reconById action is not supported.

The following example is based on the data from Sample 2b, which maps an LDAP server with the OpenIDM repository. The example reconciles only the user bjensen, using the managedUser_systemLdapAccounts mapping to update the user account in LDAP with the data from the OpenIDM repository. The _id for bjensen in this example is b3c2f414-e7b3-46aa-8ce6-f4ab1e89288c. The example assumes that implicit synchronization has been disabled and that a reconciliation operation is required to copy changes made in the repository to the LDAP system.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon?_action=reconById&mapping=managedUser_systemLdapAccounts&ids=b3c2f414-e7b3-46aa-8ce6-f4ab1e89288c"

A reconciliation by ID takes the default reconciliation options that are specified in the mapping, so the source and target queries, and source and target phases described in the previous section apply equally to reconciliation by ID.

Reconciliation operations are logged in the file /path/to/openidm/audit/recon.csv and in the repository. You can read and query the reconciliation audit logs over the REST interface, as outlined in the following examples.

By default all audit/recon query responses are formatted based on the entryType of the entry. Fields that are not required for the specific entry type are stripped away from the response. For example, a summary entry would not need to include a null targetObjectId field, as this would not add information to a summary. You can specify that this auto-formatting be disabled and return the full entry for all entry types. To disable entry formatting, include formatted=false as a query parameter in the request.

To return all reconciliation operations logged in the audit log, run a RESTful GET on the audit/recon endpoint. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon"

The following code sample shows an extract of the audit log after the first reconciliation operation in Sample 1.

{
  "entries": [
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "targetObjectId": "managed/user/scarter",
      "sourceObjectId": "system/xmlfile/account/scarter",
      "situation": "ABSENT",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "action": "CREATE",
      "actionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "exception": "",
      "_id": "fe250514-d3e1-477a-bb90-88bd4525d70b",
      "entryType": "entry",
      "timestamp": "2014-09-08T08:57:47.575Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null
    },
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "exception": "",
      "_id": "10e4195b-7b38-4b99-9916-a6d2de137c11",
      "entryType": "start",
      "timestamp": "2014-09-08T08:57:47.218Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": "Reconciliation initiated by openidm-admin",
      "messageDetail": null
    },
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "exception": "",
      "_id": "d8634325-78f6-4504-b9f4-ba7b9103e391",
      "entryType": "summary",
      "timestamp": "2014-09-08T08:57:47.607Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": "SOURCE_IGNORED: 0 MISSING: 0 FOUND: 0 AMBIGUOUS: 0 UNQUALIFIED: 0 CONFIRMED: 0 SOURCE_MISSING: 0 ABSENT: 2 TARGET_IGNORED: 0 UNASSIGNED: 0 ",
      "messageDetail": {
        "stage": "COMPLETED_SUCCESS",
        "stageDescription": "reconciliation completed.",
        "progress": {
          "links": {
            "created": 2,
            "existing": {
              "processed": 0,
              "total": "0"
            }
          },
          "source": {
            "existing": {
              "processed": 2,
              "total": "2"
            }
          },
          "target": {
            "created": 2,
            "existing": {
              "processed": 0,
              "total": "0"
            }
          }
        },
        "duration": 388,
        "situationSummary": {
          "SOURCE_MISSING": 0,
          "FOUND": 0,
          "SOURCE_IGNORED": 0,
          "UNQUALIFIED": 0,
          "UNASSIGNED": 0,
          "TARGET_IGNORED": 0,
          "CONFIRMED": 0,
          "AMBIGUOUS": 0,
          "ABSENT": 2,
          "MISSING": 0
        },
        "statusSummary": {
          "FAILURE": 0,
          "SUCCESS": 2
        },
        "state": "SUCCESS",
        "mapping": "systemXmlfileAccounts_managedUser",
        "started": "2014-09-08T08:57:47.218Z",
        "ended": "2014-09-08T08:57:47.606Z"
      }
    },
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "targetObjectId": "managed/user/bjensen",
      "sourceObjectId": "system/xmlfile/account/bjensen",
      "situation": "ABSENT",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "action": "CREATE",
      "actionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "exception": "",
      "_id": "939fd113-1158-4f5c-a7f7-6c4b005dce2f",
      "entryType": "entry",
      "timestamp": "2014-09-08T08:57:47.579Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null
    }
  ]
} 

Most of the fields in this audit log are self-explanatory. Each distinct reconciliation operation is identified by its reconId. Each entry in the log is identified by a unique _id. The first log entry indicates the status for the complete reconciliation operation. Successive entries indicate the status for each record affected by the reconciliation.

To obtain information on a specific audit log entry, include its entry _id in the URL. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon/fe250514-d3e1-477a-bb90-88bd4525d70b"

The following sample output shows the results of a read operation on a specific reconciliation audit entry.

{
  "mapping": "systemXmlfileAccounts_managedUser",
  "targetObjectId": "managed/user/scarter",
  "sourceObjectId": "system/xmlfile/account/scarter",
  "situation": "ABSENT",
  "reconciling": "source",
  "ambiguousTargetObjectIds": "",
  "action": "CREATE",
  "actionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
  "exception": "",
  "_id": "fe250514-d3e1-477a-bb90-88bd4525d70b",
  "entryType": "entry",
  "timestamp": "2014-09-08T08:57:47.575Z",
  "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
  "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
  "status": "SUCCESS",
  "message": null,
  "messageDetail": null
} 

To query the audit log for a particular reconciliation operation, use the audit-by-recon-id keyword, specifying the reconciliation ID, as follows:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon?_queryId=audit-by-recon-id&reconId=<reconID>"

Output similar to the following is returned, for the specified reconciliation operation:

{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 4,
  "result": [
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "exception": "",
      "_id": "d8634325-78f6-4504-b9f4-ba7b9103e391",
      "entryType": "summary",
      "timestamp": "2014-09-08T08:57:47.607Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": "SOURCE_IGNORED: 0 MISSING: 0 FOUND: 0 AMBIGUOUS: 0 UNQUALIFIED: 0
           CONFIRMED: 0 SOURCE_MISSING: 0 ABSENT: 2 TARGET_IGNORED: 0 UNASSIGNED: 0 ",
      "messageDetail": {
        "stage": "COMPLETED_SUCCESS",
        "stageDescription": "reconciliation completed.",
        "progress": {
          "links": {
            "created": 2,
            "existing": {
              "processed": 0,
              "total": "0"
            }
          },
          "source": {
            "existing": {
              "processed": 2,
              "total": "2"
            }
          },
          "target": {
            "created": 2,
            "existing": {
              "processed": 0,
              "total": "0"
            }
          }
        },
        "duration": 388,
        "situationSummary": {
          "SOURCE_MISSING": 0,
          "FOUND": 0,
          "SOURCE_IGNORED": 0,
          "UNQUALIFIED": 0,
          "UNASSIGNED": 0,
          "TARGET_IGNORED": 0,
          "CONFIRMED": 0,
          "AMBIGUOUS": 0,
          "ABSENT": 2,
          "MISSING": 0
        },
        "statusSummary": {
          "FAILURE": 0,
          "SUCCESS": 2
        },
        "state": "SUCCESS",
        "mapping": "systemXmlfileAccounts_managedUser",
        "started": "2014-09-08T08:57:47.218Z",
        "ended": "2014-09-08T08:57:47.606Z"
      }
    },
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "exception": "",
      "_id": "10e4195b-7b38-4b99-9916-a6d2de137c11",
      "entryType": "start",
      "timestamp": "2014-09-08T08:57:47.218Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": "Reconciliation initiated by openidm-admin",
      "messageDetail": null
    },
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "targetObjectId": "managed/user/scarter",
      "sourceObjectId": "system/xmlfile/account/scarter",
      "situation": "ABSENT",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "action": "CREATE",
      "actionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "exception": "",
      "_id": "fe250514-d3e1-477a-bb90-88bd4525d70b",
      "entryType": "entry",
      "timestamp": "2014-09-08T08:57:47.575Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null
    },
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "targetObjectId": "managed/user/bjensen",
      "sourceObjectId": "system/xmlfile/account/bjensen",
      "situation": "ABSENT",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "action": "CREATE",
      "actionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "exception": "",
      "_id": "939fd113-1158-4f5c-a7f7-6c4b005dce2f",
      "entryType": "entry",
      "timestamp": "2014-09-08T08:57:47.579Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null
    }
  ]
}

To query the audit log for a specific reconciliation situation, use the audit-by-recon-id-situation keyword, specifying the reconciliation ID and the situation that you want to query. For example, the following query returns all ABSENT records found during the specified reconciliation operation:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon?_queryId=audit-by-recon-id-situation&situation=ABSENT&reconId=e5f3190d-41d9-4bea-907d-b287a9436a45"
  

Output similar to the following is returned, with one entry for each record that matches the situation queried:

{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 2,
  "result": [
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "targetObjectId": "managed/user/scarter",
      "sourceObjectId": "system/xmlfile/account/scarter",
      "situation": "ABSENT",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "action": "CREATE",
      "actionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "exception": "",
      "_id": "fe250514-d3e1-477a-bb90-88bd4525d70b",
      "entryType": "entry",
      "timestamp": "2014-09-08T08:57:47.575Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null
    },
    {
      "mapping": "systemXmlfileAccounts_managedUser",
      "targetObjectId": "managed/user/bjensen",
      "sourceObjectId": "system/xmlfile/account/bjensen",
      "situation": "ABSENT",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "action": "CREATE",
      "actionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "exception": "",
      "_id": "939fd113-1158-4f5c-a7f7-6c4b005dce2f",
      "entryType": "entry",
      "timestamp": "2014-09-08T08:57:47.579Z",
      "reconId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "rootActionId": "e5f3190d-41d9-4bea-907d-b287a9436a45",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null
    }
  ]
}

The activity logs track all operations on internal (managed) and external (system) objects. Entries in the activity log contain identifiers for the reconciliation or synchronization action that triggered the activity, and for the original caller and the relationships between related actions.

You can access the activity logs over REST with the following call:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/activity"

The following extract of the activity log shows the last entry in the log, which was a password change for user bjensen.

{
   "entries": [
   ...
   },
     "before": null,
     "requester": "openidm-admin",
     "parentActionId": "c2c102bc-7b32-4020-b5aa-9a7d63652cb6",
     "_id": "bbaff1e0-923b-48f0-b053-b1614cbb3647",
     "activityId": "c2c102bc-7b32-4020-b5aa-9a7d63652cb6",
     "timestamp": "2014-03-13T16:20:54.811Z",
     "action": "CREATE",
     "message": "create",
     "objectId": "managed/user/4f2f5eea-918a-4ef1-9244-be41dcf128a4",
     "rev": "1",
     "rootActionId": "c2c102bc-7b32-4020-b5aa-9a7d63652cb6"
   },
   {
     "passwordChanged": true,
     "changedFields": [
     "/password"
   ],
     "status": "SUCCESS",
     "after": {
       "securityAnswer": {
         "$crypto": {
           "value": {
             "key": "openidm-sym-default",
             "iv": "8CvlA6rWN03MAhLSKJmbvw==",
             "cipher": "AES/CBC/PKCS5Padding",
             "data": "oJBTrrX+wFAygFZkLuGPrhB/jAIICcdIBuCX1eEbpS0="
           },
           "type": "x-simple-encryption"
         }
       },
   ...

To return activity information for a specific action, include the _id of the action in the endpoint, for example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/activity/22ef6d20-bd84-4267-9db8-745825a46ad1"

Results similar to the following are returned:

{
  "passwordChanged": true,
  "changedFields": [
    "/password"
  ],
  "status": "SUCCESS",
  "after": {
    "securityAnswer": {
      "$crypto": {
      "value": {
        "key": "openidm-sym-default",
        "iv": "HpsyTtTXc2pfNrXlYbro7Q==",
        "cipher": "AES/CBC/PKCS5Padding",
        "data": "0M6O7geNjalJ7e0EGSG9B90eaeF8zJuogdL74hcAIRg="
      },
      "type": "x-simple-encryption"
    }
  },
  "userName": "bjensen@example.com",
  "stateProvince": "",
  "postalAddress": "",
  "effectiveAssignments": {},
  "roles": "openidm-authorized",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "password": {
    "$crypto": {
      "value": {
        "key": "openidm-sym-default",
        "iv": "dkRjURz761HaObBuLl+EkA==",
        "cipher": "AES/CBC/PKCS5Padding",
        "data": "9chNPUlXotHy195ERj6vlg=="
      },
      "type": "x-simple-encryption"
    }
  },
  "effectiveRoles": [
    "openidm-authorized"
  ],
  "givenName": "Barbara",
  "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
  "address2": "",
  "passwordAttempts": "0",
  "sn": "Jensen",
  "mail": "bjensen@example.com",
  "securityQuestion": "1",
  "city": "",
  "country": "",
  "_rev": "7",
  "lastPasswordSet": "",
  "postalCode": "",
  "_id": "bjensen",
  "description": "Created By XML1"
},
  "before": {
  "securityAnswer": "Some security answer",
  "userName": "bjensen@example.com",
  "stateProvince": "",
  "postalAddress": "",
  "roles": "openidm-authorized",
  "telephoneNumber": "1234567",
  "password": {
    "$crypto": {
      "value": {
        "key": "openidm-sym-default",
        "iv": "bqhRyLW1lI+KZROcpgyukg==",
        "cipher": "AES/CBC/PKCS5Padding",
        "data": "qO8A76GqNqftVVwOlasyPw=="
      },
      "type": "x-simple-encryption",
    "securityQuestion": "1",
  "givenName": "Barbara",
  "address2": "",
  "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
  "passwordAttempts": "0",
  "sn": "Jensen",
  "mail": "bjensen@example.com",
  "country": "",
  "city": "",
  "_rev": "7",
  "lastPasswordSet": "",
  "postalCode": "",
  "_id": "bjensen",
  "description": "Created By XML1",
  "accountStatus": "active"
},
"requester": "openidm-admin",
"parentActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
"_id": "ee88adb8-3329-4f81-a8f2-d9c8e0fbf72b",
"activityId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
"timestamp": "2014-03-13T16:21:27.086Z",
"action": "UPDATE",
"message": "update",
"objectId": "managed/user/bjensen",
"rev": "7",
"rootActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5"
} 

Each action in the activity log has a rootActionId and a parentActionId. The rootActionId is the ID that was assigned to the incoming or initiating request. The parentActionId is the ID that is associated with the overall action. So, for example, if an HTTP request invokes a script that changes a user's password, the HTTP request is assigned the rootActionId and the action taken by the script is assigned the parentActionId. You can query the activity log for the details of a specific action by including the parentActionId in the query. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/activity?_queryId=audit-by-activity-parent-action&parentActionId=0aaba292-1dd3-4e98-a0e2-04bec9ae5209"

The following sample output shows the result of a query that requests details of the password change for bjensen.

{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 2,
  "result": [
    {
      "rootActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
      "changedFields": [
        "/password"
    ],
      "action": "UPDATE",
      "objectId": "managed/user/bjensen",
      "before": {
        "securityAnswer": "Some security answer",
        "userName": "bjensen@example.com",
        "stateProvince": "",
        "postalAddress": "",
        "roles": "openidm-authorized",
        "telephoneNumber": "1234567",
        "password": "CAngetin1",
        "securityQuestion": "1",
        "givenName": "Barbara",
        "address2": "",
        "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
        "passwordAttempts": "0",
        "sn": "Jensen",
        "mail": "bjensen@example.com",
        "country": "",
        "city": "",
        "_rev": "7",
        "lastPasswordSet": "",
        "postalCode": "",
        "_id": "bjensen",
        "description": "Created By XML1",
        "accountStatus": "active"
      },
      "status": "SUCCESS",
      "_rev": "1",
      "_id": "ee88adb8-3329-4f81-a8f2-d9c8e0fbf72b",
      "parentActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
      "timestamp": "2014-03-13T16:21:27.086Z",
      "message": "update",
      "activityId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
      "after": {
        "securityAnswer": {
          "$crypto": {
            "value": {
              "key": "openidm-sym-default",
              "iv": "HpsyTtTXc2pfNrXlYbro7Q==",
              "cipher": "AES/CBC/PKCS5Padding",
              "data": "0M6O7geNjalJ7e0EGSG9B90eaeF8zJuogdL74hcAIRg="
            },
            "type": "x-simple-encryption"
          }
        },
        "userName": "bjensen@example.com",
        "stateProvince": "",
        "postalAddress": "",
        "effectiveAssignments": {},
        "roles": "openidm-authorized",
        "telephoneNumber": "1234567",
        "accountStatus": "active",
        "password": {
          "$crypto": {
            "value": {
              "key": "openidm-sym-default",
              "iv": "dkRjURz761HaObBuLl+EkA==",
              "cipher": "AES/CBC/PKCS5Padding",
              "data": "9chNPUlXotHy195ERj6vlg=="
          },
        "type": "x-simple-encryption"
      }
    },
    "effectiveRoles": [
       "openidm-authorized"
    ],
    "givenName": "Barbara",
    "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
    "address2": "",
    "passwordAttempts": "0",
    "sn": "Jensen",
    "mail": "bjensen@example.com",
    "securityQuestion": "1",
    "city": "",
    "country": "",
    "_rev": "7",
    "lastPasswordSet": "",
    "postalCode": "",
    "_id": "bjensen",
    "description": "Created By XML1"
  },
  "rev": "7",
  "requester": "openidm-admin",
  "passwordChanged": true
  }
 ]
} 

For more information about the entries in these logs, see Chapter 18, "Using Audit Logs".

LiveSync and implicit sync operations are logged in the file /path/to/openidm/audit/sync.csv and in the repository. You can read the synchronization audit logs over the REST interface, as outlined in the following examples.

To return all synchronization operations logged in the audit log, run a RESTful GET on the audit/sync endpoint. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/sync"

Most of the fields in the synchronization audit log are self-explanatory. Each distinct synchronization operation is identified by its actionId. The rootActionId is the ID that was assigned to the incoming or initiating request - so if a modification to a user entry triggers an implicit synchronization operation, the sync operation is assigned an actionId and rootActionId refers to the original change operation. Each entry in the log is identified by a unique _id.

To obtain information on a specific audit log entry, include its entry _id in the URL. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/sync/a311b656-508c-4f56-9df4-f907364184f1"

The following sample output shows the results of a read operation on a specific synchronization audit entry.

{
  "entries": [
    {
      "mapping": "systemAdAccounts_managedUser",
      "targetObjectId": "7e5eb90b-f643-4858-803e-a01931f9c12e",
      "sourceObjectId": "system/ad/account/rheath",
      "situation": "CONFIRMED",
      "actionId": "ea6a81e0-a98a-4e72-8c77-50b5756be1f6",
      "_id": "b3e3190c-9e9d-4cd1-8fec-01705ad54109",
      "timestamp": "2014-10-30T14:48:58.415Z",
      "rootActionId": "ea6a81e0-a98a-4e72-8c77-50b5756be1f6",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null,
      "exception": "",
      "action": "UPDATE"
    },
    {
      "mapping": "managedUser_systemLdapAccounts",
      "targetObjectId": "uid=rheath,ou=People,dc=example,dc=com",
      "sourceObjectId": "managed/user/7e5eb90b-f643-4858-803e-a01931f9c12e",
      "situation": "CONFIRMED",
      "actionId": "ea6a81e0-a98a-4e72-8c77-50b5756be1f6",
      "_id": "105a39f7-f071-481a-ae82-e233e556cc5a",
      "timestamp": "2014-10-30T14:48:58.402Z",
      "rootActionId": "ea6a81e0-a98a-4e72-8c77-50b5756be1f6",
      "status": "SUCCESS",
      "message": null,
      "messageDetail": null,
      "exception": "",
      "action": "UPDATE"
    }
  ]
} 

The output shows two records that originated from the same LiveSync action. The first record indicates a change on the system/ad entry, which triggered a LiveSync to update the corresponding managed/user entry. The second record indicates an implicit sync from managed/user to the corresponding entry in system/ldap. Note that the rootActionId is the same for both these records.

OpenIDM enables you to specify what should happen if a LiveSync operation reports a failure for an operation. By configuring the LiveSync retry policy, you can specify how many times a failed modification should be reattempted and what should happen in the event that the modification is unsuccessful after the specified number of attempts. If no retry policy is configured, OpenIDM reattempts the change an infinite number of times, until the change is successful. This behavior can increase data consistency in the case of transient failures (for example, when the connection to the database is temporarily lost). However, in situations where the cause of the failure is permanent (for example, if the change does not meet certain policy requirements) the change will never succeed, regardless of the number of attempts. In this case, the infinite retry behavior can effectively block subsequent LiveSync operations from starting.

Generally, a scheduled reconciliation operation will eventually force consistency. However, to prevent repeated retries that block the LiveSync mechanism, you should restrict the number of times OpenIDM reattempts the same modification. You can then specify what OpenIDM does with failed LiveSync changes. The failed modification can be stored in a "dead letter queue", discarded, or reapplied. Alternatively, an administrator can be notified of the failure by email or by some other means. This behavior can be scripted. The default configuration, in the samples provided with OpenIDM, is to retry a failed modification five times, and then to log and ignore the failure.

The LiveSync retry policy is configured in the connector configuration file (provisioner.openicf-*.json). The sample connector configuration files have a retry policy defined as follows:

"syncFailureHandler" : {
  "maxRetries" : 5,
  "postRetryAction" : "logged-ignore"
},
   

The maxRetries field specifies the number of attempts that OpenIDM should make to process the failed modification. The value of this property must be a positive integer, or -1. A value of zero indicates that failed modifications should not be reattempted. In this case, the post retry action is executed immediately when a LiveSync operation fails. A value of -1 (or omitting the maxRetries property, or the entire syncFailureHandler from the configuration) indicates that failed modifications should be retried an infinite number of times. In this case, no post retry action is executed.

The default retry policy relies on the scheduler, or whatever invokes the LiveSync operation. Therefore, if retries are enabled and a LiveSync modification fails, OpenIDM will retry the modification the next time that LiveSync is invoked.

The postRetryAction field indicates what action OpenIDM should take in the event that the maximum number of retries has been reached (or if maxRetries has been set to zero). The post retry action can be one of the following:

The following sample provisioner configuration file extract shows a LiveSync retry policy that specifies a maximum of four retries before the failed modification is sent to the dead letter queue.

...
"connectorName" : "org.identityconnectors.ldap.LdapConnector"
    },
    "syncFailureHandler" : {
        "maxRetries" : 4,
        "postRetryAction" : dead-letter-queue
    },
    "poolConfigOption" : {
...
    

In the case of a failed modification, a message similar to the following is output to the log file:

INFO: sync retries = 1/4, retrying

OpenIDM reattempts the modification, the specified number of times. If the modification is still unsuccessful, a message similar to the following is logged:

INFO: sync retries = 4/4, retries exhausted
Jul 19, 2013 11:59:30 AM
    org.forgerock.openidm.provisioner.openicf.syncfailure.DeadLetterQueueHandler invoke
INFO: uid=jdoe,ou=people,dc=example,dc=com saved to dead letter queue
    

The log message indicates the entry for which the modification failed (uid=jdoe, in this example).

You can view the failed modification in the dead letter queue, over the REST interface, as follows:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/repo/synchronisation/deadLetterQueue/ldap?_queryId=query-all-ids"
     {
       "query-time-ms": 2,
       "result":
       [
           {
               "_id": "4",
               "_rev": "0"
           }
       ],
       "conversion-time-ms": 0
    }

To view the details of a specific failed modification, include its ID in the URL:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/repo/synchronisation/deadLetterQueue/ldap/4"
     {
  "objectType": "account",
  "systemIdentifier": "ldap",
  "failureCause": "org.forgerock.openidm.sync.SynchronizationException:
            org.forgerock.openidm.objset.ConflictException:
            org.forgerock.openidm.sync.SynchronizationException:
            org.forgerock.openidm.script.ScriptException:
            ReferenceError: \"bad\" is not defined.
            (PropertyMapping/mappings/0/properties/3/condition#1)",
  "token": 4,
  "failedRecord": "complete record, in xml format"
  "uid": "uid=jdoe,ou=people,dc=example,dc=com",
  "_rev": "0",
  "_id": "4"
}   

By default, all mappings participate in automatic synchronization operations, that is, a change to a managed object is automatically synchronized to all resources for which the managed object is configured as a source. Similarly, if LiveSync is enabled for a system, changes to an object on that system are automatically propagated to the managed object repository. You can prevent a specific mapping from participating in this automatic synchronization by setting the "enableSync" property of that mapping to false. In the following example, implicit synchronization is disabled. This means that changes to objects in the internal repository are not automatically propagated to the LDAP directory. To propagate changes to the LDAP directory, reconciliation must be launched manually.

{
    "mappings" : [
        {
            "name" : "managedUser_systemLdapAccounts",
            "source" : "managed/user",
            "target" : "system/ldap/account",
            "enableSync" : false,
             ....
}
   

If enableSync is set to false for a system to managed user mapping (for example "systemLdapAccounts_managedUser"), LiveSync is disabled for that mapping.

When implicit synchronization is used to push a large number of changes from the managed object repository to several external repositories, the process can take some time. Problems such as lost connections might happen, resulting in the changes being only partially synchronized.

For example, if a Human Resources manager adds a group of new employees in one database, a partial synchronization might mean that some of those employees do not have access to their email or other systems.

You can configure implicit synchronization such that the system reverts an entire synchronization operation, in the event that it was not completely successful. An example of such a configuration is illustrated in Section 3.11, "Sample 5b - Failure Compensation With Multiple Resources" in the Installation Guide. That sample demonstrates how OpenIDM compensates when synchronization to an external resource fails.

Failure compensation works by using the optional onSync hook, which can be specified in the conf/managed.json file. The onSync hook can be used to provide failure compensation as follows:

...
"onDelete" : {
    "type" : "text/javascript",
    "file" : "ui/onDelete-user-cleanup.js"
    },
"onSync" : {
    "type" : "text/javascript",
    "file" : "compensate.js"
    },
"properties" : [
    ...
   

The onSync hook references a script (compensate.js), that is located in the /path/to/openidm/bin/defaults/script directory.

When a managed object is changed, an implicit synchronization operation attempts to synchronize the change (and any other pending changes) with any external data store(s) for which a mapping is configured.

The implicit synchronization process proceeds with each mapping, in the order in which the mappings are specified in sync.json.

The compensate.js script is designed to avoid partial synchronization. If synchronization is successful, for all configured mappings, OpenIDM exits from the script.

If an implicit synchronization operation fails for a particular resource, the onSync hook invokes the compensate.js script. This script attempts to revert the original change by performing another update to the managed object. This change, in turn, triggers another implicit synchronization operation to all external resources for which mappings are configured.

If the synchronization operation fails again, the compensate.js script is triggered again. This time, however, the script recognizes that the change was originally called as a result of a compensation and aborts. OpenIDM logs warning messages related to the sync action (notifyCreate, notifyUpdate, notifyDelete), along with the error that caused the sync failure.

If failure compensation is not configured, any issues with connections to an external resource can lead to data stores that are out of sync, such as the example cited earlier where some new employees do not have access to their corporate email accounts.

With the compensate.js script, any such errors will result in each data store using the information it had before the implicit synchronization operation started. OpenIDM stores that information, temporarily, in properties such as oldObject and oldTarget.

In this particular example, human resource managers should see that new employees are not shown in their database. Then, the administrators of the OpenIDM system can check log files for errors, address them, and then restart the implicit synchronization process with a new REST call.

During synchronization, OpenIDM categorizes objects according to their situation. Situations are characterized by whether an object exists on a source or target system, whether OpenIDM has registered a link between the source object and the target object, and whether the object is considered valid, as assessed by the validSource and validTarget scripts. OpenIDM then takes a specific action, depending on the situation.

You can define actions for particular situations in the policies section of a synchronization mapping, as shown in the following excerpt.

{
    "policies": [
        {
            "situation": "CONFIRMED",
            "action": "UPDATE"
        },
        {
            "situation": "FOUND",
            "action": "UPDATE"
        },
        {
            "situation": "ABSENT",
            "action": "CREATE"
        },
        {
            "situation": "AMBIGUOUS",
            "action": "EXCEPTION"
        },
        {
            "situation": "MISSING",
            "action": "EXCEPTION"
        },
        {
            "situation": "UNQUALIFIED",
            "action": "DELETE"
        },
        {
            "situation": "UNASSIGNED",
            "action": "EXCEPTION"
        }
    ]
}

If you do not define a policy for a particular situation, OpenIDM takes the default action for the situation.

The following sections describe the possible situations and their default corresponding actions.

{
    "situation" : "ABSENT",
    "action" : {
        "workflowName" : "managedUserApproval",
        "type" : "text/javascript",
        "file" : "workflow/triggerWorkflowFromSync.js"
    }
}
   

Reconciliation can work in tandem with workflows to provide additional business logic to the reconciliation process. You can define scripts to determine the action that should be taken for a particular reconciliation situation. A reconciliation process can launch a workflow after it has assessed a situation, and then perform the reconciliation, or some other action.

For example, you might want a reconciliation process to assess new user accounts that need to be created on a target resource. However, new user account creation might require some kind of approval from a manager before the accounts are actually created. The initial reconciliation process can assess the accounts that need to be created, launch a workflow to request management approval for those accounts, and then relaunch the reconciliation process to create the accounts, once the management approval has been received.

In this scenario, the defined script returns IGNORE for new accounts and the reconciliation engine does not continue processing the given object. The script then initiates an asynchronous process which calls back and completes the reconciliation process at a later stage.

A sample configuration for this scenario is available in openidm/samples/sample9, and described in Section 3.15, "Sample 9 - Asynchronous Reconciliation Using Workflows" in the Installation Guide.

By default, OpenIDM is case-sensitive, which means that case is taken into account when comparing IDs during reconciliation. For data stores that are case-insensitive, such as OpenDJ, IDs and links that are created by a reconciliation process may be stored with a different case to the way in which they are stored in the OpenIDM repository. Such a situation can cause problems during a reconciliation operation, as the links for these IDs may not match.

For such data stores, you can configure OpenIDM to ignore case during reconciliation operations. With case sensitivity turned off in OpenIDM, for those specific mappings, comparisons are done without regard to case.

To specify that data stores are not case-sensitive, set the "sourceIdsCaseSensitive" or "targetIdsCaseSensitive" property to false in the mapping for those links. For example, if the LDAP data store is case-insensitive, set the mapping from the LDAP store to the managed user repository as follows:

"mappings" : [
{
"name" : "systemLdapAccounts_managedUser",
"source" : "system/ldap/account",
"sourceIdsCaseSensitive" : false,
"target" : "managed/user",
"properties" : [
...
   

If a mapping inherits links by using the "links" property, it is not necessary to set case sensitivity, because the mapping uses the setting of the referred links.

Note that configuring OpenIDM to be case-insensitive when comparing links does not make the OpenICF provisioner case-insensitive when it requests data. For example, if a user entry is stored with the ID testuser and you make a request for https://localhost:8443/openidm/managed/TESTuser, most provisioners will filter out the match because of the difference in case, and will indicate that the record is not found. To prevent the provisioner from performing this secondary filtering, set the enableFilteredResultsHandler property to false in the provisioner configuration. For example:

"resultsHandlerConfig" :
{
    "enableFilteredResultsHandler":false,
}, 

By default, reconciliation is configured to function in an optimized way. Some of these optimizations might, however, be unsuitable for your environment. The following sections describe the optimizations and how they can be configured.

{
    "mappings": [
        {
            "name"                     : "systemMyLDAPAccounts_managedUser",
            "source"                   : "system/MyLDAP/account",
            "target"                   : "managed/user",
            "correlateEmptyTargetSet"  : true
        },
    ]
}

{
    "mappings": [
        {
            "name": "systemMyLDAPAccounts_managedUser",
            "source": "system/MyLDAP/account",
            "target": "managed/user"
            "prefetchLinks" : false
        }
    ]
}

    "mappings" : [
        {
            "name" : "systemXmlfileAccounts_managedUser",
            "source" : "system/xmlfile/account",
            "target" : "managed/user",
            "taskThreads" : 20
            ...
         }
    ]
}

Every time OpenIDM creates an object through synchronization, it creates a link between the source and target objects. OpenIDM then uses the link to determine the object's situation during later synchronization operations.

Initial, full synchronization operations can involve correlating many objects that exist on both source and target systems. In this case, OpenIDM uses correlation queries to find target objects that already exist, and that correspond to source objects. For the target objects that match a correlation query, OpenIDM needs only to create a link, rather than a new target object.

Correlation queries are accomplished by using script to construct the actual query map. The content of the query is generated dynamically, using values from the source object. Each source object results in a new query being sent to the target system, using (possibly transformed) values from the source object for its execution.

Correlation queries are defined as part of the mapping (in sync.json) and run against target resources, either managed or system objects, depending on the mapping. Correlation queries on system objects access the connector, which executes the query on the external resource.

The preferred syntax for a correlation query is a filtered query, using the _queryFilter keyword, although predefined queries (using _queryId) and native queries (using _queryExpression) are also supported for correlation queries.

A correlation query must return a map that holds a generic query, with the following elements:

The following query finds objects on the target whose uid is the same as the userName of a source object.

    "correlationQuery" : {
        "type" : "text/javascript",
        "source" : "var qry = {'_queryFilter': 'uid eq \"' + source.userName + '\"'}; qry"
    },
  

The query can return zero or more objects. The situation that OpenIDM assigns to the source object depends on the number of target objects that are returned.

Correlation queries that do not use common query filter syntax must be defined in the configuration file for the repository, either openidm/conf/repo.jdbc.json or openidm/conf/repo.orientdb.json, and must be referenced in the mapping (sync.json) file.

The following example shows a query, defined in the OrientDB repository configuration (openidm/conf/repo.orientdb.json), that can be used as the basis for a correlation query.

"for-userName" : "SELECT * FROM ${unquoted:_resource} WHERE userName = ${uid}"
  

By default, a ${value} token replacement is assumed to be a quoted string. If the value is not a quoted string, use the unquoted: prefix, as shown above.

You would call this query in the mapping (sync.json) file as follows:

{
  "correlationQuery": {
    "type": "text/javascript",
    "source":
      "var qry = {'_queryId' : 'for-userName', 'uid' : source.name}; qry;"
  }
}

The _queryId property value (for-userName) matches the name of the query specified in openidm/conf/repo.orientdb.json. The source.name value replaces ${uid} in the query. OpenIDM replaces ${unquoted:_resource} in the query with the name of the table that holds managed objects.

OpenIDM 3.1 offers a new declarative correlation option, named the expression builder, that makes it easier to configure correlation queries. The easiest way to use the expression builder to build up a correlation query is by using the Admin UI. The following image shows how the expression builder is used to build up a correlation query for a mapping from system/ldap/accounts to managed/user objects. The query essentially states that, in order for a match to exist between the source (LDAP) object and the target (managed) object, both the userName and telephoneNumber of those objects must match.

The resulting correlation query, in the mapping configuration (sync.json) is as follows:

"correlationQuery" : {
    "type" : "text/javascript",
    "expressionTree" : {
        "all" : [
            "givenName",
            "telephoneNumber"
        ]
    },
    "mapping" : "systemLdapAccounts_managedUser",
    "file" : "ui/correlateTreeToQueryFilter.js"
},

The logic in the expression builder is in the script openidm/bin/defaults/script/ui/correlateTreeToQueryFilter.js which converts the expression into the required query filter.

Section 12.3, "Basic Data Flow Configuration" shows how to trigger scripts when objects are created and updated. Other situations require you to trigger scripts in response to other synchronization actions. For example, you might not want OpenIDM to delete a managed user directly when an external account is deleted, but instead unlink the objects and deactivate the user in another resource. (Alternatively, you might delete the object in OpenIDM but nevertheless execute a script.) The following example shows a more advanced mapping configuration.

{
    "mappings": [
        {
            "name": "systemLdapAccount_managedUser",
            "source": "system/ldap/account",
            "target": "managed/user",
            "validSource": {
                "type": "text/javascript",
                "file": "script/isValid.js"
            },
            "correlationQuery" : {
                "type" : "text/javascript",
                "source" : "var map = {'_queryFilter': 'uid eq \"' +
                     source.userName + '\"'}; map;"
            },
            "properties": [
                {
                    "source": "uid",
                    "transform": {
                        "type": "text/javascript",
                        "source": "source.toLowerCase()"
                    },
                    "target": "userName"
                },
                {
                    "source": "",
                    "transform": {
                        "type": "text/javascript",
                        "source": "if (source.myGivenName)
                            {source.myGivenName;} else {source.givenName;}"
                    },
                    "target": "givenName"
                },
                {
                    "source": "",
                    "transform": {
                        "type": "text/javascript",
                        "source": "if (source.mySn)
                            {source.mySn;} else {source.sn;}"
                    },
                    "target": "familyName"
                },
                {
                    "source": "cn",
                    "target": "fullname"
                },
                {
                    "comment": "Multi-valued in LDAP, single-valued in AD.
                        Retrieve first non-empty value.",
                    "source": "title",
                    "transform": {
                        "type": "text/javascript",
                        "file": "script/getFirstNonEmpty.js"
                    },
                    "target": "title"
                },
                {
                    "condition": {
                        "type": "text/javascript",
                        "source": "var clearObj = openidm.decrypt(object);
                            ((clearObj.password != null) &&
                            (clearObj.ldapPassword != clearObj.password))"
                    },
                    "transform": {
                        "type": "text/javascript",
                        "source": "source.password"
                    },
                    "target": "__PASSWORD__"
                }
            ],
            "onCreate": {
                "type": "text/javascript",
                "source": "target.ldapPassword = null;
                    target.adPassword = null;
                    target.password = null;
                    target.ldapStatus = 'New Account'"
            },
            "onUpdate": {
                "type": "text/javascript",
                "source": "target.ldapStatus = 'OLD'"
            },
            "onUnlink": {
                "type": "text/javascript",
                "file": "script/triggerAdDisable.js"
            },
            "policies": [
                {
                    "situation": "CONFIRMED",
                    "action": "UPDATE"
                },
                {
                    "situation": "FOUND",
                    "action": "UPDATE"
                },
                {
                    "situation": "ABSENT",
                    "action": "CREATE"
                },
                {
                    "situation": "AMBIGUOUS",
                    "action": "EXCEPTION"
                },
                {
                    "situation": "MISSING",
                    "action": "EXCEPTION"
                },
                {
                    "situation": "UNQUALIFIED",
                    "action": "UNLINK"
                },
                {
                    "situation": "UNASSIGNED",
                    "action": "EXCEPTION"
                }
            ]
        }
    ]
}

Your scripts can get data from any connected system at any time by using the openidm.read(id) function, where id is the identifier of the object to read.

The following example reads a managed user object from the repository.

repoUser = openidm.read("managed/user/ddoe");

The following example reads an account from an external LDAP resource.

externalAccount = openidm.read("system/ldap/account/uid=ddoe,ou=People,dc=example,dc=com");

Note that the query targets a DN rather than a UID, as it did in the previous example. The attribute that is used for the _id is defined in the connector configuration file and, in this example, is set to "uidAttribute" : "dn". Although it is possible to use a DN (or any unique attribute) for the _id, as a best practice, you should use an attribute that is both unique and immutable.

You can schedule synchronization operations, such as LiveSync and reconciliation, using cron-like syntax.

This section describes scheduling for reconciliation and LiveSync, however, you can also use OpenIDM's scheduler service to schedule any other event by supplying a link to a script file, in which that event is defined. For information about scheduling other events, and for a deeper understanding of the OpenIDM scheduler service, see Chapter 13, "Scheduling Tasks and Events".

{
 "enabled"       : true,
 "persisted"     : false,
 "type"          : "cron",
 "startTime"     : "(optional) time",
 "endTime"       : "(optional) time",
 "schedule"      : "cron expression",
 "misfirePolicy" : "optional, string",
 "timeZone"      : "(optional) time zone",
 "invokeService" : "service identifier",
 "invokeContext" : "service specific context info"
}
   

{
    "invokeService": "sync",
    "invokeContext": {
        "action": "reconcile",
        "mapping": "systemLdapAccount_managedUser"
    }
}
   

{
    "invokeService": "provisioner",
    "invokeContext": {
        "action": "liveSync",
        "source": "system/OpenDJ/__ACCOUNT__"
    }
}
   

{
    "enabled": true,
    "type": "cron",
    "schedule": "0 08 16 * * ?",
    "invokeService": "sync",
    "invokeContext": {
        "action": "reconcile",
        "mapping": {
            "name": "CSV_XML",
            "source": "system/Ldap/account",
            "target": "managed/user",
            "properties": [
                {
                    "source": "firstname",
                    "target": "firstname"
                },
                ...
            ],
            "policies": [...]
        }
    }
}
   

In the boot properties configuration file (openidm/conf/boot/boot.properties), the instance type is standalone and persistent schedules are enabled by default:

# valid instance types for node include standalone, clustered-first, and clustered-additional
openidm.instance.type=standalone

# enables the execution of persistent schedulers
openidm.scheduler.execute.persistent.schedules=true
  

The scheduler service configuration file (openidm/conf/scheduler.json) governs the configuration for a specific scheduler instance, and has the following format:

{
 "threadPool" : {
     "threadCount" : "10"
 },
 "scheduler" : {
     "executePersistentSchedules" : "&{openidm.scheduler.execute.persistent.schedules}"
 }
}
  

For details of all the configurable properties for the Quartz Scheduler, see the Quartz Scheduler Configuration Reference.

Each schedule configuration file, openidm/conf/schedule-schedule-name.json, has the following format:

{
 "enabled"             : true,
 "persisted"           : false,
 "concurrentExecution" : false,
 "type"                : "cron",
 "startTime"           : "(optional) time",
 "endTime"             : "(optional) time",
 "schedule"            : "cron expression",
 "misfirePolicy"       : "optional, string",
 "timeZone"            : "(optional) time zone",
 "invokeService"       : "service identifier",
 "invokeContext"       : "service specific context info",
 "invokeLogLevel"      : "(optional) level"
}