Start date filter for modify operation

[venetrius]

User Story (Required on creation)

When filtering for process instances to modify in cockpit modify workflow I want to be able to apply a filter to the startDate of the process instance.

Functional Requirements (Required before implementation)

API:

• A new incidentIdIn filter is available on historicProcessInstanceQuery
• A new activityIdIn filter is available on historicProcessInstanceQuery. It returns all non completed / deleted activity with an exception regarding :asyncBefore/asyncAfter and compensation. More about exception in this note
• executeModificationAsync command (/camunda/api/engine/engine/default/modification/executeAsync) accepts historicProcessInstanceQuery param to select instances

Client - Cockpit

Swap processInstanceQuery to historicProcessInstanceQuery in modify operation
Users can filter on startDate in process instance modify workflow.
All the existing filters are working
Saved filters are not shared between process instance modify workflow and other pages/workflows.

Breakdown

Add IncidentIdIn filter to HistoricProcessInstanceQuery

Java API

• add a new method incidentIdIn(String... incidentIds); to the HistoricProcessInstanceQuery API
• add a new field incidentIds with setter /getter to HistoricProcessInstanceQueryDto(impl)

SQL

incidentId is available in ACT_HI_INCIDENT the logic to join ACT_HI_INCIDENT is already present in HistoricProcessInstanceQuery and only needed to be updated with a check on the new field.

Code changes in `HistoricProcessInstance.xml`

-<if test="query != null &amp;&amp; (query.withIncidents || query.withRootIncidents || query.incidentStatus != null || query.incidentMessage != null || query.incidentMessageLike != null || query.incidentType != null>
+<if test="query != null &amp;&amp; (query.withIncidents || query.withRootIncidents || query.incidentStatus != null || query.incidentMessage != null || query.incidentMessageLike != null || query.incidentType != null || (incidentIds != null &amp;&amp; incidentIds.length > 0))">
    <bind name="INC_JOIN" value="true" />
</if>

...

+           <if test="query.incidentIds != null &amp;&amp; query.incidentIds.length > 0">
+              ${queryType} INC.ID_ IN
+              <foreach item="incidentIdItem" index="index" collection="query.incidentIds" open="(" separator="," close=")">
+                  #{incidentIdItem}
+              </foreach>
+            </if>

Swap processInstanceQuery to historicProcessInstanceQuery in modify operation

Update instancesList.js to use historicProcessInstanceQuery

Code changes

InstancesList.prototype.updatePage = function(resetSelection) {

...

-self.delegate.api
-  .resource('process-instance')
-  .list(params, function(err, result) {
-    self.delegate.instances = result;
-    self.delegate.applySelection();
-    checkLoading();
-  });
-
-self.delegate.api
-  .resource('process-instance')
-  .count(params, function(err, result) {
-    self.delegate.instancesCount = result.count;
-    checkLoading();
-  });
+  const HistoryResource = self.delegate.api.resource('history');
+HistoryResource.processInstance(params, function(err, result) {
+  self.delegate.instances = result;
+  self.delegate.applySelection();
+  checkLoading();
+});
+HistoryResource.processInstanceCount(params, function(err, result) {
+  self.delegate.instancesCount = result.count;
+  checkLoading();
+});

Filter out finished instances

In instancesList.js add unfinished = true filter to all modify instances query to only show runtime instance and not finished or canceled ones

Update keys in filter configuration

Keys, values and available operators are defined in instances-search-config.json
Keys are the filter names that are sent in a request, values are the labels that are visible for a customer.

Example:

Config for filtering by subprocess instance id

{
      "id": {
        "key": "subProcessInstanceId",
        "value": "PLGN_MOD_SEARCH_SUB_ID"
      },
      "operators": [
        {
          "key": "eq",
          "value": "="
        }
      ]
    },

What the users sees when filtering by subprocess instance id

Update the key for the filters and leave the values unchanged so the users don't have to re-learn the filter names.

Update local storage key used to save modify queries

Update the storage-group in modification-confirmation-dialog.html from "'PI'" to "'PIM'" (Process Instance Modification)

Limitations of Scope

Hints

Links

epic

Breakdown

Beta Give feedback

1. Add IncidentIdIn filter to HistoricProcessInstanceQuery #4587
   1 of 1
   type:subtask version:7.22.0 version:7.22.0-alpha6 +3
   
2. Cockpit - Swap processInstanceQuery to historicProcessInstanceQuery in modify operation #4588
   1 of 1
   type:subtask version:7.22.0 version:7.22.0-alpha6 +3
   
3. Cockpit: Update local storage key used to save modify queries #4589
   type:subtask version:7.22.0 version:7.22.0-alpha6 +3
   
4. Add activityIdIn filter to HistoricProcessInstanceQuery #4618
   1 of 1
   type:subtask version:7.22.0 version:7.22.0-alpha6 +3
   
5. Start date filter for modify operation - Documentation #4632
   type:subtask version:7.22.0 +2
   
6. Add historicProcessInstanceQuery param to executeModificationAsync #4620
   1 of 1
   type:subtask version:7.22.0 version:7.22.0-alpha6 +3
   

Pull Requests

Beta Give feedback

No tasks being tracked yet.

Dev2QA handover

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

[tasso94]

Decisions

Due to replacing the runtime with the history query, some behavioral changes occur:

1. Tokens sitting on an asyncBefore/asyncAfter task won't yield process instances with the activityIdIn filter since no history has been produced yet.
   • The user filtering always races against the job executor, leading to potentially frequent state state changes that impact what the query returns. Usually, the job executor is faster than a user can filter. The main use case of this filter is for real wait states like user tasks, external tasks, timers, etc., and not for transaction boundaries. We have already accepted this limitation for the standalone batch operation page. This feature alignes the behavior between token move and the standalone batch operation page.
2. When doing compensation, previously, it was possible to retrieve process instances with the activityIdIn filter on the subprocess "activity". This is an edge case and is not possible for all sub-process setups. We were only able to reproduce this for the compensation scenario. We accept this behavior change. The alternative way to do this, which we think is more common for most of the users, is to filter for concrete flow nodes and not for subprocesses.
   

[venetrius]

Dev2QA:

@gbetances089
There are 3 things to pay extra attention:

• activityIdIn filter has a few edge cases see comment
• In modify operation processInstanceQuery has been swapped to historicProcessInstanceQuery in modify operation. Only incidentIdIn & activityIdIn filters are newly added to the API but all filter options has been swapped to use the historic API.
• executeModificationAsync command (/camunda/api/engine/engine/default/modification/executeAsync) accepts historicProcessInstanceQuery param to select instances:
  -- executeModification can also be called with historicProcessInstanceQuery param, it might worth to have some test for that as well.
  -- Testing when Process Instances modifications are requested with a query

Screenshot

[gbetances089]

Tested on the 7.22.0 release candidate final