Beyond Quick Start

Following the “Spring Boot” section of the Camunda BPM Quick Start/Get Started documentation, I used the Camunda Platform Initializr to create a project with the Webapps, REST API, and Spin.

I followed the documented process except for “deploying” the process definition by adding it to the project. Instead, I was able to deploy it from the Modeler and run it in my Spring Boot project using a REST all from Postman.

I’ve gone through several of the Tutorial Videos and the Introduction, User Guide, and Reference | JavaDoc sections of the Documentation.

Now what?

I urgently need to extend the REST API, but despite the amount of documentation on the parts and pieces of the BPM Platform, I haven’t come across anything that explains how they actually work together.

Is there an explanation of request flow/lifecycle? If I add a REST endpoint to my Spring Boot project (implemented with a controller), what Camunda engine object(s) do I need to instantiate in order to start an instance of a process definition and have access to its resulting variable data? And how should I do that?

What is the Java entry point for a request that comes in from the REST API? In the absence of documentation of request flow/lifecycle, I could trace the execution if I knew this, but it doesn’t seem to be documented either.

Between the vastly simplified Quick Start and the detailed JavaDocs, there seems to be a huge gap in practical, actionable “how does this stuff actually work?” information and examples.

How can I best implement my immediate use case so that I can convince my organization that Camunda is worth seriously evaluating and licensing? And more generally, how does someone go from a beginner to a “combat effective” Camunda developer, especially under time pressure. Help?

I would add 2 cents here. I believe you already worked on Getting Started Guide to explore about Camunda capabilities. Camunda has flexible architecture you can plugin. For example if your model start event expects few parameters, that can be injected from your java code. this can be in service layer, where you pass the params and start the process instance. you can refer the code snippets provided by Camunda.

Thank you. I do believe that everything you are saying is true, but this doesn’t answer my question.

Specifically, where can I find documentation on the execution flow and lifecycle of a request that is sent into the REST API?

What is the Java entry point for a request that comes in from the REST API?

Can you direct me to a code snippet that shows how to to start an instance of a process definition and have access to its resulting variable data?

Where can I find these marvelous code snippets that show a newcomer how all this actually works?

Here is the Camunda examples:

Thank you. I very much appreciate your responses and your desire to help, but my questions still remain unanswered.

All of these very brief, very basic examples seem to focus primarily on HOW to get something specific done. That’s great if what you want to do fits one of the examples, but none of these examples address what I want to do, which is to start an instance of a process definition and have access to (and probably to manipulate) its resulting variable data without making a second server roundtrip.

When I look at the REST API documentation for Process Definition > Start Instance, I can see everything I need to make this API call.

I can even request that variables be returned from the process, which seems to be what I want to do. But the example response contains only scalar values (Boolean, String, etc, no JSON objects, which is what I need to do):

{
  "links": [
    {
      "method": "GET",
      "href": "http://localhost:8080/rest-test/process-instance/aProcInstId",
      "rel": "self"
    }
  ],
  "id": "aProcInstId",
  "definitionId": "aProcessDefinitionId",
  "businessKey": "myBusinessKey",
  "ended": false,
  "suspended": false,
  "tenantId": null,
  "variables": {
    "anotherVariable": {
        "type": "Boolean",
        "value": true,
        "valueInfo": {
          "transient" : true
        }
    },
    "aVariable": {
        "type": "String",
        "value": "aStringValue",
        "valueInfo": { }
    }
  }
}

If there was something that explained the execution flow and lifecycle of a request that is sent into the REST API, I could probably figure out whether what I want to do is possible and how to try to do it.

If the documentation referenced the Java object and entry point method that began processing any request that comes in to the REST API, I could set a breakpoint in my Spring Boot project and trace the flow. This would probably enable me to answer my own questions.

But there doesn’t seem to be anything at all that deals with WHY the platform behaves as it does, and none of the examples show how to hook into or intercept the request processing in order to change or add to the output like this:

{
  "links": [
    {
      "method": "GET",
      "href": "http://localhost:8080/rest-test/process-instance/aProcInstId",
      "rel": "self"
    }
  ],
  "id": "aProcInstId",
  "definitionId": "aProcessDefinitionId",
  "businessKey": "myBusinessKey",
  "ended": false,
  "suspended": false,
  "tenantId": null,
  "variables": {
    "anotherVariable": {
        "type": "Boolean",
        "value": true,
        "valueInfo": {
          "transient" : true
        }
    },
    "aVariable": {
        "type": "String",
        "value": "aStringValue",
        "valueInfo": { }
    },
    "aJsonVariable": {
        "type": "Object",
        "value": {
          "aVariable": "aStringValue",
          "anotherVariable": true
        },
        "valueInfo": { }
    }
  }
}

I hope that this makes what I’m asking more clear. The problem with not having any mid-level information about how the system processes information is that we have a VERY general, high-level picture (just a few boxes connected with lines) and VERY specific, low-level code examples with nothing in between. If none of the examples is what someone wants to do, the solution is very difficult (nearly impossible?) to determine.

Let me explain in sequence, this will clear your questions.

  1. The way you accessed the Rest API is for processes which are already running in the Camunda Engine. Camunda Engine itself exposed as Rest end points to identify the process status/definitions. The same info is available in Cockpit.

  2. What you are looking for is from Micro Service, you are submitting the values asJSON object, which are used for triggering the business process as start event.

For example in MS service layer, you can get the value from Controller layer and start the process

    LOGGER.info("EMP ID" + empId);
    LOGGER.info("DAYS REQUESTED"+ leaveRequested);

    Map variables = new HashMap();
    variables.put("empId", empId);
    variables.put("noOfDaysLeaveRequested", leaveRequested);

    ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();
    RuntimeService runtimeService = processEngine.getRuntimeService();
    ProcessInstance instance = runtimeService.startProcessInstanceByKey("EmpMgmt-process", variables);


}
2 Likes

This looks promising! Giving it a try in the custom API endpoint I’m building. I’ll let you know if it works. Thank you!

This was essentially what I needed. It took a little while to fill in the missing pieces, wire it up with Spring Boot annotations, parse the input variables from the request body, etc, but I’ve got it basically working.

Thank you. So (if I may I ask), how/where did you learn how to do this?

1 Like

Good to hear that i am able to help you. Being a developer, i was going through the documentation/sample code, I learnt it.

1 Like

Hi @Doug_Wilson,

since I saw your first question I was wondering what to answer. I thought by myself: your are right, that it is difficult to find something beyond quickstart in the now overwhelming docs.

A benefit of these docs: everything is documented. The dowside: the relevant facts to fulfill your knowledge requests may be hard to find.

When I started using Camunda in the beginning, it took only about a day to read the complete user guide and to understand nearly eveything. Now, seven years and a lot of added features later, it’s hard to follow the red thread.

I looked though the docs and a good starting point could be these chapters:

  1. Process Engine Concepts | docs.camunda.org
  2. Delegation Code | docs.camunda.org
  3. Process Variables | docs.camunda.org
  4. External Tasks | docs.camunda.org if you look for an microservice environment.
  5. User Task Forms | docs.camunda.org

The first chapters reference Java API examples, but you can map them to the alphabetically ordered Rest API endpoints afterwards.

This is the sequence that we use in our developer trainings.

And there is the wide area of BPMN modeling, where only the first steps are handle here: BPMN - Camunda

Hope this helps, Ingo

1 Like

Thank you so much, Ingo. I very much appreciate this advice and will certainly follow the pathway you’ve charted.

I’m coming at this “backward” in a sense, having started with Zeebe and now working with the Camunda BPM Platform. I’m a big fan of Camunda, and I believe strongly in the value you provide.

Thanks again for your concern and your thoughtful, candid reply.

Best regards,

Doug

Hello @Ingo_Richtsmeier,

Thank you so much for your guidance.
This is very helpful to start the Camunda for all the beginners…!

2 Likes