355e5661379644c081271b23fa8b966a098a42d2Jon Branch### Copyright
355e5661379644c081271b23fa8b966a098a42d2Jon BranchDO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
355e5661379644c081271b23fa8b966a098a42d2Jon BranchCopyright (c) 2015 ForgeRock AS. All Rights Reserved
355e5661379644c081271b23fa8b966a098a42d2Jon BranchThe contents of this file are subject to the terms
355e5661379644c081271b23fa8b966a098a42d2Jon Branchof the Common Development and Distribution License
355e5661379644c081271b23fa8b966a098a42d2Jon Branch(the License). You may not use this file except in
355e5661379644c081271b23fa8b966a098a42d2Jon Branchcompliance with the License.
355e5661379644c081271b23fa8b966a098a42d2Jon BranchYou can obtain a copy of the License at
355e5661379644c081271b23fa8b966a098a42d2Jon BranchSee the License for the specific language governing
355e5661379644c081271b23fa8b966a098a42d2Jon Branchpermission and limitations under the License.
355e5661379644c081271b23fa8b966a098a42d2Jon BranchWhen distributing Covered Code, include this CDDL
355e5661379644c081271b23fa8b966a098a42d2Jon BranchHeader Notice in each file and include the License file
355e5661379644c081271b23fa8b966a098a42d2Jon BranchIf applicable, add the following below the CDDL Header,
355e5661379644c081271b23fa8b966a098a42d2Jon Branchwith the fields enclosed by brackets [] replaced by
355e5661379644c081271b23fa8b966a098a42d2Jon Branchyour own identifying information:
355e5661379644c081271b23fa8b966a098a42d2Jon Branch"Portions Copyrighted [year] [name of copyright owner]"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch### About this package
355e5661379644c081271b23fa8b966a098a42d2Jon BranchThis is a custom scripted connector bundler used to generate the boilerplate necessary to produce a
355e5661379644c081271b23fa8b966a098a42d2Jon Branchcustom connector based on the ForgeRock OpenICF Groovy connector. Having this code pre-generated for
355e5661379644c081271b23fa8b966a098a42d2Jon Branchyou will save a lot of time and effort, accelerating the process of creating your own custom
355e5661379644c081271b23fa8b966a098a42d2Jon BranchWhen given a JSON configuration file this will produce all of the required source code to then build an
355e5661379644c081271b23fa8b966a098a42d2Jon BranchOSGi-compatible jar file usable in any OpenICF-compliant project such as OpenIDM. See below for a template
355e5661379644c081271b23fa8b966a098a42d2Jon BranchFor the connector to serve any useful purpose the generated Groovy templates must be populated with
355e5661379644c081271b23fa8b966a098a42d2Jon Branchcode appropriate to the resource to be accessed. The templates contain notes and, where appropriate,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch"starter code" to aid in this process.
355e5661379644c081271b23fa8b966a098a42d2Jon Branch### Step by step
355e5661379644c081271b23fa8b966a098a42d2Jon BranchFirst obtain a copy of this project either in source or binary form. If in source form first build
355e5661379644c081271b23fa8b966a098a42d2Jon Branchthe binary jar with 'mvn install'.
355e5661379644c081271b23fa8b966a098a42d2Jon BranchPlace your JSON configuration file in a clean directory and execute the jar:
355e5661379644c081271b23fa8b966a098a42d2Jon Branch $ java -jar custom-scripted-connector-bundler-<version>.jar -c <config.json>
355e5661379644c081271b23fa8b966a098a42d2Jon Branch OpenICF Scripted Groovy Connector SourceGenerator v<version>
355e5661379644c081271b23fa8b966a098a42d2Jon Branch Generating connector sources for <connector name>
355e5661379644c081271b23fa8b966a098a42d2Jon BranchThis will create a directory tree of source files that can be used to build your custom connector.
355e5661379644c081271b23fa8b966a098a42d2Jon BranchEdit the Groovy templates found at ./src/main/resources/script/<connectorname>/*.groovy. For the connector
355e5661379644c081271b23fa8b966a098a42d2Jon Branchto do anything useful these must be enhanced with code to do the real work.
355e5661379644c081271b23fa8b966a098a42d2Jon BranchNow it's time to build your custom connector:
355e5661379644c081271b23fa8b966a098a42d2Jon Branch $ mvn install
3437677679324afd5af50dac4de68ae39418c655Jon Branch#### Groovy Script Location
355e5661379644c081271b23fa8b966a098a42d2Jon BranchThis will produce an OSGi-compatible jar in the ./target directory. Copy this jar to your OpenICF-compatible
355e5661379644c081271b23fa8b966a098a42d2Jon Branchproject or distribute it for others to use.
54507660fb2716977261f50e2ba31e6198e44319Jon BranchThis jar contains all of the Groovy scripts which are executed directly from the jar. These may optionally
54507660fb2716977261f50e2ba31e6198e44319Jon Branchbe extracted to the filesystem and run from there with a change to the provisioner JSON file. Change:
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "scriptRoots" : [
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "jar:file:&{launcher.install.location}/connectors/awesome-connector-1.0.jar!/script/awesome/"
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "classpath" : [
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "jar:file:&{launcher.install.location}/connectors/awesome-connector-1.0.jar!/script/awesome/"
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "scriptRoots" : [
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "file:&{launcher.project.location}/<your_extracted_script_location>/"
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "classpath" : [
54507660fb2716977261f50e2ba31e6198e44319Jon Branch "file:&{launcher.project.location}/<your_extracted_script_location>/"
3437677679324afd5af50dac4de68ae39418c655Jon Branch#### OpenIDM Provisioner Configuration
54507660fb2716977261f50e2ba31e6198e44319Jon BranchThe OpenIDM provisioner file must be extracted to the filesystem as it presently cannot be detected and used
3437677679324afd5af50dac4de68ae39418c655Jon Branchdirectly from within the jar. To identify the filename grep the jar's catalog:
3437677679324afd5af50dac4de68ae39418c655Jon Branch jar -tvf <filename>.jar | grep "provisioner*json"
3437677679324afd5af50dac4de68ae39418c655Jon BranchThe file should appear in a conf/ directory. Next extract the file to the conf directory on your local filesystem:
3437677679324afd5af50dac4de68ae39418c655Jon Branch jar -xvf <filename>.jar <provisioner filename>
3437677679324afd5af50dac4de68ae39418c655Jon Branch#### OpenIDM UI Connector Template
3437677679324afd5af50dac4de68ae39418c655Jon BranchThe Admin UI provides a default template for configuration of connectors that lack a specialized template. If
3437677679324afd5af50dac4de68ae39418c655Jon Branchyou prefer to have a specialized template to use with your new connector there is one in the connector bundle
3437677679324afd5af50dac4de68ae39418c655Jon Branchfor this purpose. Because the UI template is named after this connector you must first identify the file:
3437677679324afd5af50dac4de68ae39418c655Jon Branch jar -tvf <filename>.jar | grep "1.4.html"
3437677679324afd5af50dac4de68ae39418c655Jon BranchUsing the sample configuration this will be named:
3437677679324afd5af50dac4de68ae39418c655Jon Branch ui/org.forgerock.openicf.connectors.awesome.AwesomeConnector_1.4.html
3437677679324afd5af50dac4de68ae39418c655Jon BranchNext extract the file from the connector jar (using the example above):
3437677679324afd5af50dac4de68ae39418c655Jon Branch jar -xvf ui/org.forgerock.openicf.connectors.awesome.AwesomeConnector_1.4.html
3437677679324afd5af50dac4de68ae39418c655Jon BranchThen move it to the correct directory for the UI to find it:
3437677679324afd5af50dac4de68ae39418c655Jon Branch mv ui/org.forgerock.openicf.connectors.awesome.AwesomeConnector_1.4.html \
3437677679324afd5af50dac4de68ae39418c655Jon Branch ui/default/admin/public/templates/admin/connector/
355e5661379644c081271b23fa8b966a098a42d2Jon Branch### Sample configuration file
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "packageName" : "Awesome",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "displayName" : "Awesome Connector",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "description" : "This is my super awesome connector",
3437677679324afd5af50dac4de68ae39418c655Jon Branch "baseConnectorType" : "GROOVY",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "version" : "1.0",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "author" : "Coder McLightningfingers",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "providedProperties" : [ {
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "provided1",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "value" : "default",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "String"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "provided2",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "value" : 2,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "Integer"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "properties" : [ {
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "order" : 0,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "String",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "FirstProperty",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "value" : "firstValue",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "required" : true,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "confidential" : false,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "displayMessage" : "This is my first property",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "helpMessage" : "This should be a String value",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "group" : "default"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "order" : 1,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "Double",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "SecondProperty",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "value" : 1.234,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "required" : false,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "confidential" : false,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "displayMessage" : "This is my second property",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "helpMessage" : "This should be a Double value",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "group" : "default"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "objectTypes" : [ {
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "group",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "id" : "__GROUP__",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "object",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "__GROUP__",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "objectClass" : "ObjectClass.GROUP",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "properties" : [ {
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "name",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : true,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "__NAME__",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "gid",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "required" : true,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "gid",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "description",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : false,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "description",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "users",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "array",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "users",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "object",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "object",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "properties" : [{
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "uid",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "account",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "id" : "__ACCOUNT__",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "object",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "__ACCOUNT__",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "objectClass" : "ObjectClass.ACCOUNT",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "properties" : [ {
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "firstName",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "firstname",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "required" : true
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "email",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "email",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "password",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "password",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "NOT_READABLE",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "NOT_RETURNED_BY_DEFAULT"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "uid",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "__NAME__",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "required" : true,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "fullName",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "fullname",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "name" : "lastName",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "type" : "string",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "required" : true,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeName" : "lastname",
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch "nativeType" : "string"
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch#### Base connector types
3437677679324afd5af50dac4de68ae39418c655Jon Branch The possible values for the param baseConnectorType are:
3437677679324afd5af50dac4de68ae39418c655Jon Branch 1. GROOVY Non-pooled Groovy connector
3437677679324afd5af50dac4de68ae39418c655Jon Branch 2. POOLABLEGROOVY Poolable Groovy connector
3437677679324afd5af50dac4de68ae39418c655Jon Branch 2. CREST CREST-based connector
3437677679324afd5af50dac4de68ae39418c655Jon Branch 3. REST REST-based connector
3437677679324afd5af50dac4de68ae39418c655Jon Branch 4. SQL Connector with SQL support
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch#### ProvidedProperties vs. Properties
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch ProvidedProperties are those already provided by the base configuration class for your connector. For example,
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch if you choose SQL as your connector type then ScriptedSQLConfiguration will be your base configuration class. This
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch base class already provides properties for "username", "password", etc. There is no need for you to define them
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch yourself but you will need to provide a default value if you want them to show up in the provisioner file. To do
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch so simply add them as ProvidedProperties.
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch The other type, Properties, defines new and unique properties you want your connector to support. This is where you
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch define the attributes of each new custom property your connector will have that the base configuration class did
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch not provide.
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch#### ObjectType -> ObjectClass
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch The possible values for the objectClass in each objectType are:
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch 4. The bundler will accept any arbitrary string but you may need to edit the resulting provisioner and
a5c4e019584526e990bdb898f84300d790ebc708Jon Branch Groovy scripts to work with this arbitrary string.
355e5661379644c081271b23fa8b966a098a42d2Jon Branch### Other resources