StephenOTT/camunda-deployment-maven-plugin

A maven plugin that allows REST API based deployments to a Camunda BPM instance https://forum.camunda.org/t/camunda-deployment-maven-plugin-rest-api/8391?u=stephenott

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.StephenOTT:camunda-deployment-maven-plugin:v0.7'
	}
	dependencies {
		implementation("com.github.StephenOTT:camunda-deployment-maven-plugin:v0.7")
	}
	<dependency>
	    <groupId>com.github.StephenOTT</groupId>
	    <artifactId>camunda-deployment-maven-plugin</artifactId>
	    <version>v0.7</version>
	</dependency>

                            
    libraryDependencies += "com.github.StephenOTT" % "camunda-deployment-maven-plugin" % "v0.7"
        
        

                            
    :dependencies [[com.github.StephenOTT/camunda-deployment-maven-plugin "v0.7"]]

Readme

Camunda BPM Deployment Maven Plugin

A Maven plugin that provides the ability to deploy to a Camunda BPM instance through the Camunda Rest API.

The plugin is designed to be used along side unit testing, allowing the Build-Test-Deploy flows to easily occur.

How it works

When the plugin is executed, a groovy script is executed, which will pull in any additional dependencies through Grape, and then execute the script. All plugin parameter configurations are passed into the script through a binding with the variable name configs.

Within the Groovy script you can access the configs Map with:

Map<String, Object> config = (Map<String, Object>)configs

println config.host // outputs: http://localhost:8080

See CamundaDeployment.groovy for a working example.

Using the Plugin

The plugin can be activated directly throuhg the command line and will also be picked up by Maven UIs such as the one built into IntelliJ IDEA.

Command Line

mvn camunda-deployment:deploy-with-rest-api

IntelliJ IDEA

With your Maven project loaded in IntelliJ, go to:

  1. Maven Projects tab
  2. Open the specific Maven Project
  3. Plugins
  4. Click the arrow to the left of camunda-deployment
  5. Double click camunda-deployment:deploy-with-rest-api
  6. The build/deployment will run

intellij

Build Status

The plugin will detect if a Exception object is returned by the evaluated Groovy script, and throw a Plugin Build Failure causing a BUILD FAILURE to be returned.

The default groovy script will detect the http status-code returned by Camunda. The script expects Camunda to return a status code of 200, otherwise a Exception will be thrown.

How to Install

The plugin is located at http://github.com/stephenott/camunda-deployment-maven-plugin as a release.

You can easily install the plugin by adding the following to your maven pom.xml file:

<project>
...
    <pluginRepositories>
        <pluginRepository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </pluginRepository>
    </pluginRepositories>
...

This snippet will enable Maven dependency download directly from Github.com

If you already have a <pluginRepositories> section in your pom.xml, then just add the <pluginRepository> section.

Once this section is added, you can add the plugin configuration section in the <build><plugins> section as described in the Plugin Configuration section.

If you are using IntelliJ, you can enable the "Auto-download dependencies" feature, which will automatically add the missing dependencies described.

Plugin Configuration

The maven plugin provides multiple configuration options.

    <build>
        <plugins>
            <plugin>
                <groupId>com.github.StephenOTT</groupId>
                <artifactId>camunda-deployment-maven-plugin</artifactId>
                <version>v0.5</version>
                <configuration>
                    <host>http://localhost:8081</host>
                    <apiPath>/engine-rest</apiPath>
                    <deploymentFilesDir>${project.build.directory}/deploymentFiles</deploymentFilesDir>
                    <scriptPath>scripts/myScript.groovy</scriptPath>  <!-- Path is relative to pom.xml unless full path is provided-->
                    <additionalConfigs>
                        <deploymentName>testDeployment123</deploymentName>
                        <duplicateFiltering>false</duplicateFiltering>
                        <deployChangedOnly>false</deployChangedOnly>
                        <deploymentSource>MyLocalComputer</deploymentSource>
                        <tenantId>someTenantName</tenantId>
                    </additionalConfigs>
                </configuration>
            </plugin>
        </plugins>
    </build>

All values in teh <configuration> section are optional.

Default values:

| Parameter | Value | | ----------------- | ------------- | host | http://localhost:8080 apiPath | /engine-rest deploymentFilesDir | ${project.build.directory}/camunda-deployment-files-from-source This will typically be ./target/camunda-deployment-files-from-source scriptPath | null additionalConfigs | null

Configuration Usage:

| Configuration Parameter | Usage | | ----------------- | ------------- | | host | The URI of the camunda server, inlcuding the port if applicable | | apiPath | the url path for the Camunda Rest-API application | | deploymenFilesDir | The path to the directory with the files to deploy to the Camunda Instance. The deployment files are exepcted to all be in the root of the defined directory. | scriptPath | The path to a groovy script file (.groovy) which will be executed instead of the default script file. See CamundaDeployment.groovy for a working example. | additionalConfigs | a Map of Key/Values for holding any extra configuration options to pass into the executing script. Typically used when using a custom script path with scriptPath parameter.

Additional Configs (<additionalConfigs>):

The <additionalConfigs> has multiple configurations ready to be used with the default deployment script:

| Parameter | Value | Type | | ----------------- | ------------- | -------- | deploymentName | The name for the deployment to be created. Default: maven-deployment | String duplicateFiltering | A flag indicating whether the process engine should perform duplicate checking for the deployment or not. Default: false | Boolean: true/false deployChangedOnly | A flag indicating whether the process engine should perform duplicate checking on a per-resource basis. Default: false | Boolean: true/false deploymentSource | The source for the deployment to be created. Default: maven | String tenantId | The tenant id for the deployment to be created. Default: null | String

Deployment Output Example

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Camunda BPM Deployment Maven Plugin 0.5-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- camunda-deployment-maven-plugin:0.5-SNAPSHOT:deploy-with-rest-api (default-cli) @ camunda-deployment-maven-plugin ---
[INFO] Starting deployment to Camunda...
[INFO] Deployment Successful:
{
    "links": [
        {
            "method": "GET",
            "href": "http://localhost:8080/engine-rest/deployment/ef537f84-968a-11e8-8ea6-0242ac110002",
            "rel": "self"
        }
    ],
    "id": "ef537f84-968a-11e8-8ea6-0242ac110002",
    "name": "myDeployment",
    "source": null,
    "deploymentTime": "2018-08-02T19:33:29.968+0000",
    "tenantId": null,
    "deployedProcessDefinitions": {
        "model1:12:ef920f27-968a-11e8-8ea6-0242ac110002": {
            "id": "model1:12:ef920f27-968a-11e8-8ea6-0242ac110002",
            "key": "model1",
            "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
            "description": null,
            "name": null,
            "version": 12,
            "resource": "model1.bpmn",
            "deploymentId": "ef537f84-968a-11e8-8ea6-0242ac110002",
            "diagram": null,
            "suspended": false,
            "tenantId": null,
            "versionTag": null,
            "historyTimeToLive": null
        }
    },
    "deployedCaseDefinitions": null,
    "deployedDecisionDefinitions": null,
    "deployedDecisionRequirementsDefinitions": null
}
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.267 s
[INFO] Finished at: 2018-08-02T15:33:30-04:00
[INFO] Final Memory: 19M/148M
[INFO] ------------------------------------------------------------------------

Process finished with exit code 0