REST API Setup with Jersey and JSON and additional Mail Plug-In

[ttob...@gmail.com]

Hello all,

I'm new to camunda and I'm currently trying to set up a REST API. I have read through a lot of posts related to this topic but I haven't found a full explanation on how to set it up and I can't get it running (1).

In addition to that I'm using an email plug-in for my workflow. This plug-in works but I need to define it in my web.xml, where I now need to define Jersey and the rest-engine, too. These to definitions seem not to work in one web.xml (2).

(1): Now first to my application and REST API setup:

I have installed the Tomcat Distribution with included Camunda BPM, set up a Maven Project and created a workflow like it is explained in [1]. Furthermore to use the REST API, I have defined dependencies for "camunda-engine-rest", "jersey" and "maven-war-plugin" in the pom.xml, which looks like the following:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.camunda.bpm.getstarted</groupId>
<artifactId>project-name</artifactId>
<version>0.1.0-SNAPSHOT</version>
<packaging>war</packaging>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.camunda.bpm</groupId>
<artifactId>camunda-bom</artifactId>
<version>7.3.0</version>
<scope>import</scope>
<type>pom</type>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>org.camunda.bpm</groupId>
<artifactId>camunda-engine</artifactId>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.0.1</version>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>javax.mail</groupId>
<artifactId>mail</artifactId>
<version>1.4.7</version>
</dependency>

<dependency>
<groupId>org.glassfish.extras</groupId>
<artifactId>javaee</artifactId>
<version>3.1.1</version>
</dependency>

<!-- For REST API -->
<dependency>
<groupId>org.camunda.bpm</groupId>
<artifactId>camunda-engine-rest</artifactId>
<classifier>classes</classifier>
</dependency>

<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-grizzly2</artifactId>
<version>1.17.1</version>
<scope>test</scope>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>2.3</version>
<configuration>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
</plugins>
</build>

</project>

Next I've created a Java class namend "ProjectRest" to add the REST resources to my JAX-RS application [2]. This class is located in my package "org.camunda.bpm.getstarted.project-name" which is in the "src/main/java" source folder and it looks like the following:

package org.camunda.bpm.getstarted.project-name;

import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

import org.camunda.bpm.engine.rest.impl.*;

@ApplicationPath("/engine-rest")
public class ProjectRest extends Application{

@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> classes = new HashSet<Class<?>>();

// add your own classes
classes.add(TestRes.class);

// add all camunda engine rest resources
classes.addAll(CamundaRestResources.getResourceClasses());

// mandatory
classes.addAll(CamundaRestResources.getConfigurationClasses());

return classes;
}
}

The REST resource Java class "TestRes" is located in the same package of the same source-folder and looks like the following:

package org.camunda.bpm.getstarted.project-name;

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

import org.camunda.bpm.engine.impl.util.json.JSONObject;
import javax.ws.rs.Path;

@Path("/test")
public class TestRes{

private String firstname = "Jon";
private String lastname = "Doe";

@GET
@Produces("application/json")
public Response getCustomer(){
JSONObject jsonObject = new JSONObject();
jsonObject.put("Firstname", firstname);
jsonObject.put("Lastname", lastname);
String result = "@Produces(\"application/json\") Output: \n\nProject Name Output: \n\n" + jsonObject;
return Response.status(200).entity(result).build();
}
}

Finally I tried to define jersey and the REST API in my web.xml. I was geared to the RESTeasy Specifics[2] for this:

<?xml version="1.0" encoding="UTF-8"?>
<web-app>
<filter>
<filter-name>project-name</filter-name>
<filter-class>org.glassfish.jersey.servlet.ServletContainer</filter-class>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>org.camunda.bpm.engine.rest.impl.application.DefaultApplication</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>project-name</filter-name>
<url-pattern>/engine-rest</url-pattern>
</filter-mapping>
</web-app>

I'm able to deploy it onto Tomcat and run the process but I can't call the REST API. According to these sources [3][4] I believe I should be able to call the GET method of the ResTest class via:
"http://localhost/project-name/engine-rest/test"

(2): My second problem is, that I already need to define a "maven-war-plugin" in my web.xml to get my email plug-in running. Before setting up my REST API my web.xml looked like this:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<webXml>src\main\webapp\WEB-INF\web.xml</webXml>
</configuration>
</plugin>

Which worked well. I could run my process and automatically send emails. But now it seems like I can't define a <plugin> and a <web-app> in the same web.xml. The only way I was able to deploy the project with both included in the web.xml was to nest the <plugin> at the end of the <web-app> like:

<web-app>
...
<plugin>
...
</plugin>
</web-app>

But even like this the email plug-in did not work.

I would be very happy to get some help for these two problems. I realy searched a lot and tried out a lot but I can't manage to get this running.

Best regards,
Tassilo

[1] http://docs.camunda.org/latest/guides/getting-started-guides/developing-process-applications/
[2] http://docs.camunda.org/latest/api-references/rest/
[3] https://groups.google.com/forum/#!searchin/camunda-bpm-users/REST$20API$20URL/camunda-bpm-users/VhimSnPPCwg/Xwz_al3DGdYJ
[4] http://www-01.ibm.com/support/knowledgecenter/SSAW57_8.0.0/com.ibm.websphere.nd.doc/info/ae/ae/twbs_jaxrs_configjaxrs11method.html?cp=SSAW57_8.0.0%2F1-3-0-27-2-0-0

[Christian Lipphardt]

Hi Tassilo,

1. When you downloaded the Camunda BPM tomcat distribution, there is already an rest api deploy under http://localhost:8080/engine-rest if you are running the distro locally and did not modify anything. There is no need to embed the camunda restapi with your application except if you want to customize it. When you want to expose custom rest services from your application, see [1] for an introduction to JAX-RS. Depending on what kind of server you are using, you have to add the JAX-RS implementation dependency to your maven pom, e.g. RestEasy or Jersey.

2. Regarding your second problem. You are trying to include a maven pom configuration snippet in a web.xml file. THIS WILL NOT WORK. I do not know what kind of mail-plugin you are using but having something like the following in your web.xml is completely broken.

<?xml version="1.0" encoding="UTF-8"?>
<plugin>            
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
    <webXml>src\main\webapp\WEB-INF\web.xml</webXml>        
  </configuration>
</plugin>

Cheers,

Christian

[1]: http://www.mkyong.com/tutorials/jax-rs-tutorials/

[ttob...@gmail.com]

Hey Christian,

Thanks for your response. Given that I don't need to embed the camunda REST API in my application, I dropped the ProjectRest class where I added my resource classes and I dropped the camunda-engine-rest dependency of the pom.

Furthermore I transfered the plugin, mentioned in 2., from the web.xml into my pom and worked through the tutorial you linked to.

On deploying my .war file I get a log now that, in my opinion, indicates that the jersey api is running:

"
Jul 03, 2015 1:19:28 AM com.sun.jersey.api.core.PackagesResourceConfig init
INFORMATION: Scanning for root resource and provider classes in the packages:
org.camunda.bpm.getstarted.projectname
Jul 03, 2015 1:19:28 AM com.sun.jersey.api.core.ScanningResourceConfig logClasse
s
INFORMATION: Root resource classes found:
class org.camunda.bpm.getstarted.projectname.HelloWorldService
Jul 03, 2015 1:19:28 AM com.sun.jersey.api.core.ScanningResourceConfig init
INFORMATION: No provider classes found.
Jul 03, 2015 1:19:28 AM com.sun.jersey.server.impl.application.WebApplicationImp
l _initiate
INFORMATION: Initiating Jersey application, version 'Jersey: 1.8 06/24/2011 12:1
7 PM'
"

But I still can't call the REST API. I tried the path explained in the tutorial “projectURL/rest/hello/{any values}” (in my case: "http://localhost:8080/project-name/rest/hello/Community") and I tried out all combinations like "http://localhost:8080/engine-rest/rest/hello/Community".

I'm really stucked here and I would be happy for more tips and help.
Maybe I'm missing something here that is important for using a REST API in Camunda? Or do I use a wrong Jersey Version in my dependencies? Or is something wrong with my web.xml?

I add the code of my pom, REST Service and web.xml for further information:

Pom:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>org.camunda.bpm.getstarted.projectname</groupId>

<!-- Jersey start -->
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-server</artifactId>
<version>1.8</version>
</dependency>
<!-- Jersey end -->

</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>2.3</version>
<configuration>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
</plugins>
</build>
</project>

REST Service:

package org.camunda.bpm.getstarted.projectname;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;

@Path("/hello")
public class HelloWorldService {

@GET
@Path("/{param}")
public Response getMsg(@PathParam("param") String msg){

String output = "Jersey say: " + msg;

return Response.status(200).entity(output).build();
}
}

Web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app

xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<display-name>Restful Web Application</display-name>

<servlet>
<servlet-name>jersey-serlvet</servlet-name>
<servlet-class>
com.sun.jersey.spi.container.servlet.ServletContainer
</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>org.camunda.bpm.getstarted.projectname</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>jersey-serlvet</servlet-name>
<url-pattern>/rest/*</url-pattern>
</servlet-mapping>
</web-app>

Best regards,
Tassilo

[ttob...@gmail.com]

UPDATE: Ok it runs, like the log indicated it. The problem was that I used a wrong URL to call the REST method.

The right call is:
"http://localhost:8080/project-name-0.1.0-SNAPSHOT/rest/hello/Community"

I couldn't find that anywhere but in this Post:

https://groups.google.com/d/msg/camunda-bpm-users/VhimSnPPCwg/pQJRhTqY9qwJ

Thanks again to you Christian for your great help!

<SOLVED>

[Christian Lipphardt]

Hi Tassilo,

I thought of the name of artifact before, but normally Tomcat logs the context path when deploying the WAR. It uses the name of the WAR artifact as context path.

Cheers,

Christian