search

mikitex70 / redmine_drawio

Macro plugin to embed draw.io diagrams into Redmine wiki pages
MIT License
125 stars 51 forks source link
diagram macros redmine

readme

Redmine draw.io plugin

draw.io is free online diagramming tool.

This plugin will allow embedding draw.io diagrams into Redmine wiki pages, issues descriptions and issue notes.

Redmine Drawio UI Default Redmine Drawio UI Default

A note

Before submit an issue please read carefully the README.md file (this page): many of those that seem defects are instead the expected behavior for the macros, so read it before you start using this plugin and whenever you find unusual behaviors.

Requirements

Installation

Configuration

Administration

The plugin can be configured by the Redmine administrator via the Redmine interface, Administration -> Plugins -> Redmine Drawio Plugin -> Configure.

In the configuration form you can set the Drawio server url; the default is //embed.diagrams.net, to use the default internet installation regardless of the protocol. The value can be changed to use a private drawio editor installation (see more later).

An important configuration is Enable SVG diagrams: diagrams in SVG format can introduce Cross-Site Scripting security issues, so from version 1.2.0 they are handled in a different way:

So the Redmine administrator is responsible to choose a security level adequate to the installation (Internet vs Intranet, for example), and the usage (how much important are hyperlinks?).

User Preferences

Each user can select a custom drawio UI. To do so, navigate to My account and scroll down the preferences box to choose the UI.


Drawio UI - Default
Drawio UI - Atlas
Drawio UI - Minimal
Drawio UI - Simple
Drawio UI - Sketch

For a detailed descriptions see https://www.drawio.com/blog/diagram-editor-theme.

Security

By configuring the header Content-Security-Policy in the Redmine webserver is possible to restrict what can be loaded in a web page. An example value is this:

default-src 'self'; script-src 'unsafe-inline' 'self' 'unsafe-eval'; connect-src 'self'; img-src 'self'; style-src 'unsafe-inline' 'self'

This setting is very restrictive: is allows loading scripts, stylesheets and images only from local server. This kind of setting is too restrictive for the redmine_drawio plugin, but can be relaxed a bit:

default-src 'self' embed.diagrams.net; script-src 'unsafe-inline' 'self' 'unsafe-eval' ; connect-src 'self'; img-src 'self' data: embed.diagrams.net; style-src 'unsafe-inline' 'self'

In this case we have relaxed the policy allowing to load scripts and images from embed.diagrams.net (the external site which serves the diagram editor). If security is an issue, you can use a local installation of the editor website (see the section Using a personal installation of draw.io), modifying the Content-Security-Policy header accordingly.

Another value added in the configuration above is the data: for the image-src policy: this allows to use inline embedded images, and is fundamental for the plugin to work as it is the way edited images are shown after editing without the need to reload the page.

An additional important configuration that may be present is the frame-src: it configures the policy for the use of iframes. The diagram editor is run in a iframe, so the setting must be relaxed to allow loading contents from embed.diagrams.net. Example (to be added in the Content-Security-Policy header):

frame-src: embed.diagrams.net 'self'; child-src: embed.diagrams.net 'self'

Usage

There are three macros that can be used to embed diagrams in wiki pages/issues; use what best fits your needs.

drawio macro

This macro is now deprecated and not working anymore. Use the drawio_attach macro as a direct replacement.

drawio_attach macro

This macro handles diagrams saved as attachments of issues or wiki pages.

The supported diagrams format are:

The xml format uses a Javascript viewer to render the diagram runtime. It maybe a bit slow, but adds navigation options to the diagram (zoom, page and layer selector).

With this macro the attachments are in PNG+XML, a special format consisting in an PNG image of the diagram plus the XML diagram source embeded as a field of the image.

With an.svg attachment name extension the image format is handled as SVG+XML; like the PNG+XML, this is an SVG image with an embedded XML source of the diagram (the diagram must be created with the draw.io editor, normal SVG are displayed but cannot be edited).

WARNING: SVG images can introduce XSS(Cross-Site Scripting) security issues. For internet deploys make sure the Enable SVG diagrams configuration options is unchecked, so the svg diagrams will rendered as a base64 encoded image (no XSS issues, same quality, but hyperlinks will not work).

From version 1.0.0 are also supported diagrams in XML format (as used with the old drawio macro).

Usage is very simple:

In the toolbar editor there is a button with icon drawio_attach icon that opens a dialog that can be used to insert a macro for a new diagram to be saved as attachment (for lazy people).

The dialog can be used also for modifying a macro: simply place the caret (the cursor in the editing area) somewhere in the body of the macro, click the corresponding button in the toolbar, and the dialog will open with fields pre-filled with values from the macro source. When confirming new values, the macro source will be updated.

drawio_dmsf macro

This macro handles diagrams saved in the DMSF repository as PNG+XML or SVG+XML images, or as XML documents (from version 1.0.0). The DMSF module must be enabled for the project to be able to use this macro.

Usage is very simple:

Like for the drawio_attach macro, in the toolbar editor there is a button with icon drawio_attach icon that opens a dialog that can be used to insert a macro for a new diagram to be saved as DMSF document.

As for the drawio_attach macro, the dialog can be used for updating a macro simply by positioning the editing cursor in the right place and clicking the button.

Diagrams in PDF export

Starting from version 1.4.2, diagrams are included in PDF exports.

There is a limitation: if the diagram is saved in a document managed by the DMSF plugin you need at least the 'v3.0.3' version of the plugin to make the export work. And this means that it only works starting with Redmine 5.

Some note on the drawio editor

Someone can be concerned about security in sending own diagrams to the draw.io site.

The diagrams aren't sent to draw.io for editing/rendering, but all the operations are done by the browser using only Javascript and HTML5. The only things loaded externally are the scripts and the editor page, when the diagram editor is opened. The diagram source remains local to browser/redmine site.

Using a personal installation of draw.io

If you like, you can configure this plugin to use your own installation of the draw.io site.

The build of the war file is a bit problematic because the drawio macro needs a script dynamically produced by the EmbedServlet2 servlet, which is deployed in the draw.io site but not built from the default sources.

This servlet is excluded from build because of a missing library from Google, maybe because of copyright issues.

If you are planning to use only the png and svg formats you can use the source as is without troubles, but if you want/need diagrams in the xml format it is necessary to apply the embed2js.patch patch (included in this plugin sources).

The build steps are:

git clone https://github.com/jgraph/draw.io.git
cd draw.io
patch -p1 < PATH_TO_DRAWIO_PLUGIN/embed2js.patch
cd etc/build
ant war
cd ../../build

If the build ends without errors, in the build directory you should find a working version of the war file that you can deploy in your favourite servlet container (like Tomcat); be sure to enable the HTTPS protocol because is is required.

Then enter your Redmine installation, go to Administration -> Plugins -> Redmine Drawio plugin, click on the Configure link and then specify your address for the draw.io site.

Local MathJax installation

The MathJax library is used to render mathematical symbols in SVG diagrams.

Once enabled from the Redmine Drawio plugin settings it is loaded from internet every time a wiki page is rendered.

This can be slow (it's a big library) and maybe not doable behind a proxy or without an internet connection.

However it is possible to use a local installation of the library following these steps:

  1. install the MathJax library locally (through zip, svn, git, npm, ecc.) in a web server; for detailed instructions see here
  2. go to Administration -> Plugins -> Redmine Drawio plugin, click on the Configure link and:
    1. select the SVG mathemathics support
    2. fill the MathJax library URL with the URL of the installation, for example //my.server/mathjax/MathJax.js

Once updated the settings, go to a wiki page with a mathematical SVG diagram and you should see the diagram exactly as before. You can check from where the library is downloaded using the browser developer tools.

Known issues

TODO

Contributing

Any code contribution is well accepted. There are only a few rules that I would like to be respected to easy merging: