CMMN TimerEvent implementation.

[Subhrajyoti Moitra]

Hello Team,

We are interested in implementing TimerEvent in CMMN specification.

Can someone please do us some hand holding about how we can do it?
Is there any design/implementation thoughts on implementing TimerEvent in CMMN.
Does it follow the similar flow as with the BPMN timer events?
Cant we use the existing Job framework, to also accommodate the CMMN TimerEvents.

BPMN and CMMN timer events are very similar- is this understanding grossly wrong?

Please guide us.

Thanks,
Subhro.

[Roman Smirnov]

Hi Subhro,

The CMMN timer event listeners are not implemented yet. There are currently no plans to implement it.

What is your use case for timer event listeners?

Cheers,

Roman

[Subhrajyoti Moitra]

Thanks Roman for replying.

We have a number of tasks that occur after a specified period of time, something like scheduling along with some logical condition.


Example:
We have a Process task "Schedule Dialer Call", this can be scheduled manually, as well as based on some time computation, during the life cycle of our case. Also this task is "repetitive" since, this can be valid multiple number of times.
Some more use cases:
- During "Return by Customer", we wait for the customer to provide us the AWB Number of the packet for 15 days, non-receipt of the data from the customer within this time, would lead to case closure.
- Also we wait a lot of places in our process for stipulated time, like 5 days, 3 days etc. like waiting for courier to send us an update on the case, until we take a default action on our own.

Also, currently in BPMN timer events, we cant set the time using an API, its to be hardcoded in the BPMN definitions, someway to work around this and dynamic ability to set the timer data would be great.


Please let me know, if we can help with this implementation.

Thanks,
Subhro.

[Roman Smirnov]

Hi Subhro,

Would you like to provide a pull request?

Cheers,

Roman

[Subhrajyoti Moitra]

Hello Roman,

Following the lead from the earlier email, I have added the class TimerEventListenerItemHandler, and registered it in DefaultCmmnElementHandlerRegistry.java,

Do I have to also create a new ActivityBehavior or we use the EventListenerActivityBehavior class?
What happens to the EventListenerItemHandler and the corresponding registration (which is currently commented in the code).
Which test cases I am to use to test this?

Sorry for so many questions, Please guide.

Thanks,
Subhro.

[Roman Smirnov]

Hi Subhro,

Do I have to also create a new ActivityBehavior or we use the EventListenerActivityBehavior class?

Yes, you have to create a new ActivityBehavior. I would call it "TimerEventListenerActivityBehavior", which extends the EventListenerActivityBehavior. In the first increment of the implementation the TimerEventListenerActivityBehavior should not do anything.

 

What happens to the EventListenerItemHandler and the corresponding registration (which is currently commented in the code).

It is okay, when it stays as commented in the code. It should not be necessary to add to the registration.

 

Which test cases I am to use to test this?

 

There should be some test cases, which test that the timer event listener activity has been parsed and added to the internal case definition correctly. This can be done like in this test case: https://github.com/camunda/camunda-bpm-platform/blob/master/engine/src/test/java/org/camunda/bpm/engine/test/cmmn/handler/HumanTaskPlanItemHandlerTest.java

Does it help you?

Cheers,

Roman

[Subhrajyoti Moitra]

Hello Roman,

I have implemented the TimerEventListenerActivityBehavior as u have described.
Added a new test case TimeEventListenerItemHandlerTest and doing the basic tests like name, description, with/without parent. etc.
I have also added a timer expression test and startTrigger test, but not able to work it out.

@Test
public void testTimerExpression(){
    //create a timer expression;
    TimerExpression timerExprElement = createElement(timerEventListener, TimerExpression.class);
    timerExprElement.setText("aTest");
    Cmmn.validateModel(modelInstance);

    CmmnActivity newActivity = timerEventListenerItemHandler.handleElement(planItem, context);
    CmmnActivityBehavior timerEventActBehavior = newActivity.getActivityBehavior();
    /*Expression tmrExpr=timerEventActBehavior.getTimerDef().getTimerExpression();
    assertEquals(timerExprElement.getText(),tmrExpr.getText());*/
}

Do we also add a EventListenerDefinition, like there is a TaskDefinition assosciated with HumantTaskActivityBehavior and getting populated from the HumanTaskItemHandler?

Also, I dont see any testcase for the ActivityBehavior classes, how do I test these? Do i test using a complete deployment like below?

public class TimerEventListenerTest extends CmmnProcessEngineTestCase {
    @Deployment(resources = {"org/camunda/bpm/engine/test/cmmn/eventlistener/TimerEventListenerTest.testTimerEvents.cmmn"})
    public void testTimerEvents() throws Exception {
        Date date = new SimpleDateFormat("dd-MM-yyyy hh:mm:ss").parse("01-01-2015 12:10:00");
        Map<String, Object> variables = new HashMap<String, Object>();
        variables.put("timerVariable", date);

        String caseInstanceId = caseService.createCaseInstanceByKey("SampleCaseTimerEvent_1", variables).getId();
        List<CaseInstance> caseInstList = caseService.createCaseInstanceQuery().caseInstanceId(caseInstanceId).list();
        List<CaseExecution> caseExeList = caseService.createCaseExecutionQuery().caseInstanceId(caseInstanceId).list();
        //what goes here?
    }
}

I have added the mentioned cmmn file.

I understand that ItemHandlers populates the behavior classes with camunda application data model of cmmn. Also i could trace that the behavior methods are called from some Command Objects. But I could not get the TimerActivityBehavior.created method to execute?
Please guide.


Thanks a lot for your time.

Subhro.

[Roman Smirnov]

Hi Subhro,

In the first increment of the implementation it is not necessary to test the behavior, because you did not implement it yet. The first increment is about to transform the timer event listener into the internal engine model. If you finished that first increment, then please provide the first pull request for this.

The next step would be the implementation of the behavior of the timer event listener. In that next step we can think about, how to implement the behavior and what is needed for that.

Thanks for your effort!

Cheers,

Roman

[Subhrajyoti Moitra]

Hello Roman,

I am sort of stuck again, please help!!

I have created a new TimerEventListenerJobDeclaration class. This extends TimerDeclarationImpl class.
I do this in TimerEventListenerItemHandler. Below is the code snippet:

@Override
  protected void initializeActivity(CmmnElement element, CmmnActivity activity, CmmnHandlerContext context) {
    super.initializeActivity(element, activity, context);
    initializeTimerEventListenerJobDeclaration(element, activity, context);
  }

  private void initializeTimerEventListenerJobDeclaration(CmmnElement element, CmmnActivity activity, CmmnHandlerContext context) {
    JobDeclaration timerEventListenerJobDeclaration=parseTimerExpression(element,context);
    activity.setProperty(ItemHandler.PROPERTY_TIMERVEVENTLISTENER_JOBDECLARATION,timerEventListenerJobDeclaration);
  }

  private JobDeclaration parseTimerExpression(CmmnElement element, CmmnHandlerContext context) {
    TimerEventListener elemDef = (TimerEventListener) super.getDefinition(element);

    TimerExpression exp = elemDef.getTimerExpression();
    String expText = exp.getText();
    StartTrigger start = elemDef.getTimerStart();

    Expression expression = context.getExpressionManager().createExpression(expText);
    //TODO get the type from the camunda extensions in XML?
    TimerDeclarationType type = TimerDeclarationType.DATE;
    //TODO get the job type handler extending TimerEventJobHandler?
    String jobHandlerType= TimerEventListenerJobHandler.TYPE;
    TimerEventListenerJobDeclaration timerDeclaration=new TimerEventListenerJobDeclaration(expression,type,jobHandlerType);
    return timerDeclaration;
  }

This requires a "type" values of which are either "Date" or "Duration" or "Cycle".
This means in the CMMN1.1 TimerEventListener xml, I have to add new camunda extensions to also get this "type" from the user?
Also the timerhandler should be a new TimerEventListenerJobHandler extends TimerEventJobHandler?
Please guide on this.

I have incorporated all the changes from the earlier code review.

Thanks a lot for your time and patience,
Cheers.
Subhro.

[Roman Smirnov]

Hi Subhro,

The CMMN 1.1 specification says the following regarding the timerExpression:

An optional expression that MUST evaluate to an ISO-8601 conforming reprresentation for date and time, duration, or interval representations.

Further information about ISO-8601 can be find for example here [1].

In the CMMN 1.1 the repeating interval is specified as follows:

However, for a TimerEventListener repetition can be defined via a timerExpression based on ISO-8601, by defining repeating intervals in it (using “R<n>/” notation).

Instead of introducing a new extension attribute, we should do it in the first step as following:

1) If the timerExpression begins with a "R", then the timer declaration type is TimerDeclarationType.Cycle

2) If the timerExpression begins with a "P", then the timer declaration type is TimerDeclarationType.Duration

3) Otherwise it the timer declaration type is TimerDeclarationType.Date

The current limitation would be that the following timer expression could not be used

1) Cron jobs: 0 0/5 * * * ?

2) intervals like 2016-01-.../2016-03-....

3) expressions like ${anyExpressionToResolve}

We can have a look at the limitations later.

Does it make sense to you?

Cheers,

Roman

[1]: https://en.wikipedia.org/wiki/ISO_8601

[Subhrajyoti Moitra]

Hi Roman,
I have done as u have described above.
Let me know the next steps.

Thanks,
Subhro.

[Roman Smirnov]

Hi Subhro,

Great! I would say that you should update your pull request with your changes first. So that I could have a look into it. Would be that okay for you?

[Subhrajyoti Moitra]

Hello Roman,
Just updated the pull request. Please let me know what more changes are required.

Thanks and cheers,
Subhro.