Choreography diagrams were introduced with the release of Business Process Model and Notation (BPMN) 2.0 to model inter-organizational business processes, for example in the context of contractual agreements. They have, however, failed to attract a degree of tooling support comparable to their process and collaboration counterparts. With chor-js, we alleviate this de cit by providing a web-based, open-source choreography modeling framework based on bpmn-js. chor-js aims to be an extensible, intuitive and easy-to-integrate choreography diagram modeler faithful to the BPMN 2.0 standard and targeted at researchers and users alike.
In its second version, the BPMN standard was extended by choreography
diagrams [
In research, however, choreography diagrams emerge regularly, most recently
due to their utility in model-driven smart contract development for blockchain
applications [
With chor-js, we want to contribute to the modeling community by enabling
developers to properly implement choreography diagrams into their tooling and
research in a modern, easy-to-use and highly extensible fashion. To this end,
we extend the popular web-based, open-source bpmn-js1 process editor with
elements and features targeted at BPMN choreography diagrams. We aim at
1 https://github.com/bpmn-io/bpmn-js
a complete support of the BPMN choreography diagram standard, with novel
features carefully derived from our own experience of using and modeling
choreographies [
In this paper, we rst give an overview of chor-js (see Sect. 2). We then discuss the maturity of chor-js in Sect. 3, in which we also introduce the sample use case of a diagram validator. Lastly, we provide the necessary information to access, use and contribute to chor-js in Sect. 4. 2
Overview & Features chor-js is a web-based framework adapted to recent web browsers. Figure 1 shows the graphical user interface of our demo application. There are four principal components provided by the core chor-js library: (i) a left-hand side palette containing modeling tools and elements; (ii) a top palette providing a switching and renaming mechanism for managing multiple diagrams in one model; (iii) a context menu providing actions on the currently selected elements; and (iv) the editor itself lling the entire screen. Additionally, our demo application implements several extensions shown in a palette on the bottom left, exposing features like opening, saving or validating a diagram (v). Development and licensing information is given on the bottom right (vi).
In the scope of this paper, we can not highlight every feature provided by chor-js. Notable mentions include the many novel context actions tailored to speci c modeling elements. For example, participant bands can be freely moved (ii) Fig. 1. Screenshot of the chor-js demo application up and down; messages can be added, hidden or removed; and participants can be intuitively linked between call choreographies. Further, a prediction algorithm was devised which automatically populates new tasks with participants matching the context of the diagram, e.g., picking the correct initiator after merging several sequence ows. These features are mostly based on our own experience with other modeling tools, which are severely lacking in these functional aspects. 3
While chor-js is still in active development, it is already reasonably stable and in use for several student projects. In this section, we will rst shed light on the current level of standard coverage in comparison to other tools, and then provide an example for an extension towards a speci c use case. 3.1
chor-js already provides support for most elements of the BPMN 2.0 choreography diagram standard, with some still being work-in-progress: Table 1 shows a non-exhaustive overview as well as a comparison with four di erent existing modeling tools, namely Signavio, Eclipse BPMN2 Modeler, Visual Paradigm and Trisotech. A green checkmark implies full support for a feature, a yellow bullet hints at partial or broken support, while a red cross signi es missing support.
For space reasons, we can not go into detail on all of the assessments. To
give an example, we tested the tools' XML diagram interchange capabilities by
importing o cial example models provided by the Object Management Group
(OMG) [
As is apparent from the comparison, chor-js provides the most complete
choreography modeling experience to date | except for boundary events and
global choreography tasks, all elements are supported. This has di erent
reasons: Regarding the former, the metamodel de ned in the BPMN standard fails
to account for boundary events, making it impossible to connect them to
choreography tasks [
Global choreography tasks, on the other hand, are insu ciently speci ed in the standard, and their distinction from regular choreographies is unclear. During our extensive research regarding choreography diagrams, we have never encountered a single example of them in use. Additionally, chor-js does not yet support choreographies between collaborations, i.e., choreography diagrams between pools of a collaboration diagram. 3.2
One of the main contributions of chor-js is providing an extensible platform for projects using choreography diagrams as their conceptual basis in a modern, web-based fashion. To showcase these capabilities, we implemented a validator which provides basic validation capabilities for choreography diagrams based on the constraints posed in the BPMN 2.0 standard. The validator subscribes to the event bus of chor-js to receive updates and react accordingly.
Figure 2 shows an example of the validator feedback. The diagram models an ordering work ow which violates the simple ow constraint | the Shipper can not know when it is their turn to deliver the item since they were not part of the previous interactions. The error message hints at this, and users may resume to solve the issue, e.g., by adding and intermediate handover task.
In its current version, the validator checks for errors in the sequence
ow of choreography activities like in Fig. 2. Screenshot of the validator feedback the example above [3, Sec. 11.5.6], in- on an invalid diagram correct usage of event-based gateways [3, Sec. 11.7.2] as well as correct call choreography linking. Additionally, a few style recommendations are provided via warnings. These include, for example, a warning if participants used inside a sub-choreography do not have a corresponding band | which is actually the warning that is visible on the sub-choreography in Figure 2. 4
chor-js is implemented in JavaScript and has been tested with recent versions of the Mozilla Firefox, Google Chrome, and Apple Safari browsers. The project is maintained on GitHub and published through the npm package manager; see Table 2 for a collection of links. We further created a narrated screencast running through an example use case. A demo chor-js-demo showcasing the integration of chor-js in a Node.js application with additional features is provided as well. The demo application is updated regularly and deployed as a live version on our website. Instructions on how to set up chor-js and contribute to the project can be found in the respective repositories, among further documentation, tutorials and issue tracking that go beyond the scope of this paper. artifact
location chor-js main application: https://github.com/bptlab/chor-js npm package: https://www.npmjs.com/package/chor-js narrated screencast: https://www.youtube.com/watch?v=x1bZlFXRusI chor-js-demo application: https://github.com/bptlab/chor-js-demo live version: https://bpt-lab.org/chor-js-demo/