Starting With the Groovy Sample Project

ForgeRock provides a sample project that you can use to start writing a custom scripted Groovy connector. The sample project includes the base classes and libraries required for a simple connector, but the built connector does nothing until you add scripts to perform the operations on your remote resource.

The main use of the sample project is to make it easier to package your custom Groovy scripts into a single custom scripted connector file.

To get started with the sample project:

  1. Clone the project from the ForgeRock git repository.

    If you do not have access to this repository, contact info@forgerock.com.

  2. Open the project in your IDE.

  3. Rename the connector.

    In general, you can find and replace all instances of customscripted in your project's pom.xml file with the name of your connector. The following examples assume a new connector named myexample:

    1. Rename org.forgerock.openicf.connectors.customscripted to org.forgerock.openicf.connectors.myexample. Specify your own directory structure here.

    2. In the pom.xml file, make the following changes:

      • Change the artifactId:

        <artifactId>myexample-connector</artifactId>
      • Change the description as required. For example:

        <description>Connector that manages users in the myexample resource</description>
      • Change the connectorPackage and connectorClass:

        <connectorPackage>org.forgerock.openicf.connectors.myexample</connectorPackage>
        <connectorClass>MyexampleConnector</connectorClass>
      • Edit the repositories block to include additional repositories if necessary.

        At a minimum, the connector pulls the connector-framework and groovy-connector artifacts from the forgerock-private-releases repository.

      • In the maven-bundle-plugin configuration, change the export package name:

        <Export-Package>org.forgerock.openicf.connectors.myexample.*</Export-Package>
  4. Edit the display messages in the resources/../Messages.properties file.

    The connector.display property specifies the name of this connector as it will appear in the UI.

    Add a .display and .help property for any configuration properties for the connector. These properties are specific to each connector. For example, if your connector connects to a database, you might need to specify the properties similar to the following here:

    database.display=Database Path
    database.help=If specified, the connector attempts to connect using only this database

    The Messages.properties file is not mandatory, and is used only to manage the connector configuration in the UI.

  5. Rename the CustomscriptedConnector class. For example:

    @ConnectorClass(displayNameKey = "connector.display",
            configurationClass = MyexampleConfiguration.class,
            messageCatalogPaths = {
                    "org/forgerock/openicf/connectors/groovy/Messages",
                    "org/forgerock/openicf/connectors/customscripted/Messages"
            })
    public class Myexample extends ScriptedConnectorBase<MyexampleConfiguration>
            implements PoolableConnector {
    
        public Myexample() {
            // Empty
         }

    In this example, your connector class extends the ScriptedConnectorBase class. You can also extend the ScriptedCREST, ScriptedREST, ScriptedSQL, or ScriptedSSH class, with additional imports, if your connector should inherit those capabilities. If you extend a different connector class here, you must also extend the corresponding Configuration class in the CustomscriptedConfiguration shown in the next step.

  6. Add any new methods or override the default behavior in this Connector class, as required.

  7. Rename the CustomscriptedConfiguration class. For example:

    @ConfigurationClass(skipUnsupported = true)
    public class MyexampleConfiguration extends ScriptedConfiguration {
    
        /**
         * Setup logging for the {@link MyexampleConfiguration}.
         */
        private static final Log logger = Log.getLog(MyexampleConfiguration.class);
    
        private String example = null;
        private GuardedString guardedExample = null;
    
        /**
         * Constructor.
         */
        public MyexampleConfiguration() {
        }
    
  8. Add any new configuration properties that your connector requires (with getters, setters, and annotations).

  9. Update your project's pom.xml file to include any new dependencies.

    If you do not want to bundle the dependencies with the connector, set <scope>provided</scope> for those dependencies. For example:

    <dependency>
        <groupId>org.codehaus.groovy</groupId>
        <artifactId>groovy-all</artifactId>
        <version>2.2.2</version>
        <scope>provided</scope>
    </dependency>
  10. Write the scripts that will perform the ICF operations on the resource, and place these scripts in the src/main/resources/script/ directory of the project.

    IDM provides several sample scripts in its scripted connector samples and you can use these as a base from which to work. See the scripts in the following sample directories to get started:

    • /path/to/openidm/samples/scripted-rest-with-dj/tools

    • /path/to/openidm/samples/scripted-sql-with-mysql/tools

    To use the sample scripts, copy them from the sample directory and place them your project's script/ directory, then edit them as required. For example:

    cd /path/to/myexample-connector/
    cp /path/to/openidm/samples/scripted-sql-with-mysql/tools/TestScript.groovy src/main/resources/script/
  11. Build your connector with the following command:

    mvn clean install

    When your connector has built successfully, the target/ directory contains two JAR files:

    • myexample-connector-1.5.0.0-SNAPSHOT.jar bundles only the connector and its scripts.

    • myexample-connector-1.5.0.0-SNAPSHOT-jar-with-dependencies.jar bundles the connector with its scripts and dependencies.

    Note

    If you want to build a single JAR file, including the dependencies, named myexample-connector-1.5.0.0-SNAPSHOT.jar, edit your pom.xml accordingly.

  12. To use your connector, create a connector configuration (provisioner) file using one of the methods described in Configure Connectors.

  13. Edit the provisioner file as required. At a minimum, set the scriptRoots property to point to the location of your scripts within the bundled connector JAR. For example:

    "scriptRoots" : [ "jar:file:connectors/myexample-connector-1.5.0.0-SNAPSHOT.jar!/script/" ]
Read a different version of :