Messages are one of the core building-blocks of api-map. Messages can be defined either as xml schemas (xsd), json schema files, json instance files, or web services definition (wsdl) files.
When you use api-map for the first time, or start a new workspace and click the 'Messages' item from the top menu you'll be shown an empty list of messages, with a prompt to both add messages or service definitions.
Clicking the 'Add New Message' button will show the following page. You can either drop files in the rectangle in the middle of the screen to upload them, or click on the rectangle to open up the 'open file' dialog.
Errors During Importing
Sometimes when you upload a message to api-map it can't be imported and instead you'll see an error message at the top of the screen. The following tips can help resolve these errors.
- For xml schema files (xsds) it is possible that the message definition is split out into multiple files. This is often done if parts of the message are re-used beween different messages (for example to model common domain elements). You may need to find and upload additionl files to complete your import of the full message.
- Ensure the message is valid. A mis-placed space character, or missing '>' or '}' character can cause the message to be invalid. If you got the messages from a 3rd party check with the authors of the message to ensure the one you are uploading hasn't been corrupted.
Once you've uploaded the message files you'll see the message files shown at the top of the screen, and below that the Logical Schema for the message.
This is a hierarchy of the elements that make up the message. For some messages the root element for the message doesn't actually have a name. In this case the words (no title) are shown. You can drill down into the structure of the message by clicking the arrows beside the names of elements like "billing_address" and "shipping_address" shown in the screen-shot below.
You can also click on individual message elements and see the description, example values, and ui annotations for that particular message element. Some of these fields like description and example values can be defined in the message file you uploaded, and will be pre-populated in there by the import process. You can also add additional ones, or edit the existing ones. Some things like UI annotations are not part of the message file, and can only be added by you.
Messages are updated by either editing the message file, or by uploading a new version of one of the message definition files.
When a message is modified api-map retains the old copy of the message, creates the new message and records that the 'old' message has been superceded by the new one. Any mappings where the old version of the message was either the source or the target of the mapping will be updated to map to the new version of the message. In order to do this api-map needs to try to determine which elements in the old message correspond to ones in the new message. If the structure of the new message is substantially different, or if elements near the root of the message structure have been re-named api-map will not be albe to find these corresponding elements, and thus mappings and annotations may be lost.
Some modifications to the message which don't really change its structure can be done without triggering this message replacement process. For example adding a ui annotation or filling in default values, or the description of a message does not change the structure of the message, and so does not result in the message being superceded by a new copy.
Finding Elements in Large Messages
For large messages finding the elements you are interested in may be difficult. To search for a message element by name click in the textbox marked 'Filter' and type a part of the name to match on. Matching elements are then highlighted in yellow.