Integration Errors
MKS provides two log files to troubleshoot errors. By default, the C:\Documents and Settings\<user>\Local Settings\Temp directory contains the following log files: MSWord-log.txt displays errors with the Word integration
MSWord-APISession.log displays errors with the API If errors occur, consider the following:
Potential errors include: communication with the API, data processing with the item mapper, or committing processed items and attachments to MKS Integrity.
Possible reasons for errors occurring during the conversion process include: connection errors, misconfiguration of the Document Structure Definition, or data volume.
If an item has been partially submitted, you can attempt to fix the input and resubmit the failed parts, or cancel the submission and re-submit.
Specifying an incorrect field in the Export to MKS Integrity Wizard displays an exception error message.
Creating a Custom DSD for Other Document Types
By default, the Word integration allows for the export of requirement documents into MKS Integrity. You can also create additional DSDs to use with different document types (or domains), for example, specification, test, or input documents.
Once you have created a custom DSD for a new document type, the specified identifier will be available for selection from the list in the Word Importer dialog box.
Sample XML mapping templates for use with the Word integration are included in the Integrity2009_Server_Templates.zip file that is available for download from the MKS Customer Community (http://www.mks.com/support/community).
You extract the sample XML mapping template files, including: MS_Word_Requirements_Document.xml.sample MS_Word_Test_Suite.xml.sample
to the following directory on the MKS Integrity Server: <installdir>\data\gateway\mappings\
The XML mapping template must be renamed to remove the .sample extension, and then modified to reflect your workflow or ALM installation. The modified XML mapping template then becomes your production mapping template for the Word integration.
TIP
The XML template file name should differentiate between the default template and the custom one being created.
Ensure that the internal field values in the XML mapping template reflect the MKS Integrity field names as installed for your workflow or ALM installation. For example, if you installed ALM with a prefix, ensure that the same prefix is present in the internal field values contained in the XML mapping template.
For general information on modifying an XML mapping template, see “Configuring a Mapping Template” on page 239. For more detailed information, contact MKS Customer Care.
To create a custom DSD
1 Make note of the name of your production XML mapping template.
2 For each specific import that will be supported, you must create a new MCFG (DSD). By default, MKS Integrity includes a condensed version and non-condensed version. You can use the default versions to create two versions (condensed and non-condensed) for your document type.
If you have not already imported the MCFG file, it is available in the
<integration installdir> on the MKS Integrity Client or by default in the following directory:
C:\Program Files\MKS\MKS Word Document Import\Rulesets If you have imported the MCFG file, it resides in:
C:\Documents and Settings\<username>\.mks\integrations \Word30\RuleSets
NOTE The MCFG file is a ZIP file that can be opened and repackaged using a ZIP utility.
4 To customize a DSD, make the following changes in the MCFG files:
Update the mapping_name.txt file with the name of the custom mapping template For example, if you are working with the
MS_Word_Requirements_Document.xml.sample template, you would add Microsoft Word Requirements Document as the mapping name.
Update name.txt with a new identifier. The specified identifier will be available for selection from the list in the Word Importer dialog box.
Open the static.txt file and in the Category line, change the last (ninth) parameter to a comma separated list of the allowable categories in the your document.
NOTE Ensure that field relationship rules are respected.
5 Save the files, re-package the MCFG file, and import it. You can now export the defined document type to MKS Integrity.
IMPORTANT
When rendering rich content, broken image links are displayed if Word cannot
find the following file in the DSD:
internal_attachments_name.txt
If internal_attachments_name.txt is not found, Word defaults to using
RQ_Text Attachments as the attachment field name for the rich content attachment links. This default behavior causes the broken image links in the rich content.
To resolve this issue, you must add a file that contains the actual attachment field name in the DSD (internal_attachments_name.txt). Ensure that the internal field values in the DSD reflect the MKS Integrity field names as installed for your workflow or ALM installation. For example, if you installed ALM with a prefix, ensure that the same prefix is present in the internal field values contained in the DSD.
If you were previously using the Word integration with an RM 2007-based
solution and the rich content field did not have RQ_Text Attachments
mapped as the attachment field, you must add the
internal_attachments_name.txt file to the RM MCFG files and ensure that the file contains the correct attachment field name. To add the
internal_attachments_name.txt file, follow the instructions for “Creating a Custom DSD for Other Document Types” on page 182.
The ALM 2009 MCFG files contain the internal_attachments_name.txt
file. This file uses the ALM_ prefix to illustrate where changes are required. You must modify the contents of the internal_attachments_name.txt file if your ALM 2009 solution is installed with no prefix or a prefix other than ALM_.