A take on documenting integration platforms using Visio

Earlier this year I wrote a post about having Visio update a field on a shape automatically when editing any other field, making it possible to always know when the metadata was last changed. In the comments I was asked to share the Visio sheet which it now is time to do. This is the result of that request, in some way documenting my attempt to use Visio to document an integration platform. Hopefully you can gain some ideas to use in your documentation endeavours.


In almost all of my encounters of different integration platforms at various companies, there has been a high level view of the entire integration setup showing the various message flows available. This map has usually been constructed in Visio. There has also been two types of layouts, lets call them the structured layout and the unstructured layout.

The following is an example of the unstructured layout. It's common and does a fairly good job at describing the full environment. It is often seen when there has not been a true approach to working with integrations.

Most of the time they are filled with objects, with varying descriptions, showing the entire network.You can see that two systems interact, but you do not know in which way. It is also often hard to see how everything is connected if you as in the example has an integration hub in the middle, doing some message routing.

Hence we get the structured layout as is seen below. In this case, there is a very solid structure with the integration platform in the middle, and the integrated systems on both sides with arrows showing each and every message flowing through.

These maps are good at showing the message flows as every message is entered, but it doesn't give you the overall picture that the unstructured layout gives you since a lot of fluff is stripped away. Usually there has also been an improvement from the unstructured layout in that each message flow has been given an identity which then maps to more detailed documentation in a file archive or document portal.


So, earlier this year I did a test with a variant of the structured layout, seeing if I could document the current state of integrations at my current job. The map I was given from the beginning was according to the unstructured layout. A lot of information was out of date, systems had been taken out, others taken in, versions changed, message flows altered and so on. I had to create an up to date picture of the integrations, so that I could commence working with them.

I took a brand new Visio document and started documenting. I created a "system" shape that had the following shape data:

• System name
• System name 2
• System version
• Server name
• Database
• Database version

In my Swedish Visio it looks like this:

In order to make it easier updating and changing these properties/metadata for all shapes, I changed the Shape Sheet to make the form data window open when doubleclicking on the shape. You can do this by editing the Shape Sheet property "EventDblClick" under "Events" to read "=DOCMD(1312)".

I then did the same thing for the arrow shape adding metadata that I want to know for each message:

• ID
• Object name
• Status (i.e. Planned, Under development, In use, To be removed)
• Transport (i.e. Web service, File, FTP, WCF...)
• Type (i.e. Xml, Flat file...)
• Frequency
• Automatic (i.e. a drop down giving the option of Yes or No, indicating whether the message transfer is completely automatic)
• Sync/Async
• One way/Request-response
• From system
• To system
• Comment

Many of the fields are defined in the form data editor as dropdown menus as to make the data more consistent and easier to edit. I also added the "From system" and "To system" in order to get good documentation automatically created by exporting the form data to Excel. As with the System shapes, I added the doubleclick event to the shape.

I also altered the shape so that the choices made in the form data will be visible in the shape. Depending on the "Status", the arrow will be yellow (planned), green (under development), black (in use) or red (to be removed). This is done by editing the Data Graphic and setting that each value will match a specific color.

Also, setting the "Automatic" to "No" will show a little man besides the ID and Object name. This can be set in the Shape Sheet as well under "Text fields" and "Value". In my case, the formula is: =IF(STRSAME(Prop.Automatic,"No",TRUE)," 웃","")&" "&Prop.ID&". "&Prop.Objectname&" ". But is of course dependent on the name you give each property in the form data.

In the same manner, I have a setting that will change the arrows on the shape so that I get an indication if it is a one way transfer or a request-response one, by adding a little unfilled arrow in the other direction of the data flow.

I have also adjusted where the text appears on the connector according to this post from the Visio Guy, so that the text is always at the end of the line instead of in the middle.

So, is this a good way of documenting message flows?

Well, in this case, it has been very helpful. I have a single document that shows me quite a lot of the current setup and state. It eases on the job of manually editing shapes to indicate whether it is a planned message flow, if it is request-response, a manual job and so on. Instead, I just select the desired property and let Visio format the shape accordingly, giving me a neat view of the state.

After documenting all message flows in this Visio document, I will most likely strip it down. I will remove a lot of the metadata in the connection shapes, and have this solely in the integration specification document that I will create for each message. I do not like to have duplicate information in my documentation, and I feel that that sort of data will belong better in the written documentation than in the Visio sheet. I will still keep the color coding depending on Status, as well as some other visual cues that is helpful when looking at the overall view of the integration platform.

Having Visio update shape data automatically

Part of my job is to have an up to date documentation of all integrations we have. I am used to using Visio for this, and have at my previous clients kept it quite simple with manual formatting for visualizing if a message is under construction or to be deleted etc.

At this moment, I am trying out having "a lot" of documentation gathered in the Visio document. Besides having shapes for "Systems" and connections between these that each is equivalent of a "Message", I have added custom data fields on these that allow me to document metadata on each message flow. Part of the metadata I have on a message is Id, Name, Trigger, Status, Transport type and so on. Some of these fields are then used to dynamically alter the format of the connection to give a visual cue to the underlying data. If the Status is "Planned" I give the connection a green color, if the connection is marked as "Request/Response" I visualize this by having a symbol indicating so.

This all works fine and gives me one single document for the overview of the integrations. I then thought of implementing a change list so that I could follow up on revisions of the diagram. Having a normal text based change list on a separate sheet would be possible, but would incur manual work to update it and also not be mandatory (meaning that it would be forgotten and hence useless). Instead, I opted for an extra custom data field on the shapes used indicating the last time the shape was updated (data wise, not if it was moved). This is handled automatically by code that triggers when the shape data is updated.

I have one class module called "UpdateShapeTimeStamp":

Dim WithEvents appObj As Visio.Application

Private Sub appObj_CellChanged(ByVal Cell As IVCell)
    If (Cell.Shape.CellExists("Prop.Updated", 0)) Then
        Cell.Shape.CellsU("Prop.Updated").FormulaU = Chr(34) & Now() & Chr(34)
    End If
End Sub

Private Sub Class_Initialize()
    Set appObj = Application
End Sub

Private Sub Class_Terminate()
    Set appObj = Nothing
End Sub

and the Document code to enable this code:

Dim UpdateShapeTimeStampClass As UpdateShapeTimeStamp

Private Sub Document_BeforeDocumentClose(ByVal Doc As IVDocument)
    Set UpdateShapeTimeStampClass = Nothing
End Sub

Private Sub Document_DocumentOpened(ByVal Doc As IVDocument)
    Set UpdateShapeTimeStampClass = New UpdateShapeTimeStamp
End Sub

Now when changing the shape data on any shape, the event will trigger and check if the custom field "Updated" is available (meaning that it is one of my custom shapes) and if so, set it to the current datetime.

This allows me to have an automatic tracking of all changes in the diagram for each shape. Neat!