Setting Up New ConnId 1.x Connector Project

Last modified 14 Oct 2020 23:20 +02:00

Create the Project

Create a source code repository for a new connector. We strongly prefer if you use Github to maintain connector source code, but any reasonable way will do. E.g. connectors maintained under the Polygon project are maintained in the Evolveum area on Github. The naming convention that we use is connector-targetsystem.

Choose a license. We recommend to use Apache 2.0 license. But any reasonable license will do.

Choose a maven group ID and artifact ID.

  • Group IDs are usually based on Java package names which are in turn usually based on DNS names. We use com.evolveum.polygon. But you are free to use your own.

  • Artifact IDs are short component names. We use the same name as name of the repository, e.g. connector-gitlab.

Use our Maven archetype to create an empty project structure.

Maven 3.x changed archetype repository resolution. Our archetype is in our Nexus, not in Maven Central, and it will not be found automatically. We need to change .m2/settings.xml file (in our home directory) as mentioned in the second step below.

  1. Get the polygon framework source code and install it:

    git clone https://github.com/Evolveum/polygon.git
    cd polygon
    mvn clean install
  2. Add the following profile into your .m2/settings.xml:

    <profiles>
        ...
        <profile>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <repositories>
                <!--
                Or you can just add this repository into an existing profile.
                Be sure the profile is activated or use -Pprofile to activate it in the next step.
                -->
                <repository>
                    <!-- id expected by maven-archetype-plugin to avoid fetching from everywhere -->
                    <id>archetype</id>
                    <url>https://nexus.evolveum.com/nexus/content/repositories/releases</url>
                    <releases>
                        <enabled>true</enabled>
                        <checksumPolicy>fail</checksumPolicy>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                        <checksumPolicy>warn</checksumPolicy>
                    </snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>
  3. Generate your project structure using polygon archetype:

    cd your-project-folder
    mvn archetype:generate -DarchetypeGroupId=com.evolveum.polygon -DarchetypeArtifactId=basic-connector-archetype -DarchetypeVersion=1.4.0.49 -DgroupId=your.group.id -DartifactId=your-artifact-id
  4. The archetype will ask several questions such as these:

    Define value for property 'version':  1.0-SNAPSHOT: : 1.4.1.0-SNAPSHOT
    [INFO] Using property: package = com.evolveum.polygon
    Define value for property 'connectorName': : Foo
    Confirm properties configuration:
    groupId: com.evolveum.polygon
    artifactId: connector-ldap
    version: 1.4.1.0-SNAPSHOT
    package: com.evolveum.polygon
    connectorName: Foo
     Y: :
  5. Checkout the empty repository before you use the artifact and generate the files directly it in. Or use the generated directory for an initial import. Or simply move the generated files where you need them. It all depends on the source control system that you are using and your development process.

  6. The resulting file structure should look like this:

    pom.xml
    src
      main
        ...
      test
        ...
    LICENSE (optional, but this is a good practice)
    README  (optional, but this is a good practice)
  7. Do not forget to add the generated files under source control, e.g. for git:

    git add pom.xml src

Now you can import the project into your IDE and start the development.