How do you document your interfaces?

[Brad Gollifer]

We have a testing team that tests various system upgrades.  When a testing event happens the need arises to know what systems intregrate with others and with what message types etc.  The testing team is not part of the integration team and we do not want them in cloverleaf messing around trying to find this data.

So the question how do others using cloverleaf document their interfaces outside of cloverleaf in a way that the data can be understood by the average worker.

Has anyone parsed the NetConfig and thrown it into a db with a slick front end on it?

Topic

[Cesar Ruiz]

We keep all cloverleaf documentation on MS SharePoint.   It is very easy to do interdepartmental collaboration.

[Baron Matthews]

I’ve made some attempts at parsing the netconfig. I pull some basic stuff (host, port, connection, plus a few others) once a night, then import that into SQL Server via SSIS, and have a bit of an ASP page that puts it on our intranet.

We (as in the integration team) are the only ones that really use it, but we find it quite helpful just to keep up with port numbers, if nothing else.

I am sure some other folks on here have made a lot more progress in completely parsing the netconfig than I have. I feel that is the best way, then, you can automate documentation.

[Vince Angulo]

I’ve gone down this path a number of times over the years, but have always ended up shelving it.  Since we only have two sites and two staff members that work with Cloverleaf, it’s not been a priority.  

As for the testing and applications specialists teams, they’ve never had a use for seeing the interfaces from a Cloverleaf point of view — they find it overwhelming and it doesn’t meet the “I only want to know what I need to know” test.

So my colleague has put together is a very simple block diagram in MS-Word (about three dozen real-time, HL7 interfaces) on one page.  It turns out to be one of the most prized pieces of documentation for the apps/testing folks.  It’s a case of “less being more”, or as our ITIL service model preaches, “users want holes, not drills”.  We’re building our Sharepoint site now, and it’ll likely be a prominent link.

This may change as we implement more interfaces – -and quite rapidly, so I’m interested in seeing other responses to this thread.  

Without hijacking this topic, I’m wondering a little deeper — an issue I have is documenting which procs are in which .tcl files and tracking where they’re used in Cloverleaf.  I document this in the header comments of the proc itself, and in my own off-line documentation.  Has anyone tackled that in an on-line format?

Thanks.

[Robbie Parker]

I use excel spreadsheets.  Simple, quick, and others can use easily if needed.  I name the file the name of the interface from our master list.

I then utilize tabs for different types of the documentation such as summary, business need/owners, technical specs (IP/ports), visio diagram, translation logic & filters, troubleshooting & vendor support info, etc., etc…

[Bob Richardson]

Greetings,

We are blessed in that we have business analysts who maintain Excel spreadsheets with the mapping requirements, change history, route information, connectivity data, and filtering requirements that are summed up in various tabs in the spreadsheet.  We update these documents with Cloverleaf developer specific comments as needed.

The spreadsheets are maintained in a shared area that the business anaylsts, system analysts, and us Cloverleaf staff can access.

Not perfect by any means but the business side knows their data and their applications better than we would by any means.

Of course there is the problem of keeping good documentation for the Cloverleaf side for us:  good prologue maintenance remarks in all TCL procedures; comments in the Xlates.  Our own supporting technical documentation on the web (public) and on a shared area that is accessible by only ourselves.

Again, not perfect – it would be great to have tools available from the Cloverleaf vendor to parse/organize/report Cloverleaf configurations.

A topic at this year’s Annual Conference?

Enjoy.

[Ken Seachrist]

One of the members of our team has parsed the NetConfig so we can see much of the thread info on the web as we need.  we are able to stop, start, view the documentation, set monitoring parameters (such as only send a message if the lab gets over 100 behind between 10PM and 6 AM).  We also created Word documents that our Ops department maintains.  They create PDFs from those, and then we create a link on our portal to those PDF documents.  That way there is only one set of documentation to maintain.

Our goal, on the integration team, was to keep the off hour calls to the on call person to a minimum by allowing the operations staff the ability to handle most of it on their own by using the documentation.

[Ian Morris]

Ken,

That tool sounds pretty neat.  Are you able to post screen shots of any of it?  I’ve got a tool that I’ve been working on myself.  It relies on running the hci status and statistics commands as well as parsing the netconfig for getting information like thread name, status, last read, last written, pending outbound messages, comments, port and IP.  The port and IP information comes from a netconfig parsing .tcl script posted on these forums by someone else.  Also the comments section is used to give our helpdesk and other users some information on how to start troubleshooting an interface.

[Author]

Replies