Connector Archetype

ICF provides a Maven connector archetype that lets you get started with connector development.

The connector archetype assumes that you have Apache Maven installed on your system. Before you use the connector archetype, add the following to your Maven settings.xml file, replacing backstage-username and backstage-password with your ForgeRock Backstage credentials:

<servers>
 ...
 <server>
    <username>backstage-username</username>
    <password>backstage-password</password>
    <id>archetype</id>
  </server>
</servers>
...
<profiles>
  <profile>
    <id>test</id>
    <activation>
      <activeByDefault>true</activeByDefault>
    </activation>
    <repositories>
      <repository>
         <id>archetype</id>
         <url>http://maven.forgerock.org/repo/private-releases</url>
       </repository>
    </repositories>
  </profile>
</profiles>

To start building a connector by using the connector archetype, execute the following command, customizing these options to describe your new connector:

  • -DartifactId=sample-connector

  • -Dversion=0.0-SNAPSHOT

  • -Dpackage=org.forgerock.openicf.connectors.sample

  • -DconnectorName=Sample

This command imports the connector archetype and generates a new connector project:

mvn archetype:generate \
 -DarchetypeGroupId=org.forgerock.openicf \
 -DarchetypeArtifactId=connector-archetype \
 -DarchetypeVersion=1.4.0 \
 -DremoteRepositories=http://maven.forgerock.org/repo/private-releases \
 -DarchetypeRepository=http://maven.forgerock.org/repo/private-releases \
 -DgroupId=org.forgerock.openicf.connectors \
 -DartifactId=sample-connector \
 -Dversion=0.0-SNAPSHOT \
 -Dpackage=org.forgerock.openicf.connectors.sample \
 -DconnectorName=Sample
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.0.1:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.0.1:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO] --- maven-archetype-plugin:3.0.1:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Interactive mode
...
ALL_OPERATIONS: n
OP_AUTHENTICATE: n
OP_CREATE: y
OP_DELETE: y
OP_RESOLVEUSERNAME: n
OP_SCHEMA: n
OP_SCRIPTONCONNECTOR: n
OP_SCRIPTONRESOURCE: n
OP_SEARCH: y
OP_SYNC: n
OP_TEST: y
OP_UPDATE: y
OP_UPDATEATTRIBUTEVALUES: n
attributeNormalizer: n
compatibility_version: 1.1
connectorName: Sample
framework_version: 1.0
jira_componentId: 10191
jira_fixVersionIds: 0
poolableConnector: n
 Y: :

At this point, you can enter Y (YES) to accept the default project, or N (NO) to customize the project for your connector.

You will notice in the preceding output that the default connector supports only the create, delete, search, test, and update operations, and is not a poolable connector. To add support for additional operations, or to change any of the connector parameters, enter N (NO). The archetype then prompts you to set values for each additional parameter.

After you have imported the archetype once, you can use the local version of the archetype, as follows:

mvn archetype:generate -DarchetypeCatalog=local

Implement ICF Operations

When you have generated the archetype, implement the ICF operations that your connector will support.

For information about implementing operations, and examples for a Java connector, see OpenICF SPI.

Build the Java Connector

To build the connector, run:

cd /path/to/sample-connector/
mvn install