mscgen-logo2.png

According to the official MscGen website

Mscgen is a small program that parses Message Sequence Chart descriptions and produces PNG, SVG, EPS or server side image maps (ismaps) as the output. Message Sequence Charts (MSCs) are a way of representing entities and interactions over some time period and are often used in combination with SDL. MSCs are popular in Telecoms to specify how protocols operate although MSCs need not be complicated to create or use. Mscgen aims to provide a simple text language that is clear to create, edit and understand, which can also be transformed into common image formats for display or printing.

As we all know, diagrams are an invaluable addition to any documentation produced. They communicate a lot of information quickly, in an easy to understand form. This is especially important in situations when you need to quickly provide a clear and meaningful visualization to any vague communication between entities. If you stick to the regular usage of MSCGen program to compile your MSCGen code and then manually attaching the generated MSCs to your documentation, you will be wasting a lot of valuable time and effort in completing your documentation.

The MSCGen add-on from Addteq comes to the rescue and brings the simplicity and usefulness of Message Sequence Charts right to your Confluence Server. The amount of time and effort it saves you is apparent as soon as you start using it.  

Here is an example of an MSC depicting a simple call flow between two entities during the exchange of some standard Session Initiation Protocol (SIP) messages. The simple and self-explanatory MSCGen code used to generate this MSC is shown on the left side.

 

# Simple Call Flow
msc {
  E1, E2;
  E1->E2 [label="INVITE"];
  E1<-E2 [label="100 Trying"];
  E1<-E2 [label="180 Ringing"];
  ---      [label="the client plays ringing"];
  E1<-E2 [label="200 Ok"];
  E1->E2 [label="ACK"];
  ...;
  ---      [label="the client hangs up"];
  E1<-E2 [label="BYE"];
  E1<-E2 [label="200 Ok"];
}

 

 

 

mscgen1.png

What is MscGen for Confluence?

MSCGen is an add-on developed by Addteq to provide the ability to the teams using Confluence to readily create, edit, or share MscGen charts through Confluence through an easy to use interface. 

By simply adding this plugin, users can begin writing MSCGen code into Confluence documents that will be rendered into the corresponding message sequence charts in .png format. To add to it's usability, the plugin even indicates to the user if there has been a syntax error in their code. It even directs the user to the exact line where the error was detected.

Learn More about MSCGen for Confluence

 

How to install and configure "mscgen" executable for MscGen for Confluence Server?

After installing the MSCGen for Confluence add-on from the Atlassian Marketplace, you need to install and configure "mscgen" executable in your OS to make the add-on work. The instructions to install the executable, depends on the OS distribution and version you are using. The instructions to install the "mscgen" executable on Ubuntu and CentOS can be found below:

 

Ubuntu (Debian)

If you are using Ubuntu or Debian, then you should be able to install "mscgen" executable using the below command:

$ sudo apt-get update && sudo apt-get install -y mscgen

 

After you install it, you can find the path of your "mscgen" executable (e.g. /usr/bin/mscgen) using the below command:

$ which mscgen

 

CentOS (RedHat)

If you are using CentOS or RedHat, then you should be able to install "mscgen" executable using the below steps:

  1. Download the static binary version of mscgen on your OS.
  2. Extract the downloaded binary using the below commands:

    $ tar xzvf mscgen-static-0.20.tar.gz
  3.  After you extract it, you will find the "mscgen" executable in the "bin" subdirectory (i.e. mscgen-0.20/bin/mscgen).

 

To configure "mscgen" executable in your MSCGen add-on configuration:

  1. Login to your Confluence Server as a user with administrative privileges.
  2. Go to "Add-ons" under Confluence Administration.
  3. Provide an absolute path to the "mscgen" executable on your OS and save the plugin configuration.
    mscgen2.png
     

 

How does MSCGen for Confluence works?

Using MSCGen for Confluence is very easy. First, add an MSCGen macro in Confluence.

mscgen1.gif


Then click inside it to open the MSCGen editor which has an intuitive interface. The left side of the MSCGen editor is used to insert or edit your MSCGen code and the right side displays the generated MSC when you click the "Preview" button to see your output as you type the MSCGen code. There is no need to save it everytime to see your output.

mscgen2.gif

 

The add-on also detects any syntax errors lurking in your code and automatically displays error messages in the MSCGen editor. Once you are satisfied with your generated MSC, you can click the "Save" button to save and embed it into your Confluence page.

mscgen3.gif

 

With MSCGen for Confluence, users can add as many sequences per page as desired, edit in Confluence, and preview or render instantly. This add-on will empower your team to view, track, and collaborate around their MSCGen code and charts. It will save a lot of time and energy that is wasted on drawing MSCs directly by hand using some other available drawing tools.  Moreover, the charts can be  saved and exported as .PNG, that enables the users to share them outside their Atlassian ecosystem.  In connection with other tools, MSCGen for Confluence can be used to support methodologies for system specification, design, simulation, testing, and documentation.