Introduction
At this stage in your journey into the world of Integration Advisor, I am hoping you will have begun to understand the importance of the Message Implementation Guidelines (MIGs). In this blog post I provide detailed instructions on how you can enrich your Message Implementation Guidelines with custom documentation to ensure that when documentation is generated it is totally comprehensive and tailored specifically to your customer needs.
If you are not familiar with MIGs yet and first wish to find out more information on what a MIG actually is and how to create one, I would recommend to read the blog post Integration Advisor: Create a customized interface using the MIG editor. If you are completely new to Integration Advisor and wish to have an overall understanding of the product I would recommend to start with the blog post titled integration content advisor: Overview of components and further reading. From this blog post you will be able to access many other blogs and read them in a logical sequence.
How do I document my MIG?
One of the major paradigm shifts that Integration Advisor introduces is the move away from mapping exercises being the realm of the Technical Developer. The goal of Integration Advisor is to empower you, the Business Domain expert to perform the design and implementation end-2-end with little or no aid from a technical person.
With Integration Advisor, we also intend to take away the ‘drudgery’ of having to continually maintain documentation for interfaces in a manual fashion using the traditional Spreadsheet or Document editors on the market.
Integration Advisor is designed as a ‘one-stop-shop’ where you can design interfaces, fully and comprehensively document them and then actually generate the mappings as well…
Having the in-built capability to document your interface in the tool itself ensures that the documentation always remains tightly linked with the interface definition and can be changed and re-generated at any point in time. The typical situations where interface documents are stored on a shared drive somewhere (and eventually lost as no one can remember where they are!) are eliminated. If your Live Services team need to gain access to the documentation, they can simply login to Integration Advisor and access the documentation immediately.
The availability of standard documentation
As has been comprehensively discussed in the blog post describing Integration Advisor standard libraries, MIGs are based on message definitions that are imported from Type Systems. These message definitions are already fully documented with the standard information provided by the authors of these Type Systems. As a result, in many cases most of the documentation requirements have already been fulfilled by Integration Advisor for you.
There are situations, however, where you may want to adapt or enhance the documentation to cater for your specific needs. The next section of this blog post will explain where and how documentation can be added or changed in a Message Implementation Guideline.
How to add custom documentation to a MIG
Documentation can be added or enhanced in several places in a Message Implementation Guideline. These are:
- The Summary section in the MIG overview
- The Definition section in the MIG overview
- Notes at the MIG level
- The names of fields or segments
- Detailed documentation at the individual field or segment level
- Notes at the individual field or segment level
Each of these will be discussed below and the location of these documentation types in the generated documentation will also be illustrated.
Documentation in the MIG overview
In the MIG overview a summary of the purpose of definition can be specified. The recommendation here is to provide key administrative information about the MIG, including the version of the definition it was derived from, the date of publication and so on. If the MIG is intended to be provided to external trading partners, contact information could also be provided.
A more detailed and comprehensive definition of the MIG can also be entered in the MIG Overview. If a standard definition is provided as part of the Type System, this will be automatically replicated into the MIG. You can choose to replace or enhance the definition in order to tailor it to specific requirements. The MIG definition can be used to provide relevant information about the business process that the MIG is part of, as well as procedures and principles for its use. Some basic formatting of the text is supported in order to improve readability.
In the generated documentation, the MIG Summary and Definition are located on the overview page of the PDF or RTF file.
Notes at the MIG level
On the Notes tab of the MIG editor, one or more notes can be added. The purpose of these notes is to support the addition of more detailed technical or business-specific information regarding the MIG. The following types of Notes can be added:
- Usage
- Constraints
- Comments
- Examples
To add a new note, click the Add button as illustrated in the screenshot above. In the dialog box that appears, choose the type of Note you wish to add:
Enter a number for the Note as well as the Note Text. You can then press the Apply button:
This process can be repeated as many times as required. As can be seen in the diagram below, the different Note types are grouped to improve readability:
In the generated documentation, the Notes are again located on the Overview page of the PDF or RTF file.
Names and Documentation at the detailed Field or Segment level
Many older and more ‘traditional’ message type definitions are based on the provision of fields names that are totally technical and not human-readable. This may have been due to past restrictions on field name lengths (e.g. databases that allowed table column names to be of an extremely limited length).
The use of these technical names has meant that typical message mapping tools are only usable by Technical Developers. Integration Advisor (IA) addresses this issue by enhancing any MIG definition with a human-readable name for each field. In addition to that, where detailed documentation at field or segment level is provided by the authors of the various Type Systems, this is also incorporated into the MIG by Integration Advisor.
As already discussed, in many cases a customer using these message definitions may wish to enhance and tailor these names or descriptions to their personal needs.
In the Integration Advisor MIG editor, editing these Names or Documentation is very simple.
To modify the human-readable name or documentation for a field or segment, simply edit the existing Name or Documentation fields. In the screenshot above, as soon as [Enter] is pressed on the edited Name field, the change will be reflected in the Node tree structure.
In the generated documentation, the Name and Documentation will be updated with the revised text. This will be illustrated in the next section.
Notes at the detailed Field or Segment level
Notes at field or segment level are input in a similar way to Notes at the MIG level, and the same types of Notes are available. Simply switch to the Notes tab for the node you wish to add Notes to, and press the Add button:
The same dialog box will appear as used for Notes at the MIG Level. Once you have added your Notes, they will be displayed in the Notes tab:
In the generated documentation, the Notes will be displayed at the field or segment level in the structure documentation. As mentioned in the previous section, you will notice that the Field Name and Documentation have also been updated.
Summary
One of the least enjoyed, but arguably the most important tasks of an interface project is to provide comprehensive documentation for each and every interface. An interface may have been implemented by a Systems Integrator, or an employee that has left the organisation; if the documentation of that interface is not comprehensive, accurate and up-to-date there is a huge risk involved in the event that the interface fails or needs enhancement. Integration Advisor seeks to alleviate the effort required to create this vital part of any interface definition.
New features are continuously being added to Integration Advisor, so please re-visit our blog posts on a regular basis for news on any changes and enhancements.
Further Reading
Read the following blog posts for more information:
Overview of Integration Advisor: Integration content advisor: Overview of components and further reading
Creating MIGs using the MIG Editor: Integration Advisor: Create a custom interface using the MIG Editor
Adding qualifiers to a MIG: Integration Advisor – The precision of semantics – Use of qualifiers
Creating a MAG using the MAG Editor: Integration content advisor: Create a mapping using MAG editor
- SAP Managed Tags:
