[FEAT] Allow to only show one or a set of pools at diagram load time

[NathalieC]

Let pass a list of ids and/or names related to the participant in the BPMN semantic related to the pool(s) that will be displayed.

Discussions in progress. We should define the API and the best way to manage it internally.

Note: the original request was different, we decided to reduce the scope of the feature

By default, the library displays the bpmn file, meaning, all diagrams and pools defined in the file.
By configuration, the developer integrating the library (Fred) could define that it only displays one pool, whose id will be passed as a parameter.
By configuration, Fred could also define that it displays a pool and all its called processes (provided they are in the same diagram). Again, he will use parameters to pass the pools' ids to the lib.
In the implementation example, we should be able to show that:

• if the pool id passed as a parameter is a called process, Fred can implement a "navigation up", to the calling pool.
• if the pool id passed as a parameter is a process with call activities, Fred can implement a "navigation down" to the called process
• if both, then Fred could implement both navigations.

Linked to #422

[tbouffard]

mxgraph resources
mxGraph example that hide some elements that exist in the model
https://jgraph.github.io/mxgraph/javascript/examples/layers.html and https://github.com/jgraph/mxgraph2/blob/mxgraph-4_2_0/javascript/examples/layers.html

We tried to make pool parent of lanes and lane parent of other bpmn elements. So making pool not visible in the mxgraph model should hide the children BPMN elements.
Alternative: after load, filter elements that are stored in the mxgraph model. Less elements in the mxgraph model. --> to be investigated

[tbouffard]

In January, we have provided an example using mxgraph custom code that let hide or collapsed pools.
See process-analytics/bpmn-visualization-examples#124 for screenshots.

[csouchet]

As discussed during the POC #2020, option of the filter may look like this:

export interface ModelFilter {
    pools?: {
      ids?: string | string[];
      names?: string | string[];
    };
  };
}

[tbouffard]

Experimentation completed
We have done 2 pocs:

• [POC] Add hierarchy in the internal model  #2020: too early to switch to a new model, we will implement improvements and fixes detected during this poc, see [POC] Add hierarchy in the internal model  #2020 (comment)
• [POC] Filter by pool on load #2025

Conclusions to be written

[tbouffard]

Implementation proposal

Done with @csouchet based on the experience gained during the 2 POC.
For review, please fill a comment if you have questions or see something wrong.

API definition

// updated LoadOptions definition
interface LoadOptions {
  fit?: FitOptions;
  // new property
  modelFilter?: ModelFilter;
}

interface ModelFilter {
  pools?: PoolFilter | PoolFilter[];
}

interface PoolFilter {
  id?: string;
  name?: string;
}

Note about the usage of the pool wording

According to the BPMN Specification,

A Pool is the graphical representation of a Participant in a Collaboration

We have decided to keep the Pool wording instead of Participant because

• the action of the load method is to render the BPMN diagram
• we also use Pool to characterize the element with it ShapeBpmnElementKind
• we never use publicly Participant elsewhere in the library, whereas we do for Pool

However, when filtering by id, we are expecting the id of the Participant, no the id of the pool Shape in the BPMNDiagram. This is consistent with the ids expected in the BpmnElementsRegistry.getElementsByIds method. Generally speaking, when mentioning ids in bpmn-visualization, they always reference id from the BPMN Semantic, not id from the BPMNDiagram (the graphical representation).
We will insist on this point in the API documentation.

Example of use of the API

In the following, diagram is storing the BPMN content.

bpmnVisualization.load(diagram, {
  modelFilter: {
    // A Pool is the graphical representation of a Participant in a Collaboration.
    pools: [
      {
        /** id of the Participant related to the Pool to display */
        id: 'id1'
      },
      {
        /**
         * Name of the Participant, or name of the Process referenced by the Participant
         * when the Participant doesn't have a name.
         * This is how bpmn-visualization built the name in its internal model.
         **/
        name: 'name2'
      },
      {
        id: 'id3',
        /** in this case, we use the id, not the name*/
        name: 'name3'
      }]
  },
});

Filter a single pool by id

bpmnVisualization.load(diagram, {
  modelFilter: {
    pools: {id: 'id1'},
  },
});

Filter several pools by name only

bpmnVisualization.load(diagram, {
  modelFilter: {
    pools: [
      {name: 'name1'},
      {name: 'name2'},
      {name: 'name3'},
    ],
  },
});

Filter with other load options

bpmnVisualization.load(diagram, {
  fit: {
    type: FitType.Center,
    margin: 20,
  },
  modelFilter: {
    pools: [
      {id: 'id1'},
      {name: 'name2',},
    ],
  },
});

For the future, when implementing diagram filter, see #729

bpmnVisualization.load(diagram, {
  modelFilter: {
    diagram: {
      index: 0,
      // or one of the following option
      // id: 'id1',
    },
    pools: [
      {id: 'id1'},
      {name: 'name2',},
      {id: 'id2'},
    ],
  },
});

Behavior

The filtering looks for pools that match id or names passed as parameter.
It returns

• the matching pools and all elements within the matching pools.
• at most as many pool elements as defined in the pools filter property.
  • If there is no matching pool for a given id or name, the parameter is ignored. In other words, there is no strict control of the id or name, the method silently ignores them in this case.
  • [UPDATE] in the future, when we will implement [FEAT] Manage BPMN input source parsing warnings/errors #35, the load method will provide the list of encountered errors and warnings. Then, we will be able to return the filter warnings, for instance "ignored pool ids and names".

Error cases
In case there is no matching pool at all, the load method throws an Error including a convenient message. Throwing Error is the same behavior as for parsing issues. We prefer this behavior to rendering an empty diagram: the user wouldn't have known the cause of the problem.
Doing a pool filtering on a BPMN diagram without process/participant will always throw an error as there is no match.

[UPDATE]
In the future, after implementing #35, we will not throw error anymore but make the Error available in a dedicated way.
This will make the management of errors and warnings consistent.

Special cases
In the first implementation, we won't include in the filtered results

• group defined in a collaboration: they are not attached to a participant. We could check the graphical boundaries of the group and check they are within the boundaries of the pool.
• lanes of sub-processes finally, we will support it

If there is a need for these, please fill an issue

Tests

Use #2025 as base for tests and add at least the following tests. The POC includes a lot of TODO about tests to add.

visual tests

• add a expanded call activity in a new pool
  • We can add a new pool including the call activity in the diagram used in the POC
  • Notice there is an issue about this topic [BUG] Elements of an expanded Call Activity are not linked to the Call Activity  #2036: the elements of the call activity won't be rendered until the issue is fixed

unit tests

• group in a process
• lanes of lanes
• expanded call activities
• cross id/name tests: request the same pool twice by id and name. We should get only one instance of the pool

[jeromecambon]

I'm wondering why you silently igore an id or name that does not match?
We may miss a pool which would not be displayed without any error.

[tbouffard]

I'm wondering why you silently igore an id or name that does not match?
We may miss a pool which would not be displayed without any error.

Yes, we are aware of this. We consider it as a warning instead of an error.
We currently don't have a way to provide the filter warnings but we planned to do it in the future. So for now, the information will be hidden.
I have updated the description with more details (and mark the related section with an [UPDATE] tag).

In the future, we may also provide an option to ensure all pool ids/names match.
What we want here is a first implementation that works in most cases, then we will be able to improve it if required by users.