Scripted REST Connector

runScriptOnConnector

To run an arbitrary script on a Groovy Toolkit connector, define the script in the systemActions property of your provisioner file:

"systemActions" : [
    {
        "scriptId" : "MyScript",
        "actions" : [
            {
                "systemType" : ".*ScriptedConnector",
                "actionType" : "groovy",
                "actionFile" : "path/to/scriptname.groovy"
            }
        ]
    }
]

If you wish to define your script in the provisioner file itself rather than in a separate file, you can use the actionSource property instead of the actionFile one. A simple example follows:

"systemActions" : [
    {
        "scriptId" : "MyScript",
        "actions" : [
            {
                "systemType" : ".*ScriptedConnector",
                "actionType" : "groovy",
                "actionSource" : "2 * 2"
            }
        ]
    }
]

Running MyScript will return:

{
  "actions" : [
    {
      "result": 4
    }
  ]
}

If your script accepts parameters, you can supply them in the request body or the query string. For example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data-raw '{"param1":"value1"}' \
"http://localhost:8080/openidm/system/groovy?_action=script&scriptId=MyScript&param2=value2"

You can also call it through the script engine. The system can accept arbitrary parameters:

openidm.action("/system/groovy", "script", {"contentParameter": "value"}, {"scriptId": "MyScript", "additionalParameter1": "value1", "additionalParameter2": "value2"})

runScriptOnResource

To run an arbitrary script using runScriptOnResource, you must add some configuration details to your provisioner file. These details include a scriptOnResourceScriptFileName that references a script file located in a path contained in the scriptRoots array.

Define these properties in your provisioner file:

"configurationProperties": {
  "scriptRoots": [
    "path/to/scripts"
  ],
  "scriptOnResourceScriptFileName": "ScriptOnResourceScript.groovy"
},
"systemActions" : [
    {
        "scriptId" : "script-1",
        "actions" : [
            {
                "systemType" : ".*ScriptedConnector",
                "actionType" : "groovy",
                "actionFile" : "path/to/scriptname.groovy"
            }
        ]
    }
]

When you have defined the script, call it over REST on the system endpoint:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/groovy?_action=script&scriptId=scriptOnResourceScript&scriptExecuteMode=resource"

OpenICF Interfaces Implemented by the Scripted REST Connector

The Scripted REST Connector implements the following OpenICF interfaces.

Scripted REST Connector Configuration

The Scripted REST Connector has the following configurable properties.

Configuration properties

Property	Type	Default	Encrypted [a]	Required [b]
customSensitiveConfiguration	GuardedString	null
Custom Sensitive Configuration script for Groovy ConfigSlurper
customConfiguration	String	null
Custom Configuration script for Groovy ConfigSlurper
[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM. [b] A list of operations in this column indicates that the property is required for those operations.

Operation Script Files

Property	Type	Default	Encrypted [a]	Required [b]
createScriptFileName	String	null		Create
The name of the file used to perform the CREATE operation.
customizerScriptFileName	String	null
The script used to customize some function of the connector. Read the documentation for more details.
authenticateScriptFileName	String	null		Authenticate
The name of the file used to perform the AUTHENTICATE operation.
scriptOnResourceScriptFileName	String	null		Script On Resource
The name of the file used to perform the RUNSCRIPTONRESOURCE operation.
deleteScriptFileName	String	null		Delete
The name of the file used to perform the DELETE operation.
resolveUsernameScriptFileName	String	null		Resolve Username
The name of the file used to perform the RESOLVE_USERNAME operation.
searchScriptFileName	String	null		Get Search
The name of the file used to perform the SEARCH operation.
updateScriptFileName	String	null		Update
The name of the file used to perform the UPDATE operation.
schemaScriptFileName	String	null		Schema
The name of the file used to perform the SCHEMA operation.
testScriptFileName	String	null		Test
The name of the file used to perform the TEST operation.
syncScriptFileName	String	null		Sync
The name of the file used to perform the SYNC operation.
[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM. [b] A list of operations in this column indicates that the property is required for those operations.

Groovy Engine configuration

Property	Type	Default	Encrypted [a]	Required [b]
targetDirectory	File	null
Directory into which to write classes.
warningLevel	int	1
Warning Level of the compiler
scriptExtensions	String[]	['groovy']
Gets the extensions used to find groovy files
minimumRecompilationInterval	int	100
Sets the minimum of time after a script can be recompiled.
scriptBaseClass	String	null
Base class name for scripts (must derive from Script)
scriptRoots	String[]	null
The root folder to load the scripts from. If the value is null or empty the classpath value is used.
tolerance	int	10
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.
debug	boolean	false
If true, debugging code should be activated
classpath	String[]	[]
Classpath for use during compilation.
disabledGlobalASTTransformations	String[]	null
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.
verbose	boolean	false
If true, the compiler should produce action information
sourceEncoding	String	UTF-8
Encoding for source files
recompileGroovySource	boolean	false
If set to true recompilation is enabled
[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM. [b] A list of operations in this column indicates that the property is required for those operations.

Basic Configuration Properties

Property	Type	Default	Encrypted [a]	Required [b]
username	String	null
The Remote user to authenticate with
password	GuardedString	null
The Password to authenticate with
serviceAddress	URI	null
The service URI (example: http://myservice.com/api)
proxyAddress	URI	null
The optional Proxy server URI (example: http://myproxy:8080)
proxyUsername	String	null
The username to authenticate with the proxy server
proxyPassword	GuardedString	null
The password to authenticate with the proxy server
defaultAuthMethod	String	BASIC
Authentication method used. Defaults to BASIC.
defaultContentType	String	application/json
Default HTTP request content type. Defaults to JSON. Can be: TEXT, XML, HTML, URLENC, BINARY
defaultRequestHeaders	String[]	null
Placeholder for default HTTP request headers.
OAuthTokenEndpoint	URI	null
When using OAUTH, this property defines the endpoint where a new access token should be queried for (https://myserver.com/oauth2/token)
OAuthClientId	String	null
The client identifier
OAuthClientSecret	GuardedString	null
Secure client secret for OAUTH
OAuthRefreshToken	GuardedString	null
The refresh token used to renew the access token for the refresh_token grant type
OAuthScope	String	null
The optional scope
OAuthGrantType	String	CLIENT_CREDENTIALS
The grant type to use. Can be CLIENT_CREDENTIALS (default) | REFRESH_TOKEN | AUTHORIZATION_CODE
[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM. [b] A list of operations in this column indicates that the property is required for those operations.