README.md revision 54507660fb2716977261f50e2ba31e6198e44319
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
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>/"
54507660fb2716977261f50e2ba31e6198e44319Jon BranchThe OpenIDM provisioner file must be extracted to the filesystem as it presently cannot be detected and used
54507660fb2716977261f50e2ba31e6198e44319Jon Branchdirectly from within the jar:
355e5661379644c081271b23fa8b966a098a42d2Jon Branch jar -xvf <filename>.jar conf/provisioner.openicf-*.json
355e5661379644c081271b23fa8b966a098a42d2Jon Branch### Sample configuration file
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "packageName" : "Awesome",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "displayName" : "Awesome Connector",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "description" : "This is my super awesome connector",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "version" : "1.0",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "author" : "Coder McLightningfingers",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "properties" : [
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "order" : 0,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "String",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "FirstProperty",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "value" : "firstValue",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : true,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "confidential" : false,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "displayMessage" : "This is my first property",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "helpMessage" : "This should be a String value",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "group" : "default"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "order" : 1,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "Double",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "SecondProperty",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "value" : 1.234,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : false,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "confidential" : false,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "displayMessage" : "This is my second property",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "helpMessage" : "This should be a Double value",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "group" : "default"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "objectTypes" : [
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "group",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "id" : "__GROUP__",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "object",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "__GROUP__",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "objectClass" : "ObjectClass.GROUP_NAME",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "properties" : [
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "name",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : true,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "__NAME__",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "gid",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : true,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "gid",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "description",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : false,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "description",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "users",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "array",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "users",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "object",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "object",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "properties" : [{
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "uid",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "account",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "id" : "__ACCOUNT__",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "object",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "__ACCOUNT__",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "objectClass" : "ObjectClass.ACCOUNT_NAME",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "properties" : [
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "firstName",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "firstname",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : true
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "email",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "email",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "password",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "password",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "NOT_READABLE",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "NOT_RETURNED_BY_DEFAULT"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "uid",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "__NAME__",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : true,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "fullName",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "fullname",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "name" : "lastName",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "type" : "string",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "required" : true,
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeName" : "lastname",
355e5661379644c081271b23fa8b966a098a42d2Jon Branch "nativeType" : "string"
355e5661379644c081271b23fa8b966a098a42d2Jon Branch### Other resources