How I made BPMN and Bitbucket friends
Problem
Some of our teams use the notation BPMN to describe the business processes that we implement. A colleague of mine recently talked about how we came to use BPMN. We use the platform as an engine for executing business processes Camunda, the popularity of which, it seems to me, is due to several important factors:
- Great toolbox. This includes tools for modeling, monitoring, analysis of business processes.
- Excellent documentation, complete and detailed.
- The ability to fine-tune to fit your needs thanks to the huge number of settings for the runtime environment.
- The ability to expand the basic functionality through the implementation of their plugins.
- Community. Camunda developers organize conferences, meetups, write training video, lead thematic blogs, maintain dialogue on forum and, of course, put their code on Github…
And everything would be fine, but there is one significant problem. BPMN notation uses XML to describe all the steps, links and locations of all elements of the business process diagram. There are various visual design tools for BPMN diagrams. One of the most convenient – Camunda Modeler… Any change to the visual presentation will change the XML description. We in teams adhere to the practice of mandatory code reviews, which are carried out using Bitbucket tools as part of pull requests. But it is almost impossible to review changes in a large XML file that describes the visual presentation. I’ll try to illustrate the problem with the standard text file comparison that Bitbucket produces:
In this case, the comparison shows us that all the previous contents of the file have been deleted and completely new contents have been added. In fact, only a few elements in the diagram have changed, and the BPMN file has been additionally formatted.
Until now, we had to download two versions of a file (old and new) to the local machine, open them in the visual viewer and compare them manually. Very uncomfortable. And because of this approach, several bugs were already leaking into the production. The urgency of this problem grows along with the number of people and teams who use BPMN.
For a long time, the thought never left me that it was necessary to somehow make life easier for teams that had to manually compare schemes. And it would be nice to have a visual tool built into Bitbucket. I started looking into extending Bitbucket’s capabilities with plugins. I did not find anything suitable, but I came across this demo JavaScript library capabilities from Camunda developers. This is what you need! Asked about plans to develop a plugin for Bitbucket at forum I got a negative answer. Therefore, I had to collect my thoughts and make the plugin myself.
Developing a plugin for Bitbucket
When I started developing the plugin, I had no idea how to do this, so as a real developer, I first asked Google: “bitbucket plugin development”. Google returned a page first Beginner guide to Bitbucket Server plugin development… On this page, we learn that there are two versions of the product: Bitbucket Server and Bitbucket Cloud. We were interested in Bitbucket Server. Therefore, further steps will relate only to the development for it.
It should be noted that the Atlassian documentation has one peculiarity: the information is scattered across many different pages, loosely related to each other. It seems that as development progresses, new sections are added to the documentation, but the old ones are not revised. This approach makes it difficult to find the information you need. In addition, broken links are not uncommon. I tried to write reports about it, but the situation does not change.
In this article, I’ll try to save time for first-time Atlassian plugin development by pointing to the really important pages and sharing essential information.
The most important page is perhaps the page with installation instructions, a link to the template project, and instructions on how to run it: Getting started… A template project is a full-fledged project with a customized assembly, the necessary dependencies, examples of adding various extensions, etc. You just need to rename something according to the attached instructions, and you can add your own extensions.
There are two ways to add custom elements to the Bitbucket UI on the client side: Client Web Fragments and Client-side Extensions (aka CSE). The second method was introduced in Bitbucket Server 7 and is gradually replacing the first method. For now, CSEs are only available on pull request-related pages.
CSE includes five types of extensions: button, link, modal window, panel, page… All types are described on their respective pages with examples of use. To determine which page elements are expected to be expanded using CSE, just add ?clientside-extensions to the page URL. When you go to such a URL, suitable places will be highlighted with a special icon, by clicking on which you can find out:
- what types of extensions this element supports,
- the identifier of this place (it must be specified in the code of your extension),
- supported attributes and context (data that will be passed to the extension constructor).
Details can be found at page, but I recommend just experimenting with adding a parameter to the URLs of various pages in your Bitbucket.
I will not consider Client Web Fragments in detail, since I did not have to use this tool when implementing the plugin.
In addition to client-side extensions, the developer has a mechanism Plugin modules with a variety of functionality. For example, you can add your own resources (CSS, JS, etc.) and thus adapt the behavior and UI to your needs.
Difficulties
The first difficulty I encountered when trying to launch a templated project was that the extensions implemented in the project do not appear in the Bitbucket UI. An error was found in the start logs, which reported that the plugin did not start due to some kind of mismatch in the library version. After a long enough meditation, googling and researching the Bitbucket admin panel, the reason was found: the template project required the CSE processing library version 1.2.3. In this case, the version 1.0.0 library was installed on the server. To solve this problem, you need to modify the template project by adding the following snippet to the bitbucket-maven-plugin configuration:
<plugin>
<groupId>com.atlassian.maven.plugins</groupId>
<artifactId>bitbucket-maven-plugin</artifactId>
…
<configuration>
....
<pluginArtifacts>
<pluginArtifact>
<groupId>com.atlassian.plugins</groupId>
<artifactId>atlassian-clientside-extensions-page-bootstrapper</artifactId>
<version>1.2.3</version>
</pluginArtifact>
</pluginArtifacts>
</configuration>
</plugin>
Difficulty # 2. I needed to implement the following logic on the client side: retrieving two versions of the BPMN file content via the Bitbucket REST API, building a BPMN model, comparing, drawing and coloring the diagrams. Rendering and coloring requires the ability to add your own HTML code and include your own styles.
The only suitable place for the control to switch to the graphical schema comparison mode was the header of the comparison pane: it supports CSE and provides the necessary context (information about the project, repository, currently selected file for comparison, and revision numbers of two versions of the file). There are three types of extensions supported here: button, link and modal. The obvious solution was to use a modal window: in this case, the user would remain on the same page and would not lose context. However, when using the modal window, I ran into two problems:
- The modal window has several predefined sizes and you cannot specify an arbitrary size. In particular, you cannot draw a modal to fill the entire screen, which is desirable for drawing diagrams.
- Now there is no way to bind your resources to CSE extensions. Or I haven’t found such a way. You can try adding JS code and CSS classes inside the modal code (and I was even able to do that and render the diagrams), but the result is a completely unsupported piece of code that would be embarrassing to show people. Moreover, this does not solve the first problem.
Next, I tried using another type of CSE: page. Its use solves the first problem of the modal window, but does not solve the second: with the page, I also did not find an adequate way to connect my resources.
After suffering for a while, it occurred to me that Atlassian should have some kind of support, a forum for developers. Forum quickly showed up and I asked my question in the appropriate section: https://community.developer.atlassian.com/t/alternative-diff-view-plugin/43717… However, no response was received. And this is challenge # 3 that I faced: low activity from the community in general and from Atlassian in particular. 17 days after I asked the question, I myself posted the answer to it. At the same time, he answered the question of another developer in the next topic, who also waited 17 days.
In the end, I managed to solve my problem. I used the CSE button on the compare page, which opens a new tab with a page that draws a graphical comparison of the circuits. For a single page, I used Servlet plugin modulewhich supports connecting static resources. And for the connection itself, I applied Web Resource plugin module…
To use Servlet plugin module, you need to implement your servlet that generates the HTML code of the page. Obviously, the servlet should only serve content to authenticated users. But how can this be ensured? If you dig through the code examples on Atlassian resources, you can find the necessary code for Jira using its library, which is not suitable for Bitbucket. But this code suggests that Bitbucket should have a similar API (although I did not find a direct description in the documentation). After some searching, I found the library I needed:
<dependency>
<groupId>com.atlassian.bitbucket.server</groupId>
<artifactId>bitbucket-api</artifactId>
<version>${bitbucket.api.version}</version>
<scope>provided</scope>
</dependency>
This library has an AuthenticationContext class with the required isAuthenticated () method. The only thing left to do is to automate this class in the servlet class.
A similar problem with the template HTML generation library (in my case it is template Velocity). You need to connect the library:
<dependency>
<groupId>com.atlassian.templaterenderer</groupId>
<artifactId>atlassian-template-renderer-api</artifactId>
<version>${atr.version}</version>
<scope>provided</scope>
</dependency>
And then use it in the servlet:
templateRenderer.render(TEMPLATE_PATH, params, response.getWriter());Difficulty number 4 was that it is completely incomprehensible what kind of libraries you need to solve quite common problems. This is either not described in the documentation, or is somewhere very deep (correct me if I’m suddenly mistaken).
And the last tip. For experienced frontend developers, this will probably seem obvious, but I didn’t get to it right away. Use incognito mode in your browser to test your plugins. This will save you a lot of time and frustration, which would be spent looking for “strange” bugs.
Result
I got a plugin for Bitbucket Server version 7. The plugin adds a “BPMN Visual Diff” button to the header of the comparison panel:
The button is rendered only if a file with the extension is selected for comparison. .bpmn… This way, non-BPMN users won’t even notice the change.
By clicking on the button, a new tab opens, in which a visual comparison of the two versions of the scheme is made: you can see the deleted, added, changed elements. And for the changed elements, you can additionally see which attributes of these elements have changed and how. As a result, the absolutely useless comparison of text files, given as an example at the beginning of the article, turns into this visual comparison:
The plugin project source code is available at Github under the MIT license. Suggestions, criticism and pull requests are welcome. In the near future, we plan to adapt the plugin for Bitbucket Server version 6.
