As a service provider, you might have requested documentation from a vendor. As a vendor, you may be searching for documentation regarding a specific client install. Either way, you are looking for some information that helps you do your job (i.e., implementing, supporting, changing or fixing an interface).
To that end, what is the documentation needed for an interface implementation? Is there something different needed to support the interface long-term?
Let’s begin with identifying the types of documentation vendors and providers produce:
- Project scope
- Interface description
- What’s the business requirement?
- Workflow descriptions
- What is the functionality that is being automated in an interface?
- HL7 specifications
- Inbound data
- Outbound data
- Gap analysis
- Documents gaps between the comparison of 2 vendor specifications
- Sample messages
- Message flow diagrams
- Message transformation/mapping/filtering/routing logic
- Test plan
- Go-live plan
- Downtime plan
- Run-time archive or message logs
You will rarely have access to all of these document types on a specific interface; but, honestly, you probably don’t need all these documents at any given time. Based on the task at hand, some specific information can be very helpful.
In my interfacing experience, I have found that sample messages are the most valuable during the interface development phase (see Three Things to Keep in Mind When Developing an HL7 Interface), especially when you have the proper technology. Sample messages reflect the actual data a system can export or import into their application.
For long-term support of an interface, the truth again lies in the messaging. Having access to the actual messages via archived message logs, received from an application or sent to an application makes troubleshooting easier. You can quickly identify which side of the interface needs to be addressed.
Of course, the technical aspects of an interface are only a piece of the puzzle. I always say that the work flow of an interface is typically 75% of the project. It is helpful to have the scope document with the business requirements and workflow diagrams to help build and test the interface correctly.
The reality of the interfacing world is that we will have to make “it” work without documentation sometimes. At that point, I rely on my integration tools to help document the interface for the future.
As you go forth in the interfacing world … may the force be with you.