The datamap add-in creates a Microsoft Word custom taskpane for testing maps in the current document, with the following options:
Map Storage
Firstly, a brief explanation of how datamap keeps track of maps within the document. Even though the taskpane is where you edit maps, they are actually stored as text boxes within the shapes collection within a Microsoft Word document. You can view them by opening the Selection Pane from the Layout tab of the ribbon.
Note Editing maps in this format is not recommended and should only be done if advised by datamap support.
When you save a Microsoft Word document that contains maps, they will be saved with the document for future testing purposes.
When you click any action button within the taskpane, the following ‘admin’ tasks are completed in this order:
- The latest information you have edited within the pane is written back to the shapes collection
- The content of maps in the taskpane is always treated as the latest and greatest, and is never overwritten
- Any complete maps that are in the shapes collection and the taskpane is not aware of (unseen maps) are loaded into the pane
- This will commonly occur when you open a document that already has maps, or if you rename a map
- Unseen maps display at the top of the list in the taskpane and are temporarily highlighted yellow for the user’s attention and review
- Finally, the operation you have actually requested (refresh, add, move up, etc) is performed
Refresh
A refresh is probably the most complex operation in the taskpane.
After completing the standard map storage ‘admin tasks’ described above, the first thing datamap checks is whether details have been provided in the Login group on the ribbon tab.
- If so, the details are used to fetch the data from the online account
- If not, the refresh is executed based only on the content of the local maps
Getting Account Maps
If you have provided login details, they are used as follows:
- The User identifies your account and hence where to look for document types
- The Document Type is used to fetch the relevant posts within the account that contain maps
- Multiple document types can be specified as a pipe-separated string, however only 20 maps are supported for viewing and testing within the taskpane
- The Password is applied only if you have protected the content of your document types
The operation of getting the maps is a one-way HTTPS request.
The taskpane will only be updated with a full map from the account if it is not already defined in the pane.
During normal batch processing the account is considered the master location for maps, however during testing the taskpane is considered the latest and greatest content and local changes will never be overwritten. Any discrepancies in the contents of the maps are reported via the sync status.
Running Maps
All relevant maps in the taskpane are run. Note the following:
- Unseen maps (those present in the document, but only just loaded into the taskpane as part of map storage ‘admin’) will not be run during the first refresh
- This is to avoid unpredictable behaviour associated with the order of running
- Maps that exist in the taskpane but not the account will not be run
- Maps are run in the local order (not the account order)
As part of the refresh, surrounding events such as ProcessDocument_AfterRunMaps are also fired, and results are exported to the default Microsoft Excel workbook if not disabled via script.
Note The default Microsoft Excel export will work only for existing files with a real file path and not for temporary / unsaved test documents created from image files.
Sync Status
Finally, sync status is updated via the ‘traffic light’ system.
| Status Light | Meaning |
 | Status amber / unknown. Either no login credentials were provided, or there are unseen maps present which mean the software cannot be sure if there are discrepancies with the online account. |
 | Status green / synced. All local maps match the maps in the specified document type(s) of the online account. |
 | Status red / unsynced. Maps highlighted red either do not exist in the assigned document type(s), or their contents have been modified locally. |
Based on this, you can either update the online account, resolve the differences in the taskpane, or delete maps that are not relevant for testing.
Add Map (
)
You can create maps in the taskpane as well as in the online account.
Click this button to open a window that asks for some basic information before creating the map.
Map Name
Provide a succinct and appropriate map name. A map usually corresponds to a header field you would expect to see in a database (for example ‘Date’, ‘Invoice Number’), or a column name if you are capturing table data (for example ‘Description’, ‘Unit Price’).
Spaces (not leading or trailing) are allowed in map names, however certain characters such as pipe (|) are not.
Map Type
The purpose of map type is to set a FIND block with an appropriate regular expression from the beginning.
Two types are provided:
- Amount – this sets a FIND block that will locate all whole numbers and those with two decimal places
- Date – this sets a FIND block that will locate a date in various formats
Note The date regular expression is displayed as {date} in the user interface for readability and to guarantee compatibility with the date formatting script. It is equivalent to the following:
(\d{1,2}\s?(?:ST|RD|ND|TH)?[-.\/\\ ]*(?:JAN(?:UARY)?|FEB(?:RUARY)?|MAR(?:CH)?|APR(?:IL)?|MAY|JUN(?:E)?|JUL(?:Y)?|AUG(?:UST)?|SEP(?:TEMBER)?|OCT(?:OBER)?|NOV(?:EMBER)?|DEC(?:EMBER)?)[-.,\/\\ ]*(?:19|20)?\d{2})|((?:JAN(?:UARY)?|FEB(?:RUARY)?|MAR(?:CH)?|APR(?:IL)?|MAY|JUN(?:E)?|JUL(?:Y)?|AUG(?:UST)?|SEP(?:TEMBER)?|OCT(?:OBER)?|NOV(?:EMBER)?|DEC(?:EMBER)?)[-.\/\\ ]*\d{1,2}\s?(?:ST|RD|ND|TH)?[-.,\/\\ ]*(?:19|20)?\d{2})|(\d{1,2}\s?\\\s?\d{1,2}\s?\\\s?(?:19|20)?\d{2})|(\d{1,2}\s?\/\s?\d{1,2}\s?\/\s?(?:19|20)?\d{2})|(\d{1,2}\s?-\s?\d{1,2}\s?-\s?(?:19|20)?\d{2})|(\d{1,2}\s?\.\s?\d{1,2}\s?\.\s?(?:19|20)?\d{2})|((?:19|20)\d{2}\s?-\s?\d{1,2}\s?-\s?\d{1,2})
Add to Map (
)
The Add to Map feature creates a WITHIN block in the selected map from the text you have currently highlighted in the document.
This is useful to build up the structure of your maps more quickly than typing.
Test
You can test a map by selecting it in the taskpane and clicking Test.
This will not run the full document type, fire document-level events / export the results, or update sync status.
As such you will need to ensure any maps referenced by result have been run previously. For more information, see the syntax documentation for WITHIN blocks.
Even though in some cases you are testing a single map with this feature, in reality you are testing a map set.
Map Sets
Maps inside the same document type with the same regular expression in their FIND block are considered a linked map set. For example, all maps you add with the amount type and provided regular expression (\d{1,4}\s?[.,]\s?)?\d{1,4} form a set.
All maps in the set must be tested at the same time. When processing a document at runtime, the position in the order of maps when the maps of a particular set are executed is the position of the last map in the set. And therefore in the taskpane, you must highlight the last map in the set when testing.
What is the purpose of linking maps with the same regular expression, and hence enforcing this dependency? It is to reduce the cross-confusion and duplication of results in very similar maps, giving each map in the set a chance to claim a result for itself and remove it completely from other maps in the set. Based on the WITHIN blocks, the strongest score (coupled with lowest proximity) makes the strongest claim. In addition to reducing false positives, it is particularly useful when a map represents a table column, and every result in the collection must represent the value for a new row of the table.
Note Unclaimed results stay in all maps in the set.
Comments
You can enable comments when testing a map set. These allow you to see the position of results, keywords, and the restricted search area (which is highlighted in yellow).
Individual comments have the following elements:
| Element | Description |
| RESULT / KEYWORD (N) | Indicates whether the highlighted text is a result of a map, or a keyword. N indicates the 1-based index of the WITHIN block this keyword or result belongs to in the map set. If N is 0 this is the result for the FIND block of the map set. |
| <value> | The formatted text of the result or keyword |
| x | The x coordinate, in points |
| y | The y coordinate, in points |
| pg | The 1-based index of the page in the document |
| cs | The 0-based starting character index in the Microsoft Word main text story |
| ce | The 0-based ending character index in the Microsoft Word main text story |
| mp | The map in the set which has claimed this result, if applicable |
| co | The final confidence score (results only) |
| pr | The final proximity, in points (results only) |
The author tag for all comments is updated with the name of the Windows user who is running the current Microsoft Word session.
All datamap comments are deleted each time you test a map set.
Move Up (
) / Move Down (
)
These self-explanatory options can be used to reorder the maps in the taskpane.
Remember that the order can be important when referencing map results from the WITHIN block.
Running a refresh will respect the local order.
Delete Map (
)
Clicking this button will delete the selected map from the current document.
Tip If you delete a map unintentionally, immediately press the standard undo command CTRL + Z to restore the map to the Microsoft Word shapes collection. Then refresh the taskpane to get your map back for editing.