Need documentation for creating a flowable REST server

I have spent a lot of time trying to get flowable-rest running under
Tomcat, but it still doesn’t work. I’m using Flowable 6.3.1.

I wrote a Java application to load an external Postgres DB with all the user and group information, deploy *.bar files, start process, etc. And this also works just fine.

Now I want to develop a flowable-rest server running in Tomcat to use that Postgres DB. I’ve hacked the flowable-rest.war to insert my custom JavaDelegate subclasses. But I can’t get this piece to work at all.

I have a number of questions:

  1. Flowable has great documentation on the application parts, but I’ve yet to find any good documentation on how to create your own flowable-rest server. Yes, the docs list 4 steps for hosting under Tomcat, but there are a lot of unanswered questions.

  2. I know I need flowable-rest.war inside Tomcat, but do I also need flowable-idm.war? I really don’t understand what flowable-idm does. Is it JUST the UI (my assumption), or is it needed at run-time to do authn/authz processing (as suggested by the need for the FLOWABLE_COMMON_APP_IDM-REDIRECT-URL variable)?

  3. If I need multiple *.war files, how do I get them to use a single, common properties file? I’ve seen posts that talk about flowable-ui-app.properties, db.properties, application.properties. Which one is correct?

  4. Why do some of the flowable environment variables contain “-” characters? This is an invalid character for bash and sh environment variables, which makes it impossible to set these env vars.

I’ve tried lots of different variations, but can’t find one that works. Mostly I get 401 (authentication) errors from CURL.

Hi,

  1. I see we can improve our documentation in this area yes. Maybe we can use your use case as an example on what documentation is missing exactly.

  2. No, you don’t need flowable-idm.war. We use that app for our UI pass to have a common entry point to login to these applications. But for Flowable REST this is done via basic auth and you don’t need anything in addition.

  3. Yes I can see this is a bit confusing, because it changed when we migrated to Spring Boot 2 for our apps. One application.properties file on the classpath should do the trick. We are using standard Spring Boot 2 for this now.

  4. Ok, that sound like something that needs to be solved. Could you give some examples of this and create a Github issue?

Best regards,

Tijs

Thanks so much for your answers. They clear up some points. I’ve made the changes you suggest, but the server is still failing when I “catalina.sh run”. My current error is the following. I don’t understand how to debug this. I haven’t found any of the identifiers in any of the property files.

2018-08-28 21:36:33.167  WARN 37335 --- [           main] ConfigServletWebServerApplicationContext : Exception encountered during context initialization - cancelling refresh attempt: org.springframework.context.ApplicationContextException: Unable to start web server; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'servletEndpointRegistrar' defined in class path resource [org/springframework/boot/actuate/autoconfigure/endpoint/web/ServletEndpointManagementContextConfiguration.class]: Bean instantiation via factory method failed; nested exception is org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.springframework.boot.actuate.endpoint.web.ServletEndpointRegistrar]: Factory method 'servletEndpointRegistrar' threw exception; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'processEngineEndpoint' defined in class path resource [org/flowable/spring/boot/EndpointAutoConfiguration.class]: Unsatisfied dependency expressed through method 'processEngineEndpoint' parameter 0; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'processEngine' defined in class path resource [org/flowable/spring/boot/ProcessEngineServicesAutoConfiguration$AlreadyInitializedAppEngineConfiguration.class]: Unsatisfied dependency expressed through method 'processEngine' parameter 0; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'org.flowable.spring.boot.app.AppEngineServicesAutoConfiguration': Unsatisfied dependency expressed through method 'setEngineConfigurers' parameter 0; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'processAppEngineConfigurationConfigurer' defined in class path resource [org/flowable/spring/boot/ProcessEngineAutoConfiguration$ProcessEngineAppConfiguration.class]: Bean instantiation via factory method failed; nested exception is org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.flowable.spring.boot.EngineConfigurationConfigurer]: Illegal arguments to factory method 'processAppEngineConfigurationConfigurer'; args: ; nested exception is java.lang.IllegalArgumentException: wrong number of arguments
2018-08-28 21:36:33.191  INFO 37335 --- [           main] ConditionEvaluationReportLoggingListener : 

Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
2018-08-28 21:36:33.195 ERROR 37335 --- [           main] o.s.b.SpringApplication                  : Application run failed

Ideal solution

This is unrelated to the problem I posted, but … I have a full set of Flowable Docker images running. I would love to use these servers, but I haven’t figured out a way to add my own JavaDelegate subclasses. If there were a REST api to dynamically add/remove user jars to flowable-rest.war, I would have been done months ago. That would be ideal.

New document

I’d like to see an new “Configuration and Deployment” document, which includes the following:
– A description of how the various modules (wars) interact. I suspect that they all interact ONLY thru the database. Is that true?
– What changes, if any, require each war to be restarted?
– a list of all the environment variables, any alternate names, which war files use it, a description of what it does, and some indication of its valid values.
– A list of all user-changable configuration files, and their directory locations. From the configuration files I’ve seen, you’ve done a pretty good job of using in-line comments to describe each property.

Regarding your current error that errors occurs when you are missing the JDBC driver on your classpath. The error is misleading due do an issue within Spring or Spring Boot. There is spring-projects/spring-boot#13222 issue logged for Boot.

Which driver do you use? How did you add the library?

I would love to use these servers, but I haven’t figured out a way to add my own JavaDelegate subclasses.

Why not build your own Spring Boot application with your own JavaDelegates and use the flowable-spring-boot-starter-rest? That would create the same dependency war / jar as the flowable-rest.war

A description of how the various modules (wars) interact. I suspect that they all interact ONLY thru the database. Is that true?

Yes they interact through the database. However, for logging in to the flowable-idm.war, flowable-task.war, flowable-admin.war and flowable-modeler.war they use the flowable-idm.war as a SSO server.

The flowable-modeler.war also has a publish button that publishes the application over REST to the configured rest endpoint.

The flowable-admin.war actually uses REST to fetch the information for the display.

All this means that you can use your own custom rest application and configure the flowable-modeler.war and flowable-admin.war to talk with it.

The flowable-task.war has the UI and an engine. It and the flowable-rest.war are actually the same, so you should not use it if you are adding custom JavaDelegates and build your own REST application.

Clicked reply by mistake. Here is the rest of my reply.

What changes, if any, require each war to be restarted?

Don’t quite understand the question.

– a list of all the environment variables, any alternate names, which war files use it, a description of what it does, and some indication of its valid values.
– A list of all user-changable configuration files, and their directory locations. From the configuration files I’ve seen, you’ve done a pretty good job of using in-line comments to describe each property.

This are linked. For the UI applications have you had a look at Flowable UI Applications section of the documentation. And for the engine properties have you seen the Spring Boot Flowable Application Properties section of the documentation?

All Flowable UI applications are Spring Boot applications, so alternative names, configuration files are Spring Boot based and can be found in the Externalized Configuration section of the Spring Boot documentation.

Adding the JDBC driver fixed the specific error. THANKS.

This next comment means “When you change X, you need to restart the flowable-rest.war in the server”. Are there any X’s? It was just a general question; I didn’t have anything specific in mind.

What changes, if any, require each war to be restarted?

I am SO glad you pointed out the contents of “Flowable UI Applications”. Since I was only interested in building a REST server, I’ve always skipped this section. But it DOES contain the “missing” information I was looking for. I’d ask you to consider renaming this section or perhaps reorganizing things a bit to prevent others from skipping this important section.

Finally, I have my app running now – ONLY because of your assistance! (ignoring a few of my bugs). I can’t thank you enough.

Great that everything works out.

Regarding

Since I was only interested in building a REST server, I’ve always skipped this section. But it DOES contain the “missing” information I was looking for. I’d ask you to consider renaming this section or perhaps reorganizing things a bit to prevent others from skipping this important section.

Can you point out what was the “missing” information that you were looking for so we can reorganise a bit? The idea of that part is to have only information about the UI applications that we have.

Cheers,
Filip

In putting this list together, my previous comments was too sweeping. I found the following items in Flowable UI applications pertain to flowable-rest.

  • This set of paragraphs beginning with Usually, you will want to change the default H2 in-memory database configuration down to the link to the Postgres drive. This is the most important item.

  • “Table 4. Old properties managed by the Flowable Spring Boot Starter” contains properties relevant to flowable-rest.

  • Not as sure about this one, but “Table 5. Old properties managed by Spring Boot” may also contain properties relevant to flowable-rest.

  • the access-rest-api priviledge

1 Like

I’m trying to follow your flowable-spring-boot-starter-rest suggestion. I made a copy of the pom.xml and it builds cleanly, but the jar is essentially empty.

  1. I’ve read the documentation, but I don’t understand what else I have to add to the pom to get a working jar.
  2. I don’t understand how I add my own JavaDelegates to the jar.

And I’m new to Spring Boot. Do you have any other links?

Scott

Anyone know how to address by previous post?

Hi,

The easiest approach is to have a look at the flowable-app-rest module (https://github.com/flowable/flowable-engine/tree/master/modules/flowable-app-rest), because this module is exposing the Flowable REST API using the flowable-spring-boot-starter-rest module. Then you can add your JavaDelegate classes to this same module.

Best regards,

Tijs