IDM 7.2.1

ICF operations with Groovy scripts

The Groovy Connector Toolkit lets you run a Groovy script for any ICF operation, such as search, update, create, and so forth, on any external resource.

You must write a Groovy script that corresponds to each operation that your connector will support. For information about all the operations that are supported by the ICF framework, refer to OpenICF SPI.

Your scripted connector can implement the following ICF interfaces:

Authenticate operation

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

Create operation

Creates an object and its uid.

Delete operation

Deletes an object, referenced by its uid.

Resolve username operation

Resolves an object to its uid based on its username.

Schema operation

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

Script on connector operation

Enables IDM 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 IDM.

Script on resource operation

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

Search operation

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

Sync operation

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

Test operation

Tests the connector configuration. Testing a configuration checks that 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 the 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 operation

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

The following sections provide more information and pointers to sample scripts for all the operations that are implemented in the Groovy Connector Toolkit.

Variables available to all Groovy scripts

The following variables are available to all scripts used by the Groovy Connector. Additional variables are available to specific scripts, as described in the sections that follow:

configuration

A handle to the connector’s configuration object is injected into all scripts.

operation

The connector injects the name of the action or operation into the script, to indicate which action is being called.

The sample scripts for the Groovy connector define one script file per action. You can use a single file, or amalgamate multiple actions into one file. For example, the CREATE and UPDATE operations often share the same code.

The operation type can be one of the following:

  • ADD_ATTRIBUTE_VALUES

  • AUTHENTICATE

  • CREATE

  • DELETE

  • GET_LATEST_SYNC_TOKEN

  • REMOVE_ATTRIBUTE_VALUES

  • RESOLVE_USERNAME

  • RUNSCRIPTONCONNECTOR

  • RUNSCRIPTONRESOURCE

  • SCHEMA

  • SEARCH

  • SYNC

  • TEST

  • UPDATE

options

The ICF framework passes an OperationOptions object to most of the operations. The Groovy connector injects this object, as is, into the scripts. For example, the search, query, and sync operations pass the attributes to get as an operation option.

The most common options are as follows:

  • AttributesToGet (String[]) for search and sync operations

  • RunAsUser (String) for any operation

  • RunWithPassword (GuardedString) for any operation

  • PagedResultsCookie (String) for search operations

  • PagedResultsOffset (Int) for search operations

  • PageSize (Int) for search operations

  • SortKeys (Sortkey[]) for search operations

objectClass

The category or type of object that is managed by the connector, such as ACCOUNT and GROUP.

log

A handle to the default ICF logging facility.

connection

Available to the ScriptedREST, ScriptedCREST, and ScriptedSQL implementations, this variable initiates the HTTP or SQL connection to the resource.

Copyright © 2010-2022 ForgeRock, all rights reserved.