Documentation of Interfaces

[Wilhelm Pettersson]

A question for everyone;

1) How do people go about documenting their interfaces?

2) Do people come up with new adjusted HL7 specification documentation?

3) Is a tool used create the documentation?

4) XLATE documented with the HL7 specifications or separately?

Thanks,

Wilhelm

Topic

[Jim Kosloskey]

Unless you count the various Office products as tools then I do not use a tool.

All of our specifications are done in MS-Word.

There is a template for the source system which is changed as the source system changes either the construct or usage of the message sets.

We create our own Integration Specification (using the template). The specification contains a section for the inbound message set and one for the outbound message set.

The sections are constructed as tables.

For the inbound section each segment that the inbound system populates is specified in a tbale that has every field. All of the fields are identified as to wheter they are populated or not. Comments and notes are kept as to wheter a field is populated or not and how. There is a column for the source DB field(s) that provide the data.

For the outbound, only the segments needed by the receiving system are listed.

Each segment is specified in a tbale that identifies the fields that the receiving system wants. For each field (among other things) are the source of this field from the inbound message, the destination DB field9s) that will be poluated with this field, comments and Notes regarding any special handling for this field, how this field is displayed (if it is) in the receiving system.

In addition there are sections spelling out exactly the protocols being used,

email: jim.kosloskey@jim-kosloskey.com 29+ years Cloverleaf, 59 years IT - old fart.

[Russ Ross]

I’ve been dreaming some recently about if I can take the MS word document that Jim spoke of and place it on our AIX server in binary mode for safe keeping and then have the Cloverleaf IDE on MS windows point to it via the thread notes section and be able to launch it in MS word when clicked on.

I have’nt spent the necessary time to figure out if there is any hope but I do know these things are possible because I’ve done them:

– can launch an htlm document in the thread notes

– can store a MS word document on an AIX box and lauched it on a windows PC using the Hummingbird neigborhood

I also want to say I think I launched a URL from the thread notes in the IDE but I don’t remember clearly.

Jim and I work together and have become suspicious of spec documents for various reasons and the worst thing is finding them years later when shared drives remain in constant flux with so many old versions of the spec or they disappear altogether from any known location.

If anyone is able to figure out how to store an interface spec on their cloverleaf AIX server and launch it from the thread notes in the IDE, I would like to hear about that success and leverage that experience.

If it turns out this isn’t something that can be done currently, I would like someone like Robb Abbot to consider it and start discussing possible development of such a concept.

You can make your cloverleaf integrations self documenting and be certain it is the difinitive document since it is the actual integration but it is’nt all that handy at sharing that information outside the inhouse cloverleaf team.

Russ Ross
RussRoss318@gmail.com

[Kevan Riley]

Why not save them as HTML, and use that format.  It is immediately viewable in the NetMonitor, and most things you would want to do in MS Word should be possible in HLTML.

[Tom Rioux]

Placing the spec documents on the AIX Server sounds like a good idea.  However, that is only a good idea if the persons looking at them are other Cloverleaf programmers.

We have spec documents for our interfaces out on a shared drive.  It allows read access to the documents by the people affected by the interfaces, the users.   This way they know what Cloverleaf is doing with the data they recieve.   Also, our spec document has a “change log” for requesting changes to the interface.   The user must fill out the change log before making a change request.  That way, there is always a record of what is being changed and who requested it.

Tom

[Russ Ross]

Thomas:

We currently do have our specs on a shared drive and that hasn’t worked so well for us.

Russ Ross
RussRoss318@gmail.com

[Max Drown (Infor)]

I like to use wiki software for documentation (I don’t mean sharepoint). My personal favorite is dokuwiki. And don’t forget that in recent versions of Cloverleaf, the Notes field was added to the Netconfig. Also, check out this thread for a neat way to generate diagrams: http://clovertech.infor.com/viewtopic.php?t=4007&highlight=diagram

-- Max Drown (Infor)

[Eric Kavanagh]

Hi

I use a program call “Doctools” that creates a complete crossed referenced html documentation of your site. It is really an impressive bit of programming, not to mention the excellent html results. Then I write the general documentation and workflows in Visio, linking the relevant parts down to the html created by Doctools. Save the Visio as html, but here you have to change some of the dumb links created by Visio. For the first time in my life I enjoyed creating the documentation.

Regards

Eric M. Kavanagh

[Russ Ross]

How much effort up front is it to implement doctools?

I googled doctools and found a webpage that talks about TCL procs we can call to create taylored made documentation I presume.

This led me to wonder if you need to write a home grown TCL program to use these TCL doctool procs to generate the desired documentation.

If that isn’t the approach you are describing please elaborate.

I would like to estimate what kind of investment in time I would be looking at to try out doctools and get it to generate meaningful documentation output.

Russ Ross
RussRoss318@gmail.com

[Eric Kavanagh]

Hi

Doctools is a set of tcl scripts which includes an installer. Takes a few minutes to install. Then you just open the command window and write “docsite “. Borders on brilliant, imho.

Best part is what it produces, 2nd best, it’s free!

Send an email to Raymond.Bakker@enovation.nl as there is a new version 1.3.1.

I only have 1.3, but I can send that if you like.

Regards

Eric

[Russ Ross]

I’m trying to understand if doctools is a frame work to prodcue integration documentation or is smart enough to read the NetConfig/xlates and procduce the documentation itself and if so how does it accomplish that?

Russ Ross
RussRoss318@gmail.com

[Eric Kavanagh]

It reads the NetConfig/xlates. If you want to see how it does, what it does, just read the tcl code. An unusual “gift-horse”, you can open this ones mouth.

I sent it to you, just install it, and run it.

If you are using 5.3 you might want to comment

#  append op ” mqconnwaitint=”[keylget threadconfig PROTOCOL.MQCONNWAITINT]””

#  append op ” mqsysque=”[keylget threadconfig PROTOCOL.MQSYSQUE]””

OK, Friday calls, I’m off to the country.

[Russ Ross]

Now that I understand it has been preprogrammed and tailored made to read the NetConfig/Xlates, my interest has peaked.

I will put this on my wish list of things to look into.

Thanks for sharing.

Creating documentation for Cloverleaf integrations that others can use reamins a challenge for us.

Our static documentation is marginal at best and I have to rely on Cloverleaf itself as the definitive document, which is only useable to the integration team and not others.

It would be cool if HealthVision came up with something like doctools or leveraged doctools to inclue a capablity to have cloverleaf auto generate static customer useable documentation for integrations at points in time of your choosing using the definitive sources such as NetConfig/Xlates/etc.

Russ Ross
RussRoss318@gmail.com

[Shaun Beckman]

I emailed Raymond Bakker asking about information regarding Doctools. Here is his response:

Hereby I would like you thank you for your interest in the Doctools XML.

Last week I have been contacted by a number of people who have shown interest and I understand that this is due to a post on the Clovertech forum.

Although we are pleased by the feedback we have received, we cannot provide you with the software as it was built by E.Novation with sole purpose to provide it to our direct customers and business partners.

Next versions of the Doctools software will have a modified disclaimer where this will be explicitly stated.

If you have any further questions I will be happy to answer them for you.

Thank you.

With kind regards,

Raymond Bakker

Integration Consultant

[Russ Ross]

I deleted my post since it was essentially the same as the one above and we sbmitted our replies almost simultaneously.

Russ Ross
RussRoss318@gmail.com

[Max Drown (Infor)]

Lawson does have a tool for sale that is currently called “SiteDoc” that will generate HTML documentation of your sites. Contact your CRM if that interests you.

-- Max Drown (Infor)

[Michael Hertel]

Just like the airlines charging for checked baggage.

This should be free.

[Chris]

[Author]

Replies