Creating a new end-point in Camunda


#1

Preface: I am not a Java developer, my first time touching anything Java related was yesterday.

We have a need for a new endpoint in Camunda for dealing with external tasks. I opened a Feature Request in Jira about our desired functionality here: https://app.camunda.com/jira/browse/CAM-6415

After receiving a comment asking if we would be willing to contribute this functionality, I installed all the required Java dev tools and pulled and compiled the Camunda repository from GitHub.

Poking around in the code, I eventually added some files/lines within the External Tasks portions of the engine and engine-rest and got a compiling version of Camunda with my changes. I have also verified that my endpoint is listening and responding to requests.

However, I cannot figure out how to get the request to update the database. I don’t know how to log, debug, or trace anything I am doing in Java. I am primarily a NodeJS developer with previous experience in PHP.

I’ve made changes to/added the following files: https://github.com/camunda/camunda-bpm-platform/compare/master...goyney:CAM-6415?expand=1

Can anyone point me in the correct direction? I would really like to solve this issue and contribute something useful to the Camunda project.

Thank you!


#2

Hi @goyney,

First of all, its great that you are willing to make this effort :slight_smile:

Looking at your code, I see that you have found the right places that need extension (REST API resources and ExternalTaskService).

I have feedback on four aspects:

  • I think we do not need an additional field in ExternalTaskEntity but should rather the field lockExpirationTime. The fetch and lock API considers this field when it picks external tasks. If we go in that direction, you do not need to make any changes in order to update the value in the database. That is done implicitly. It is just when you add a new field, you have to extend the database schema and object relational mapping.
  • In terms of API, we should decide whether we want the user to provide the delta x that the lock time should be extended by (i.e. new lock time = old lock time + x) or if the user should provide the absolute lock time. I personally prefer the first option, since that is consistent with the fetch and lock API where the user also provides the time span. I think that is also what you intend to build.
  • We need unit tests for the External Task Service API. Have a look at ExternalTaskServiceTest for how the other methods of the ExternalTaskService are tested.
  • We need unit tests for the new REST API method. Have a look at ExternalTaskRestServiceInteractionTest for similar tests.

If you like, you can already create a pull request against the camunda master branch even if it is not done yet. That makes it easier to discuss/annotate concrete changes.

Feel free to ask for any clarifications.

Cheers,
Thorben


#3

Hi Thorben–

Thanks for the advice. The only reason I was trying to use a date instead of a delta was to test proof-of-concept. I was hoping that my current changes would allow me to provide a new timestamp and that would work. Then I could go figure out where to actually do my logic.

I originally tried to provide an extension in milliseconds to extend the date, but since I’m touching so many different files and I’m not sure how they relate (or where even to put the mathematical logic to extend the timestamp), I was getting all sorts of typing errors between int and Date. My goal was to just get a REST endpoint listening and working, which I got halfway there.

I’ve been trying to look at how fetchAndLock works (and another one I cannot remember off the top of my head that manipulates DueDate). Besides the advice your provided, are there any other files that I need to touch to complete this functionality, or did I pretty much find everyone? I will be looking more closely at your suggestions and my changes this evening.

I hadn’t started any any unit tests because I hadn’t gotten the functionality working yet, but would want to make sure those were in place before any type of pull request. However, I will open a pull request here shortly so those discussion can take place there.

Thank you!
Mike


#4

Hi @goyney,

You found all the places that you have to extend.

If you just want to override the lock time for a given task with an absolute date, just assign the date to the existing field lockExpirationTime, then it should work.

In plain Java, you can add to a java.util.Date like so:

Date givenDate = ...;
long millisecondsToAdd = ...;

givenDate = new Date(givenDate.getTime() + millisecondsToAdd);

Note that the delta should be of type long, not int.

I hope that helps.

There will also be some aspects of validation that we have to handle, but we can discuss that once we have the basic functionality in place and tested.

Cheers,
Thorben