Get Process Instance API to return Process Definition Key value in the API response

[Nandanrshenoy]

User Story

As a developer I would like to have the process definition key associated with a process instance API response
In the current day scenario to achieve this , I would need to first make a call to the Get Process Instance API(https://docs.camunda.org/rest/camunda-bpm-platform/7.21-SNAPSHOT/{url}/process-instance/{id}) through which the Definition ID can be retrieved and then subsequently make a call to the Get Process Definition API(https://docs.camunda.org/rest/camunda-bpm-platform/7.21-SNAPSHOT/{url}/process-definition/{id}) to retrieve the Process Definition Key.
Adding the PDK value in the Get Process Instance API response will avert making the additional call to Get Process Definition API

Functional Requirements (Required before implementation)

Get Process Instance API response is updated so that it returns the Process Definition Key.

Technical Requirements (Required before implementation)

Update the camunda rest API for Get Process Instance to accommodate the Process Definition key in its response https://docs.camunda.org/rest/camunda-bpm-platform/7.21-SNAPSHOT/{url}/process-instance/{id}

Limitations of Scope

Hints

Links

• Issue link in forum : https://forum.camunda.io/t/is-there-a-way-get-the-process-definition-key-by-processinstanceid/9066
• Camunda Rest API to be updated : https://docs.camunda.org/rest/camunda-bpm-platform/7.21-SNAPSHOT/{url}/process-instance/{id}

Breakdown

Pull requests

Preview Give feedback

1. Feature/git issue 4049 process instance api enhancement #4222
   +0
   
2. Fidelity contributions feature/git issue 4049 process instance api enhancement #4291
   ci:all-db ci:no-build ci:rest-api +3
   
3. Feature/git issue 4049 process instance pdk api enhancement #4792
   +0
   
4. feat: process instance pdk api enhancement #4847
   ci:all-db ci:default-build ci:migration ci:rest-api ci:rolling-update +5
   
5. revert(deps): revert accidental bump of a library #4895
   ci:spring-boot +1
   

Dev2QA handover

• Does this ticket need a QA test and the testing goals are not clear from the description? Add a Dev2QA handover comment

[Nandanrshenoy]

I will be involved in incorporating this feature.As such kindly request you to assign this ticket to me.

[yanavasileva]

Hi @Nandanrshenoy,

Thank you for raising this feature.

I will be involved in incorporating this feature.

Great to hear that, please don't forget to link the ticket to your pull request.
Hint from my side, the Java API will need updates as well. Let me know if I can support you during the process of providing the contribution.

As such kindly request you to assign this ticket to me.

The tickets are being processed by the team, no need for an action here.

Best,
Yana

[Nandanrshenoy]

Hi @yanavasileva ,
Thanks for your support and inputs.
I will definitely touch base with you in case I need some support while making this contribution.

Regards,
Nandan Shenoy

[Nandanrshenoy]

@yanavasileva ,Could you kindly assign this feature to me, as I have already started working on it.

Thanks and Regards,
Nandan Shenoy

[yanavasileva]

@Nandanrshenoy
Tickets cannot be assigned to someone outside of the team. For contributions, the pull requests are assigned to the author and reviewed by a team member. The reviewer is responsible to reflect the progress in the ticket status.
So no actions for you, just link the pull request to the ticket once you open it.

[Nandanrshenoy]

@yanavasileva ,The Initial analysis for the proposed code changes to accommodate Process definition key in Get API Process instance call has been summarized below. Kindly have a look and let me know if I am missing any detail.

Request Flow :
Rest Controller and service Implementation : The flow of request first starts from ProcessInstanceRestService which exposes the ProcessInstanceQuery interface as a REST service.
Package details : org.camunda.bpm.engine.rest
Module Name : camunda-engine-rest-core
Interface : ProcessInstanceRestService

Implementation Class : ProcessInstanceRestServiceImpl
Package Name : org.camunda.bpm.engine.rest.impl
Module Name : camunda-engine-rest-core

Code Changes : No code changes would be required at RestController and Service Implementation end.

Resource and ResourceImpl  : 
The call from the rest controller navigates to the resource interface represented by ProcessInstanceResource .The getProcessInstance() method with in the implementation class ProcessInstanceResourceImpl invokes the data mapping layer implemented through Mybatis.

Code changes: The ProcessInstance POJO class which is returned from the Data access layer , needs to have a place holder for the definitionKey.This in turn needs to be mapped to the ProcessInstanceDto for end user to retrieve this value.

DAO layer changes: MyBatis Entity and Data Mapper

The ProcessInstanceQuery interface class allows programmatic querying of Process Instances. In case of Get Process Instance API call based on instance ID, the ProcessInstanceQueryImpl class is only set with process instance ID as a query criteria.

The Mybatis Data mapper file which deals with various operations on Process instances and executions employs the ExecutionEntity class to respond to Get Process Instance API call.

Code changes:
Since the Definition Key is part of ACT_RE_PROCDEF and not present in ACT_RU_EXECUTION table , the mapper data file (Execution.xml) needs to be modified so that the definition key value is shared back along with the existing execution table details. The response of this execution which is of type "org.camunda.bpm.engine.impl.persistence.entity.ExecutionEntity" also needs to be modified to accommodate this additional information.

[yanavasileva]

@Nandanrshenoy, thank you for the detailed summary. On first read it the analysis look correct.
Let me double check the details before you start with the implementation.

[yanavasileva]

Hi @Nandanrshenoy,

Before continuing, I want to make sure you considered using the historic data.
If you have enabled the history via configuring the history level in your process engine (history level), it's possible to query for the historic process instance and its response contains the required process definition key, along with the PD id, name and version:
https://docs.camunda.org/rest/camunda-bpm-platform/7.20/#tag/Historic-Process-Instance/operation/getHistoricProcessInstance

Let me know if that will work for you, in that case we can avoid introducing the key in the runtime tables.

Best,
Yana

[Nandanrshenoy]

Hi @yanavasileva,

Thanks for your inputs.
Querying the history table will give us the process definition key but it’s known fact that calls targeted towards history tables comes with a price i.e performance issues.
If I am interested in only getting the active instances from client(both UI and system), then querying the history table for such active instances will be another additional API and time consuming as it houses both ACTIVE and COMPLETED instances. In our case, UI uses definition key as one of the filters on ACTIVE process instance grid.
In addition to this, we have some requirement where instances may or may not have history enabled where it becomes bottleneck to get the Process definition Key.
I totally understand that, there are filters which I can apply but that doesn’t take away the performance concerns related to when querying History tables.

On the other hand ,with the feature that we are implementing, we are no-where planning to introduce Process Definition Key field in the ACT_RU_EXEC table. The database schema doesn’t change. There is a join that already is happening between the ACT_RU_EXEC table and ACT_RE_PROCDEF when Get Process definition based on Process ID is being executed(Get Process List/Post process List uses the same sql) and we are planning to utilize this feature to just get that addition value of PDK programmatically. Kindly let us know your thoughts.

Thanks and Regards,
Nandan Shenoy

[yanavasileva]

Hi @Nandanrshenoy,

I agree with the performance concerns when querying the historic tables. I wanted only to lay out all of the possibilities to rule out the need of code change.

The change now is fully argumented, please continue with the contribution as planned. Please check the contribution guidelines: https://github.com/camunda/camunda-bpm-platform/blob/master/CONTRIBUTING.md

Best regards,
Yana

[yanavasileva]

I am closing the ticket due to inactivity.
We can reopen the ticket, once a pull request is raised on the topic.

[Nandanrshenoy]

@yanavasileva,
The PR against this feature will be raised soon.Thanks.

Regards,
Nandan Shenoy

[Nandanrshenoy]

@yanavasileva ,
The external PR has been raised.PFB the PR details.
#4222

Requesting your support to kindly review the PR.

Thanks and Regards,
Nandan Shenoy

[Nandanrshenoy]

@yanavasileva ,
Requesting your support to kindly review the PR.

Thanks and Regards,
Nandan Shenoy

[yanavasileva]

TODO:

• Create follow up ticket to investigate if we can simplify the selectProcessInstanceByQueryCriteriaSql and selectExecutionsByQueryCriteriaSql since the processDefinitionKey will be a column of the Execution table.
• #getProcessDefinitionKey() can be exposed to DelegateExecution

[Nandanrshenoy]

Thanks @yanavasileva for taking your time out and reviewing my code.
I have created follow up Task against GIT issue 4049 : #4848 and I will be involved in investigating the same.

On your second comment : #getProcessDefinitionKey() can be exposed to DelegateExecution .Is this the only change that you would need on my PR ? Do you want me to look in to this logic end to end .

Please share me any other comments so that I can take things along with this suggested change.Thanks.

[yanavasileva]

@Nandanrshenoy, I haven't completed the review yet and there might be more findings, I just started a list to mark potential improvements. I found a potential blocker for the PR so please wait with any further changes related to it. I will share more when I finish the code review.

#getProcessDefinitionKey() can be exposed to DelegateExecution

I see this as nice to have separate feature if there's interest.

[yanavasileva]

Dev2QA

• Env any setup with h2 and non-h2 database
• Have at least three process models
  • two simple process models and
  • a process with a start timer or condition or message
• Start few process instances
• Test via REST API GET/POST only for runtime data
  • filter for process instances via process definition key
  • filter for execution via process definition key
  • when requesting process instances (process) definitionKey is populated in the response

Docs

• PI: https://stage.docs.camunda.org/rest/camunda-bpm-platform/7.23-SNAPSHOT//#tag/Process-Instance/
• Execution: https://stage.docs.camunda.org/rest/camunda-bpm-platform/7.23-SNAPSHOT/#tag/Execution