PTC Integrity 10.7 Gateway User Guide

Transcription

1 PTC Integrity 10.7 Gateway User Guide

2 PTC Integrity 10.7 Gateway User Guide Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively "PTC") are subject to the copyright laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this documentation if provided on software media, but only for internal/personal use and in accordance with the license agreement under which the applicable software is licensed. Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC. Training materials may not be copied without the express written consent of PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly available by any means without the prior written consent of PTC and no authorization is granted to make copies for such purposes. Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written prior approval from PTC. UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND CRIMINAL PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and private surveillance resources. As part of these efforts, PTC uses data monitoring and scouring technologies to obtain and transmit data on users of illegal copies of our software. This data collection is not performed on users of legally licensed software from PTC and its authorized distributors. If you are using an illegal copy of our software and do not consent to the collection and transmission of such data (including to the United States), cease using the illegal version, and contact PTC to obtain a legally licensed copy. Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of your PTC software. UNITED STATES GOVERNMENT RESTRICTED RIGHTS LEGEND This document and the software described herein are Commercial Computer Documentation and Software, pursuant to FAR (a)-(b) (OCT 95) or DFARS (a) and (a) (JUN 95), and are provided to the US Government under a limited commercial license only. For procurements predating the above clauses, use, duplication, or disclosure by the Government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS (OCT 88) or Commercial Computer Software-Restricted Rights at FAR (c)(1)-(2) (JUN 87), as applicable PTC Inc., 140 Kendrick Street, Needham, MA USA

3 1 Installation Installation Requirements Installing Gateway Parser Use and Configuration Exporter Use and Configuration Configuring JVM Understanding Gateway Gateway Import Overview Source File Why Use the Item Interchange Format? Gateway Export Overview System Administrator Tasks Remote Loading of Gateway Configuration Scenario Support Import Scenarios Export Scenario Sample Files Gateway Operations Using the Gateway Wizard Importing Content Importing Content From an External Document Re-importing Content Troubleshooting Import Errors and Warnings Exporting Content Gateway Logging Command Line Interface Gateway import Command Gateway export Command Item Interchange Format XML Elements The IIF XML Schema Wizard Configuration File XML Elements Import Configuration Export Configuration Sample Wizard Configuration File Sample Wizard Configuration for Filtered Export Gateway Configuration File How the Gateway Configuration File Works XML Elements Sample Gateway Configuration File Microsoft Word Support Replacing the Microsoft Word Integration With Gateway Exporting to DOCX Format DOCX Template Exporter Configuration Importing DOCX Files Importer Configuration Writing a DSD For DOCX Import

4 Testing and Debugging a DSD Using the Relationship Tree Adapter Embedded Object Support Bookmark and Cross-reference Support Caption Support Caption Representation in Integrity List Support Export of List Styles From Integrity to Microsoft Word Documents Sub-list Support Missing List Level List Information Stored in Attributes Continuous List Examples Non-continuous List Examples List Starting Number Examples List Type Support Index

5 C HAPTER O NE Installation 1 Installing Gateway Components This guide provides details on how Gateway supports importing documents into Integrity. This chapter provides information on installing and configuring Gateway. This chapter includes the following topics: Installation Requirements on page 6 Installing Gateway on page 6 5

6 Installation Requirements Before installing Gateway, ensure the following is installed: Integrity Client Integrity Server 1 A third-party application (such as Adobe Acrobat Pro for PDFs) may be required to create the XML source file used as input for the import. The application is not directly used by Gateway. IMPORTANT If using an Oracle Database with the Integrity Server, ensure that at least 4000 cursors are configured before installing and using Gateway. Installing Gateway Gateway is included with Integrity Client 2009 or later, and does not require a separate installation. To install (or uninstall) the Integrity Client, see the PTC Integrity User Guide. NOTE To use Gateway with an Oracle database, PTC recommends some performance tuning. Increase the setting Automatically extend datafile when full (AUTOEXTEND) from 5 MB to 10 MB (the recommended size for the Oracle tablespace). In addition, run Gather Optimizer Statistics. Parser Use and Configuration Gateway requires a parser to read content from a source file and transform it into the Item Interchange Format (IIF). The parser and its configuration may be the responsibility of your system administrator (see System Administrator Tasks on page 12). To write the parser, consult the Integrity Item Interchange Format specification (see Item Interchange Format on page 31). For information on configuring Gateway to use the parser during import, see Wizard Configuration File on page 39. The Wizard Configuration file also instructs Gateway to use a specific Gateway Configuration file. For details on that file, see Gateway Configuration File on page 51. TIP You can use an external parser to transform the document content into Item Interchange Format, and import that IIF file directly in the wizard without transformation. Exporter Use and Configuration Gateway requires an exporter to transform the Item Interchange Format (IIF) file into an external format. For information on the IIF specification, see Item Interchange Format on page 31. For information on configuring Gateway to use the exporter during export, see Wizard Configuration File on page Required for Gateway to connect to the Integrity Server. 6

7 The Wizard Configuration file also instructs Gateway to use a specific Gateway Configuration file. For details on that file, see Gateway Configuration File on page 51. The exporter and its configuration may be the responsibility of your system administrator (see System Administrator Tasks on page 12). Configuring JVM Gateway runs in its own Java Virtual Machine (JVM) instance. The default heap size values are: min heap size = 8 MB max heap size = 128 MB When working with large documents, PTC recommends increasing the maximum heap size. To configure the heap size settings, contact PTC - Integrity Support. 7

8 8

9 C HAPTER T WO Understanding Gateway 2 Overview of Importing Content From Documents This chapter provides an overview of Integrity support for importing content from documents using Gateway. This chapter includes the following topics: Gateway Import Overview on page 10 Scenario Support on page 13 Sample Files on page 15 9

10 Gateway Import Overview Gateway is a data-driven bridge between an external document format and Integrity. It provides a way to import content from an external source document file into Integrity, producing a document that has the full functionality available with Integrity for Requirements. Gateway Import Overview The following is a high-level overview of how to import content using the Gateway: 1 Obtain an external source document file containing content (see Source File on page 10). 2 Using the Gateway Import Wizard, select the parser used to transform content in the file into Item Interchange Format (see Item Interchange Format on page 31). 3 There may be fields in Integrity that require values that do not exist in the source document. In the wizard, specify additional field mappings as needed. For example, the project and category of the document. TIP If re-importing the document, specify the Integrity Item ID of the document so that the same document is updated and versioned (if the ID is not specified, then a new document is created). For more information, see Re-importing Content on page 23. NOTE The field mappings are configured in the Gateway Configuration file, and that file is specified in the Wizard Configuration file. Your system administrator may configure those files for you. For information on the Gateway Configuration file, see Gateway Configuration File on page 51. For information on configuring the parser to register and connect with Gateway, see Parser Use and Configuration on page 6. 4 Import the XML file into Integrity. Source File In this guide, Gateway uses an external XML formatted file as its source for importing content into Integrity. However, the source file can be any format if you provide a parser capable of transforming its content into Item Interchange Format (see Item Interchange Format on page 31). The available list of parsers is generated based on the file extension of the source file selected in the Gateway Wizard, while the list of available parsers is specified in the Wizard Configuration file (see Import Configuration on page 40). 10

11 Why Use the Item Interchange Format? The Item Interchange Format (IIF) is a PTC proprietary XML standard for documents that enables mapping of content and importing it into Integrity. For details on the IIF specification, see Item Interchange Format on page 31. Although Gateway provides a mechanism to parse content from a file, if you use your own external parser to transform that content into IIF format, you can directly import the output file into Integrity. Gateway Export Overview Gateway is a data-driven bridge between Integrity and an external document format. It provides a way to export content from Integrity to an external source document file, that can then be used in an external editor. Gateway Export Overview 1 Open the document in Integrity and then launch the Gateway Export Wizard. The document is automatically specified in the wizard. 2 Specify an exporter (see Exporter Use and Configuration on page 6) to transform the document into the desired format. NOTE The field mappings are configured in the Gateway Configuration file, and that file is specified in the Wizard Configuration file. Your system administrator may configure those files for you. For information on the Gateway Configuration file, see Gateway Configuration File on page Export the file to an external file. You can now use that file in an external editor. Gateway can export to any format, if you provide an exporter capable of transforming Item Interchange Format (see Item Interchange Format on page 31) to the desired format. The available list of exporters is generated based on those specified in the Wizard Configuration file (see Export Configuration on page 45). 11

12 System Administrator Tasks To simplify the import process, your system administrator may be responsible for configuring the Wizard Configuration file and Gateway Configuration file, as well as writing the parser. NOTE The Gateway Configuration file used during import is specified in the Wizard Configuration file. The following information is available to assist administrators with Gateway configuration: Parser Use and Configuration on page 6 Exporter Use and Configuration on page 6 Wizard Configuration File on page 39 Gateway Configuration File on page 51 Remote Loading of Gateway Configuration on page 12 Remote Loading of Gateway Configuration The system administrator may choose to provide the Gateway configuration files on the Integrity Server to be remotely loaded by Gateway. The benefit of a centralized location is that it ensures all users are using the correct configuration when importing files into Integrity. If the files are stored in the default locations, no configuration is required (see proceeding table). However, non-default locations must be specified in the following file: installdir/config/properties/is.properties where installdir is the Integrity Server installation directory. For information on configuring is.properties, consult the PTC Integrity Server Administration Guide. The following properties affect Gateway: Property mks.gateway.configdir mks.gateway.tool.configdir mks.gateway.tool.configfile Description Specifies the directory for Gateway Configuration files. The default location is: installdir/data/gateway/mappings/ where installdir is the Integrity Server installation directory. Specifies the directory for the Wizard Configuration file. The default location is: installdir/data/gateway/ where installdir is the Integrity Server installation directory. Specifies the file name of the Wizard Configuration file. The default file name is: gateway-tool-configuration.xml. For remote loading of DOCX templates and DSD files, see Exporter Configuration on page

13 Scenario Support This section includes supported scenarios that illustrate using Gateway with Integrity. They do not exhaustively document all possible actions, and are not intended as procedures. For information on performing the tasks, consult Gateway Import Overview on page 10 and Gateway Export Overview on page 11. The following topics are covered in this section: Import Scenarios on page 13 Export Scenario on page 15 Import Scenarios This section includes supported scenarios for using Gateway to import content into Integrity. Although the scenarios use requirements from documents as the source content for importing, other content may be used (see Source File on page 10). The following scenarios are supported for importing content: Import Third-Party Formatted File Scenario on page 13 Re-import Scenario on page 14 Import IIF File Scenario on page 14 Import Third-Party Formatted File Scenario Mary Chang is a team lead with KeyStroke Electronics company, designing a new portable audio player for a customer. The requirements for the player project are provided to the company by the customer in a third-party format. Mary needs to import the requirements into Integrity so that her team can work from them to create the product. Before Mary starts, she ensures she has all of the files needed to import the requirements from the file into Integrity. She obtains a document parser file that matches the type of requirements in the document (the Wizard Configuration file contains a reference to a Gateway Configuration file that maps all of the data from the file to fields in Integrity). Mary launches the Gateway Import Wizard, and selects that file. Mary also specifies the document parser provided to her to read the document data. Because some data is needed for Integrity that was not in the source file, Mary specifies that information. In this case, the information is the project MediaPlayer, and the category System Requirements. Now that all the data is inputted into the wizard, Mary runs a validation on the information and reviews it for correctness. There are no errors, so Mary continues and views a preview of the information being imported into Integrity. Because this is a first time import, all of the list items are marked as additions to Integrity. Mary is satisfied that the information is correctly represented, and runs the import operation. The import proceeds, and the results display. Mary then opens the document in Integrity, and uses those requirements to assign and track work for her team. 13

14 Re-import Scenario Patrick Molinas is a lead software architect with SuperSoft company. Patrick is notified by his product manager that the requirements he is working from to design his software application have changed. Patrick needs to update the requirements document stored in Integrity with the new ones. The product manager provided Patrick with an XML file containing the requirements (outputted from Adobe Acrobat Pro). Patrick needs to re-import those requirements into Integrity. Before Patrick starts, he ensures he has all of the files needed to re-import the requirements from the file into Integrity. He obtains a document parser file that matches the type of requirements in the file (the Wizard Configuration file contains a reference to a Gateway Configuration file that maps all of the data from the file to fields in Integrity). Patrick launches the Gateway Import Wizard, and selects that XML file. Patrick also specifies the document parser provided to him to read the document data. Because some data is needed for Integrity that was not in the source file, Patrick specifies that information. In this case, the information is the project HappyApp, and the category Software Requirements. Also, because this is a document that was previously imported in Integrity, Patrick enters the Integrity item ID for the document. This updates the document on import, rather than creating a new document. With all the data inputted into the wizard, Patrick runs a validation on the information and reviews it for correctness. There are no errors, so Patrick views a preview of the imported information. Because this is a re-import, there are not only additions to Integrity, but changes specified as well. Patrick also notices some content deletions (marked with - symbol); and after confirming with his product manager, decides they are acceptable. Patrick is satisfied that the information is correctly represented, and runs the import operation. The import proceeds, and the results display. Patrick opens the document in Integrity, and notices that the document is versioned, with the reimported requirements as the current version, and the original requirements a previous version. Patrick uses the new version of the document to assign and track work for his team. Import IIF File Scenario Wendy Patterson is a software architect at AnyTime Solutions. Wendy s manager previously used an external parser to create an IIF file containing the requirements for the project, and provided that IIF to Wendy. Wendy needs to import the requirements from the IIF into Integrity so that she can use them to design the software application. Wendy launches the Gateway Import Wizard, and selects that IIF file. Because the file is in IIF format, Wendy specifies the default document parser Sample IIF Importer. Because some data is needed for Integrity that was not in the source file, Wendy specifies that information. In this case, the information is the project HydroApp, and the category Software Requirements. Now that all the data is inputted into the wizard, Wendy runs a validation on the information and reviews it for correctness. There are no errors, so Wendy continues and views a preview of the imported information. Because this is a first time import, all of the list items are marked as additions to Integrity. Wendy is satisfied that the information is correctly represented, and runs the import operation. The import proceeds, and the results display. 14

15 Wendy then opens the document in Integrity, and uses those requirements to create items to track her work and product design. Export Scenario Neil Singh is an analyst for KBJ Communications. He needs a copy of an Integrity document to work with a word processor and send to clients. Neil opens the document in the Integrity Client, and then launches the Gateway Export Wizard. The document ID for the document he was viewing is already specified in the wizard. In the wizard, Neil specifies an exporter for the file format he needs (DOCX). The wizard then retrieves the document information from the Integrity Server and Neil reviews it to ensure it contains the information he intends to export. There were 5 warnings in the document, so Neil reviews the log file and determines that no action is required to resolve the warnings. Neil then exports the document to the DOCX format. The export was successful with the results and confirmation displayed in the wizard. Neil can now use the exported file. Sample Files Integrity provides samples to assist with import and export operations, with the Integrity Client, Integrity Server, or the Integrity Support Center found at: IMPORTANT PTC may update sample files in service packs or product releases. It is important that you rename the sample files you choose to modify and use (ideally copying the sample as a new file with a new name) so that the files you are using are not changed by a future update. When copying and renaming a sample Gateway Configuration File for use in your system, the mapping name in the XML header must also be edited to a suitable name. For information on sample DOCX templates included with Gateway, see Sample DOCX Templates on page 75. Integrity Server-side Samples Sample Gateway Configuration files are installed with Gateway in the following location: installdir/data/gateway/mappings/ where installdir is the Integrity Server installation directory. The following sample is included and self-documented: IIF_Document.xml. To use a sample Gateway Configuration file, configure it to match your specific installation. Integrity Client-side Samples Sample Gateway Configuration files are installed with Gateway in the following location: installdir/config/gateway/mappings/ where installdir is the Integrity Client installation directory. 15

16 The following samples are included and self-documented: Document_Export.xml MS_Word_Requirements_Document_ExternalID.xml Sample_Requirement_Document_Import_Reimport.xml Sample_Test_Suite_Import_Reimport.xml MS_Word_TestSuite_Document.xml Samples are intended for use with the ALM template and may require modification for use with your implementation of Integrity. To learn more about the ALM template, view the Integrity solution templates (which provide reference implementations of Integrity). The solution templates and accompanying documentation are available from the Integrity Support Center at: 16

17 C HAPTER T HREE Gateway Operations 3 GUI Tool for Importing Content From External Documents This chapter provides information on the Integrity Gateway Wizard, a graphical user interface for importing content from external documents into Integrity. This chapter includes the following topics: Using the Gateway Wizard on page 18 Gateway Logging on page 27 Command Line Interface on page 27 17

18 Using the Gateway Wizard Gateway provides GUI support in the form of a wizard for importing external document content. For more information on Gateway, see Gateway Import Overview on page 10. For information on using the Gateway Import Wizard, see Importing Content From an External Document on page 18. For information on the functionality available through the command line interface (CLI), see Command Line Interface on page 27. Importing Content This section provides information on using Gateway to import content into Integrity. The following topics are covered: Importing Content From an External Document on page 18 Re-importing Content on page 23 Troubleshooting Import Errors and Warnings on page 23 Importing Content From an External Document This section provides information on importing content from an external XML file (see Source File on page 10) using the Gateway Wizard. IMPORTANT When using the Gateway Import Wizard, the import operation is not committed until you click Import on the Preview pane. Prior to committing the operation, you can make changes and revisions. CAUTION While the first import is in progress, do not start a second import operation. Key Considerations During processing, the Gateway Wizard stores a temporary copy of IIF files and attachment directories to the system Temp directory as configured for your system. By default, the location is: C:\Documents and Settings\UserName\Local Settings\Temp where UserName is the currently logged in user name. For UNIX clients, the location is /tmp. The files are deleted when the user exits the wizard. The directories are not deleted. Gateway supports importing sub-documents (documents contained in documents as a nested hierarchy). To change the MKS ID value, manually edit the IIF file. Alternatively, if the input data is suitable, use REQUIREMENT_ID values from the document and enable ID priming (by changing the Gateway Configuration file to make use of a content link-field). 18

19 PTC recommends configuring Integrity to prevent users from editing fields in items affected by re-importing a file. Contact your Integrity administrator for assistance, or consult the PTC Integrity Server Administration Guide. Integrity supports populating fields on creation of items only as effectively as the rules that describe when fields can be updated (and not updated). When re-importing a file, all configured fields are available for the user to input values into; but the values may appropriately not be applied during the operation. The Integrity Project field is one such field that is ignored during a re-import process, and others may exist based on your specific Gateway implementation. When viewing a large document in Integrity at the same time you are using Gateway to import a large document (possibly due to large image files), a JavaHeapSize error may occur. To reduce the risk of error, PTC recommends exiting the Integrity Client before starting the import, or increasing the Integrity Client heap size setting (see the PTC Integrity User Guide). Ensure Integrity field sizes are large enough to accommodate content from imported documents, because Gateway permits users to exceed the field size limits when importing documents (bypasses field size limits). To import content from a document in the GUI 1 To launch the Gateway Import Wizard, do one of the following: Select Document > Import. NOTE You may need to add the command to your ViewSet (see the PTC Integrity User Guide). From the console, run the command Gateway import (see Gateway import Command on page 27). The Gateway Import Wizard launches. The first step of the wizard is the Configure Select File pane. Under Configuration, specify the following: File specifies the file to import. For more information, see Source File on page 10. TIP You can also specify a ZIP file containing an IIF file named item.iif at its root. Import Configuration specifies the configuration (which may specify a parser) to use to read the document data from the source file. Select the parser from a list. The list is determined by the file extension of the file you specified in the Select File field, and generated using information from the Wizard Configuration file (see Import Configuration on page 40). The description for the selected configuration displays below it. TIP For IIF files, Sample IIF Importer is available in the commented section of the serverside Wizard Configuration File. 19

20 Under Fields, specify the field mappings, if needed. These may be fields in Integrity that require values that do not exist in the source document. The available mappings are derived from the Wizard Configuration file (see Wizard Configuration File on page 39). NOTE Red field labels denoted with an asterisk (*) are mandatory. The following are examples: Document ID specifies the ID of the root document item. The value is only required (and relevant) when re-importing a document (see Re-importing Content on page 23). For new documents, do not enter a value. An ID is automatically assigned on import. Project specifies an optional Integrity project to assign the document on import. To continue, click Next. If you are importing a file other than IIF, the Creating IIF from input file dialog box displays. When the IIF file is created, the Select Content pane displays. 2 From the Select Content list, select the document to import. To continue, click Next. 3 From the Configure: Validation pane, review the information specified in previous steps. The validation step verifies that each field marked as required in the Gateway Configuration file contains a value. If the validation step fails, click Back and then correct the problems before resuming the wizard. For more information, see Troubleshooting Import Errors and Warnings on page 23. To continue, click Next. 4 If a document ID was specified in a previous step, Gateway evaluates the document and determines if the content matches existing content in Integrity. From the Preview pane, review the document information on the Summary and Review tabs. The Summary tab provides sum values for the changes. To generate a report, specify the location under Output File Location and then click Generate Report. The fields in the report match those in the Review tab (specified in the Gateway Wizard Configuration, see Wizard Configuration File on page 39). If the filename already exists for the generated report, you are prompted to rename the file. If you generate the report anyway, the file is appended with a sequential numerical digit. The Review tab provides details about the changes and a preview of the document. If no document ID was specified, the document is considered new and all content is represented with the Added status type. Selecting a content item in the one pane selects the match for that content in the other pane. For example, the Importing Document pane highlights its corresponding Integrity content item in the Integrity Document pane. If needed, nodes expand to display the item. The Review tab of the Preview pane displays the following information: 20

21 Field Status Description Displays the type of change to the Integrity document that results from the import. The Status text appears in the Details pane, and corresponds to the icon selection in the Importing Document and Integrity Document panes. Added indicates content added to the document. Indicates content added to the document and changes to its children. Expand the node to see the changes. Changed indicates content changes in the document. Indicates content changes in the document and its children. Expand the node to see the changes. Moved indicates content moved in the document to another location in the tree. Indicates content moved in the document and changes to its children. Expand the node to see the changes. Moved and changed indicates content changes in the document and the content moved to another location in the tree. Indicates content moved and changed in the document, and there are changes to its children. Expand the node to see the changes. Deleted indicates content deleted (removed) from the document. Indicates content deleted from the document and changes to its children. Expand the node to see the changes. Unchanged indicates content is identical in the imported document and Integrity. Indicates document content is unchanged, and there are changes to its children. Expand the node to see the changes. Integrity ID Field Importing Value Integrity Value If available, displays the item ID of the content item in Integrity. To view the item, or the document (if it is mapped to the Integrity Document Model) in Integrity, click the ID. Caution: When re-importing document data, each click on the Integrity ID link for a document launches a new Document view. Since loading large documents can be a client resource intensive operation, you may want to limit your use of the link. When a field is selected, displays the field name as specified in the Gateway Configuration File. Fields are displayed if they are specified in the Gateway Wizard Configuration file (see Wizard Configuration File on page 39). The fields are specified using the <review-fields> element, and appear in the same order as specified, except for the first field presented (which is the first rich text field in the list of comparable fields in the Gateway Configuration File used for field mapping). Rich text is displayed as plain text when displayed in the tree. Displays the value for the selected field in the imported document. Displays the value for the selected field in Integrity. Note: Integrity bookmarks do not display as fully functioning hyperlinks. The bookmarks display in the Details pane with a blue outline; however, clicking them does nothing. If you disagree with the type of change (or its content item match), you can right-click the content item and select Override Status and then make a selection. Available status types appear for selection based on the type of change. For the Importing Document pane: Added can be converted to Changed. Changed can be converted to Add. Unchanged can be converted to Add. 21

22 For the Integrity Document pane: Deleted can be converted to Changed. Changed can be converted to Deleted. Unchanged can be converted to Deleted. Converting to Changed requires a selection from the Override Status dialog box to create a new content item match. The Override Status dialog box includes its own Details pane to assist you in determining if the item you intend to select is a match. For ease of use, right-click and select Expand All to see children of all nodes in the document tree. Visually compare the preview with your original source document and make overrides as required. When you are satisfied with the content and that the document is ready for import, click Import. The import operation begins and the Results pane with Importing requirements displays. The results pane displays the following information: Processed Items lists the number of unique items edited or published to the Integrity Server. Skipped Items lists the number of items skipped (not processed). Items are skipped either based on the Gateway Configuration file settings (see Gateway Configuration File on page 51) or due to errors in publishing the item or its parent item. Deleted Items lists the number of items deleted during re-import (not applicable for new imports). NOTE If there is an error or failure while updating, some items may not be deleted, and are not included in Deleted Items, Skipped Items, or Processed Items totals. If any items will be deleted, Integrity displays a warning message, indicating how many items will be deleted and that any important information such as trace relationships will also be deleted. PTC recommends confirming the affected item(s) in the Review tab. Errors Encountered lists the number of errors encountered during the import. When the import completes, click View log file to view error details. For more information, Gateway Logging on page 27 and Troubleshooting Import Errors and Warnings on page 23. Warnings list the number of warnings encountered during the import. When the import completes, click View log file to view warning details. For more information, Gateway Logging on page 27. Created Document with ID displays the ID of the root document created in Integrity to correspond to the imported document. In the case of a re-import, the value is the item ID for the document updated and versioned. A progress bar displays the percentage of completion for the import operation. TIP The results pane displays the estimated time remaining for the import operation to complete. The estimated time changes, depending on information processed while the import is in progress. The estimated time is based on the average time it has taken to process an item. 22

23 If the import is successful, Success displays. To view the log, click View log file (see Gateway Logging on page 27). If Failed to import the document displays, the import is unsuccessful. To resolve the problem, close the wizard and then start the import again. For more information, see Troubleshooting Import Errors and Warnings on page 23. Re-importing Content If you are using the samples provided, re-import by specifying the document ID in the Document ID field on the Select Configuration pane of the Gateway Import Wizard. Key Considerations When re-importing documents, ensure that you are importing the correct file. Gateway does not verify if you are re-importing the correct document, even if it is a completely different document with a different file name and content. PTC recommends that you configure Integrity to prevent users from editing fields in items affected by re-importing a file. Contact your Integrity administrator for assistance. Because Gateway performs HTML tag replacement on unsupported tags, re-importing a file may take longer due to the increased comparison time. Additionally, the tag replacement operations appears as changes in the Integrity item history for content. When re-importing a document exported from Integrity without usable IDs, Gateway attempts to match textual changes to existing items, even if those items were moved within the document tree. Larger requirements with changes are easier for Gateway to match than smaller requirements with changes. Formatting changes are not considered comparable differences in large requirements. If items cannot be identified (either because there is no ID or because the change wasn t significant enough), then Gateway creates new items and drops old ones as needed. Samples for re-importing documents are available in Sample Files on page 15. Troubleshooting Import Errors and Warnings The following table provides information on troubleshooting import errors in the Gateway.log file: Error Configuration file error: Mandatory field mismatch for field <configuration field>. Data is missing for optional field <configuration field>. Resolution Error occurs because a configuration field is marked as required, but no data for that field exists in the content parsed from the source file. If the data is not required from the source file, modify the parser configuration so that the field is not mandatory. If the data is required and exists in the document, modify the document parser so that the value is parsed correctly. Warning occurs when the mapping configuration defines a field that is not required, and no data exists in the content parsed from the source file. The warning states that there is no data to save to Integrity for this field. 23

24 Error Data will be ignored for field <configuration field>. Field <configuration field>, configured to link input to MKS items, is not present. General punctuation was found and mapped to '?'\n" if $line =~ s/ \p{general Punctuation}/?/g The value for field <configuration field> should not be empty. Unable to retrieve previous import data Resolution Warning occurs when a source has provided data for this field, but the mapping configuration is not configured to accept that field. The warning states that there are data fields present in the input file that cannot be saved to Integrity with the current configuration. Error occurs if a link-field (configured in the Gateway Configuration file) does not exist in the content parsed from the source file. Ensure that the fields configured as link fields are present in the document, even if they are empty or have no value. If there is value in the source document, ensure that the Wizard Configuration file is configured to ask for the value. Alternatively, if there is no value in the source document, ensure that the parser is generating an empty value for the field. Warning occurs if UTF-8 characters in the General Punctuation Unicode block are not correctly escaped. Modify the parser to escape those characters. Error occurs in conjunction with Configuration file error: Mandatory field mismatch for field <configuration field>. Error occurs when a configuration field is marked as required, but no data has been provided by any source. If DEBUG logging is enabled, Gateway attempts to determine the most likely cause of the error. Error occurs on re-import only. Ensure that the document ID entered is correct, and that item has a source IIF file from the previous import attached to it in Integrity. Additionally, ensure the Gateway Configuration file has the prior-data-field and prior-data-name settings configured correctly. Exporting Content This section provides information on using Gateway to export documents from Integrity to an external file format. Key Considerations Gateway supports exporting sub-documents that are children in the hierarchy of the root document you are exporting. For information on sub-documents, see the PTC Integrity User Guide. If you do not intend to allow edits of the exported documents by a user other than yourself, ensure that the mapping file only permits edits on import by your user ID (set at the time of first export). This ensures that only your changes are included on import of the document. CAUTION If you permit edits by other users, your data may be lost from the document (and corresponding Integrity items deleted) upon import. To configure the mapping file, refer to the owner property in the <set-property> element. For Double, Float, Integer, and Long field types, Gateway uses the actual field value and not the display value. This may have an impact on importing a document that was exported. 24

25 To export content from a document in the GUI 1 To launch the Gateway Export Wizard, choose the document you want to export and select Document > Export. NOTE You may need to add the Document command to your ViewSet (see the PTC Integrity User Guide). To export an historical document, you can also launch the Gateway Export Wizard from the historical document view. The Gateway Export Wizard launches. The first step of the wizard is the Configure pane. Under Configuration, specify the following: Integrity Item IDs specifies the Integrity item number of the root item for the Document you are exporting. The value for this field is determined by the document itself and is only editable if the wizard is launched from the console (see Gateway export Command on page 29). Export Configuration specifies the export transformer file to be used to create the output document file. The list is determined by the configuration in the Wizard Configuration File (see Export Configuration on page 45). Under Options, specify the following as required: Filter specifies the filter query definition to be applied on the exported document. The available options are: None does not filter the exported document. This is the default setting. User Specified applies a filter that you define. You can define the filter in the Integrity Document view. For more information on the Document view, see the PTC Integrity User Guide. Filters can also be defined using the Gateway command line interface. For more information, see Gateway export Command on page 29. From Configuration automatically applies the filter that is defined through the Gateway configuration file. For more information on the required XML syntax for the filter query definition, see <filter-query-definition> on page 46. NOTE To view the filter that Gateway will apply, click Show Definition. The Filter Definition dialog box displays the definition. If you need to save that definition, you can manually copy the text to another file. To dismiss the dialog box, click OK. When applying a filter query definition to a document, you cannot use a text-only filter; however, you can use a filter that specifies "any text field contains". Structure specifies the Show Parentage option. When enabled, all ancestors in the exported document are shown, from leaf nodes to the document root. To use this option, you must also specify a filter. By default, parentage is not shown. If the Document view is configured to show parents in filtered documents (and a filtered is applied), the Show Parentage option is enabled. The Show Parentage option can also pre-set through the Gateway configuration file. For more information on the required XML syntax for showing parentage, see <showparentage> on page 47. As of specifies a previous version of the document to export (exporting an historical document) as of a specific date or label. If no value is specified, the current date and time is used. 25

26 The following panel shows a sample export configuration: To continue, click Next. The Retrieve pane displays the progress of retrieving the document from Integrity. 2 From the Retrieve pane, review the document information. The Retrieve pane contains a summary of the items that the document is composed of, as well as a log of any errors or warnings encountered during retrieval. To resolve any problems, see Troubleshooting Import Errors and Warnings on page 23. To continue, click Next. 3 From the Export pane, review the Export Configuration and summary information, and ensure you are satisfied with it before starting the actual export. 4 In the Select File field, specify the file name you are exporting the document to. The default file name is of the form: itemid - date.fileextension where itemid is the ID of the document (root Integrity item) you are exporting. date is the date of export. fileextension is the file type. For example, iif. 5 To export the document, click Export. The document is exported to the specified file. 26

27 NOTE If you specified a filter, the resulting exported document includes only the content segments defined in that filter. If you specified an external script exporter as your export configuration, additional dialog boxes may display. To view the export log, see Gateway Logging on page 27. There are currently no known issues with re-exporting documents using Gateway. Documents are re-exported in the same way they are exported. However, if exporting to the same file, it is the exporter configuration (see Exporter Use and Configuration on page 6) that determines if the file is overwritten or appended. Gateway Logging Gateway provides a log file that contains information useful for troubleshooting problems. View the log from the Gateway Wizard results pane by clicking View log file. The log file is displayed in the default editor configured for your operating system, for example notepad.exe. The log file is generated in the following default location: installdir\bin\gateway.log where installdir is the location the Integrity Client is installed. By default, Gateway is configured to maximum logging levels. To configure Gateway.log (including turning debug on), contact PTC - Integrity Support. Command Line Interface This section provides information on the commands available from the command line interface. IMPORTANT At this time, Gateway does not return the necessary information to the console to make it suitable for scripting purposes; however, some information is written to Gateway.log (see Gateway Logging on page 27). To make full use of this information, Gateway must be launched from the Integrity Client GUI. Gateway import Command The Gateway import command imports content into Integrity. For detailed information on importing content from an external file, see Gateway Import Overview on page 10 and Importing Content From an External Document on page 18. CAUTION While the first import is in progress, do not start a second import operation. From the command line, type: Gateway import [--user=value] [--password=value] [--hostname=value] [--port=value] [--config=value] [--file=value] [--fields=value] [--fieldsdelim=value] [--silent] [--importmode] 27