Scripted REST Connector

The Scripted REST Connector enables you to connect to any resource over HTTP/REST. The connector creates the HTTP/REST context (specifying the content type, authentication mode, encoding, and so on), and manages the connection.

The connector relies on the Groovy scripting language and its RESTClient package. The Groovy scripts are responsible for sending requests and processing results.

The following sample Groovy script creates a new user in OpenDJ, using OpenDJ's REST API:

connection.put(
    path: '/users/' + name,
    headers: ['If-None-Match': '*'],
    contentType: JSON,
    requestContentType: JSON,
    body: JsonOutput.toJson(
        [_id : name,
            name : [
                familyName: "Doe",
                givenName : "John"
            ],
            displayName: "John Doe"
        ]
) );

This chapter describes the structure and configuration of the Scripted REST Connector, the operations that are supported by the connector, and the connector schema.

The Scripted REST Connector does not support connector pooling.

Scripted REST Connector Reference Object

The Scripted REST Connector has the following unique identifiers, expressed here in JSON format.

"connectorRef": {
    "bundleName": "org.openidentityplatform.openicf.connectors.groovy-connector",
    "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector",
    "bundleVersion": "[1.4.0.0,2)"
}

You can use OpenIDM to generate this configuration automatically when you configure the connector. Alternatively, you can copy this section and paste it directly into your connector configuration file (provisioner.openicf-connector-name.json). (for example, provisioner.openicf-scriptedrest.json

Samples

Scripted REST to OpenDJ

OpenICF Interfaces Implemented by Scripted REST Connector

Authenticate

Provides simple authentication with two parameters, presumed to be a user name and password.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Resolve Username

Resolves an object by its username and returns the uid of the object.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics:

• The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
• The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.
• The script has access to any script-arguments passed in by the application.

Script on Resource

Runs a script on the target resource that is managed by this connector.

Search

Searches the target resource for all objects that match the specified object class and filter.

Sync

Polls the target resource for synchronization events, that is, native changes to objects on the target resource.

Test

Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

Scripted REST Connector Configuration

Configuration Properties

Property	Description	Type	Default	Encrypted	Required
serviceAddress	CREST service address	URI	null		Yes
customConfiguration	Custom Configuration script for Groovy ConfigSlurper	String	null		No
customSensitiveConfiguration	Custom Sensitive Configuration script for Groovy ConfigSlurper	GuardedString	null	Yes	No
defaultAuthMethod	Default authentication method	String	BASIC		No
proxyAddress	Proxy address	URI	null		No
defaultRequestHeaders		String[]	null		No
defaultContentType		String	application/json		No

Basic Configuration Properties Properties

Property	Description	Type	Default	Encrypted	Required
username	username for authentication	String	null		No
password	password for authentication	GuardedString	null	Yes	No

Groovy Engine configuration Properties

Property	Description	Type	Default	Encrypted	Required
targetDirectory	Directory into which to write classes	File	null		No
warningLevel	Warning Level of the compiler	int	1		No
scriptExtensions	Description is not available	String[]	['groovy']		No
minimumRecompilationInterval	Sets the minimum of time after a script can be recompiled.	int	100		No
scriptBaseClass	Base class name for scripts (must derive from Script)	String	null		No
scriptRoots	The root folder to load the scripts from. If the value is null or empty the classpath value is used.	String[]	null		Yes
tolerance	The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.	int	10		No
debug	If true, debugging code should be activated	boolean	false		No
classpath	Classpath for use during compilation.	String[]	[]		No
disabledGlobalASTTransformations	Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/ org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled.	String[]	null		No
verbose	If true, the compiler should produce action information	boolean	false		No
sourceEncoding	Encoding for source files	String	UTF-8		No
recompileGroovySource	If set to true recompilation is enabled	boolean	false		No

Operation Script Files Properties

Property	Description	Type	Default	Encrypted	Required
createScriptFileName	The name of the file used to perform the CREATE operation.	String	null		Create
customizerScriptFileName	The script used to customize some function of the connector. Read the documentation for more details.	String	null		No
authenticateScriptFileName	The name of the file used to perform the AUTHENTICATE operation.	String	null		Authenticate
scriptOnResourceScriptFileName	The name of the file used to perform the RUNSCRIPTONRESOURCE operation.	String	null		Script On Resource
deleteScriptFileName	The name of the file used to perform the DELETE operation.	String	null		Delete
resolveUsernameScriptFileName	The name of the file used to perform the RESOLVE_USERNAME operation.	String	null		Resolve Username
searchScriptFileName	The name of the file used to perform the SEARCH operation.	String	null		Get Search
updateScriptFileName	The name of the file used to perform the UPDATE operation.	String	null		Update
schemaScriptFileName	The name of the file used to perform the SCHEMA operation.	String	null		Schema
testScriptFileName	The name of the file used to perform the TEST operation.	String	null		Test
syncScriptFileName	The name of the file used to perform the SYNC operation.	String	null		Sync