A R package for visualizing process execution data on BPMN diagrams
Home Page: https://process-analytics.github.io/bpmn-visualization-R/
License: Apache License 2.0
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
covered by https://github.com/orgs/process-analytics/projects/1#card-69368800
We would like to link to a live environment that can showcase the usage of our package
The solution requires we can install our package and probably from CRAN (see #10)
To check
#27 (comment) shows that in the first implementation, if the parameter is not a list but a single overlay, the overlay is not displayed and we don't see any errors in the R console.
We could make the display function fails in that case or transform the parameter into a list.
Following the recommendation of this article: https://www.r-bloggers.com/2020/07/how-to-write-your-own-r-package-and-publish-it-on-cran
The package: https://github.com/mangothecat/goodpractice
bpmn-visualization already provides a CSS API but it requires the CSS styles are defined in the html page. Is this convenient for the R integration? the R package may not let R user to modify the underlying html page.
We may need bpmn-visualization to provide a new API that let style specific BPMN elements: process-analytics/bpmn-visualization-js#1030. This feature is available as of [email protected] which is bundled in bpmnVisualizationR 0.4.0.
Describe the bug
If we try to add an overlay to a non existing bpmn element, an error is displayed in the browser console and subsequent overlays are not added.
To Reproduce
Steps to reproduce the behavior:
Add several overlays, with one overlay relating to a non existing bpmn element id. The overlays in the list declared after the special one are not displayed.
bpmn_file <- system.file("examples/Email_Voting.bpmn", package = "bpmnVisualization")
# generate error in js binding file
overlays <- list(
bpmnVisualization::create_overlay("does_not_exist_bpmn_element_id_1", "42"),
bpmnVisualization::create_overlay("sub_process_1", "110") # id of an existing bpmn element, overlay not added
)
bpmnVisualization::display(bpmn_file, overlays)console error
Uncaught TypeError: Cannot read property 'bpmnSemantic' of undefined
at x.overlays.x.overlays.map.overlay (bpmnVisualization.js:33)
at Array.map (<anonymous>)
at Object.renderValue (bpmnVisualization.js:29)
at Object.renderValue (htmlwidgets.js:886)
at htmlwidgets.js:653
at Array.forEach (<anonymous>)
at forEach (htmlwidgets.js:55)
at htmlwidgets.js:576
at Array.forEach (<anonymous>)
at forEach (htmlwidgets.js:55)
JS binding code
const elementsByIds = bpmnVisualization.bpmnElementsRegistry.getElementsByIds(overlay.elementId);
if (elementsByIds) {
// this is line 33
const overlayConfig = elementsByIds[0].bpmnSemantic.isShape ? {Expected behavior
The overlay for existing bpmn elements should be added.
For non existing elements, we shouldn't have error. We may log a warning.
Additional context
commit: 600286d
bpmn-visualization: 0.19.0
It seems that in the elementsByIds array returned by bpmn-visualization, we have undefined elements.
Notice that the TS lib implementation is supposed to avoid undefined in the array: https://github.com/process-analytics/bpmn-visualization-js/blob/v0.19.0/src/component/registry/bpmn-elements-registry.ts#L75
We already have tests for this use case and more are added without showing any issue (process-analytics/bpmn-visualization-js#1507)
The getElementsByIds function is only needed here because we need to know if we have a shape or an edge to choose the arbitrary position of the overlay. This may not be needed anymore when implementing #15 if we let the user choose the overlay position or if we use the TS lib overlay default position.
We would like to update the js lib used by the R package when a new bpmn-visualization JS release is available.
If possible, automate the process. We do this for the examples repository with GitHub workflows.
Note: not exhaustive, add new ideas
Getting the js file
We use the min IIFE bundle, that can be retrieved from unpkg or jsdelivr (what we use in bpmn-visualization-examples).
It is available for download usage once the npm package has been published.
Triggering the workflow
We can do as for the bpmn-visualization-examples: on new git tag in bpmn-visualization, the existing workflow could trigger a workflow in bpmn-visualization-R by sending a repository dispatch. We need to pass the new version to use in the R package
It should also be possible to trigger the workflow manually with workflow_dispatch
Knowing that the file is available on npm
To wait for npm package availability, we could use the npm info command as done by bpmn-js: https://github.com/bpmn-io/bpmn-js/blob/v8.7.3/.github/workflows/POST_RELEASE.yml#L21
The wait check could be done in the R package repository as this is where we know that we need it.
But technically, this can also be done in the bpmn-visualization repository
If we decide to use htmlwidgets, see http://www.htmlwidgets.org/develop_intro.html#scaffolding for starting the integration
The activity rounded by a red circle and the following sequence flow don't have overlays
The image has been first created with the script described in #45.
Then, it was recreated in #72 with the same script but store as SVG. This involves manual work to make the label be displayed at the right position (manually migrate foreignObject to SVG text). The SVG was finally cleaned in #78 (no visual change).
The easiest way to fix the overlay is to try to update the SVG directly and also provide an updated version of the script that would also generate it. That way, next time we will regenerate it, no overlays will miss.
See also #157
Prerequisites: #10
Currently (v0.2.0), the release process explains that the source archive that is submitted to CRAN has to be built locally. This is a pain and error prone. So this should be automated instead
We could
workflow_dispatch (for manual rerun on issue)workflow_dispatch (for manual run)workflow_dispatch and when a new tag is publishedIs your feature request related to a problem? Please describe.
GitHub pages (#19) only host the documentation the development version. Web browsing of the package on CRAN only shows the documentation of the latest release.
This make hard to browse or check the documentation of past release
Describe the solution you'd like
When publishing a GH release or at least when the tag of a released version is pushed, attach the documentation as a release assets.
Additional context
The documentation generation and attachment to the release should be automated to avoid human errors.
This was done in the experimental package
Advantages: user can experiment the package out of the box, no need for external resources
Cons: larger package
If this is a common practice for R-package, let's do it. Otherwise, rethink about it.
And if we package examples
Decision
we could add
see
Generate and deploy the site with GitHub actions
Tasks
Currently (in v0.2.1), the announce to twitter and discord must be done manually.
The maintainers documentation provides a template, but this is painful and error prone
We could setup a workflow to publish on our name. It will be run on demand (workflow_dispatch) with some inputs:
Notes: we have the same needs for the bpmn-visualization TypeScript library, see process-analytics/bpmn-visualization-js#2341
From CRAN: #10
From GitHub for latest unreleased/development version or for alternative
See https://cynkra.github.io/dm/#installation for instance
https://www.rdocumentation.org/packages/remotes/versions/2.4.0/topics/install_github
We already do this in the bpmn-visualization repository and this saves us a lot of time.
In version 0.2.0, the package documentation file is not handled via roxygen2. This is inconsistent with other files and can lead to error.
It also prevent to address #30
Also review the content of this file
See https://roxygen2.r-lib.org/articles/rd-other.html#packages
Current baseline: A R package which embeds BPMN Visualization
It doesn't describe the purpose of the package. See also #1 (comment).
We will keep the ref to the bpmn-visualization-js integration.
Sources of inspiration
Tasks
Do it manually as a starting point.
Automate fix and check in #35
Note: this is supported by the experimental implementation
See http://www.htmlwidgets.org/develop_intro.html#r-binding
See #22 for documentation
For example, we can write something like in http://christophergandrud.github.io/networkD3/
We can also include some live rendering examples in the documentation via RMarkdown
See also #23 (comment) for a working example with our package
For a more user friendly documentation, we should provide HTML documentation and publish it (#19)
This could include
Also include the following feedback from #128
See also #30
Notes: next improvements will start with #161
Initial proposal is bpmnVisualization in #21 --> we will keep this name (lowerCamelCase)
Resources
we decide to use
. (like Google R style)Ressources
DoSomethingCurrently (in v0.2.1), the version must be updated prior and after releasing (by creating a PR). This is painful and error prone
The git tag is created only when the GitHub release is published.
I suggest we do something like for the bpmn-visualization TypeScript library.
We provide a GitHub workflow that will do everything for us:
If possible, the development version should be automatically computed by the workflow to avoid human error
Also update the GitHub workflow introduced by #25
See https://r-pkgs.org/tests.html and https://r-pkgs.org/r-cmd-check.html#tests-1
For coverage, see
For now, we have to manage formatting manually. In RStudio, select the file content and then do Ctrl + Shift + A
See this article for general guidelines: https://blog.r-hub.io/2022/03/21/code-style/
For formatting rules
tooling candidates
IDE extension supporting autoformating
You're one step away of starting your contribution and becoming our HacktoberHero 😍
Before you start, check out our article and please follow these rules:
Following the recommendation of this article: https://www.r-bloggers.com/2020/07/how-to-write-your-own-r-package-and-publish-it-on-cran
The package: https://github.com/jumpingrivers/inteRgrate
Add a new job who execute the command devtools::document(), and commit the change in the current PR if there is updating in the documentation.
See also #30
Seen while attempting to release version 0.2.2.
Workaround: follow the manual procedure
Workflow runs: https://github.com/process-analytics/bpmn-visualization-R/actions/runs/3533388259
3 attempts, all failed. The last one was run in debug mode, no additional information
Action configuration
Run benjefferies/[email protected]
with:
access_token: ***
enforce_admins: true
branch: main
retries: 5
Error stack
Getting branch protection settings for process-analytics/bpmn-visualization-R
Traceback (most recent call last):
File "/bin/run.py", line 83, in <module>
toggle_enforce_admin(p.parse_args())
File "/bin/run.py", line 22, in toggle_enforce_admin
protection = get_protection(access_token, branch_name, owner, repo_name)
File "/bin/run.py", line 61, in get_protection
protection = branch.protection()
File "/pyroot/lib/python3.7/site-packages/github3/decorators.py", line 31, in auth_wrapper
return func(self, *args, **kwargs)
File "/pyroot/lib/python3.7/site-packages/github3/repos/branch.py", line 73, in protection
json = self._json(resp, 200)
File "/pyroot/lib/python3.7/site-packages/github3/models.py", line 157, in _json
raise exceptions.error_for(response)
github3.exceptions.NotFoundError: 404 Not Found
Generate a sticker with the "Process Analytics" SVG logo. See https://github.com/GuangchuangYu/hexSticker
See #26 (comment)
The man folder contains only generated files except bpmnVisualization-package.Rd
This file could be generated as done in https://github.com/bergant/bpmn/blob/9768cccc551831846a6d404271e330d710c8ef3b/R/bpmn.R#L1 (add roxygen comments on a NULL statement)
We will probably use Roxygen2 that generates the Rmd files from documentation as R comments located in the source code (see https://kbroman.org/pkg_primer/pages/docs.html and https://r-pkgs.org/man.html)
Once roxygen2 is installed, documentation can be generated by calling devtools::document()
See also https://github.com/r-lib/roxygen2
The NAMESPACE file is also generated
To avoid roxygen2 warning roxygen2 requires Encoding: UTF-8
Add Encoding: UTF-8 to the DESCRIPTION file --> done in #49
For contributors, document RStudio configuration to be setup to avoid running doc generation when changing the code
The following in the default configuration. Some files aren't generated if the config is left unchanged.
When the R package is mature enough, update the experimental repository
The GH_TOKEN available in this repository as readonly permissions by default. If more permissions are required, they need to be configured in the workflow definition.
Rationale
This is something we want to put in place for all repositories of the organization
As a good security practice, you should always make sure that actions only have the minimum access they require by limiting the permissions granted to the GITHUB_TOKEN
Source: GitHub documentation
Is your feature request related to a problem? Please describe.
The default overlays colors in v0.1.1 are defined in the rgba form. Please use hexa color form.
Describe the solution you'd like
We generally use the hexa forms in the lib examples.
The rgba currently used in the js bridge code is not well supported in Inkscape: this was an issue when we exported the SVG generated in the R View and edit it in this software. See #72.
Additional context
See https://github.com/process-analytics/bpmn-visualization-R/blob/v0.1.1/inst/htmlwidgets/bpmnVisualization.js#L42.
Currently (in v0.2.1), the version must be updated prior and after releasing (by creating a PR). This is painful and error prone
The git tag is created only when the GitHub release is published.
I suggest we do something like for the bpmn-visualization TypeScript library.
We provide a GitHub workflow that will do everything for us:
If possible, the development version should be automatically computed by the workflow to avoid human error
Add a Github workflow triggered by workflow_dispatch (manual run)
Documentation
We could do something like we have in the bpmn-visualization-js repository (send slack message when the npm package is published).
We need to decide after which step we send the message here.
We currently reference the experimental poc:
https://process-analytics.dev/#libraries
Once we have a first version, we should reference this repository instead.
In version 0.1.1, it is hard coded and cannot be changed. We set a specific style depending if the BPMN element is a edge/flow or a shape.
Currently, in the Dependencies update section of the release notes, we display the changes that apply to all types of dependencies. They include bump of development dependencies and GitHub Actions.
Most of the time, we only have updates for this kind of dependencies and we have plenty of them.
Thus, it is difficult to see that a runtime dependency has changed and, in its current form, the Update Dependencies section is not useful to library users.
It is the same issue as process-analytics/bpmn-visualization-js#2208.
| Version | Current list | Useful list for users |
|---|---|---|
| pending v0.1.3 |  |
 |
It is the same as process-analytics/bpmn-visualization-js#2208 but here the process is simpler.
Dependabot only updates GitHub Actions: it can set the skip-changelog label and we won't have to do post-processing.
The bpm-visualization JS lib is updated by a PR created by a workflow we own, and other dependencies are updated with PR created by contributors.
Recently, we introduced a shared configuration for release-drafter: see process-analytics/.github#14 and process-analytics/github-actions-playground#132.
It can be used in this repository as the release-notes layout will be exactly the same as the one defined in the shared configuration.
Make the coverage results public. Codecov supports the R language and it widely used.
According to #117, coverage is 100% 💪🏿
Resources
We use SonarCloud for the bpmn-visualization TypeScript library, so why using a new tool/services?
Today (2022-10-26), SonarQube doesn't support the R language. See https://docs.sonarqube.org/latest/analysis/languages/overview/
This is the first implementation to match the experimental implementation: Pass the bpmn element id and the label to display
The position, font settings, ... are hard coded by the package.
More options will be provided later, see #15
In version 0.1.1, it is hard coded and cannot be changed. We set a specific position depending if the BPMN element is a edge/flow or a shape.
Find an image/gif that represents what the package can achieve.
https://cran.r-project.org/
This let users consume our package easily
Release how-to: see https://r-pkgs.org/release.html and https://www.r-bloggers.com/2020/07/how-to-write-your-own-r-package-and-publish-it-on-cran
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.