Interfaces COMOS. Platform Interfaces. Trademarks 1. XML connectors. Standard import: Blank for XML

Transcription

1 COMOS Platform Operating Manual Trademarks 1 XML connectors 2 Standard import: Blank for XML 3 Tabular reimport 4 Reimporting a file or a directory 5 Standard import: Blank for tables 6 PCS 7 - COMOS data transfer via Automation 7 Interface AutoCAD (Export, Import DXF) 8 COMOS Document Interface (CDI) 9 RTE (Report-to-Excel) 10 Values in XML 11 NOXIE Plugin 12 Synchronizing COMOS databases 13 Engineering projects 14 Base projects 15 Templates 16 System projects 17 WMF data 18 COMOS interface with Teamcenter 19 09/2011 A5E

2 Legal information Legal information Warning notice system This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger. DANGER indicates that death or severe personal injury will result if proper precautions are not taken. WARNING indicates that death or severe personal injury may result if proper precautions are not taken. CAUTION with a safety alert symbol, indicates that minor personal injury can result if proper precautions are not taken. CAUTION without a safety alert symbol, indicates that property damage can result if proper precautions are not taken. NOTICE indicates that an unintended result or situation can occur if the relevant information is not taken into account. If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage. Qualified Personnel The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems. Proper use of Siemens products Note the following: WARNING Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed. Trademarks All names identified by are registered trademarks of Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner. Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions. Siemens AG Industry Sector Postfach NÜRNBERG GERMANY A5E P 09/2011 Copyright Siemens AG Technical data subject to change

3 Table of contents 1 Trademarks XML connectors Introduction Requirement Structure of an XML connector Connector document Connector template Basic principle of XML connectors "Envelope" field Supported codes Creating an XML connector Create at least one object query Generating an XML connector document Configuration of object queries Opening the configuration tool Configuration of queries Column properties Creating objects with different base objects via an object query "Extra" tab Configuration tool General information (fields above the tabs) "COMOS" tab "XML" tab "Mapping" tab "Assembly" tab "Error" tab Configuration for the export Basic principles Exporting XML attributes: XML mapping Comparing XML data and COMOS data Nested object queries / data hierarchy Configuration for the import Key columns Master column Expressions only supported the import Drag&drop mapping Using an XML connector Other options in the configuration tool Define COMOS collection: REFID Mapping table / assignment table for values...36 Operating Manual, 09/2011, A5E

4 Table of contents "COMOS info" column Check column XML fragments (XFRAG) Basic concept of data mapping Basic concept of data mapping Generating references (links) Connector expansion with C# assemblies Connector expansion for C# assemblies Creating a new C# assembly Loading existing assemblies Class documentation "ICodeProviderActions" interface "IAdapterActions" interface "IJobHelper" interface "IXMLExecJob" interface Preprocessing / postprocessing: The adapter "Custom" adapter type All other settings in the XML connector Properties of a column, Extra Options of a column, MotionX Direct help in the XML connector "Script" tab Maintaining old connectors prior to version Reusing object queries Query pointer XML adapter Triggering connectors via a script Standard import: Blank for XML Scope and concept of the table import function Application Tabular reimport General Call Overview Read the data into the query Preparing read data for the reimport Carry out the reimport Error messages Reimporting a file or a directory General Call Overview Procedure Operating Manual, 09/2011, A5E

5 Table of contents 6 Standard import: Blank for tables Overview: Scope of services and concept The interface of a table import Properties of an action object The interface in the draft mode The interface for the runtime mode (execute) Import sources Access Excel Text file Script for import actions Complete overview of an import script Script modules Declarations Example PCS 7 - COMOS data transfer via Automation Interface AutoCAD (Export, Import DXF) Export Preparations: DWG/DXF mapping editor Conducting an export Scope of the interface Import Import of an AutoCAD object Preparing fonts Import step Mouse menu of the AutoCAD object Import step 2: Dissolving the drawing into engineering objects Preparations: DWG/DXF mapping editor Other import settings Central base data branch for DXF imports Adjustments for the import Scope of the interface Import step 2: Dissolving the drawing graphically Only display AutoCAD files COMOS Document Interface (CDI) Initial situation and aim Overview Evaluation reports Office link CDI method: Requirements Software Licenses Microsoft Office configuration CDI method: Operation Creating an Office document Preparing Office documents Operating Manual, 09/2011, A5E

6 Table of contents Working in the CDI plugin Export Reimport Reference of the programming interface Get Property: Document Get Property: MappingTableExcel Get Property: Project Get Property: ReportObject Get Property: Workset Function: ExcelABC Function: Content Function: ContentFix Examples and scripts Excel Word Changes to the Word document Technical procedure Export COMOS -> Word Export COMOS -> Excel and Import Excel -> COMOS Special case: Checkboxes and combo boxes RTE (Report-to-Excel) Area of application Preparation of the evaluation report Start export Using the report in Excel Control via the options script Reimport Values in XML NOXIE Plugin Aim Export Import Structure of the generated XML file Synchronizing COMOS databases Overview Data collisions Engineering projects Import Base projects Export Operating Manual, 09/2011, A5E

7 Table of contents 16 Templates Import System projects Import WMF data Import COMOS interface with Teamcenter Basic principles Aim Terms Workflow overview User interface reference "Teamcenter login" window Status area "Synchronize plant from Tc" window "Synchronize plant to Tc" window "Element properties" window "Select Tc resource" window Data transfer from Teamcenter to COMOS Basic principles Mapping a unit from Teamcenter Checking and making settings Synchronizing a unit from Teamcenter Data transfer from COMOS to Teamcenter Basic principles Checking and making settings Synchronizing a unit to Teamcenter Documents for Teamcenter Checking settings Publishing documents Changes in COMOS Creating a mapping object Specifying an instance assignment Administration Basic principles Aim Naming conventions User interface reference "Teamcenter units of measurement" tab "CTI attribute mapping" tab "CTI resource mapping" tab "Element properties" window in the base objects view "Synchronize resource info" window "CTI instance mapping" tab Teamcenter configuration Defining the "Application Interface" with transfer types Operating Manual, 09/2011, A5E

8 Table of contents Setting Teamcenter options Making changes in the "Default.xml" file Project in Teamcenter Creating the "Collaboration Context" and "Structure Context" for resources Specifying resources and types for the assignment Creating an "Application Interface" Creating a "Collaboration Context" for an existing unit Creating a "Collaboration Context" to synchronize a unit from COMOS Installing the buffer component for the COMOS client Settings in COMOS Synchronizing resources Assigning units of measurement Assigning resources and types Assigning attributes Synchronizing resource information Preparations for publishing documents Operating Manual, 09/2011, A5E

9 Trademarks 1 Trademarks Registered trademark: COMOS Operating Manual, 09/2011, A5E

10 Trademarks 10 Operating Manual, 09/2011, A5E

11 XML connectors Introduction An XML connector is an object of the document type used to build interfaces. The XML connector consists of a template, in which the configuration is stored, and the document. An XML connector additionally requires object queries to create the mapping between XML data and COMOS data. Following specialties are provided by an XML connector: Checking data in and out Mapping via XPath Support for object queries in order to find objects Scripting to enhance the functions Triggering processes via the Enterprise server Interface between COMOS and external applications Delta management Versioning Function XML connectors import and export data that are structured in accordance with a valid XML format. The XML format does not necessarily need to correspond to COMOS s own XML format. The mapping between COMOS data and XML data can be basically bidirectional. An XML connector in COMOS can be used to both read and to write XML data. 2.2 Requirement The following requirements must be met when working with XML connectors: You have experience with object queries. Before you create and implement XML connectors, define the design structures and objects to be imported or exported. You need to be familiar with the target XML structure described by the data. This simplifies the configuration of the XML connectors. Operating Manual, 09/2011, A5E

12 XML connectors 2.3 Structure of an XML connector 2.3 Structure of an XML connector Connector document Overview COMOS XML connectors are documents of the type "XML connector document". You usually create documents on the "Documents" Navigator tab or link the document to the tab. Document groups To make the layout of the "Documents" Navigator tab clearer, you can combine documents to create document groups. Connector documents that were triggered via the Enterprise server should be saved in an own document group. Create this document group directly underneath the project node. Name the document group Connector documents that are not triggered by the Enterprise server can be saved at any location in COMOS where documents are allowed. Reference object You assign a template and a reference object to the object on the "XML document" tab in the properties of the connector document. The reference object is the start object of the XML connector document and contains the objects that are exported. The objects to be imported are created underneath the reference object. The reference object is stored in the connector document, not the connector template. It can be changed when the connector document is triggered. Configuration Configurations of the connector document are stored in the connector template. When you open the connector document for the configuration, the available configurations are loaded from the connector template. 12 Operating Manual, 09/2011, A5E

13 XML connectors 2.3 Structure of an XML connector Connector template Overview The template for XML connector documents must be an "XML connector template" type. Every XML connector document must be linked to a connector template. A connector template can be linked to several connector documents. Create a document group for connector templates. Assign the "@O Documents > XML XML Document" base object or an object underneath it to the connector template Basic principle of XML connectors Structure of a typical XML file XML files contain a tree-like structure. The individual levels of the hierarchy are collections of similar elements. You can freely choose the names of these collections. The name "Loops" is used in the following example. <?xml version="1.0" encoding="utf-8"?> - <XML_Export xmlns=" - <loops Test=""> <loop no="f4455"/> <loop no="l4444"/> <additional_loop_data> -<loop_identification> <subproject_no>w1</subproject_no> <unit_main_no>h1</unit_main_no> <unit_sub_no>t1</unit_sub_no> </loop_identification> </loops> </XML_Export> In the "<loops Test="">" level of the collection, there are two "loop" nodes, which represent the elements of the collection. Operating Manual, 09/2011, A5E

14 XML connectors 2.3 Structure of an XML connector "Envelope" field Overview The "Envelope" field can be found on the "Attributes > XML" tab in the properties of the XML connector document. To edit the field, click on the "..." button. You can use the "Envelope" field to enter fixed strings to enclose the XML content and declare the XML format. The XML version and the code used are displayed here. The following rules apply for the "Envelope" field: The root node of the XML file must match the node that you have specified in the "XML start node" field of the configuration tool. If you want to use XML name spaces, you must enter them in the "Envelope" field. Example <?xml version="1.0" encoding="utf-8"?> <CAETest xmlns=" xmlns:cis=" <Content/> </CAETest> You then insert the data created in the XML connector at the location of the <"Content/"> placeholder Supported codes MotionX supports codes up to UFT-16. Pure Unicode, such as UTF-32, is not supported. Example To ensure correct procesinig of the XML file, the following definition cannot be included: <?xml version="1.0" encoding="utf-32"?> 14 Operating Manual, 09/2011, A5E

15 XML connectors 2.4 Creating an XML connector 2.4 Creating an XML connector Create at least one object query Overview Queries are required. There are two ways of linking queries to the connector: Option 1 1. Open a query. 2. Click on the "COMOS" tab. 3. Click on the "Save / Load..." button and select the "Save as..." command from the list. The "Save as..." window opens. 4. Drag&drop the XML connector template into the "Save as" field. 5. Enter a name for the query in the "Name" field. 6. Click on the "OK" button. Option 2 Once you have created the connector document, you can also create the object query using the configuration tool of the XML connector document. 1. Mark the connector document. 2. Click "XML > Configure XML connector" in the context menu. See also chapter Configuration tool (Page 22). 3. Click on the "..." button next to the "Query" list. 4. In the "Edit queries" window, right-click on the XML connector template and select the "New > Query" command from the context menu. 5. The "Edit query container" window opens: 6. Enter the desired name in the "Name" field. 7. Select a query type in the "Base object" field. See also chapter Configuration of queries (Page 17). 8. Click on the "OK" button. The "Edit queries" window opens: The query is now displayed. You can arrange queries in a hierarchy. See also chapter Nested object queries / data hierarchy (Page 27). Operating Manual, 09/2011, A5E

16 XML connectors 2.4 Creating an XML connector "Base objects" Navigator tab If you have already worked with XML connectors in the database, you find the basic types at the following location: system settings data data" These object queries have no default settings or permission restrictions. The node is created automatically by COMOS when you create a new object query using the configuration tool. Click the "OK" button to apply the settings. A node is created. If this node does not yet exist, you will find the object queries at the following location: "@Q Action: Decision tables and object queries" Rule Check if the object query can be fully edited Generating an XML connector document Procedure To create an XML connector document, proceed as follows: 1. Open the engineering project 2. Select the "Units" or "Locations" Navigator tab. 3. Create a new document of the "XML connector document" type. 4. Open the properties of the document. 5. Select the "XML document" tab. 6. Click the "..." button next to the "Template" field. The attributes in particular are inherited from the template and the object queries underneath it are evaluated. 7. Assign a template to the document. 8. "Reference object" field You can change the default setting. This field also sets the default setting for the "Query start object" field. 9. "Import" button/"export" button Click this button to open the "MotionX import"/"motionx export" window. A common XML connector document The same XML connector is used for import and export, i.e. the same XML connector document with the same XML connector and template. 16 Operating Manual, 09/2011, A5E

17 XML connectors 2.5 Configuration of object queries 2.5 Configuration of object queries Opening the configuration tool Procedure To open the configuration tool, proceed as follows: 1. Right-click on the XML connector document. The context menu opens. 2. Select the "XML > Configure XML connector" command. Result The configuration tool opens Configuration of queries Overview To select a query type for the XML connector document, click in the "Base object" field in the "Edit query container" window. The following query types are available: Query for base objects Query for connectors Query for engineering objects Query for documents Query for attributes Query pointer See also section Reusing object queries Query pointer (Page 54). Which query type you select depends on the object you process. You can find the queries listed here in the base project on the "Base objects" Navigator tab under the "@System data" node. You also save predefined queries under this node. The queries you created can then be selected in the "Base object" field. Rule Test the object query before linking it to the XML structure. Operating Manual, 09/2011, A5E

18 XML connectors 2.5 Configuration of object queries Naming object queries The name of object queries for connector documents must begin with a letter. Names of queries are used in the script as name of subfunctions. Subfunctions must begin with a letter due to a Microsoft convention. A script error occurs if a subfunction has a number as its first character. Special tasks for importing You only have to configure the object queries for imports to ensure they are also capable of creating new row objects. You find additional information on this topic in the "Queries" manual Column properties Overview When you open an object query, you see the table with the column headers. You can also access this view via the configuration tool, "COMOS" tab. To display the properties of each column, proceed as follows: 1. Call the context menu via the column header. 2. Select the "Properties" command. The "Properties" window opens for that column. The following tabs are provided for each column: Tab "General" "Object evaluation" "Value calculation" "Object by value" "Extra" "Languages" Description You make general settings for the column properties here. Used to evaluate an object. The information gathered from this object is displayed in the object browser. Value calculation uses the object of the object evaluation for further information processing. This means that the value calculation cannot supply a result unless the definition provided on the "Object evaluation" tab is correct. You define rules for creating new objects. This requires that you select the "Options" command in the column header context menu. Enable the "Permit new row" option in the "Editing type" control group on the "General" tab. You make additional settings for the column properties here. The name of the column is output in English and German. You find additional information on this topic in the "Queries" manual. See also "Extra" tab (Page 20) 18 Operating Manual, 09/2011, A5E

19 XML connectors 2.5 Configuration of object queries Creating objects with different base objects via an object query Requirement The "COMOS" tab must be open in the configuration tool. There are two columns: one for creating the object and one for the base object. Configuring the column for the base object Proceed as follows to create several objects with different base objects via an object query: 1. Open the properties of the column which is to return the base object for creating new objects. 2. Click on the "Object by value" tab. 3. Select the "Root CDevice Search" item from the "Calculation mode" list. 4. Drag&drop the required base object to the "Root CDevice" field. When you create a new object, this base object then serves as the start object for searching for base objects. 5. Click on the "OK" button. Base object properties To set the base object properties, proceed as follows: 1. Open the properties of the base objects that are located below the Root Cdevice. 2. Drag&drop the base object you want to set the reference for into the "Base object" field on the "System" tab. 3. Activate the "Dereference" option. 4. Save your entries. Result The reference object serves as a library object for the new object that is to be created. Operating Manual, 09/2011, A5E

20 XML connectors 2.5 Configuration of object queries Column for the engineering object Proceed as follows to make the settings for the second column: 1. Open the properties of the master column. 2. Select the "Object by value" tab. 3. Select the "Default definitions(for engineering objects only)" item from the "Calculation mode" list. 4. From the "Owner object" list, select the object under which new objects are to be saved. 5. Select the "Neighbor cell object" item from the "Base object" list. 6. From the list of the neighbor cells, select the name of the column that you defined as "Root CDevice". 7. Save the settings. 8. Close the column properties. Creating an object To create a new object, proceed as follows: 1. Enter the name of the base object that you want to use to create a new object in an empty cell of the column you have defined for the start object of the base object search. 2. The cell returns the found base object as the value. 3. The object is created underneath the specified start object of the query. If no base object is found underneath the start object for the search, a new base object is created. You find additional information on this topic in the "Queries" manual "Extra" tab Overview The "Extra" tab is for making additional settings for the column properties. "For MotionX only" control group The "For MotionX only" control group at the bottom of the window provides additional settings that are generally not applicable for object queries. These settings relate to the use of XML connector documents. These settings can be found in the table on the configuration tool's "Mapping" tab. 20 Operating Manual, 09/2011, A5E

21 XML connectors 2.5 Configuration of object queries Control element "Key columns" option "XML type" list "Check column" option "Optional" option "Nillable" option "XML assignment" field: "Mapping table for values" list Description Key columns are used to uniquely identify entries for the object query. The connector document can only import new objects if you have defined key columns. Key columns are used during runtime to synchronize the rows of the COMOS object query table with the rows of the XML table. If a row of the COMOS table contains the same key as the XML table, the connector overwrites the entries in the COMOS table with those from the XML table. If the connector cannot find a suitable entry in the COMOS table, it creates a new row and fills it with the XML data. You can define several key columns for an object query. Key columns are read only when importing XML data. You can select from three items in this list: "ID": The XML data type "ID" uniquely identifies XML nodes within an XML file. "IDREF": The "IDREF" data type is used in the XML attributes and sets references between the XML elements. "Double": The "Double" data type stores the value of the attribute as a number with decimal places in English format, for example: is output if no value is present. You can use the ID/IDREF method to form COMOS references in XML. You can use an XML connector document to automatically set references between COMOS objects when importing XML data. See also section Generating references (links) (Page 39). The Check column writes information to the Enterprise server. Check columns are always executed at the end of the calculation of a row. When the check column function is executed, all other cell values of this row are available and can be queried. When the Enterprise server started an XML connector, the value of the check column is written to the MXR file, the response file. The enabled option causes an element in the XML file to not be created when it is empty. When this option is enabled, an element can have an empty value. A namespace prefix is assigned to the zero value on the "Mapping" tab of the configuration tool. By default, the value "xsi" is entered in the "Name space prefix for the nill node" field. The result is then "<element xsi:nil="true"/>". This field shows the assigned XPath expression. Select the required standard table from this list or drag&drop it from the Navigator. Operating Manual, 09/2011, A5E

22 XML connectors 2.6 Configuration tool Control element "Column with COMOS values" list "Column with external values" list Description This list shows the columns of the standard table selected under "Mapping table for values". The values of the selected column are stored in COMOS. Example: COMOS value: "mm" This list shows the columns of the standard table selected under "Mapping table for values". The values of the column selected here are stored in the XML file. Example: XML value: "Millimeter" You find additional information on this topic in the "Queries" manual. 2.6 Configuration tool General information (fields above the tabs) Control elements above the tabs The following table describes the control elements of the configuration tool: Control element "Navigate..." button "Refresh" button "Save" button "Export" button "Import" button Description Open the navigation menu. Refresh the window. Required after every import/export. Save the settings of the object query. Call the window for the export. Call the window for the import. "Query" list "Query start object" field "XML start node" field This list contains the created object queries that are available for editing. Create new object queries here. This field shows the COMOS object from which the example data on the "COMOS" tab is calculated. Initially, this field contains the object from the "Reference object" reference on the "XML document" tab in the properties of the XML connector document. You can drag another object to the "Query start object" field and thereby change the data on the "COMOS" tab. Note: The change in this field is not saved. The next time you open the tab, the object is displayed in the "Reference object" field. This object is only set if you have selected an XML file in the "XML file name" field on the right-hand side. You can drag&drop another XML element from the XML file into this field. When the field is set, the "Navigate > XML node" option is available in the context menu. When this option is enabled, the corresponding node is selected in the XML file. 22 Operating Manual, 09/2011, A5E

23 XML connectors 2.6 Configuration tool You need to be aware of a few specialties concerning when working with hierarchically nested object queries. See also Nested object queries / data hierarchy (Page 27) "COMOS" tab The user interface and functions of the "COMOS" tab are the same as those for an object query. You can use the "COMOS" tab to create new columns or edit the options of the object query. It also provides the navigation menu and all other tools of an object query. Click the "Search" button to check your previous entries. The information is evaluated. You find additional information on this topic in the "Queries" manual "XML" tab Overview The data from the XML file is shown on this tab, which is for information purposes only. The "XML" tab is similar to the "COMOS" tab "Mapping" tab Overview On the "Mapping" tab you enter how the COMOS data should appear in the XML file. Save your entries before switching to another tab. Operating Manual, 09/2011, A5E

24 XML connectors 2.6 Configuration tool Control elements The following table describes the control elements of the "Mapping" tab: Control element "XML collection" field: "COMOS collection" field "COMOS collection type" list "Name space prefix for the nill node" field Description Is a mandatory field. The entry in this field creates an XML element in the XML file. All XML elements are on the same level and together form an XML collection. The entry cannot start with character because this character is reserved for XML attributes. Shows the COMOS collection to be handled by the object query. Indicates the COMOS collection type. Shows the prefix of the namespace of the nillable attribute "Assembly" tab Overview You can use the "Assembly" tab of the configuration tool to load existing assemblies or create a new assembly. Save your entries before starting an import or export. 24 Operating Manual, 09/2011, A5E

25 XML connectors 2.6 Configuration tool Control elements when enabling the "Write code" option The following table describes the control elements of the "Assembly" tab when the "Write code" option is enabled. Control element Toolbar: "Source code templates" button Description Via this list you can insert a template for the source code in the editor. The following templates are provided for the full code: "Empty class" The template creates an empty class in which only the "ICodeProviderActions" interface is implemented. "Example class" This template contains an example class for implementation of the "ICodeProviderActions" interface. All properties and methods required for working with the connector via the assembly are included here. "Options for the import" The import options for the XML connector are displayed here. "Options for the export" "Enable debugging" option "Save code to file:" field "Compile" button The export options for the XML connector are displayed here. When the option is selected, you can save debug information in the DLL. Shows the path to the file in which the source code is saved. This file is needed for compiling and creating the DLL. The following value is entered by default: "<COMOSPath>\Bin\CompiledAssemblies\<ConnectorName>.cs". Compiles the source code of the editor. The source code is then saved to the specified file. Any errors that occur are shown on the "Error" tab. Control elements when enabling the "Load compiled assembly" option The following table describes the control elements of the "Assembly" tab when the "Load compiled assembly" option is enabled. Control element "Assembly file name" field Button "..." "Assembly file" field "Fully qualified class name" field Description Click the "..." button to open the "Select file" window. Select the file for the compiled assembly. Enter the name of the assembly here. The assembly can contain a number of classes. Enter the name of the class loaded by the connector here. See also Connector expansion with C# assemblies (Page 42) Operating Manual, 09/2011, A5E

26 XML connectors 2.7 Configuration for the export "Error" tab The "Error" tab displays the errors that occur during manual compilation of the C# source code. 2.7 Configuration for the export Basic principles You can configure the connector document on the "Mapping" tab of the configuration tool. Execute the following tasks: 1. Separate the COMOS data and XML data into groups of similar data by assigning COMOS objects to the corresponding XML nodes. 2. Create tables that can describe both XML and COMOS data. Use one table for each data group. You can represent hierarchical structures using nested tables. 3. Select one or more data fields through which the table entries can be uniquely identified. These fields serve as key columns. Not all XML structures can be displayed in tabular form. In this case, use a VB script or C# code. COMOS data is collected using the standard COMOS query methods; XML data is collected via XPath. You can use VB script or C# code to collect data from complex COMOS or XML structures Exporting XML attributes: XML mapping The following naming conventions are used for XML mapping: Structure description: / and attribute Individual descriptions as well as mixed descriptions are allowed. The XML mapping "@Label" generates/uses an XML attribute with a corresponding name. The XML mapping "/Unit1/Position1/" creates a corresponding XML structure, i.e. a hierarchical sequence of nodes. "/Unit1/@Label" is also allowed. Default: Forward slash "/". If the forward slash as well as the "@" sign are missing, the forward slash is used by default to create a structure. 26 Operating Manual, 09/2011, A5E

27 XML connectors 2.7 Configuration for the export Empty XML elements Definition "Empty XML elements": Element that have no further attributes or elements. Technically, creating empty XML elements is not a problem. However, for consistency reasons it is recommended to only create XML structures that have at least one attribute or value on the last level. The last level could look as follows: "<Position> P001 </Position>" Result Each column of the "COMOS" tab is displayed as a separate line on the "Mapping" tab Comparing XML data and COMOS data You will already be familiar with the method for comparing the exported XML file with the "Mapping" tab: The in this object query collected objects were exported as "Position" XML elements. The XML attributes "Tag" and "Description" were created in this XML element. The content of the "COMOS" tab should match that of the generated XML elements Nested object queries / data hierarchy You usually will be working with a data hierarchy. A set of objects is searched. When an object is found, the search for other objects continues underneath that object. You can perform such tasks with the help of nested object queries. See also section Create at least one object query (Page 15). Operating Manual, 09/2011, A5E

28 XML connectors 2.7 Configuration for the export Sorting / Assigning names If you create the object queries underneath the XML connector, you have to regard two things when assigning names: The queries are processed in the order in which they appear in the "Queries" list. The sequence of the queries is defined solely by their names. If you require a specific execution sequence, adapt the names accordingly. The names of the object queries must begin with an alphabetic character. If the name of a query begins with a number, the name in the script cannot be used as the name of functions. This results in a script error. Effects to the base data All entries in the "Edit query container" window have an effect on the connector template. Deleting queries affects all XML connectors that access the connector template. Hierarchically nested object queries If there are several collections on one level of the XML file, create an object query for each of the collections. Each object query is then dedicated to a single collection. Example Both object queries are dedicated to the same level of the XML file. However, each of the object queries handles a different collection of information on this level. For this, the object queries are called as often as required. The object queries "Attribute HSD" and "Attribute SYS" are called for each object of the "Q11 functions" object query. Alternatives procedure You can also determine the two attributes via an object query. Switch between the queries / edit various queries All queries saved underneath the template are available in the "Queries" list. When you select a query, the "COMOS" tab is updated accordingly, i.e. the columns and settings of the selected object query are displayed. 28 Operating Manual, 09/2011, A5E

29 XML connectors 2.7 Configuration for the export Query start object and reference objects with multiple object queries "Query start object field" in the "General information (fields above the tabs) (Page 22)" section explained that the "Query start object" field is pre-allocated initially by the "Reference object" field. This statement only applies to object queries that are located directly underneath the XML template. The exact mechanism works as follows: For object queries located directly underneath the XML template, the "Query start object" field is initially pre-allocated by the "Reference object" field. If you select another query in the list within the XML connector, the current selection is evaluated on the "COMOS" tab and is set as the start object. The REFID collection is an exception to this rule. See also section Basic principle of XML connectors (Page 13). You can use drag&drop to reset the "Query start object" of the object query. This object is not saved. COMOS discards this manual setting as soon as you select another query. For queries located deeper in the hierarchy and not directly underneath the XML template, you can reset the "Query start object". The most recent setting is stored as long as the window is open. You can only set one starting point in an XML connector. This one starting point is set with the help of the "Reference object" in the "MotionX" window and applies to all queries directly underneath the XML template. The entry in the "Reference object" field in the "MotionX" window is saved in the properties of the XML connector, in the "Reference object" field. As such, both fields contain the same information for XML documents. Since for technical reasons there can only be one reference object in COMOS, there is only one initial reference object for XML documents. All other work steps are produced automatically and cannot be set manually. This has consequences particularly if the data to be exported is not located underneath a shared node, but is instead (for example) scattered across various Navigator tabs. In this case, you will need to use a VB script to collect the objects. You can find additional information on this topic in the "Queries" manual. If the objects are associated via references, you can apply the REFID collection method. See also section "Define COMOS collection: REFID (Page 34)". Edit newly created queries You can also edit the queries directly on the "COMOS" tab. Right-click in the column header and select an option from the context menu. For example, you can create a new column. Ensure that you open the context menu from the correct column. The newly created columns are based on the column from which you opened the context menu. You can also check at a later point in time which reference column is set. To do so, open the properties of the newly created column. The reference column is shown in the "Reference" field of the "General" tab. However, this shall only apply if the object query has been stored there. Operating Manual, 09/2011, A5E

30 XML connectors 2.8 Configuration for the import Effect in the base data Each action described here changes the object query in the base data. This applies also when you are processing the XML connector in an engineering project. 2.8 Configuration for the import Key columns During mapping of the COMOS data and the XML file, you need to consider that the order of data can and may change. The position of an item of information on a layer therefore cannot be used as the basis for mapping. The import cannot be executed without key columns. Key columns link the rows of the COMOS table to the corresponding rows of the XML table. In principle, there can be multiple Key columns. Reimport A configured XML connector is always based on a fixed XML structure. The data can be reimported through the XML connector as long as this XML structure remains unchanged. If you do not define key columns, the data cannot be reimported. In this case, you can call the import function, but the data is not written to the COMOS objects because they cannot be found. Specifying Key columns Each object query can have multiple Key columns. The overall purpose of the key columns is to uniquely identify an object within a query in the XML connector. Example The sum of the name of the object, the unit, and the position are always unique in COMOS. If you create three columns in the object query and fill them with a name, unit and position, and define all three columns as key columns, you can assign any object to them. Key columns are required for the import. The COMOS objects to be changed are identified via key columns, or new COMOS objects are created or deleted. The Key columns play no role at all for the export. 30 Operating Manual, 09/2011, A5E

31 XML connectors 2.9 Drag&drop mapping Master column The Master column shows the query which cell contains the object that is to be searched for or created in the OrgCollection. The Master column is a general function of the queries, but which can also be useful for an import operation. There can only be one "Master" column Expressions only supported the import Expressions that are supported for the import but not for the export: Expressions with "OR", "AND" Example: /../Specifications/Specification [@Name="Temperature" A unique object must be addressed during an export. Expression for selecting an unknown node: /*, Example: Valve/* 2.9 Drag&drop mapping Linking via drag&drop COMOS uses tables to link COMOS data to XML data. You can link XML data to COMOS objects on the "Mapping" tab of the configuration tool. To link the XML data to an object query, assign the corresponding XML node to a column of the object query via drag&drop. "COMOS" tab In the case of linked data, the object query refers to the object collection you create on the "COMOS" tab. You select the object collection type by dragging the desired object from the Navigator into the "Class(es)" field and the "Base object(s)" field of the object query. "Mapping" tab On the "Mapping" tab, complete the object query that is to be evaluated on the "XML" tab. The evaluated COMOS objects of the object query are displayed on the "COMOS" tab. The evaluated XML nodes are displayed on the "XML" tab. Therefore, there are two object collections, one for COMOS objects and one for XML nodes. First, edit the "XML collection" field on the "Mapping" tab. Operating Manual, 09/2011, A5E

32 XML connectors 2.10 Using an XML connector The collection of XML nodes is created based on the node that you dragged from the XML file and dropped into the "XML collection" field on the "Mapping" tab. This automatically creates the XPath expression, which points to the desired node. The XPath expression in the "XML collection" field is dependent upon the entry in the "Start XMLNode" field. The XPath expression indicates the position of the nodes contained in the XML collection, dependent upon the entry in the "Start XMLNode" field. You can see the columns of the object query used in the lower section of the "Mapping" tab. This is where you link the COMOS data with the XML data. The columns of the object query are displayed as rows in the Mapping table. When you drag&drop an XML node to a cell in the "XML mapping" column, you assign the XML node to the corresponding column of the object query. The XML connector document then knows which XML value needs to be entered in the assigned column during runtime. The XPath expression generated in the "XML mapping" column is dependent upon the entry in the "XML collection" field. "XML" tab If the XML table on the "XML" tab has been filled out correctly, the data is successfully linked. Alternative procedure You can also create links by dragging the XML nodes directly into the column header of the object query on the "COMOS" tab Using an XML connector Export To export COMOS data, proceed as follows: 1. Right-click on the XML connector document. The context menu opens. 2. Select the "Export" command. The window for the export opens. You can also open this window in the configuration tool by pressing the "Start Export" button. 32 Operating Manual, 09/2011, A5E

33 XML connectors 2.10 Using an XML connector Control elements in the export window The following table describes the control elements in the export window: Control element "File name:" field "Reference object:" field "Include in version management" option "Show file" option Description This is where you select a file or specify the name for a new file. If you select an existing file, it will be overwritten. All calculations and actions relating to the export operation are started at this object. The default setting for the reference object is taken from the "Reference object" field on the "XML document" tab in the properties. If you set another object in the "Reference object" field, this new setting is written back to the "Reference object" field on the "XML document" tab. In addition, the "Query start object" field is set to a new default, since the field is also controlled by the "Reference object" field. This option has nothing to do with the version management of PQM. The option causes the creation of an XML connector document during the export operation. This document is linked via the "File name" field with an XML file that is located in the documents directory of COMOS. If this option is enabled, the XML file is opened with the configured default program when the export is completed. Import To import XML data into COMOS, proceed as follows: 1. Right-click on the XML connector document. A menu opens. 2. Select "Import". The window for the import opens. You can also open this window in the configuration tool by pressing the "Start Import" button. Rule Prior to the import, check the mapping between the XML and COMOS data if it was created via drag&drop. Operating Manual, 09/2011, A5E

34 XML connectors 2.11 Other options in the configuration tool Control elements Control element "File name:" field "Reference object:" field "Delete objects" option "Create working layer" option "Include in version management" option "Work with different objects only" option "Cancel on error" option "Show file" option Description Select the to be imported file here. All calculations and actions relating to the preparation of the import operation start at this object. When enabled, this option deletes all objects that are available in COMOS but not in the XML file to be imported. You created a new working layer via this option and switch to it. The to be imported data is created in the new working layer. This option has nothing to do with the version management of PQM. This option has the effect that an XML Connector document is created during the import operation. This document is linked to an XML file via the "File name:" field which is located in the document directory of COMOS. This option causes the XML connector to only import the delta data. This means that only the differences between the current XML file and the most recently imported XML file are imported. This option presupposes that at least one import operation that uses the "Include in version management" option has already been carried out and that there is at least one other version of the XML Connector document. If an error occurs during the import of the data, all changes triggered by the XML connect up to this point are discarded. There are restrictions for changes per script. Imported working layers are not deleted. If this option is enabled, the XML file is opened with the configured default program when the import is completed Other options in the configuration tool Define COMOS collection: REFID You can only set one start object for an XML connector. See also section Nested object queries / data hierarchy (Page 27). After that, the object queries that are located underneath are executed for each row in turn. Example You want to find the locations that are used for a set of engineering objects. To do this, you insert a column in the object query that outputs the location pointer for each row reference object, i.e. for each engineering object. 34 Operating Manual, 09/2011, A5E

35 XML connectors 2.11 Other options in the configuration tool Previous work method You cannot create a clean XML structure with already described work methods: There is only ever one initial start object for the export, for example, a unit on the "Units" Navigator tab. You can search for the components underneath the unit using an object query, for example. You can easily output all attributes for these components, and therefore also the location pointer. However, in order to create a correct "Component (IDREF) -> Location (ID)" relation, you also require the location objects. An XML connector is executed to search for objects beginning with a start object (in this case, a unit). Each of the found objects can be forwarded as a start object to a query that is located deeper in the hierarchy. Since no locations are found underneath the start object, you cannot forward a location for a start object to a deeper query. You will not find the location objects. Collection REFID In this case, you should use the REFID collection. This method discards the normal "Query passes start object for deeper query" method. With regard to the configuration tool, this means that the "Query start object" field is no longer of any significance. Instead, a collection is formed that contains all objects that were previously already used. Example The following section introduces an example in which the location pointers for engineering objects are written to an XML file. 1. Create an object query in which the engineering objects are collected. 2. Click on the column and select the "New > Location" command from the context menu. A new column, "Location", is created. 3. Mark the new row, "Location", on the "Mapping" tab. 4. For the "Location" row, select "IDREF" from the list in the "Corresponding XML type" column. 5. Create an object query that collects locations underneath the existing query. A column with an ID is created in this query as a counterpart to the above IDREF. 6. Click on the column and select the "New > General" command from the context menu. A new column, "ID", is created. 7. Mark the new row, "ID", on the "Mapping" tab. 8. For the "ID" row, select "ID" from the list in the "Corresponding XML type" column. 9. In the object query on the "Mapping" tab, select "REFID objects" from the "COMOS collection type" list. Operating Manual, 09/2011, A5E

36 XML connectors 2.11 Other options in the configuration tool You get an XML structure. However, the REFID collection is formed on demand during the course of the export. Previously used objects in this collection are not deleted again. This means an ever increasing number of XML elements are created in the XML files during the export operation Mapping table / assignment table for values Data conversion during runtime You have the option of converting XML data before saving it in COMOS. You can also convert COMOS data before saving it in an XML file. Standard tables are used to convert data. You define a standard table where a column with COMOS values and a column with XML values are available. If an external value is found in the column of the XML values during runtime, the corresponding value from the column of COMOS values is written to the object query. Example 1. You want to convert text into another key text. In COMOS, "mm" is used for the millimeters unit, but the string "Millim." needs to be in the XML file. 2. Import or export values are to be assigned to another value on the basis of a fixed key. Multiple import values form a COMOS value or vice versa. Such a simplified mapping excludes a bidirectional mapping. In such a case you either export nor import. Procedure To convert data during runtime, proceed as follows: 1. Click "Administrator" in the menu bar. 2. Select the menu command "Administrator > Base data > Standard tables". 3. Drag&drop the required standard table to the "Mapping table" column. You can use standard tables from the engineering project, the base project or the system project. COMOS only stores the name of the standard table and not the project from which the standard table derives. COMOS first searches for the standard table in the engineering project, then in the base project, and finally in the system project. If you select a standard table from the base project and there is a standard table with the same name but different content in the engineering project, the standard table from the engineering project is found. You find additional information on this topic in the "Basic Operation" manual. 36 Operating Manual, 09/2011, A5E

37 XML connectors 2.11 Other options in the configuration tool Column with COMOS values/column with external values These two columns relate to the standard table specified in the "Mapping table" column. A column of the standard table is specified in both columns. One column has to contain the COMOS values, the other the values to be imported or exported. The two columns must contain different data. If you enter this key text, the "Name", "Description", and "Value 1" through "Value 10" columns of the standard table are used "COMOS info" column Automatically generated static information is entered in the "COMOS info" column. This data is ultimately generated by this column of the object query. Each row on this tab represents a column of the object query. The information can be imprecise, for instance if you are working with a script Check column The Check column writes information about the values of the row to the Enterprise server: Check columns are always executed at the end of the calculation of a row. When the check column function is executed, all other cell values of this row are available and can be queried. If the Enterprise server started an XML connector, all values of the check column are written to the MXR file (response file) XML fragments (XFRAG) XML fragments are strings that are not evaluated nor changed and passed to an XML file. You must ensure that these strings comply with the applicable XML syntax and contain meaningful content. Procedure 1. Prepare a "Memo field" type attribute at the objects in the base data. 2. Enter the string in the memo field of the engineering data. 3. On the "COMOS" tab of the configuration tool, create a reference column using the context menu. 4. To create a new column, select the desired column "New > General" from the context menu. 5. Enter the name and description for the new column. 6. Select the "Object evaluation" tab of the new column. Operating Manual, 09/2011, A5E

38 XML connectors 2.11 Other options in the configuration tool 7. Select "SpecificationByNestedName" from the "Navigation step" list. 8. Enter (Name_of_Tab.Name_of_Attribute) as a parameter. 9. Select "GetDisplayXValue" in the "Display" field of the "Value calculation" tab and enter "0" as the index in the "Parameter(s)" field. 10. Save the properties of the column. 11. Select the "Mapping" tab in the configuration tool and enter the newly created row "XFRAG ("Fragment name")" in the "XML mapping" column. The fragment name Export If the to be exported attribute has a valid XML string, the entire <Fragment> node is generated. If the XML string has no valid XML syntax, the fragment name is generated only as an XML element <Fragment>. Import This information is required for the import in order to find the fragment in the XML file. This entry causes the entire <Fragment> node in COMOS to be written to the attribute as an XML string during import. There may be several fragments within the XML file. The fragment name must be oriented towards the XPath syntax. Example XFrag("ABC/XY") XFrag("MN") Rule If you perform a reimport, make sure the in the memo field entered string has the same root name as the fragment name. Example String in the memo field: <Fragment X1="234" X2="CX"> <SubFragment>Hello</SubFragment> </Fragment> XML assignment: XFRAG(""Fragment"") 38 Operating Manual, 09/2011, A5E

39 XML connectors 2.12 Basic concept of data mapping 2.12 Basic concept of data mapping Basic concept of data mapping Overview Basically, there are four different option available for mapping data: Drag&drop mapping Conversion of values via standard tables Formation of object hierarchies through nested object queries Formation of object hierarchies via reference columns Generating references (links) References in Comos In COMOS, references are used in addition to the object hierarchy to create logical links between items of information. You find additional information on this topic in the "COMOS.dll" class documentation. A brief overview follows. Reference A reference is a function or property that contains connection information for a single object and is both read (Get) and written (Let, Set, depending on the programming language). You find additional information on this topic in the "COMOS.dll" class documentation, keyword "Reference". For example, you can save the information about a component belonging to a specific location. To do this, you do not need to place the component underneath the location. You can the save reference to the location at the component: "Device.Location". "Device" is the component and "Location" is the reference to the location. Another example is the link between two connectors. There is a collection of connectors underneath a component. These connectors can be linked to the connectors of another component, which would then have the following reference: "Connector.ConnectedWith". Operating Manual, 09/2011, A5E

40 XML connectors 2.12 Basic concept of data mapping References in XML XML manages references by using the following pointers: ID: Information IDREF: Reference to this information Therefore, there can be multiple IDREFs for a single ID. Configuring references in the XML connector Since the target information has to have an ID, create an "ID" column. 1. Right-click in the header of the "Name" column and select the context menu command "New > General". 2. Enter the desired name in the "Name" and "Description" fields, for example: ID number. In this column, COMOS will automatically generate the IDs. Since IDREF searches for the ID, the object with the ID must be known. In the definition of the IDREF you have to consider that it finds the right object with the ID. You have two options: The objects in which the IDREFs is defined are a different object group than the objects with the ID. You could create two object queries for the "Device.Location" example: One that searches the locations and generates the ID and a second query that searches for the component and generates the IDREF. You can use the REFID collection method. See also section Define COMOS collection: REFID (Page 34). Background: COMOS does not export any empty object queries to XML. When you create an object query whose sole task is to provide the ID, this query is only exported when the IDs are required. If COMOS finds an ID column, COMOS remembers the SystemUID and the fact that an ID needs to be resolved to an object. When at least one IDREF requesting an ID is not found and the query otherwise does not export defined XML elements or XML attributes, this object will not appear in the XML file. The objects all belong to a group and are efficiently searched with an object query. Using "Connector.ConnectedWith" as an example, you can search all connectors in a single query and also generate the ID and the IDREF in this query. Then right-click in the header of the "Name" column and select the context menu command "New > Connected > Connector". 40 Operating Manual, 09/2011, A5E

41 XML connectors 2.12 Basic concept of data mapping XML mapping Switch to the "Mapping" tab and make the following assignments for XML mapping (examples): Assignment "Object > "ID Number > ID "Object_ConnectedWith > Conn. Description This column was already available in the object query. Although not required technically, it is recommended to always also export the names of the objects (in this case, names of the connector objects). This increases the legibility of the XML file. You created this column manually in the object query. This column will generate the ID in the next step. The column can also have another name than "ID". This column is to put out the IDREF in the next step. To do this, you first have to find the object with the target ID using the predefined column "New > Connected > Connector". To verify this, open the properties of the column on the "COMOS" tab. The properties show the "ConnectedWith" navigation step on the "Object evaluation" tab. This is a COMOS reference that is calculated from the row reference object (i.e. the "Object > Name" column). The mapping is made with the definition of IDREF. Here you have to ensure that the object with the ID is found. Inverse to the "ID Number" column, you can enter the XML mapping "@IDREF". However, the legibility of the XML file increases when you specify the kind of reference it pertains to. It is therefore recommended to use an XML assignment such as "@IDREF_ConnectedWith". Corresponding XML type Make the following settings based on the example above: Operating Manual, 09/2011, A5E

42 XML connectors 2.13 Connector expansion with C# assemblies "ID Number > ID Click on the desired cell in the "Corresponding XML type" column to set the focus to this cell. Click on the cell again to activate the list and select the "ID" entry. Only then is the ID generated and the ID is assigned a SystemUID internally. "Object_ConnectedWith > Conn. Click on the desired cell in the "Corresponding XML type" column to set the focus to this cell. Once again click on the cell to activate the list and select the "IDREF" entry. Only then is the IDREF generated. See also Nested object queries / data hierarchy (Page 27) 2.13 Connector expansion with C# assemblies Connector expansion for C# assemblies Recommendation Use previously compiled DLLs and embed these in COMOS..NET development environment To use an already compiled DLL, you need a.net development environment that supports.net Framework 3.5, for example Visual Studio You can also use an editor to write source code directly in COMOS. You compile this source code during the configuration of the XML connector for an assembly. COMOS does not provide any special functions for.net development. Debugging If you use Visual Studio, debug from the development environment. To do this, configure the project properties and declare Comos.exe under "Start external program" on the "Debugging" tab. 42 Operating Manual, 09/2011, A5E

43 XML connectors 2.13 Connector expansion with C# assemblies Creating a new C# assembly Procedure To create a new C# assembly, proceed as follows: 1. Select the "Assembly" tab in the configuration tool. 2. Select the "Write code" option. 3. Specify the desire C# source code in the editor. 4. Save the setting. See also section "Assembly" tab (Page 24) Loading existing assemblies Procedure There are two ways to specify an already compiled assembly: 1. Enter the path and file name of the DLL file in the "Assembly file" field. This file is searched to find the "ICodeProviderActions" interface and an instance of the class you specified in the "Class name" field is created. The instance of the class implements the interface. In addition to the file path, you can also specify the fully qualified class name. The class name is formed as follows: "Namespaces.ClassName". If you specify the class name, the search targets an instance of the specified class instead of a class. 2. If you do not state the file name you have to state the assembly name and the fully qualified class name. The DLL of the assembly must be located paralled to the Comos.exe or in a subfolder of the "Comos\Bin" folder. If the DLL is located in a subfolder, you need to edit "Comos.exe.config" file. Specify the subfolders in which to search for DLLs. Rule You always have to specify the assembly name. Operating Manual, 09/2011, A5E

44 XML connectors 2.13 Connector expansion with C# assemblies Example The subfolder is named "CompiledAssemblies". Enter the following line in the "Comos.exe.config" file: <assemblybinding xmlns="urn:schemas-microsoft-com:asm.v1"> <probing privatepath="interop;compiledassemblies"/> </assemblybinding> The file name of the DLL must correspond to the name of the assembly: "AssemblyName".dll. See also "ICodeProviderActions" interface (Page 44) Class documentation Overview The following describes the most important interfaces and properties you need to work with.net assemblies "ICodeProviderActions" interface Overview All methods that are to be called by the XML connector must be defined beforehand for a.net assembly. To ensure this, there is an interface that you need to implement when creating a class. This is the only way to guarantee that all classes follow the same scheme. Interface: 1. short version { get; } Returns the version of the implemented interface (currently 1). 2. bool Import Is called for an import. 3. bool Export Is called for an export. 44 Operating Manual, 09/2011, A5E

45 XML connectors 2.13 Connector expansion with C# assemblies Parameters The following table describes the parameters of the interface: Parameter (data type) Value Description queryname (string) jobhelper (IJobHelper) comosobj(icomosbaseobject) XMLNode (System.Xml.XmlNode) XMLNodeCompare(System.Xml.XmlNo de) <Name of query> Master call; forwarded Call from query; forwarded The 'jobhelper' parameter returns an object with which you can access different environment variables of a job. These variables were made available globally in the VB script in the past; in other words, you could access them directly. Example for these variables: 'CurrentJob' (VB-Script) and 'CreateNewJob()' (C#) Corresponds to the parameter with the same name from the VB script. Corresponds to the parameter with the same name from the VB script. For import only Corresponds to the parameter with the same name from the VB script. Explanations There is a difference between "Master_..." and " _ExportRow". The same method is called in both cases. If a master call is involved, the method is passed via the 'queryname' parameter of the "@@Master" value. If a call from an object query is involved, the method is passed via the 'queryname' parameter of the value for "name of object query". Evaluate the forwarded parameter. Do not randomly select the return value from both methods, since it will be interpreted and influences the execution of the job. The return value tells you if your actions were performed when a method was called return value: TRUE. Since an assembly is saved for the entire connector and not for each object query, you need to be able to distinguish when actions are performed. This is not possible before the methods are called. You can use the 'queryname' parameter to determine if the actions should be performed. Example When you call the 'Export' with 'queryname' = "@@Master" method and want to extend the execution, the return parameter must have the value TRUE. If FALSE is the return value, COMOS executes its standard procedure. Operating Manual, 09/2011, A5E

46 XML connectors 2.13 Connector expansion with C# assemblies "IAdapterActions" interface Structure of the interface The interface is structured as follows: public interface IAdapterActions { short Version { get; } short PostAction(string jobtype, IComosDDocument document, ref string FileName, IOptions joboptions); short PreAction(string jobtype, IComosDDocument document, ref string FileName, IOptions joboptions); } Parameters Parameter Version PreAction PostAction jobtype Description Returns the current interface version. Starts the PreAction of the XML adapter and runs before the XML connector is started internally. Starts the PostAction of the XML adapter and runs after the XML connector is started internally. Name of the job type: Import Export document FileName joboptions The XML connector document that is to be used. The XML document is a COMOS object. Name of the XML file that is to be used. Note: This is a REF parameter. If the value is changed within the method, this change persists after the method is called and is, therefore, retained throughout the remainder of the XML connector process. Options for the XML connector. The options are defined (via the user interface, for example) before the connector starts. 46 Operating Manual, 09/2011, A5E

47 XML connectors 2.13 Connector expansion with C# assemblies "IJobHelper" interface Overview The following table describes methods and properties. Method / Property IComosDDocument Document { get; } ComosQueryInterface.IOptions Options { get; } ComosQueryInterface.qeProgressState ProgressState { get; } IComosDProject Project { get; } IJobHelper ThisGlobal { get; } IComosDWorkset Workset { get; } XMLExecJob Current job { get; set; } string ProgressText { get; set; } string XMLFileName { get; set; } double GetProgressPercentage(int level) void SetProgressPercentage(int level, double value) void CheckMessage(string msgtext) XMLExecJob CreateNewJob() void OutputDebugString(string lpoutputstring) ComosQueryInterface.IProgressBar ProgressBar() IComosBaseObject ReportObject() Description Returns the 'Document' property of the current job. Note: The document is the Comos XML connector. Returns the external options of the current job. Returns the status of the progress bar. Returns the current project. Returns itself. Returns the instance of the currently created workset. Returns the started job / sets a job and thereby all parameters depending on it (e.g. document, options). Returns / sets the text of the progress bar. Returns / sets the name of the processed XML file. Returns the progress of the passed levels of the current progress bar. Permitted parameter values: 1, 2. Returns the progress of the passed levels of the progress bar. Permitted parameter values: 1, 2 level ; 0 to 100 value Writes a text to the log file. Syntax:<check description="<<msgtext>>" /> Creates a copy of the current job. Writes a text to the trace listener 'QueryX'. The corresponding file is defined in Comos.exe.config. Note: The Trace.Listener property is.net-standard. Returns the current progress bar as an object. Returns the 'ReportObject' property of the current document. Operating Manual, 09/2011, A5E

48 XML connectors 2.13 Connector expansion with C# assemblies "IXMLExecJob" interface Methods The following table describes the methods: Method void Export() void Import() Description Starts the export for the current query Starts the import for the current query Properties The following table describes the properties: Property (data type) ComosObjects (Object) Description Specifies the OrigCollection of the query. The property returns one of the following three types: ComosKDictionary VBACollection IComosDCollection RootComosObject (IComosBaseObject) QueryContainer (IComosBaseObject) TopQuery (ITopQuery) RootXMLNode (System.Xml.XmlNode) RootXMLNodeCompare (System.Xml.XmlNode) XMLNodes (System.Xml.XmlNodeList) XMLNodesCompare (System.Xml.XmlNodeList) Start object of the query Currently processed query Top query object of the query Root start node Root start node for the "Difference Only" mode. Comparison node from the predecessor file. Lists all nodes to be processed; COMOS collection objects List from the comparison document Version (short) Internal version number of the interface (currently: 1) Preprocessing / postprocessing: The adapter Overview You can use an assembly to adapt XML connectors in line with your requirements. The XML adapter is used to process the COMOS and XML data both before and after the import or export. 48 Operating Manual, 09/2011, A5E

49 XML connectors 2.13 Connector expansion with C# assemblies Recommendation: "Assembly" tab Implement the IScriptConnectorActions interface in the same class as "ICode Provider Actions". Configure the PreAction method for actions that need to be performed before the connector is called. Configure the PostAction method for actions that need to be performed after the connector is called "Custom" adapter type General The Custom connector gives you a degree of control over pre/postprocessing. See also section Preprocessing / postprocessing: The adapter (Page 48). This means you can exercise a degree of control over the XML connectors before and after the import and export processes. For this purpose, implement the interface in the same class as "ICode Provider Actions". Configure the XML connector via the "Assembly" tab. See also section "Assembly" tab (Page 24). XML connector document properties Go to the "Attributes" tab in the properties of the XML connector document and select the "Custom" adapter type. Operating Manual, 09/2011, A5E

50 XML connectors 2.14 All other settings in the XML connector 2.14 All other settings in the XML connector Properties of a column, Extra "For MotionX only" area All the properties listed in the "For MotionX only" section can be accessed via the "Mapping" tab Options of a column, MotionX "MotionX" tab The columns and options of the "MotionX" tab are described in the "Queries" manual. The following only describes the columns that result from the XML connector technology and have not been explained before. "Display XML mapping" The column also displays the text from the "XML mapping" field in the column header of the object query Direct help in the XML connector Hyperlinks You will find a help section consisting of hyperlinks in the lower right of the application area. When you click on the text in the help area, a window opens in which you perform the suggested work step. 50 Operating Manual, 09/2011, A5E

51 XML connectors 2.14 All other settings in the XML connector "Script" tab Display of the "Script" tab If you have saved or commented out a VB script for an existing connector document, the "Script" tab is displayed. This tab is disabled for newly created connector documents. Connector documents with a VB script continue to be run with the VB variant of the "Components ComosXMLInterface" connector document. Function By default, the object queries that are located directly underneath the XML template get their respective COMOS start objects from the XML connector document. The object queries subsequently pass their row objects as COMOS start objects to the queries that are located underneath them in the hierarchy. You have the option of intervening in this sequence by using a script. The top object queries directly underneath the XML template can call the following functions: "Master_Export" "Master_Import" If there are master methods, they are called. The following functions are available for all other levels: "<"QueryName">_ImportRow" "<"QueryName">_ExportRow" This applies for each row of the running query. If there is a script method, it is called line-byline. If there is no script method, all underlying queries get the row object of the query currently being executed as the start object. The CurrentJob When the query is processed, the so-called CurrentJob runs. You can then query the following from this object: Current query OrigCollection of COMOS objects XMLNodes at the XML document Operating Manual, 09/2011, A5E

52 XML connectors 2.14 All other settings in the XML connector New jobs You have the possibility of creating and starting new jobs in the script: Type of the job object: "ComosQueryInterface.IXMLConnectorJob" Properties: Job.QueryContainer = <query container> Job.TopQuery = <ITopQuery> Job.RootComosObject = <query StartObject> Job.ComosObjects = <query OrigCollection> Job.RootXMLNode = <RootNode for 'XML-Rows'> Job.XMLNodes = <'XML-Rows'> Job.RootXMLNodeCompare = <RootNode for 'XML-Rows' of compare version> Job.XMLNodesCompare = <'XML-Rows' of compare version> There are two methods available for this: Job.Import Job.Export The following table describes the properties: Property "QueryContainer" "TopQuery" "RootComosObject" "ComosObjects" "RootXMLNode" "XMLNodes" "RootXMLNodeCompare" and "XMLNodesCompare" "Job.Import" and "Job.Export" Description Corresponds to the objects in the interface that you edit in the "Edit query container" and "New query container" dialogs. This involves an object or base object that carries the actual query. The XObjects for these objects are saved. Actual object query. This parameter corresponds to the the calculation core, not the query browser. Corresponds to the "Start Comos object" field in the user interface. The Comos collection that was determined and returned by "TopQuery". Corresponds to the "Start XML node" field in the interface. Corresponds in the user interface to the set of results on the "XML" tab. Parameter for import only, when there is at least one XML version. The parameters supply the XML node of the previous version. This is important if you only want to edit the differences from the previous version. These parameters start the execution of the job. 52 Operating Manual, 09/2011, A5E

53 XML connectors 2.14 All other settings in the XML connector Examples: Redundant properties If you enter "QueryContainer", you do not have to enter the "TopQuery"if it comes from this container. In this case, it is determined automatically by "QueryContainer". If you have entered "RootComosObject"and the query should search for the objects in the standard way, you do not have to enter "ComosObjects". If you want to define "OrigCollection"yourself in another way, you do not have write "IExtender"for the query. You can here enter the suitable objects as "ComosObjects" properties here. Example 1 This is how the standarc case looks like in the script: Sub Q1_ExportRow(ComosObj, XMLNode) Set QSubs = CurrentJob.QueryContainer.EnObs("J") For i = 1 To QSubs.Count Set NJ = CreateNewJob() NJ.QueryContainer = QSubs.Item(i) NJ.RootComosObject = ComosObj NJ.RootXMLNode = XMLNode NJ.Export Next End Sub Sub Q2_ImportRow(ComosObj, XMLNode, XmlNodeCompare) Set QSubs = CurrentJob.QueryContainer.EnObs("J") For i = 1 To QSubs.Count Set NJ = CreateNewJob() NJ.QueryContainer = QSubs.Item(i) NJ.RootComosObject = ComosObj NJ.RootXMLNode = XMLNode NJ.RootXMLNodeCompare = XmlNodeCompare NJ.Import Next End Sub Script templates The templates for script methods can be accessed via the "Source code templates" button. Operating Manual, 09/2011, A5E

54 XML connectors 2.14 All other settings in the XML connector Maintaining old connectors prior to version 9.0 Overview As of version 9.0, XML connectors are no longer processed with VB script. All old functions continue to be supported. The old connectors are downwards compatible. See also section "Script" tab (Page 51) Reusing object queries Query pointer Overview Query pointers reduce data redundancy by excluding duplicates. Base object You can find the base object for the query pointer under Data Data > QP Query Pointer". Function Within XML connectors, you use a query pointer to define an object, that refers to an object query within or outside the connector. The query pointer is the copy of the target query and therefore has the same functionalities. Lower level object queries are also considered. If a query pointer is found during the processing of an XML connector document, the target query is used to import or export COMOS objects. Assigning an object query to a query pointer There are two ways to assign an object query to a query pointer: Via the configuration tool Via the properties Procedure To use the configuration tool to select a new object query, select the desired object query from the "Reference query" list. Result An object query is assigned to the query pointer. 54 Operating Manual, 09/2011, A5E

55 XML connectors 2.14 All other settings in the XML connector Alternative procedure Drag&drop an object from the Navigator into the "Reference query" list. Procedure To assign the object query via the properties, proceed as follows: 1. Open the properties of the query pointer. 2. Select the "Attributes" tab. 3. Select the "Query Pointer" tab on the level below. 4. Use the "Set pointer..." button to select the desired query. Alternative procedure: Drag&drop an object from the Navigator into the "Query" field. Alternative procedure Drag&drop an object from the Navigator into the "Query" field XML adapter Function A so-called job is started while the XML connector is running for each object query. The job has the query container property that shows which object query is to be used for the current import or export job. Via the XML adapter you process the COMOS and XML data both before and after the import or export. JobOptions If JobOptions have already been created through the Enterprise server and forwarded to the XML adapter, for example, the settings only need to be read. If you start the XML adapter from COMOS, the JobOptions must be created and adapted via the option of the interface. Adapter type A variety of components can implement the "IAdapterActions" interface. These components are assigned to the XML adapter via the "Adapter type" attribute on the "XML" tab. Here, in the list behind the "Adapter type" attribute on the "XML" tab, all the components listed in the properties of the XML connector are assigned a name. Operating Manual, 09/2011, A5E

56 XML connectors 2.14 All other settings in the XML connector Structure of the list The following table describes the columns of the "A2GKGD4EPX" list: Column "Name" "Description" "Value 1" "Value 2" "Value 3" "Value 4" Description This column displays the internal name. This column shows the name of the component that can be selected in the "Adapter type" list. This column shows the internal name by which the adapter is queried in order to load the special settings. This column displays the name of the class to be loaded. "KomponentenName.KlassenName" applies for all COM components. "Namespaces.ClassName" applies for all.net components. This column shows the "AssemblyName" of a.net class. This value remains empty for COM components. This column shows the path and the name of the XML file for internal processing Triggering connectors via a script The previousl examples assumed that you have written a script in the configuration tool and then started it in the XML connector document using the context menu command " XML > Export" or "XML > Import". You also have the option of starting the export or import per script. Example as of version 9.0 Creating the options Set XMLImpExport = CreateObject("Comos.XMLConnector.Exec") Set Options = XMLImpExport.CreateJobOptions(<JobType>) Permitted values for <JobType>: 1 / 2 (1 for import, 2 for export) Setting an option Options.Item("<OptionName>").Value = <value> Available options Options 1-4 are are only relevant for the import. 56 Operating Manual, 09/2011, A5E

57 XML connectors 2.14 All other settings in the XML connector The following table describes the default values of the option: Option Default value "DeleteObjects" False "CreateWorkingOverlay" True "DifferenceOnly" False "SaveMode" 0 "VersionsAdministration" False "ShowFile" False Options as of version 9.0 Option Value Description "ProgressBar" Nothing The progress display as (.NET) object. "qedialogtype" 2 The type of the displayed dialog window. "Cancel" False Status / success of execution -- true = cancel For explanation, see: If you set the "ProgressBar" option manually the value "Nothing", you have to set "qedialogtype" to "0". Set Options.Item("ProgressBar").Value = Nothing Options.Item("qeDialogType").Value = 0 Values for "qedialogtype": Value Description 0 No window / no progress bar 1 Full dialog with options, requires manual start by user 2 Minimum dialog, only shows the progress bar The above listed options must be changed as described for the server mode. This has already been done by MXExec.exe. Starting the job Set XMLAdapter = CreateObject("Comos.XMLAdapter.Adapter") Set <XMLCOnnector>.reportobject =<Reference object> result = XMLAdapter.LoadFromScript(<JobType>, <XMLConnector>, <Destination Filename>, Options) Operating Manual, 09/2011, A5E

58 XML connectors 2.14 All other settings in the XML connector Permitted values for <JobType> Value Description 1 Import 2 Export Return value Once the "LoadFromScript" function was successfully executed, the return value of the function is "0". Example version 8.2 (normal notation) Set XMLImpExport = CreateObject("ComosXMLInterface.XMLInterface") Set Options = XMLImpExport.CreateJobOptions("Import") ' Import: Options.Item("VersionsAdministration").Value = False Options.Item("DeleteObjects").Value = False Options.Item("CreateWorkingOverlay").Value = True Options.Item("DifferenceOnly").Value = False XMLImpExport.Import <Document>, <FileName>, Options 'Export: Set Options = XMLImpExport.CreateJobOptions("Export") Options.Item("VersionsAdministration").Value = False Options.Item("ShowFile").Value = True XMLImpExport.Export <Document>, <FileName>, Options 58 Operating Manual, 09/2011, A5E

59 XML connectors 2.14 All other settings in the XML connector Example version 8.2 (abbreviated notation) Set XMLImpExport = CreateObject("ComosXMLInterface.XMLInterface") ' Import: XMLImpExport.Import <Document>, <FileName>, False, False, True, False 'Export: XMLImpExport.Export <Document>, <FileName>, False, True Recommendation Use the normal notation, because it makes the meaning of the parameters clear. If you use the abbreviated notation, you need to keep script documentation to describe the meaning of the script and the parameters. Operating Manual, 09/2011, A5E

60 XML connectors 2.14 All other settings in the XML connector 60 Operating Manual, 09/2011, A5E

61 Standard import: Blank for XML 3 To start a standard import of XML data, proceed as follows: 1. Open the base project. 2. Select the "Base objects" Navigator tab. 3. Right-click on the object underneath which you want to save the XML data. A menu opens. 4. Select "New > Standard Import > XML data". The object is created underneath the selected node. 5. Double-click on the newly created object. The "Standard import: XML data" tab opens. 3.1 Scope and concept of the table import function External XML data can be imported into COMOS and stored in the form of base or engineering objects. The table import function uses DOM ("MSXML.DOMDocument"). The data is first read into the action and displayed on the screen for checking, but it is not actually imported into the COMOS database until the second step takes place. The import process can be controlled by means of a script. This script and all other details on a special import process are stored in an "archive" and can be reused at any time. Operating Manual, 09/2011, A5E

62 Standard import: Blank for XML 3.2 Application 3.2 Application In the upper part of the action, the XML file to be imported is allocated either by drag&drop or via the "Open XML file" window and the associated XML code is displayed in the field underneath. The instructions on how the XML data is to be handled are input in the script area in the form of a VB script. Controls and switches The part that generally applies to controls was already explained, so for that reason only special points relating to queries are discussed at this point. This button opens the following administration mask: 62 Operating Manual, 09/2011, A5E

63 Standard import: Blank for XML 3.2 Application These two buttons turn on Draft mode (left) and Runtime mode (right) respectively: Operating Manual, 09/2011, A5E

64 Standard import: Blank for XML 3.2 Application 64 Operating Manual, 09/2011, A5E

65 Tabular reimport General The query enables the reimport of edited COMOS data exported from Access or Excel. The reimport of text files or XML files is not possible. The prerequisite for the correct use of the query is the input of the local ID (Language.LCID) for COMOS languages. Reimport involves the following steps: Import the data into the query interface. Controlling the to be imported data individually and planning the actual reimport. Transfer the data into the database. 4.2 Call Click on "Extra > Standard import > Access/Excel/XML reimport" in the menu bar. 4.3 Overview The following table describes the control elements of the "Access/Excel/XML reimport" window: Control element "Database" field "Table" field Description Select an "XLS" or "MDB" format file here. Select a table from the selected file here. Operating Manual, 09/2011, A5E

66 Tabular reimport 4.4 Read the data into the query 4.4 Read the data into the query Select the database: Select a table from the database: Import the data into the query interface. No COMOS data is changed yet. The data that has been read in can be edited, see below A progress bar may be displayed depending on the imported data and the computer performance: 66 Operating Manual, 09/2011, A5E

67 Tabular reimport 4.5 Preparing read data for the reimport 4.5 Preparing read data for the reimport "Action selection" column Is initially suggested by COMOS. The action can be changed manually if the "Status" column is set to "green" or "yellow". No change is possible if the status is set to "Red". The action is changed by right-clicking on a cell and making another selection from the mouse menu. "Status" column Each status value has a tooltip (a small yellow post-it that appears when the mouse cursor hovers over the cell). The meaning of the status value is explained in this tooltip. The tooltip can also be displayed as a column of its own. To do this, right-click on the header of the "Status" column and select the context menu command "New > Standard reimport columns > Status description". "Green": The viewed value of the row object has changed since the export and there are no reasons that prevent a reimport. Status "Yellow" An import is not necessary. The value under consideration has not changed since the export and there was no external change or the change within COMOS is identical to the external change. Status "Red" Importing is not possible! Example: the Comos object no longer exists. "Import value" column All white cells can be changed. Cells highlighted in gray cannot be edited. Operating Manual, 09/2011, A5E

68 Tabular reimport 4.6 Carry out the reimport 4.6 Carry out the reimport The data read into the query is written back to the COMOS data. This button is only enabled after the data was read. Before COMOS updates the database, you will see an important safety prompt. The log is opened in the lower window area: COMOS checks all objects during the import to determine whether they own all necessary rights at project and/or object level. If this is not the case, the import is rejected at those points. The individual error messages can be seen in the import log: Double-click on an error entry to jump to the corresponding entry in the import list. 68 Operating Manual, 09/2011, A5E

69 Tabular reimport 4.7 Error messages 4.7 Error messages StatusValue = 1 Import will be carried out. StatusValue = 2.1 Warning: No import necessary; the COMOS value and the import value are identical. StatusValue = 2.2 Warning: No import necessary, the COMOS value and the export and import values are identical. StatusValue = 2.3 Warning: The COMOS value and the import value were changed. StatusValue = 2.4 Warning: The COMOS value was changed; the import and export values are identical. StatusValue = 3.1 Error: The COMOS object could not be found. StatusValue = 3.2 Error: Unknown conversion object. This means that the hidden information written to the table during the export cannot be restored correctly. This can only actually occur if the hidden table sheets were manipulated. StatusValue = 3.3 Error: The property is unknown or not reimportable. StatusValue = 3.4 Error: Property is not reimportable. StatusValue = 4 Import was carried out. StatusValue = 5 Error: Not imported. Operating Manual, 09/2011, A5E

70 Tabular reimport 4.7 Error messages 70 Operating Manual, 09/2011, A5E

71 Reimporting a file or a directory General Dialog-controlled reimport uses the reimport object query internally and is identical in terms of technical functions. See also section Tabular reimport (Page 65). 5.2 Call Click on the "Reimport" button on the toolbar or "Extra > Reimport" on the menu bar. 5.3 Overview Control elements of the "Reimport" window The following table describes the control elements of the "Selection" control group: Control element "File" option "Directory" option "Log file" option Description Select a file here. Select a directory here. You can now enable the "With all subdirectories" option under the "Settings" control group. Enable the option to create a log file during the reimport. The log file is in "CSV" format. You can now enable the "Log all events" option under the "Settings" control group. Operating Manual, 09/2011, A5E

72 Reimporting a file or a directory 5.4 Procedure The following table describes the control elements of the "Settings" control group. Control element "With all subdirectories" option "Create working layer" option "Log all events" option Description This option is available if you enable the "Directory" option in the "Selection" control group. The option includes all subdirectories in the reimport. A working layer is created during the reimport. This option is available if you enable the "Log file" option in the "Selection" control group. The "In progress" control group cannot be edited. It just shows you the status of the reimport. 5.4 Procedure Reimporting a file To reimport a file, proceed as follows: 1. Select the "File" option in the "Selection" control group. 2. To select a file, click on the "..." button. The "Select file" window opens. 3. Click "Open". Enter the path in the "File" option field. The path is entered automatically in parallel in the "Log file" option field. 4. There is an option to log your reimport. Activate the "Log file" option. The path has already been entered. You can change the path with the "..." button. The "Log all events" option is now available to you in the "Settings" control group. 5. Specify the storing location and the file name of the log file in "CSV" format. 6. There is an option to create your reimport as a working layer. Select the "Create working layer" option in the "Settings" control group. 7. To start the reimport, click on the "Start reimport" button. 72 Operating Manual, 09/2011, A5E

73 Reimporting a file or a directory 5.4 Procedure Reimporting a directory To reimport a directory, proceed as follows: 1. Select the "Directory" option in the "Selection" control group. The "With all subdirectories" option is now available to you in the "Settings" control group. 2. To select a directory, click on the button. The "Search folder" window opens. 3. Select your directory and confirm with the "OK" button. Enter the path in the "Directory" option field. The path is entered automatically in parallel in the "Log file" option field. 4. There is an option to log your reimport. Activate the "Log file" option. The path has already been entered. You can change the path with the "..." button. The "Log all events" option is now available to you in the "Settings" control group. 5. You can choose to run your reimport with all subdirectories. Select the "With all subdirectories" option in the "Settings" control group. 6. To start the reimport, click on the "Start reimport" button. Operating Manual, 09/2011, A5E

74 Reimporting a file or a directory 5.4 Procedure 74 Operating Manual, 09/2011, A5E

75 Standard import: Blank for tables Overview: Scope of services and concept In COMOS, external tables can be imported and the data of the tables can be stored in the form of base or engineering objects. Currently Access databases, Excel spreadsheets, and text files are supported. We recommend using Access databases as an import source. The table import function uses ADO ("ADODB.Recordset). An import consists of the following steps: 1. Open the import source First of all a database or a sub-directory must be opened. All tables / spreadsheets / files in it are then displayed. The selected table is then transferred to the display area. Only one table after another can be imported. 2. View the import data Double-clicking on a table in the window of the selection area displays the data in the display area. The column designation is used here as a column title. The status field at the lower edge of the area indicates the current table and rows and the number of rows (data records) selected. The buttons to the right and left of the status field enable a fast navigation within the datasets. Use "Shift + Left Mouse Button" to make multiple selections. 3. Write the import script The import process is controlled by means of a script. This script and all other details on a special import process are stored in an "archive" and can be reused at any time. 4. Execute The import starts for the selected datasets. Only now is it possible to create or change COMOS data. Operating Manual, 09/2011, A5E

76 Standard import: Blank for tables 6.2 The interface of a table import 6.2 The interface of a table import Creation: The context menu for base data contains the "New > New standard import > Table" command Properties of an action object The usual double-click opens the special interface in the case of objects of the "Action" class, and not the properties of the object. The properties are opened as follows: For a base object: Right-click on the object in the Navigator and select the "Properties" command from the context menu. For an engineering object: You cannot open the standard properties here. The general data of the properties ("Name", "Label", "Description", "Base object") can be opened in the special interface by means of the "Properties icon button The interface in the draft mode The stipulations that are saved later in the archive are developed in the draft mode. The interface display differs slightly depending upon whether it is opened with a base object or an engineering object. The differences are listed in the following list. 76 Operating Manual, 09/2011, A5E

77 Standard import: Blank for tables 6.2 The interface of a table import The icons at the top left Navigate: Displays the object in the Navigator. Refresh: The special interface is updated. Save / Save as: A mouse click on the diskette symbol saves the object itself, including the archive. A click on the arrow to the right of the diskette symbol offers the following commands: "Save" This command has the same effect as clicking on the diskette symbol. "Save as" Duplicates the object, including the archive. The following small dialog window is opened: In the drag&drop field you stipulate underneath which object the copy is to be created. Simply drag an object from the Navigator into the field. Input the name and the description of the new copy to be created in the "Name" and "Description" fields. Properties (only for engineering objects): You cannot open the standard properties for the engineering object. This button superimposes the general data of the properties (Name, Label, Description, Base object). Administration: Here you stipulate to what extent the engineering object of the import may be changed: Operating Manual, 09/2011, A5E

78 Standard import: Blank for tables 6.2 The interface of a table import Stop / continue on error (only for an engineering object) Continue on error: an attempt is made to complete the rest of the import. Continue on error: the import stops. The extent to which COMOS data is created depends on the import script. If anything was saved in the script up to this point, then this data is imported. Draft mode / execute (runtime): The draft mode opens the already displayed interface. The stipulations that will also be saved later in the archive are developed here. The runtime mode is used to execute an import after concluding all preparatory work. See also section The interface for the runtime mode (execute) (Page 79). Buttons at the bottom right in the script area You find additional information on this topic in the "Properties" manual, keyword "The script editor". Execute / Stop: "Execute": The import starts for the selected datasets. "Stop": Cancels the triggered import process. The extent to which COMOS data is created depends on the import script. If anything was saved in the script up to this point, then this data is imported. Undo COMOS objects: All COMOS objects that are imported on a test basis in the draft mode are initially temporary. The temporary objects can be saved manually or are saved automatically in specific situations (for example, when the properties are opened). This function undoes all changes that were created in the course of a test import for objects that were not saved yet (newly created objects are deleted; changes in existing objects are undone). Save COMOS objects: All COMOS objects that are imported on a test basis in the draft mode are initially temporary. The temporary objects are saved manually with this command. If you choose this method of saving objects, you can no longer use the "Undo COMOS objects" command to undo changes. Apply example: A fully usable example for an import that can actually be run is called. Please note: all entries made up to this point in the "Import" dialog window are discarded! Script help: The interactive script help is called with this icon button. See also section Script for import actions (Page 81). 78 Operating Manual, 09/2011, A5E

79 Standard import: Blank for tables 6.2 The interface of a table import Keyboard commands If you open the tree structure on the left and double-click on a "Table" object or on a "Query" object, the contents are displayed in the preview (here is an example for Access): The rows in the preview can be selected individually by means of the mouse. In addition, the usual selection commands are supported: <Ctrl> + mouse click <Shift> + mouse click <Ctrl> + <A> Selects the additionally clicked row. Selects all dataset between the last selected row and the next selected row. Selects all datasets in the table The interface for the runtime mode (execute) In runtime mode only those commands and scripts that were developed in draft mode can be run. You see the following interface: "Database" This field is automatically filled and displays the name of the source that was selected in the draft mode. Operating Manual, 09/2011, A5E

80 Standard import: Blank for tables 6.3 Import sources "Table / Query" This field is automatically filled and displays the name of the table that was selected in the draft mode. The progress bar displays the number of data records already imported on the left and the total number on the right. "Execute / Stop" "Execute": The import process begins. Base and / or engineering objects are created and saved at regular intervals. The "Stop" command cancels the started import process. Any objects that were saved up to then cannot be undone. 6.3 Import sources Access Access is fully supported. If an Access database is selected, then all Access tables and all Access queries of the selected database are offered for import. All tables and queries that were found are listed with all table columns. Information on the type and size is also given with the table columns. The table or query that was selected is then imported. Tables and queries can only be imported one after another Excel Excel spreadsheets must use a header row. The field names are entered in the header row. If an Excel file is selected, then all Excel worksheets of this file are offered for import. The worksheets are described as "tables" in the import object. The relevant selected table (Excel worksheet) is then imported. Only one table after another can be imported. Please note: The data from Excel can only be imported without errors if the columns of the Excel worksheets have been formatted (number, text), before the first entry is made. Otherwise data can be lost during the import. Reason: Excel uses formats of its own such as "General". However, this format is not a format but only a function that reacts to inputs and formats the cells in various ways according to the situation. Standardized software products (SQL, ADO, TrueDBGrid) cannot process such undefined constructs. 80 Operating Manual, 09/2011, A5E

81 Standard import: Blank for tables 6.4 Script for import actions Retrospective changes to the column definition have no effect. Although Excel displays the desired effect on the screen, in reality it does not change its formats. If you want to retrospectively format an Excel spreadsheet, each cell has to be formatted individually. This sort of undefined Excel worksheet can be imported into Access and then you can open the Access database in the import object Text file The text files must be saved without a format. Then structure of the text file depends on the definition within the registry. A typical structure could look as follows: Field delimiters: Include the field name in the first line: Text delimiter character: Semicolon Yes None The for the PC valid settings for the ADO import are located in: "\HKEY_LOCAL_MACHINE\Software\Microsoft\Jet\4.0\Engines\Text" During the import of a text file, there is no superordinate file in which there are separate worksheets or tables, unlike the case with Access or Excel. For that reason the option to select a sub-directory and to import all text files from this sub-directory is offered when importing text files. The individual text files within a sub-directory are offered as "tables" in the import object. The relevant selected table (= text file) is then imported. Only one table after another can be imported. 6.4 Script for import actions Operating Manual, 09/2011, A5E

82 Standard import: Blank for tables 6.4 Script for import actions Complete overview of an import script Each script should cover the areas "Global", "Init", "ImportRow", and "Finish". Further, the user can supplement the script with own "Subs" or "Functions" Script modules Each of the following modules can be transferred into the script at once. In such cases it is always the actual script text that is transferred and not the examples that were commented out. The following methods are available: Place the text marker on the desired point in the script. Then double-click on the desired module. The script of the module is inserted at the position of the text marker. Drag&drop a module in the script to the desired position: 82 Operating Manual, 09/2011, A5E

83 Standard import: Blank for tables 6.4 Script for import actions Module "Set RootObject = <Object> " "Set RootCObject = <Object> " "Set <Object> = NewObject(<RelativeName>, [<Description>])" "Set <Object> = NewCObject(<RelativeName>, [<Description>])" Meaning <Object> = Any desired variable name; filled with an object. Root object in the form of an engineering object (device). In other words: the objects in which the imported data is stored are created underneath this engineering object. As a rule, the variable is defined in Global and can thus also be redefined in one of the other script constituents. Root object in the form of a base object (CDevice). In other words: the objects in which the imported data is stored are created below this base object. As a rule, the variable is defined in Global and can thus also be redefined in one of the other script constituents. Please note: it is possible to simultaneously stipulate a root object for engineering objects in an import procedure with the RootObject command and a root object for base objects with the RootCObject command. But only one project can be opened! If engineering and base objects are created simultaneously with the various Set commands, then of necessity these two deposited in the same project, thus, for example, local base objects are created in an engineering project. Reference object/reference command: Set RootObject <RelativeName> = Name plus the specified path relative to the root object. The levels of the path are separated with the default delimiter. "X XY": In this case, a search would be made for an "X" node or one is created underneath the root object and an object with the name XY is searched for or created there. <Description> Optional: Sets or overwrites the description of the object (here: XY). Note also: CNameForNewObject Reference object/reference command: Set RootCObject <RelativeName> = Name plus the specified path relative to the root object. The levels of the path are separated with the default delimiter. "X XY": In this case, a search would be made for an "X" node or one is created underneath the root object and an object with the name XY is searched for or created there. Optional: Sets or overwrites the description of the object (here: XY). Operating Manual, 09/2011, A5E

84 Standard import: Blank for tables 6.4 Script for import actions Module "Set <Object> = NewSpec(<CObject>, <NestedName>, [<Description>])" "SpecValue(<SpecOwnerObject>, <NestedName)>) = <vnewvalue>" "SpecUnit(<SpecOwnerObject>, <NestedName)>) = <vnewvalue>" "<Variant> = Field(<Field Name>)" "<String> = StrField(<FieldName>)" "OutputDebugString" <Text> Meaning Creates a new attribute and/or a new "Attributes" tab for a base object. <CObject> = The base object at which the new attributes are created. <NestedName> = The NestedName is the combination of the name of the "Attributes" tab and the name of the attribute - separated by a period (full stop). Example: Chap1.Spec1 is attribute "Spec1" on the "Chap1" tab. <Description> Optional: Sets or overwrites the description of the object. Please note: The control properties (location of the attribute on the tab, size of the attribute, etc.) cannot be set. Sets the value of an attribute or overwrites it. <SpecOwnerObject> = The object variable of a device or CDevice. (No string variable with the name of a device or CDevice!) <NestedName> = Combined name of the tab and the attribute. (String) <vnewvalue> = The new value. Sets the unit of an attribute or overwrites it. <SpecOwnerObject> = The object variable of a device or CDevice. (No string variable with the name of a device or CDevice!) <NestedName> = Combined name of the tab and the attribute. (String) <vnewvalue> = The new value. Alternative command for <Variant> = StrField Fetches information from a special cell of the current row of the imported table. <Variant> = Variable of type variant <FieldName> = Name of the column (field name) or the index of the field, starting with one. Alternative command for <Variant> = Field Fetches information from a special cell of the imported table. <String> = Variable of type string <FieldName>= Name of the column (field name) or index of the field, starting with zero. Supplies output to DBMon. 84 Operating Manual, 09/2011, A5E

85 Standard import: Blank for tables 6.4 Script for import actions Module CNameForNewObject(<Index>) = <FullName> "Select Case <...> " "..." "End Select " "For i = <...> To <...> " "..." "Next " "For Each <...> In <...> " "..." "Next " "Do <...> " "..." "Loop " "While <...> " "..." "Wend " The following variables are automatically available: "WorkSet" Meaning Set... = NewObject Specifies the base object for the level (or to be more precise, the engineering object that makes up this node). The base object must exist already, the base object could also have been created already at an earlier point in time while the script was running. <Index> = Number of the level starting from the root object. In the example "X XY": The node "X" has index 1 and the object "XY" has index 2. (The first level always gets 1.) <FullName> = Name plus the specified path relative to the project of the base object, e.g., "@U Anl1". As a rule, the variable is defined in Global and can thus also be redefined in one of the other script constituents. A normal VBScript routine: is enabled when (case) occurs. A normal VBScript routine: is run as often as specified. A normal VBScript routine: runs as many times as there are members in this collection. A normal VBScript routine: runs as long as the condition (Do...) is fulfilled. With Exit option. A normal VBScript routine: as for Do... Loop, but without the Exit option. Returns the entire COMOS environment. All possible functions and properties can be found in Reference 1. See also chapter Declarations (Page 86). "Project" Returns the current project. The command is the quick alternative to WorkSet.GetCurrentProject. Operating Manual, 09/2011, A5E

86 Standard import: Blank for tables 6.4 Script for import actions Declarations This tab displays the functions and properties of the DLLs. A number of important DLLs have already been entered in the dropdown list: ISGlobalObj.dll The functions and properties that are available as script modules are programmed in this DLL. See also section Script modules (Page 82). comos.dll Displays all functions and properties of the WorkSet. You find additional information on this topic in the "COMOS.dll" class documentation. Applies to all DLLs: The last level (functions and properties) can be transferred as follows to the script: <Ctrl>+Drag&Drop Apart from the DLLs offered in the list, any other meaningful DLL can also be dragged into the edit field. The corresponding DLL is read in and its functions and properties are offered. Nonetheless, the DLL is not saved permanently and must be dragged manually into the list again next time. 86 Operating Manual, 09/2011, A5E

87 Standard import: Blank for tables 6.4 Script for import actions Example The following example can be used to import engineering objects. "CNameForNewObject(1) = "MyTest ABC"" "CNameForNewObject(2) = "MyTest MM"" These two rows ensure that the engineering objects of the first level (Index=1) and the objects of the second level (Index=2) are linked with base objects. The base objects must exist already. "ImpObjectsCount = 0" Here a counter is initialized to zero. "Sub Init()" " ' Let us assume that such an object exists already" " Set RootObject = Project.Devices.Item("XX3") " Object XX3 is set as the root object in the start routine that is run right at the beginning. XX3 is located directly underneath the project. All objects that are created subsequently are deposited underneath this root object. This assumes that XX3 exists already. If XX3 does not exist, an error occurs. "End Sub" "Sub ImportRow()" " RName = "Imp " + StrField("CategoryID")" Here a string is assembled that likewise supplies the node and the name for the objects to be created later. The name is made up of two constituent parts: - A fixed text part "IMP " : this fixed constituent supplies the node, under which the object is created - and the text, which is likewise read from the cells of the imported table - this variable text serves as the name of the object to be created. "Set ND = NewObject(RName, "imported object")" New objects are created. RName was created as a string further above. The text "imported object" is always used as the description. "If Not ND Is Nothing Then " " ImpObjectsCount = ImpObjectsCount + 1" " End If " If the object was created correctly, then the counter from Global is incremented by one. "End Sub" "Sub Finish()" " OutputDebugString CStr(ImpObjectsCount) + " objects imported"" "End Sub" The number of imported data records (= number of created objects) is output in DBMon. "End Sub" Operating Manual, 09/2011, A5E

88 Standard import: Blank for tables 6.4 Script for import actions 88 Operating Manual, 09/2011, A5E

89 PCS 7 - COMOS data transfer via Automation 7 Interface You can find additional information on this topic in the "COMOS Automation Interface" manual, keyword "Data transfer PCS 7 - COMOS via Automation Interface". Operating Manual, 09/2011, A5E

90 PCS 7 - COMOS data transfer via Automation Interface 90 Operating Manual, 09/2011, A5E

91 AutoCAD (Export, Import DXF) Export Preparations: DWG/DXF mapping editor To start, click on the "Plugins > Basic > DWG/DXF mapping editor" menu in COMOS. In COMOS, the import/export of DWG data is controlled by means of an ini file. This ini file contains conversion stipulations for colors, lines, layers, etc. The DWG mapping editor creates and modifies such ini files via an easy-to-understand Windows dialog. Prior to the export you have to create a correct dxf.ini using the DWG mapping editor. The export operation always uses the file "comos\ocx\report\dxf.ini". "General" tab "DWG/DXF-Version": AutoCAD 14, AutoCAD "Polyline": AutoCAD knows two different "Circles": One is a real circle, the other is comprised of an assembled set of line segments. The "True" circles can only be fully controlled externally as of AutoCAD "AutoCAD 14", "Polyline" ON: Circles are exported as polylines (which are made up of several lines). The circle attributes (color, line thickness) are also exported. "AutoCAD 14", "Polyline" OFF: Circles are exported as real circles. The circle attributes are not exported and the circle is drawn in AutoCAD with default parameters. "AutoCAD 2000", "Polyline" ON: Circles are exported as polylines (which are made up of several lines). The circle attributes (color, line thickness) are also exported. "AutoCAD 2000", "Polyline" OFF: Circles are exported as real circles. The circle attributes (color, line thickness) are exported as well. Operating Manual, 09/2011, A5E

92 AutoCAD (Export, Import DXF) 8.1 Export "Line types" tab Is not evaluated during an export operation. The following allocation is always applied: $DWG COMOS CONTINUOUS 1 ACAD_ISO02W100 2 ACAD_ISO03W100 2 ACAD_ISO04W100 4 ACAD_ISO05W100 5 ACAD_ISO06W100 1 ACAD_ISO07W100 9 ACAD_ISO08W100 2 ACAD_ISO10W100 3 "Colors" tab Is evaluated. "Layer" tab Is not evaluated. Any layers defined in the COMOS drawing that have not yet been input in the "dxf.ini" are stored there automatically. "Combination" tab Here you can identify special objects by specifying all convertible properties (color, line, layer). The objects are then converted individually. In other words: even if only one of the properties is described inaccurately, the individual object in question cannot be found and converted. Set a desired input with * If an asterisk is entered for an information it is interpreted as an "Optional value" or "All values" respectively. Do not enter an asterisk on the "Layer" tab in the "COMOS layer" column; if you do so, the export will produce meaningless data. On the "Combinations" tab experienced users can work with asterisks. 92 Operating Manual, 09/2011, A5E

93 AutoCAD (Export, Import DXF) 8.1 Export Conducting an export In COMOS, click on the "Documents > DWG/DXF export"menu. or Right-click in the Navigator to select the corresponding report and select the "Export > DXF/DWG" command from the context menu. Reports can be exported as AutoCAD files. If you select this command in the COMOS menu, the PrintManager will open first. There you collect the to be exported reports and then select [Execute]. If you select the mouse menu on the report, then only this single report is exported Scope of the interface The following information and objects can be exported from a report to AutoCAD: Layer Scale Lines COMOS lists Lists are broken down into lines and text. Hatching Circles (empty or filled) In dependency to the AutoCAD version and settings, as true circles or polylines. All report objects that can support a script The script is evaluated to determine which objects are generated in the script (texts, lines...). All these objects are generated, exported, and put together in a block. bmp files Icons AutoCAD cannot process icons. In such cases icons that are placed on a report are exported automatically as bitmaps. Texts Line breaks are exported as well. The current language is exported. If the texts have translations as well, then not all the languages are exported but only the one that is currently visible. Operating Manual, 09/2011, A5E

94 AutoCAD (Export, Import DXF) 8.1 Export Dimensions Dimensions are broken down into texts and lines. Dimensions are not exported as "dimensions" as such. Objects with the DXF tab If an engineering object has the DXF tab, then a block is created and all attributes of the DXF tab are created as "attributes" of the block. Exclusions Disabled (gray optional) objects are not exported to DXF. AutoCAD does not support the "ico" (icon) data format. For that reason icons are converted into bitmaps when they are exported to AutoCAD. Dimensions are broken down and are not exported as "blocks" but as dimensions. OLE file links in COMOS are not exported to AutoCAD. In the AutoCAD drawing, BMPs that are embedded in COMOS are only created as file links. This means that if you want to pass on the drawing you also need to pass on the corresponding BMPs. wmf files are not exported. Circles: AutoCAD knows two different "Circles": One is a real circle, the other is comprised of an assembled set of line segments. The "True" circles can only be fully controlled externally as of AutoCAD The color "white" is not exported. In AutoCAD the color "white" is interpreted in different ways, for example, as "black" in screen views and as "gray" in hard copy output. For that reason the color "white" is not exported at all so as to avoid any errors. Non-dissolved AutoCAD objects Import step 1 conducted, but not import step 2. Afterwards the complete report including the imported AutoCAD file is exported. Effect:: 1. The report is created as an own drawing. 2. The non-dissolved AutoCAD drawing is also created as an own drawing in AutoCAD. 3. The non-dissolved AutoCAD drawing in the report is created as a XRef (External reference). This means that it is referenced from the AutoCAD drawing of the report to the other AutoCAD drawing. 94 Operating Manual, 09/2011, A5E

95 AutoCAD (Export, Import DXF) 8.2 Import 8.2 Import An import operation is carried out in two stages. 1. Import of an object In this case the AutoCAD object still exists as a whole. This is called an "embedded object". 2. Dissolving the object The AutoCAD object is broken down into COMOS objects Import of an AutoCAD object Preparing fonts The quality of the text display of a DXF file improves clearly if the AutoCAD font files are available. This only applies to DXF files that were not dissolved yet. In this case COMOS only uses the AutoCAD display. 1. You need to take the original AutoCAD font files and copy them into a single directory on the hard disk. 2. The directory of these font files must be registered as an (environment) system variable on the computer. For example: "ACAD=c:\autocad\fonts" The settings are applied the next time COMOS is started. The import is then conducted as described below. The improved text display relates to: text alignment, text size, text font Import step 1 AutoCAD drawings can be imported to interactive reports or used in a base object as a symbol. Import to a report: Drag a dwg or dxf file from the Windows Explorer into the report. Import as symbol: Open the "Symbols" tab for a CDevice and select the file selection on the bottom of the "Symbol" field using the ["..."] button. In the dialog box that opens, you can also select dwg and dxf files under the "Drawings" heading. No COMOS objects have yet been generated at this point; also, no conversion file "dxf.ini" or "dxf_inch.ini" is evaluated. The AutoCAD object is displayed with the help of Windows and AutoCAD interpreters. In other words: the display of the placed AutoCAD object is not yet controlled by COMOS at this time. The AutoCAD object owns own properties. Operating Manual, 09/2011, A5E

96 AutoCAD (Export, Import DXF) 8.2 Import Undo Please note: Due to technical reasons there is no "undo" available for an import of dwg / dxf drawings. An import can be undone, by closing the report without saving it Mouse menu of the AutoCAD object AutoCAD objects cannot be selected in the usual way. Instead, AutoCAD objects have a selection box: You select an AutoCAD object when you check this box. You can then call the context menu of the object. The following commands are available in the context menu: <Default commands>: These function in the usual way. "Dissolve DWG/DXF drawing into engineering objects" menu Import step 2: Creating COMOS objects. See also chapter Import step 2: Dissolving the drawing into engineering objects (Page 98). "Dissolve DWG/DXF drawing graphically" menu Import step 2: Creating COMOS objects. In this case, however, you only generate report elements and no engineering or base objects. See also chapter Import step 2: Dissolving the drawing graphically (Page 103). "Analyze DWG/DXF drawing" menu Import preparation: The DWG drawing is analyzed and the results are written to a new conversion file. The file has the name of the DWG file: a Motordrive.ini file is created with a Motordrive.dwg file. Analysis options: Once drawing analysis has started, the dialog window "Analyze DWG/DXF file" opens with two options. These two options are not evaluated. Only the layers and lines that are used will be entered in the ini file. Assign COMOS values to the DWG values in the DWG mapping editor. See also chapter Preparations: DWG/DXF mapping editor (Page 99). 96 Operating Manual, 09/2011, A5E

97 AutoCAD (Export, Import DXF) 8.2 Import "DWG/DXF mapping editor" menu No import, but an import preparation. "Properties" menu The information of the embedded AutoCAD object is displayed in the properties window: "File name" field Path to the embedded AutoCAD file. "Editable" option The individual elements of the drawing can be selected and deleted individually. "Generate AutoCAD line types" option Windows cannot display all AutoCAD line types correctly. If the display of the AutoCAD drawing in COMOS contains errors, you can turn on the above option. In such a case all windows character routines are turned off and the display is only conducted via ViewKit. The performance might decrease. "Layout" list Here you change the layout of the DWG drawing that you want to display. When you place the DWG drawing, the layout that was saved as first visible layout by default in AutoCAD is automatically selected. You recognize the standard layout by an asterisk in front of or behind the name. All layouts created in AutoCAD are offered as possible values. "Layers" table The layers of the AutoCAD object are displayed here. Layer 0 must always exist. Visible: You can switch between Yes and No by double-clicking. The corresponding layer is displayed or not displayed in the report. Plot: Cannot be changed. Operating Manual, 09/2011, A5E

98 AutoCAD (Export, Import DXF) 8.2 Import Import step 2: Dissolving the drawing into engineering objects The following import dialog appears: "File version" Self-explanatory. "Ini file": The ini file contains the parameters that control the import operation. The ini file thus determines what specific objects should look like after the import (for example, line thickness, etc.). The ini files are edited with the DWG mapping editor. See also section Preparations: DWG/DXF mapping editor (Page 99). "Create graphic in document" Only report objects are generated. "Create base objects only" Only base objects are created; neither engineering objects nor report elements are created. "Create engineering objects" Engineering objects and base objects are created. The engineering objects are placed on the report. 98 Operating Manual, 09/2011, A5E

99 AutoCAD (Export, Import DXF) 8.2 Import "Correct point of origin of page automatically" ON: The lower left point of the AutoCAD drawing to be dissolved is placed on the lower left point of the report. The origin of the report is not evaluated. OFF: The lower left point of the AutoCAD drawing to be dissolved is placed at the point of origin of the report. "Unit conversion" Controls the display size of the generated objects. For 1:2 the report elements would be displayed twice the size after dissolving. For 1:0.5 the result would be displayed half the size Preparations: DWG/DXF mapping editor To start, click on the "Plugins > Basic > DWG DXF mapping editor" menu in COMOS. General In COMOS, the import/export of DWG data is controlled by means of an ini file. This ini file contains conversion stipulations for colors, lines, layers, etc. The DWG mapping editor creates and modifies such ini files via an easy-to-understand Windows dialog. You can find a sample file in the COMOS directories /"ocx/dxf.ini" and /"dxf_inch.ini". If changes are made in the DWG mapping editor and a "dxf.ini" file or a "dxf_inch.ini" file is saved at another point, then this file is used in the current working session. The template files in the ocx directory are used again after restarting COMOS. If an AutoCAD object is dissolved, you have the option to choose a specific ini file. Interface "General" tab: Import: "Ignore all hidden layers": Layers that have been grayed-out in AutoCAD are not imported to COMOS. "Drawing type": you must select a drawing type, since the layers are defined in COMOS according to drawing type. "Line types" tab: Self-explanatory. Operating Manual, 09/2011, A5E

100 AutoCAD (Export, Import DXF) 8.2 Import "Colors" tab: Largely self-explanatory. Important additional information: You find a corresponding command in the icon menu: you can call a complete sample mapping between DWG colors and COMOS colors with "Create DWG color palette". "Layer" tab: Largely self-explanatory. Important additional information: You find a corresponding command in the edit icon menu: "Set COMOS layers automatically". Application: Start by selecting a number of rows on the "Layer" tab, then select the "Set COMOS layers..." command from the icon menu. You can input a "-" minus sign in the cells of the "COMOS Layer" column. The minus sign is translated into the text "@IGNORE". All DWG elements whose DWG layer is allocated to the COMOS layer "@IGNORE" are not imported. "Label" column Here you can enter additional information such as the "Header class". Example: You could then write a script in which evaluates this label at texts so that specific text is not created as text objects but as connector objects instead. "Combination" tab: Here you can identify special objects by specifying all convertible properties (color, line, layer). The objects are then converted individually. In other words: even if only one of the properties is described inaccurately, the individual object in question cannot be found and converted Other import settings Automatic scaling for the import of AutoCAD files: Details are input into standard (often in the system project) for the individual drawing types. For example, value 1 contains a LogoCAD label, value 2 the template grid. The unit can be input in value 3. If, for example, the value here is set to "1" (1 = inch), then scaling factor 25.4 will be used when converting AutoCAD drawings Central base data branch for DXF imports If DWG drawings are dissolved while using the "Create base data" option, then the base data is stored in branch "Import DXF": If an import is made into the base project and if a corresponding node does not yet exist there, this is created automatically. In the case of an import into an engineering project when an "Import DXF" node already exists in the base project, then no such node is created in the engineering project. Instead local base objects are created in the existing node (which is in the base project anyway). If there is no "Import DXF" node in the base project, the node is created in the engineering project. 100 Operating Manual, 09/2011, A5E

101 AutoCAD (Export, Import DXF) 8.2 Import Importing DXF data within an engineering project: Each object is checked individually if it is already existent in the base data of the base project. Only those objects that do not already exist in the base project in "Import DXF" are created within the engineering project. Importing DXF data within an engineering project: When overwriting symbols (which can be selected via a dialog) the base objects in the base project remain unchanged. The existing symbols in the base project thus take priority and an import is only made for the case that symbols are exclusively located in the engineering project. If you want to modify the symbols in the base project, the import also has to be done in the base project Adjustments for the import After import step 2 with the creation of base objects you should conduct the following base data actions: Base objects Link the generated import CDevices to "real" CDevices. The import CDevices can be found in the base project under "Import Therefore you create a base object reference to a "real" CDevice in the properties of the import CDevice. The symbol which was read out from the ACAD file is used for the subsequent conversion, not the referenced original symbol for the linked CDevice. It can be exchanged later with the "real symbol" via "Restore the original symbol". Attributes Linking the created DXF attributes underneath the DXF CDevices to the "real" attributes of the COMOS CDevice. To do so you call the linked DXF attribute and create a view attribute on the "real" attribute. Link type "Via own object", "Fully dynamic". Afterwards drag the "real" attribute from the base data into the "Attribute" input field. Automation by means of script Creation of a script on the CDevice (and linked) base object with the name "OnDXFImportDone". In this script, for example, the newly created object can be sorted into a KKS unit tree. For this purpose, the following function is required in "UserScriptBlock1": Function OnDxfImportDone() End Function Please note: "Sub" is not supported here. Operating Manual, 09/2011, A5E

102 AutoCAD (Export, Import DXF) 8.2 Import Repeating the import After dissolving the DWG drawing again (this time without creating base objects), devices are created on the document and in the COMOS tree and the corresponding attribute values are applied to the "real attributes" Scope of the interface All objects that were created or designed as follows are considered and imported: Circles, arcs Also when mirrored. Ellipses Lines, polylines, LwpType, MLine Vertices (endpoints of polylines) Solids HatchType Is dissolved in the graphic, therefore is not a COMOS hatch. Reason: the properties of an AutoCAD hatch (line sample, thickness, distance, color) are not compatible with the properties of a COMOS hatch. Blocks Scaling, moving, rotating, and mirroring is also considered for nested AutoCAD blocks. Text movements in AutoCAD blocks are considered. AutoCAD objects with subsequent changes in text height of placed text blocks are considered. Text, MText (MText includes line break) During the conversion the text height is checked to ensure that it has a size of at least 1 point; if the value is smaller than this, it is set to 1 point. Report texts are located in the set layer and not in layer 0. AttDef Are converted into report texts. AttribDef Are converted into attributes. Texts from text attributes are also generated if the associated block does not have any graphical elements or Attdefs. Texts are not generated if the text is an empty string! Units supported for import: "inch", "mm", and "no unit". If the import detects that the AutoCAD drawing has the unit "inch", the ini file "DXF_inch.ini" from the OCX directory is used automatically. 102 Operating Manual, 09/2011, A5E

103 AutoCAD (Export, Import DXF) 8.2 Import Exclusions Note regarding layers / colors If an ACAD element is supposed to fetch its color from the layer, then the layer color has priority over the element color. If an ACAD color is not defined in the DXF.INI, the default color (black) is taken. Note regarding the line thickness The line thickness always deviates from the color valid for the element (from: DXF.INI). If a line thickness is not defined in the DXF.INI, the default line thickness (0.13 mm) is taken. Dimensions Dimensions including texts are not imported. Special conversions Meaning in AutoCAD drawing Attribute definition with a description within a block. (This is used as a placeholder in AutoCAD.) Meaning after COMOS conversion New attribute with attribute name + generation of a %N text in the block symbol. Setting the attribute definition to invisible. The attribute is created, but no symbol is created for %N text. Editing entries via "Edit attributes" (can be input after Attribute values for created attributes on the devices. creating blocks). Block with label. New CDevice with a CDevice name (if not yet present) under "Import Block.Description contains the "Ignore" text entry CDevice is created, but is not placed on the document. Drawing elements within a block. Drawing elements for the symbol script of the CDevice. (The current document drawing type is taken over for the symbol.) Import step 2: Dissolving the drawing graphically The user gets the same dialog window as the one described in section "Import step 2: Dissolving the drawing into engineering objects (Page 98)". However, only the "Create graphic in document" option is enabled. At first the DXF import is conducted as described, although afterwards all report objects are dissolved into report elements, and all engineering objects are deleted afterwards. In the end, the removed AutoCAD object exists graphically on the report, but no engineering objects or base objects exist. Operating Manual, 09/2011, A5E

104 AutoCAD (Export, Import DXF) 8.3 Only display AutoCAD files 8.3 Only display AutoCAD files The following options can be used to display an AutoCAD file without converting it: As an external document Use drag&drop to drag the file from the Windows Explorer to the Comos Navigator. As a PQM document Use drag&drop to drag the file from the Windows Explorer to the Comos Navigator. The AutoCAD drawing is checked for external references during this operation. As an external drawing on a report Use drag&drop to drag the file from the Windows Explorer or Comos Navigator on an interactive report. The OpenDWG interface is used to display the AutoCAD drawing. Afterwards it is possible to dissolve this file. 104 Operating Manual, 09/2011, A5E

105 COMOS Document Interface (CDI) 9 The "COMOS Document Interface" (CDI) is a plugin that automates the export of COMOS data into Office documents (Word and Excel). These documents can be incorporated into the customer's corporate design in terms of layout, archived with other documents or forwarded (e.g., to external customers). Furthermore, data edited in Office (only in Excel) can be reimported into COMOS. The following section describes: which requirements the CDI plug-in underlies, which alternative techniques are available, and the relative advantages and disadvantages the various methods have: Section "Initial situation and aim (Page 106)" which technical preconditions need to be fulfilled in order to be able to use the CDI plugin: Section "CDI method: Requirements (Page 108)" how the CDI plug-in is handled: Section "CDI method: Operation (Page 109)" the interface that the user uses when scripting the import/export: Section "Reference of the programming interface (Page 115)" which changes an import/export operation causes in Word documents: Section Changes to the Word document (Page 125) the technical procedure behind an import/export operation on the software level: Section "Technical procedure (Page 126)" It additionally contains a number of examples which simplifies scripting for the user: Section "Examples and scripts (Page 118)" Operating Manual, 09/2011, A5E

106 COMOS Document Interface (CDI) 9.1 Initial situation and aim 9.1 Initial situation and aim Overview Data stored in COMOS objects must be made accessible to the user transparently in the form of documents. The content of these documents is to be generated automatically upon opening and should always be up to date, meaning that the documents must match their data with the data stock of the COMOS objects. It should also be possible to structure the documents flexibly, depending on their intended use. This means that it should be possible to freely determine both the number and the type of evaluated objects depending on the intended use and also which object data is to be evaluated and how it is to be displayed. Users must be able to create data sheets for the various types of components, generate parts lists, PipeSpec reports, etc. In addition, it should be possible to modify the content of the data in the documents and then to write it back automatically from the documents to the objects. A number of methods have been developed in COMOS to do this: Evaluation reports New Office link via the CDI plugin Evaluation reports Functionality Evaluation reports are COMOS-specific reports. Report administrators configure report templates that define which objects the reports evaluate, which actual object data is actually evaluated and how it is displayed. When a report is created, the content of the report is generated automatically. Users can edit the data in the reports - the modified values are then directly written back to the objects. If changes to the data were conducted directly in the object properties, conversely, the reports can be updated at any time. Reports can be printed, revisioned, and exported to Excel or Word. 106 Operating Manual, 09/2011, A5E

107 COMOS Document Interface (CDI) 9.1 Initial situation and aim Disadvantages Evaluation reports are extremely flexible automated to a high degree, but also have a number of disadvantages: They cannot be viewed independently of COMOS. This means that COMOS must be running for the entire period they are being viewed. The information they contain can only be externally transported by printing the report (to paper or file, in PDF format, for example) or exporting it (ReportToExcel or ReportToWord). ReportToExcel is executed up to Microsoft Office The formatting options are restricted. This means that an evaluation report that visually matches the various other business documents of the company (such as reports, business correspondence, etc.) can only be produced and integrated into the overall corporate design with some difficulty. In order to counteract these disadvantages, there is an option in COMOS to write the desired information directly to an Office document (Word or Excel) Office link Advantages of an Office integration The advantages of exporting the data to Word or Excel are as follows: Office offers significant more comprehensive formatting options. The work is made easier for users who have relatively little experience in working with COMOS, since they only need to open the Office document within COMOS and after that they can work in the Office application they are familiar with. The external editing of COMOS objects is simplified by editing the document independently of COMOS. In the case of Excel, the changes can later be written back to COMOS by means of a reimport query. CDI plugin In the plugin, the user writes a script for each Office document ("Sub DocCDI()"); which is evaluated and executed when the document is opened: Excel file: The script determines which data from COMOS is written to which table or cell of the Excel file. If the spreadsheet does not yet exist, it is created automatically. The values can be reimported into COMOS when the file is closed. Operating Manual, 09/2011, A5E

108 COMOS Document Interface (CDI) 9.2 CDI method: Requirements Word file: DocVariables must have been input beforehand to the Word file. It is then specified in the script which value is written to which DocVariable. The DocVariable is not created if it does not exist in the Word file. No reimport operation takes place when the file is closed. The functionality of the CDI plugin is described in detail in this manual. See also chapter CDI method: Requirements (Page 108). User requirements Substantial knowledge in VB Experience in working with COMOS script technology Users should be familiar with the classes, variables, and methods that are important when writing COMOS scripts. You find additional information on this topic in the "COMOS.dll" class documentation, keyword "ivbquery_dll", or in the "Programming" manual. 9.2 CDI method: Requirements Software Microsoft Office must be installed on the computer on which COMOS is running in order to use the technology for exchanging data between COMOS and Office. Office 97, 2000, 2003, and 2007 are currently supported Licenses CDI is already included in the basic license. Please note when using a viewing license that there is no evaluation for Word documents. Excel documents, on the other hand, are evaluated if you have a viewing license. 108 Operating Manual, 09/2011, A5E

109 COMOS Document Interface (CDI) 9.3 CDI method: Operation Microsoft Office configuration Macros are no longer used for CDI as of version 9.0. The following applies for earlier versions: Since modified values are written back to COMOS in Excel using macros, it is necessary to lower the level of security for macros. This requires that the security level for macros has to be reduced to medium. There you have to consider that bulk revision or similar processes such as dialog boxes that prompt if the macro should be executed are interrupted. This can only be avoided by setting the security level to low. In addition, the "Trust access to Visual Basic project" option must be selected. 9.3 CDI method: Operation Operation overview The following list offers an overview of the steps that need to be executed in order to export data from COMOS into an Office document, to edit it there, and to reimport it into COMOS if necessary: Create the Office document in COMOS. If required: open the Office document and prepare it. With Word documents: create the DocVariables. Start the COMOS document interface plugin. If required: drag the Office document to the plugin. Write the CDI script. Check the result of the script in the preview window. Save the CDI script. Close the plugin. Open the Office document to start the export operation. Work in the Office document. Excel: It is possible to start a reimport into COMOS by closing the document. Operating Manual, 09/2011, A5E

110 COMOS Document Interface (CDI) 9.3 CDI method: Operation Creating an Office document First of all, an Office document has to be created in COMOS. 1. In the Navigator, select the object under which the document is to be located. 2. From the context menu, select the "New > General > New Document" command. A new document is created and its properties are opened. 3. Enter a name and a description for the document. 4. Select the "Word document" or "Excel sheet" item from the "Type" list on the "General" tab. 5. Save your changes. You find additional information on this topic in the "Properties" manual, keyword "General documents" Preparing Office documents Preparing an Excel spreadsheet No preparations are required for Excel spreadsheets. If the spreadsheet addressed in the CDI script does not yet exist at the time of the import operation, you must create it. Preparing a Word document 1. Double-click to open the document from within COMOS. 2. In Microsoft Word, open the "Extras", "View" menu item. 3. Enable the "Show field functions instead of values" option in the "Show" control group: 4. Enter the DocVariables in the areas of the document in which you later want to output the COMOS data: Place the cursor at the desired position in the Word document. Click the "Quick Parts" button in the "Text" control group on the "Insert" tab and select the menu item "Field". The "Field" window opens. Select the list entry "Document Automation" and select "DocVariable" as field name. In the "New name" field, enter the name of the DocVariable. All DocVariables must have unique names. It is not possible to generate DocVariables dynamically during an export operation. Close the dialog by clicking on "OK": Result: The DocVariable is pasted into the document at the position of the mouse cursor: 110 Operating Manual, 09/2011, A5E

111 COMOS Document Interface (CDI) 9.3 CDI method: Operation 5. If the COMOS data is to be output in a spreadsheet: Create a spreadsheet with the desired columns before pasting the DocVariables (the number and names of the columns can be defined by the user as desired). Input the DocVariables into the cells of the spreadsheet. 6. Disable the display of field functions once again. 7. Save. Example The technical data of all components below a common owner is to be output. The corresponding number of DocVariables is created in the Word document. If additional components are created afterwards below the owner and an import operation is carried out, then the new components are not taken into consideration in the import because the corresponding DocVariables are missing in the Word document Working in the CDI plugin Select the icon of the COMOS document interface plugin from the plugin toolbar. The plugin window is opened. It is divided into four areas: 1. Object Pointer: 2. Toolbar 3. Script editor 4. Preview window (here with tree view) Operating Manual, 09/2011, A5E

112 COMOS Document Interface (CDI) 9.3 CDI method: Operation Document pointer Pointer to the document into which the import is to be made / for which a script is to be written. If the plugin is started while you are in the Navigator on a document, the document pointer is initialized with this document. Alternatively, the document can also be dragged into the field later using drag&drop (only possible with Excel and Word documents). Toolbar The known tools for script editors are available here (for example, for indenting, commenting out, saving, printing, etc.). Script editor In the script editor the user must implement the "Sub DoCDI()" script. The "Sub DoCDI()" script is also referred to as CDI script in this documentation. It defines which COMOS data is to be written to the Office document and where it is to be output. The user can call all public properties and methods from "ComosXMLContent.SCGlobal" in the script. See also chapter Reference of the programming interface (Page 115). In addition, all usual COMOS default script commands are available to the user. You find additional information on this topic in the "COMOS.dll" class documentation. The script that was input in the script editor can be started for testing by using the [!] icon from the toolbar. The result of the script is output in the preview window. Save the script. As a result, the script is saved in the XValue(1) of a hidden attribute. Since attribute values are not allowed to contain any pipe characters (" "), you are not allowed to use any pipe characters in the CDI script either. You find a number of tips about scripts in this manual. See also chapter Examples and scripts (Page 118). 112 Operating Manual, 09/2011, A5E

113 COMOS Document Interface (CDI) 9.3 CDI method: Operation Preview window The preview window offers a preview of the result of the import operation. Two view modes are available: Tree view and XML view. You can switch from tree view to XML view and back by clicking on the tree icon on the toolbar. The user will normally work with the tree view. It gives an overview of which data is to be exported and where. The following information is passed for each node: Icon of the node: The data is exported using the "Content" method. The data is exported using the "ContentFix" method. Word: Name of DocVariable to which is exported Excel: Name of the table/cell to which the data is to be exported: Which value is to be exported: Excel: For attributes that were saved with standard tables: The node can be expanded. The values offered in the standard table are listed underneath. These values are available in Excel as well after the export operation. Operating Manual, 09/2011, A5E

114 COMOS Document Interface (CDI) 9.3 CDI method: Operation Export When the Office document is opened, the CDI script of the document is executed automatically. The data is exported from COMOS to the Office application. See also chapter Technical procedure (Page 126). Apart from the data import, the changes have already been written to the document. See also chapter Changes to the Word document (Page 125). The data can be edited in the Office application. However, it should be noted that only Excel spreadsheets support the reimport of data into COMOS. Export to Word If the DocVariables addressed in the script do not exist in the Word document, then no data is exported. The exported data is only displayed in the document if the field codes in the document are not displayed (Open the "View" tab by selecting the "Tools > Options" menu from the menu bar in Word. Disable the "Field functions" option in the "Display" control group.) Export to Excel If the spreadsheet that is addressed in the script does not exist, it is created dynamically. The data is written into the specified cells of this spreadsheet. If an attribute that is saved with a standard table is in the exported data: The cell is saved in Excel with a dropdown list. All values of the standard table are available. If there is an attribute of type "Checkbox" in the exported data: A check is made to determine whether it is a checkbox or an options group. A checkbox or an options button is then included in the table accordingly Reimport If the data was exported to Excel using the "Content()" method, a reimport to COMOS takes place when the Excel file is closed: The values edited in Excel are automatically written back to the COMOS objects if the IO parameter of the method Content() has the value I. 114 Operating Manual, 09/2011, A5E

115 COMOS Document Interface (CDI) 9.4 Reference of the programming interface 9.4 Reference of the programming interface As soon as the CDI plugin is initialized with a document, the following method appears in the Editor window: Sub DoCDI() End Sub This method is started automatically when evaluating the document if a CDI script was saved in the document (in the "XValue(1)" of a hidden attribute). In this method the user can input his own script. All public properties and methods from "ComosXMLContent.SCGlobal" are made available to the user in the script Get Property: Document Declaration "Public Property Get Document() As IComosDDocument" Description Returns the underlying Comos document Get Property: MappingTableExcel Declaration "Public Property Get MappingTableExcel() As IMappingTableEx" Description Is only set if there is a MappingTableEx below the document Get Property: Project Declaration "Public Property Get Project() As IComosDPro ject" Description Returns the current project Get Property: ReportObject Declaration "Public Property Get ReportObject() As IComosBaseObject" Description If a ReportObject was set at the document, then this is returned; otherwise, the owner of the COMOS document is returned. Operating Manual, 09/2011, A5E

116 COMOS Document Interface (CDI) 9.4 Reference of the programming interface Get Property: Workset Declaration "Public Property Get Workset() As IComosDWorkset" Description Returns the Workset Function: ExcelABC Declaration "Public Function ExcelABC() As String" Description Enables the conversion of a number into its equivalent as a column name. This method can be helpful if you iterate collections via an index. You can thus determine the index of the column name with the help of the "ExcelABC()" function Function: Content Declaration "Public Sub Content(ByVal DocPointer As String, " " ByVal ComosObject As IComosBaseObject, " " ByVal PropName As String, " " ByVal PropParameter As Variant, " " ByVal PhysUnitLabel As String, " " ByVal IOMode As String, " " Optional ByVal AllValuesNumeric As Boolean)" Description Depending on "IOMode", data is exported from COMOS into Office, imported from Office into COMOS or exported and reimported using "Content()". "Content()" can also be used for Word documents. However, since these only support the exporting of data from COMOS, the more simple "ContentFix()" function can also be used for Word files. Parameters "DocPointer" Specifies at which position in the document the value is to be written and/or from which position the value is to be written back to COMOS. Excel: Specify the spreadsheet and the cell here: "Spreadsheet name!cell name", for example, "Spreadsheet1!B9". If the specified spreadsheet does not yet exist, then it is created. Word: Input the name of the DocVariables here, for example, "volume". It is not possible to write this data back to COMOS. "ComosObject" Unlike with Excel, the specified DocVariable is not created if it does not yet exist. The object from which the value of a property is to be queried or to which the value is to be written back (normally the "Specification" SystemType, although other SystemTypes are possible). 116 Operating Manual, 09/2011, A5E

117 COMOS Document Interface (CDI) 9.4 Reference of the programming interface Parameters "PropName" "PropParameter" "PhysUnitLabel" "IOMode" "AllValueNumeric" Determines which "ComosObject" property is to be read in or out. Either a property or a function of the "ComosObject" is passed (for example, "Name", "GetDisplayValue", "GetXValue", etc.). If a method was passed using the "PropName" method, a parameter can here be specified for the queried property For example, if you want to query "ComosObject.GetXValue(0)" via a CDI script, this would look as follows: Content "Table1!C2", ComosObject, "GetXValue", 0, "", "IO", False Physical unit of the value returned by "PropName" in the form of a string. The value is converted into the unit specified in "PhysUnitLabel" and then passed to Excel as a number. This means that the cell gets the "Numeric" format. The value can then be used in Excel for further calculations. The specified unit must originate from the units group that was set at "ComosObject". Otherwise the current unit of the COMOS attribute is used automatically. Empty string: No unit is passed. Specifies in which direction the data is to be written: "I": Is only supported by Excel. Data is written from Excel to COMOS "O": Is supported by Excel and Word. Data is written from COMOS to Word or Excel. "IO" or "": A combination of "I" and "O". Is only supported by Excel. Optional parameter. Specifies if an attempt is to be made first of all to interpret the value that is to be written as a numeric value. This parameter is extremely relevant to Excel. For example, it may be that an alphanumeric attribute only contains numbers. If you were to write these values to Excel as a string, you would no longer be able to use them to make any calculations Function: ContentFix Declaration "Public Sub ContentFix(ByVal DocPointer As String, " " ByVal vnewvalue As Variant, " " Optional ByVal AllValuesNumeric As Boolean)" Description This method is a simplified variant of the "Content()" method. It can only be used to export values from COMOS. It is not possible to write back the values. Since only the value that is to be output is passed but the information about which object and which property this value belongs to is missing, numeric attributes cannot be detected automatically. Therefore, each value is formatted as a string in Excel by default. Only through the last optional parameter you have the option to force the formatting to be numeric. Parameters "DocPointer" "vnewvalue" "AllValuesNumeric" In the same way as for "Content()", the position where the value is to be written to within Office is specified here. The to be written value value. Specifies if the value should be interpreted as a number. Operating Manual, 09/2011, A5E

118 COMOS Document Interface (CDI) 9.5 Examples and scripts 9.5 Examples and scripts The following section describes how to make use of the Office integration via CDI using the following two cases: Case 1: Output all data of a component The Office document should be a container data sheet. This means that it only outputs the attributes of a container. Case 2: Output the data of several components Several containers are located underneath a folder. The Office document is to output the technical data of all objects underneath this folder Excel Create a document of type "Excel spreadsheet" in COMOS. Mark the document in the Navigator and start the CDI plugin. 118 Operating Manual, 09/2011, A5E

119 COMOS Document Interface (CDI) 9.5 Examples and scripts Case 1: Output all attributes of a component Input the following script in the script editor: (1) Set the ReportObject (2) Read the name and description of the container (3) Read the name and description of the tab(s) (4) Read the name, description, and value of the attributes of the tab(s) Execute the script on a test basis ([!]) and save it via the COMOS status bar. Open the Excel spreadsheet: The import to Excel is conducted automatically. The spreadsheets that are addressed in the script are created automatically as the script runs: Operating Manual, 09/2011, A5E

120 COMOS Document Interface (CDI) 9.5 Examples and scripts Since the attribute values were read via "Content()" and the "IOMode" is set to "IO", the attribute values can be modified in Excel and automatically written back to COMOS by closing the Excel file. Case 2: Output the data of several components Input the following script in the script editor: (1) Set the ReportObject (2) Output the object name and description (3) Output the attribute name, attribute description, and value of all attributes from the "PI030" "Technical data" tab. Execute the script on a test basis ([!]) and save it via the COMOS status bar. 120 Operating Manual, 09/2011, A5E

121 COMOS Document Interface (CDI) 9.5 Examples and scripts Open the Excel spreadsheet: The import to Excel runs automatically. The spreadsheets that are addressed in the script are created automatically as the script runs: Since Content() passed "cm" as the PhysUnitLabel in this example, the values in COMOS are converted into "cm" in Excel. Since the attribute values were read via "Content()" and the "IOMode" is set to "IO", the attribute values can be modified in Excel and automatically written back to COMOS by closing the Excel file Word Create and open a document of type "Word document" in COMOS. Enable the field codes and insert DocVariables. It is recommended that you input a combination of column title and line index as the name of the DocVariables. Case 1: Output all data of a component Input the column caption in the first line. Create a DocVariable for the component name and another for the component description in the second line. Operating Manual, 09/2011, A5E

122 COMOS Document Interface (CDI) 9.5 Examples and scripts Create the respective DocVariables for the name, description, and value of the attribute in the third line. Copy the line and paste it as many times as the attributes are to be read. Manually modify the counter in the DocVariables: In the lines in which the name and description of the tabs are to be output later: delete the Value-DocVariables. (In our example: Delete DocVariable "Spec1_Value".) Reason: Tabs do not have a value. Therefore, this DocVariable would cause an error message during the import. Disable the display of the field codes and save the document. Mark the document in the Navigator and start the CDI plugin. Input the following script: Execute the script on a test basis ([!]) and save it via the COMOS status bar. 122 Operating Manual, 09/2011, A5E

123 COMOS Document Interface (CDI) 9.5 Examples and scripts Open the Word document. The import to Word runs automatically. The number of values read from COMOS will not exceed the number of DocVariables created. If you take the spreadsheet from the illustration above, then the name/description of the container, the name/description of the first tab, and the name/description/value of the first attribute of this tab are read: Case 2: Output the data of several components Input the column caption in the first line of the Word document. Create a DocVariable for the component name and another one for the component description in the second line (1). Create the respective DocVariables for attribute name, description, and value of the attribute in the third line. Copy the line and paste it as many times as the component attributes are to be read. Ensure that you create as many lines/docvariables so that the data of all components located below the folder can be exported. Increment the counter of the DocVariable for each line (2). Copy the second line (DocVariable for the component name and description) and increment the counter (1). Copy the attribute lines and increment the counter (2). Operating Manual, 09/2011, A5E

124 COMOS Document Interface (CDI) 9.5 Examples and scripts Continue in the same way until DocVariables were pasted for all components below the folder: Disable the display of the field codes and save the document. Mark the document in the Navigator and start the CDI plugin. 124 Operating Manual, 09/2011, A5E

125 COMOS Document Interface (CDI) 9.6 Changes to the Word document Input the following script: Execute the script on a test basis ([!]) and save it. Open the Word document. The import to Word runs automatically. The number of values read from Comos will not exceed the number of created Docvariables: 9.6 Changes to the Word document The content of the Word document changes when values are exported to Word. Other changes, such as reformatting or the insertion of macros, are not made. Operating Manual, 09/2011, A5E

126 COMOS Document Interface (CDI) 9.7 Technical procedure 9.7 Technical procedure The "Execute()" method is called at an instance of "ComosXMLContent.CDIScript" when the document is opened. This method initiates the CDI script of the document. More precisely: The "CDIScript" object initializes a "ScriptLib.Script" object and via its "ItemScriptObject("CDIScriptRun")" calls the "DoCDI()" method of the actual CDI script. In this way, the actual evaluation process takes place in the "ScriptLib". The "IDocWord" or "IDocExcel" instance receives a "MSXML.DOMDocument" as a result. Subsequently "CDIxExcel" or "CDIxWord" starts to read this "DOMDocument" and writes the values to the Word or Excel document respectively Export COMOS -> Word The procedure for the export of data to Word is relatively clear. The CDI script is executed after opening the document. Subsequently "CDIxWord" analyzes the XML document that was generated by "ScriptLib" and writes the values to the associated DocVariables: 126 Operating Manual, 09/2011, A5E

127 COMOS Document Interface (CDI) 9.7 Technical procedure Export COMOS -> Excel and Import Excel -> COMOS Only Excel supports writing back values from Excel to COMOS. To do so the CDI script is again initiated in the "BeforeSave()" and "BeforeClose()" events of the "WorkBook". Both events were implemented in "ThisWorkbook" for this purpose. In "CDIxExcel.CdiToComos()" the "DOMDocument" is now run again and the values are written back to COMOS with the help of a query: Special case: Checkboxes and combo boxes In COMOS there are attributes for which you can select from predefined values. In the case of catalog attributes, these are normally displayed as a combo box; in the case of Boolean values, they are normally displayed as a checkbox. If the "Content()" method of "XMLContent.SCGlobal" was called with "IOMode" "IO" or "O", the corresponding control element for such attributes is pasted in within Excel. To that end, the "IOMode" is first of all checked within "CDIxExcel.CdiToExcel". If this is set to "IO" or "O", a check is made to see whether it is a checkbox or an options group. If this is the case, a checkbox or option button is created accordingly in the Excel document. If the "XMLContent" offers "ValueItems" for the current COMOS object, a combo box is created and the DisplayValues of "ValueItems" are input there. Operating Manual, 09/2011, A5E

128 COMOS Document Interface (CDI) 9.7 Technical procedure 128 Operating Manual, 09/2011, A5E

129 RTE (Report-to-Excel) Area of application Please note: The RTE (Report-to-Excel) module is not included in the scope of the standard licenses. With the help of the "Report-to-Excel" module, evaluation reports can be exported in Excel format. The data can be fully edited in Excel and even the layout of the Excel page can be freely changed. This enables you to forward COMOS data to companies that do not use COMOS, such as suppliers. Scope of export The following report elements can be exported: lines, circles, text boxes, checkboxes, SubReports, lists, picture boxes, and WMF images. Interactive reports Interactive reports are not supported with regard to content: neither symbols nor connection lines are exported to Excel. However, it is possible to export an interactive report by means of RTE. This, for example, allows the following special case used in FEED: a standard table is created by means of an interactive report in order to use FEED-specific automated processes. The result of this FEED technique corresponds to the normal scope/content of a list based on an evaluation report. Because of that it is possible to export such a report via RTE Preparation of the evaluation report Report elements may not overlap on an evaluation report, or lie outside the sheet range. Only free graphics may be placed on top of other report elements Start export To start the export, open the PrintManager, set a start object, and then mark one or more evaluation reports in the results list. Then, in the options, select "Extended functions" and click on the "Report-to-Excel" icon on the PrintManager icon bar. You can also select a document of the document package type. Then all reports below the package will be exported. Operating Manual, 09/2011, A5E

130 RTE (Report-to-Excel) 10.4 Using the report in Excel 10.4 Using the report in Excel As of Office 2007 users no longer see a separate dialog window prompting them to activate the macros. Instead, a cell containing the text "Safety prompt: Some active content has been deactivated" appears towards the top of the Excel spreadsheet. Click on the ["Options"] button on this line and select the "Enable this content" option which appears in the next dialog. This option must always be enabled if you want to work with the Excel table generated by the export. The above described activation has to be conducted each time Control via the options script The following options can be entered in the options of the relevant report templates (context menu " Options"). "xlfoldermargin" (numeric) The variable "xlfoldermargin" can be entered in the options script of a report. Thus you can set a margin for the page in mm that takes effect when the report is written to Excel. "ExcelRaster" (numeric) Changes the report grid. "ExcelMergeAll" (bool) If the variable is not used in the options script, "False" applies as the default value. If the variable is set to "True", blank text fields are also exported to Excel. Blank text fields are not exported if set to "False" (better performance). "Hairline", "ThinLine", "MediumLine", "ThickLine" (numeric in mm) In Excel, there are four line types in order to differentiate the thickness. Variables with identical names were created in COMOS. Example: "Hairline=0.2, ThinLine=0.5, MediumLine=0.75, ThickLine=1.0" In this case, all COMOS lines with a line thickness between 0 mm and 0.2 mm are passed as type "Hairline", lines between 0.2 mm and 0.5 mm in thickness are passed as type "ThinLine", etc. All four variables must be set, otherwise this technique cannot be applied. If no or not all of the variables are set, then the default setting "Thinline" is set for all cell borders. 130 Operating Manual, 09/2011, A5E

131 RTE (Report-to-Excel) 10.5 Control via the options script "ExcelSheetScaleH", "ExcelSheetScaleV" (numeric in percent) These variables calculate the size of the object properties newly. Thus the text sizes, line thicknesses, width, height, etc., of the objects are correspondingly scaled up or down when an export operation is carried out. The "SheetScale" function thus has nothing to do with zooming, which only increases or reduces the size of the display of the object on the monitor but the size of the object itself remains the same. Values between 50% and 120% are permitted. Background: The time required by Excel to calculate an imported object increases with the size of the object. Excel thus requires noticeably more time to calculate a large text field than a small one. If the export operation to Excel takes a very long time, you can then speed it up by setting the sheet scale to a smaller value. This will require a little more time, since a calculation is made within COMOS for the smaller size; however, on the other hand, Excel requires noticeably less time to generate the objects. The "SheetScale" option is functionally identical to "Sheet scaling" in the "Save file" dialog window when the export to Excel is prepared within the Print Manager. "ExportFreeGraphic" (bool) If "ExportFreeGraphic = True" is set, then the free graphics are also exported to Excel. If the variable is not existent or set to "False", then these graphics are not exported. Background: In evaluation reports circles and lines are classified according to whether they fulfill a "function" or are "free". A line fulfils a "function" if it is part of a text field frame or visually separates a column or a row, etc. The line is "free" if it does not fulfill a function. In practice, lines nearly always fulfill a function within evaluation reports, since a table is drawn in the report, text boxes are drawn, etc., with the help of lines. Therefore, in the default setting, lines and circles in evaluation reports are regarded as having a function. For lines, the user can define if a line is to be functional or "free". To do this, the user opens the properties of the line and clicks on the "No cell delimiter" button. This button sets the "G" label internally, which COMOS uses to identify free graphics. "exvisible" (bool) If the variable is set to "True", then Excel remains visible during the export operation and you can see how the individual elements are generated one after another in Excel. If the variable does not exist or is set to "False", Excel is not visible. The export operation is much faster when Excel is not visible. Operating Manual, 09/2011, A5E

132 RTE (Report-to-Excel) 10.6 Reimport 10.6 Reimport It is possible to reimport such exported evaluation reports. The report options script has to contain the following: "Keepscriptrunning = True ExcelMergeAll = True ExcelReimportModus= True" The "ExcelReimportModus" variable generates a "Shadowtable", i.e., a hidden Excel sheet. All reimported cells are displayed with a green background in Excel. Log file during reimport "Options script ExcelMergeError = True" A file "..\temp\errorexcelexport.log" is created if there is a collision. This file contains the report objects (with X- and Y-coordinates) that were overwritten by other report objects. 132 Operating Manual, 09/2011, A5E

133 Values in XML 11 Administration Base data, properties of an attribute: Values in XML (restricted functionality) ("SpecInheritanceXML") Values in XML (restricted functionality) - High priority ("SpecInheritanceXMLHighPriority") The edit field is displayed in red and is a mandatory field. Values in XML (restricted functionality) - script can set value ("SpecInheritanceXMLPartialBlocked") The edit field is blocked. The following types are allowed for the three "Values in XML" editing modes: Number Text Alphanumeric Effect From a user point of view these three editing modes for XML values are the counterparts of the three editing modes "Editable", "Editable (high priority)", and "Editable (Script can set value"). From a technical point of view the changes to the attribute in the XML string are stored in the attribute of the y-owner, hence on the device, document or project. The following information is stored in the XML string of the owner: "NestedName" on an attribute "Value" "Unit" The name of the owner is accordingly saved in the working layers, not the attribute. The complete XML string is always saved. Operating Manual, 09/2011, A5E

134 Values in XML Advantages The attribute is not checked into the engineering project. This leads to a performance increase for large data imports or exports, if the data is mainly static. The performance for read access to large data amounts is also increased. Application example: In COMOS FEED, attributes with this editing mode are used on the simulation objects, thereby significantly accelerating the import. Restrictions Group work The complete XML string is always saved. If several users edit the same object (device, document or project object) in the same working layer with XML attributes, then the changes from one user can be overwritten by another user. Object-based access Since the XML attributes are no longer regular attribute objects, there are different restrictions when working with the objects. Everything seems to be the same on the interface, since temporary attribute objects are created during runtime. However, these temporary attribute objects are never saved (when explicitly working with values and units). The query whether the attribute object is checked in always returns "False". The attribute does not have a timestamp. No timestamp-based revisioning is possible. The status of the attribute is not changed. For example, there is no apparent difference in the way the working layer appears in the Navigator. Links are excluded This mode cannot be used for link attributes ("Display type": Link). 134 Operating Manual, 09/2011, A5E

135 NOXIE Plugin Aim Click on the "Native Object XML Import Export" button on the toolbar or "Plugins > Basic > Native Object XML Import Export" on the menu bar. The plugin writes specified branches of the structure tree to an XML file. The documents are taken along and their files are maintained. This is how base objects, engineering objects, and documents from a source database can be transferred to another database. Objects, tabs, attributes, and their standard tables are covered. This information is copied into the target database in its correct structure. If these structures do not exist in the target they are reproduced and only then the information is copied in. The interface also works between working layers and supports import and export operations Export Procedure To start the export, proceed as follows: 1. Select the "Export" option in the "Options" control group. 2. Click on the "..." button next to the "XML Import / Export file" field and select an XML file or generate a new XML file and give it a new file name. 3. To select a directory, click on the "..." button in the "Document directory" field and select the required directory. COMOS automatically creates a document folder called "documents" parallel to the XML file after the selection. The processed documents are saved or searched in this directory. 4. Drag one or a number of objects from the Navigator and drop them into the "Object(s) to export" field. During the export all start objects and all objects lying underneath are exported. To delete one or all objects from the "Object(s) to export" field, mark an object and click on "Remove" or "Remove all" in the context menu. 5. If you enable the "Own properties only" option, only the information about the engineering objects that has been checked in is exported. This has no effect for base objects. Please note that in COMOS, a great deal of information is only inherited. For example, you see a lot of default information in engineering objects that derives from base objects. If this option is enabled, the inherited values are no further processed. Operating Manual, 09/2011, A5E

136 NOXIE Plugin 12.3 Import 6. If you enable the "With owner info" option, the information about the owner structure is included. 7. You can only start the export with the "Start export" button once steps 1 through 4 have been completed. The XML file is created. The documents are collected in the "documents" folder. This also applies to external documents. When you send the XML file, please include the "documents" folder; if you do not, the documents will be empty Import Procedure To start the import, proceed as follows: 1. Select the "Import" option in the "Options" control group. 2. Click on the "..." button next to the "XML Import / Export file" field and select an XML file or generate a new XML file and give it a new file name. 3. To select a directory, click on the "..." button in the "Document directory" field and select the required directory. COMOS automatically creates a document folder called "documents" parallel to the XML file after the selection. The processed documents are saved or searched in this directory. 4. Drag&drop an object from the Navigator into the "Drag&drop a root object to import" field. During the import the to be created objects are created underneath this start object. To delete the start object from the "Drag&drop a root object to import" field, click on the "Remove pointer" button next to the field. 5. If you enable the "Update" option, only objects that have changed are processed. Not all information is replaced. The timestamp changes. Use the option only when reimporting identical data. All changed and, therefore, new data is taken over into the target directory without an evaluation. 6. If you enable the "With owner info" option, the information about the owner structure is included. 7. You can only start the import with the "Start import" button once steps 1 through 4 have been completed. All objects are created together below the selected node. The references are set subsequently. A prerequisite is that the referenced object was also exported. Since all data is initially imported underneath a shared node, copy and move the units and locations to the right positions. 136 Operating Manual, 09/2011, A5E

137 NOXIE Plugin 12.4 Structure of the generated XML file 12.4 Structure of the generated XML file Reference of the XML nodes COMOS collections XML nodes on a device: "Elements" "Connectors" "Specifications" "OwnDocuments" All connections that are not empty are written out. You find additional information on this topic in the "COMOS.dll" class documentation, keyword "OwnCollections". References XML node "References" Contains the references. You find additional information on this topic in the "COMOS.dll" class documentation, keyword "Reference". Translations XML node "InternationalDescriptions" Contains the object description in all languages. The "Index" is the index from COMOS language management. If German is selected as the primary language, it has the index "1". Owner information XML node "ObjectOwnerInfo" Contains the information about the owner structure. Operating Manual, 09/2011, A5E

138 NOXIE Plugin 12.4 Structure of the generated XML file 138 Operating Manual, 09/2011, A5E

139 Synchronizing COMOS databases Overview COMOS has an option for version management for distributed data storage. Thus there can be physically separated databases whose stocks of data can be synchronized semiautomatically. After the synchronization, the project data from two databases is combined in a common project. This method is not to be confused with the import or export of projects, where projects that are not synchronized are created in parallel. You have the option to combine the data in one of the synchronized databases or alternatively to match the databases. In the first case the source database remains unchanged, while in the second case the updating is done in both directions. For both options you use the "ImportDB.exe" program from the "\bin" directory. You find additional information on this topic in the "COMOS Administration" manual, keyword "Database" Data collisions Collisions occur during synchronization as a result of inconsistencies in the course of planning. The same objects were modified in both of the databases to be synchronized. Since COMOS cannot know which modification is correct, these objects are not synchronized. These collisions are documented in the test list of the Object Tester. It is not possible to save definitively as long as there are collisions. Please note that you should not simply cancel an action, since the entire work step will be undone and a lot of working time lost. Correct the objects that do not match and save the changes. Operating Manual, 09/2011, A5E

140 Synchronizing COMOS databases 13.2 Data collisions 140 Operating Manual, 09/2011, A5E

141 Engineering projects Import You can import engineering projects from another database. When you import projects, please note that inconsistencies can result if standard tables in different databases do not use structures with identical hierarchies. In the case of mismatches, the "Object test" tab opens automatically. You find additional information on this topic in the "Basic Operation" manual, keyword "Import project". Operating Manual, 09/2011, A5E

142 Engineering projects 14.1 Import 142 Operating Manual, 09/2011, A5E

143 Base projects Export You can export base projects to other databases. You find additional information on this topic in the "Basic Operation" manual, keyword "Export project". Operating Manual, 09/2011, A5E

144 Base projects 15.1 Export 144 Operating Manual, 09/2011, A5E

145 Templates Import You can import templates from another database. You find additional information on this topic in the "Basic Operation" manual, keyword "Import project", the "COMOS Administration" manual, keyword "Templates/Assemblies", and the "Quickstart Basic" manual, keyword "Project types". Operating Manual, 09/2011, A5E

146 Templates 16.1 Import 146 Operating Manual, 09/2011, A5E

147 System projects Import Important base objects are prepared in the system project. You find additional information on this topic in the "COMOS Administration" manual, keyword "Copy system project". Operating Manual, 09/2011, A5E

148 System projects 17.1 Import 148 Operating Manual, 09/2011, A5E

149 WMF data Import When you open an interactive report in the report designer, the "Place WMF picture" icon is available for selection: The import function for Windows metafiles is useful for importing AutoCAD files. You first need to export the AutoCAD file in AutoCAD as a WMF file. Select a mapping file on the "AutoCad" tab. Mapping files have the file extension "*.pcp". You find additional information on this topic in the "Reports - Basic Operation" manual, keyword "Place Windows metafile". Operating Manual, 09/2011, A5E

150 WMF data 18.1 Import 150 Operating Manual, 09/2011, A5E

151 COMOS interface with Teamcenter Basic principles Aim COMOS features an interface to link up with the Siemens PLM software Teamcenter 8.1. The interface supports data exchange in both directions. You can start the exchange from COMOS. The link with Teamcenter provides you with the following options: You can create units in Teamcenter and synchronize them with COMOS You can synchronize your existing COMOS unit with Teamcenter You can edit a synchronized unit either in COMOS or in Teamcenter and then resynchronize You can transfer COMOS documents to Teamcenter Requirements Most defaults have to be set by the administrator. See also chapter Administration (Page 169) Terms If you are working with Teamcenter, you should be familiar with the following terms: Mapping object In the following, the term "mapping object" describes an engineering object created based on a base object. A Teamcenter resource or a Teamcenter type must have been assigned to the base object (see Assignment). Mapping objects can be synchronized between Teamcenter and COMOS. PLM Product Lifecycle Management - uniform management of product data throughout the entire product lifecycle. Operating Manual, 09/2011, A5E

152 COMOS interface with Teamcenter 19.1 Basic principles Synchronization The equivalent of repeated importing or exporting of data. Also used to describe scenarios where only a subset of the existing data is to be updated due to an optional protection setting being applied. Tc The abbreviation for Teamcenter used in this document. Teamcenter Siemens PLM software Teamcenter. The COMOS interface has been designed to link up with Teamcenter Version 8.1. Assignment The resources and types declared in Teamcenter are originally independent of COMOS base objects or templates. To link the relevant objects, they must be assigned to one another. Resource assignment determines which base object or template is used to create an object from Teamcenter in COMOS. In the opposite direction, instance assignment defines the translation of COMOS engineering objects into resources or types which can be understood by Teamcenter. Attributes and units of measurement are translated in both directions using corresponding assignments. 152 Operating Manual, 09/2011, A5E

153 COMOS interface with Teamcenter 19.1 Basic principles Workflow overview Tc Configuration Transmission method Settings Legend: Teamcenter Admin Resources: - Create Collaboration Context - Create Structure Context - Create Application Interface Unit: - Create Collaboration Context - Create Application Interface Teamcenter User COMOS Admin COMOS User Teamcenter = Tc Synchronize resources Create corresponding base objects, e.g. CItem Assign resources Assign types Assign attributes Assign units Synchronize resource information if no change of the unit e.g. resources was added in Tc Latest version of the unit? if in Tc if in COMOS Yes No Synchronize unit from Tc to COMOS Synchronize unit from COMOS to Tc New resources? Synchronize unit from Tc to COMOS Make changes in Tc in Tc Changes planned? In COMOS Make changes in COMOS, e.g. creating a Tc object in COMOS Project completed Operating Manual, 09/2011, A5E

154 COMOS interface with Teamcenter 19.2 User interface reference 19.2 User interface reference "Teamcenter login" window To establish a connection to Teamcenter, log in. If a connection to Teamcenter has to be established in order to perform steps, the "Teamcenter login" window will open automatically. Alternatively, you can call the "Teamcenter login" window on the "Units" tab in the Navigator. To do this, right-click on the image of the unit in COMOS and select the "Teamcenter > Login..." command from the context menu. As the administrator, you can also call the context menu on the "Base objects" tab in the Navigator from the "@02 > 230 > CTI > M > RL Teamcenter resources" node. "Login" control group Field "Server" "User ID" "Password" "Group" "Role" Description Mandatory field. Expected format: " Mandatory field. The user name agreed with the administrator. Mandatory field. For authentication. Optional. Group membership in the Teamcenter organization structure. As stored in Teamcenter. Optional. Role in the selected group, if not the default role. As stored in Teamcenter. "Status" control group See also section Status area (Page 155). "OK" button Click on this button to start the login process. "Cancel" button Use this button to cancel the login process. 154 Operating Manual, 09/2011, A5E

155 COMOS interface with Teamcenter 19.2 User interface reference Status area To keep track of time-consuming processes, the corresponding windows have a status area. "Status" control group The element at the top is a progress bar which displays the current status of the process. These windows have a status area for displaying system messages. If you started the corresponding process by clicking "OK", the following types of system message are output: Category "Errors" "Warnings" "Messages" Description The process has not been executed successfully. Further processing is not possible. Check the content of the error message and repeat the process with the correct settings. This message shows information about problems that do not actually prevent further processing but may lead to an unwanted result. When a warning is displayed, use the description to check the result of the process. If you wish to continue despite the warnings, click "Cancel". The window closes. To restart the process, click "OK". This message shows information that has no impact on further processing. It might contain additional information about the progress of the process, for example. To close the window, click "Cancel". To hide certain types of system message, click on the appropriate buttons ("Errors", "Warnings", or "Messages"). The entries in the status window are context-sensitive. To navigate to the cause of the system message, double-click on the entry in the status window. If the message is uniquely assigned to a specific COMOS object, the object is selected in the Navigator "Synchronize plant from Tc" window To synchronize a unit from Teamcenter, make your settings in the "Synchronize plant from Tc" window. See also section Synchronizing a unit from Teamcenter (Page 160). Operating Manual, 09/2011, A5E

156 COMOS interface with Teamcenter 19.2 User interface reference "Project" control group Field "Server URI" "Project selection" "Current project" Description Displays the connection to the current Teamcenter server. Selects the required project from the list. If called again, the previously selected project is set by default. To select a different project, show the list by clicking the button. Displays the current project. "Project selection" "Incremental update" To retain existing data, enable this option. This option is only available for the first execution. "Create working layer" To create transferred data on a separate working layer, enable this option. "Status" control group See also section Status area (Page 155). "OK" button Starts the synchronization process from Teamcenter. "Cancel" button Cancels synchronization "Synchronize plant to Tc" window To synchronize a unit to Teamcenter, make your settings in the "Synchronize plant to Tc" window. See also section Synchronizing a unit to Teamcenter (Page 163). "Project" control group Field "Server URI" "Project selection" "Current project" Description Displays the connection to the current Teamcenter server. Selects the required project from the list. If called again, the previously selected project is set by default. To select a different project, show the standard table by clicking the "Project selection" button. Displays the current project. "Status" control group See also section Status area (Page 155). 156 Operating Manual, 09/2011, A5E

157 COMOS interface with Teamcenter 19.2 User interface reference "OK" button Starts the synchronization process to Teamcenter. "Cancel" button Cancels synchronization "Element properties" window To create a new representation of an object in COMOS, you must specify certain properties of the object. The entry is made via the "Element properties" window, which you open by clicking the "Instance properties..." button. See also section Creating a mapping object (Page 166). Only after this can you synchronize the representation to Teamcenter. "COMOS instance" control group Field "Name" Description Shows the name assigned in COMOS. "Teamcenter instance" control group Field "Item ID" "Revision ID" "Assign" "Name" "Type" "Description" Description Mandatory field. A valid value can be written to this field automatically by clicking the "Assign" button. A 6-digit consecutive number is assigned by default. Alternatively, free text can be entered to identify the object in Teamcenter. Mandatory field. A valid value can be written to this field automatically by clicking the "Assign" button. By default, the letter "A" is assigned for the first revision. Alternatively, free text can be entered to identify the first revision in Teamcenter. Automatically writes valid values assigned by the Teamcenter server to the "Item ID" and "Revision ID" fields. Mandatory field. Free text can be entered to designate the object in Teamcenter. Shows the resource or type to which the base object is assigned. Optional. Free text. "Teamcenter position" control group Field "Name" "Quantity" Description Optional. Designates the position of the object in the Teamcenter unit. Optional. Frequency of the object at the position in the Teamcenter unit. Operating Manual, 09/2011, A5E

158 COMOS interface with Teamcenter 19.3 Data transfer from Teamcenter to COMOS "Status" control group See also section Status area (Page 155) "Select Tc resource" window When you create a representation in COMOS, you might have to specify an actual Teamcenter resource. The entry is made via the "Select Tc resource" window. The new representation corresponds to the reference object used. See also section Specifying an instance assignment (Page 168). Working area Select a resource to be the instance assignment for the reference object via the working area. Only resources whose resource assignment points to the reference object are displayed. "Remove pointer" button To remove the existing instance assignment, click on the "Remove pointer" button and then click "OK" Data transfer from Teamcenter to COMOS Basic principles This section describes how to transfer data from Teamcenter to your project in COMOS. Preparation for data exchange by the user In order to be able to start transfer for the first time, you have to make preparations for data exchange in COMOS. See also section Mapping a unit from Teamcenter (Page 159) and section Checking and making settings (Page 159). If you have already performed synchronization from Teamcenter or to Teamcenter, use the existing settings. In the event of problems during data exchange, check that the defaults have been met and contact your administrator if necessary. Starting data transfer See also section Synchronizing a unit from Teamcenter (Page 160). 158 Operating Manual, 09/2011, A5E

159 COMOS interface with Teamcenter 19.3 Data transfer from Teamcenter to COMOS Mapping a unit from Teamcenter Aim To transfer unit data from the Siemens PLM solution Teamcenter to COMOS for the first time. Procedure 1. Create a new unit underneath the project node on the "Units" tab in the Navigator. 2. To define the type of unit used in Teamcenter, open the "@02 > 230 > CTI > M > TL Teamcenter types" node on the "Base objects" tab in the Navigator. The types used in Teamcenter are listed. 3. Open the properties of the object matching the type of your unit in Teamcenter, e.g. "MEPlant". 4. To navigate to the corresponding base object, click on the "Navigate, properties" button on the "Attributes > CTI resource mapping" tab and select "Navigate > Object". This object is to be created in the engineering view. Example: The base object "CMEPlant" has been selected and marked. 5. Drag&drop this object onto the empty bar underneath the Navigator tree. A new tab named after the object is displayed towards the bottom of the Navigator. 6. Open the "Units" tab at the top of the Navigator. 7. Drag&drop the selected object from the bottom of the Navigator onto the unit. Result The representation of the unit from Teamcenter is created underneath the unit node in COMOS Checking and making settings Introduction To prepare the interface for a connection with Teamcenter, the unit created must be classified and a Teamcenter integrator object added to it. Operating Manual, 09/2011, A5E

160 COMOS interface with Teamcenter 19.3 Data transfer from Teamcenter to COMOS Procedure 1. To check the classification, select the unit created, e.g. ""CMEPlant1", on the "Units" tab in the Navigator and navigate to the base object. 2. Open the base object properties. 3. Open the "System settings" tab. 4. Check whether the "CT" entry has been set in the "Functional classification" list. If it has not, inform your administrator. 5. Check whether the "TCI Teamcenter integrator" object is listed on the "Units" tab of the Navigator in the representation of the unit: If this object is listed, the interface is ready for connection to Teamcenter. If it is not listed, add a Teamcenter integrator object: On the "Base objects" tab in the Navigator, open the "@02 > 230 > CTI > C > TCI Teamcenter integrator" node. Drag&drop the Teamcenter integrator object onto the empty bar underneath the Navigator tree. A new tab named after the object is displayed towards the bottom of the Navigator. Open the "Units" tab in the Navigator. Drag&drop the Teamcenter integrator object from the detail window at the bottom of the Navigator onto the unit. The interface is now ready for connection to Teamcenter Synchronizing a unit from Teamcenter Requirements Your administrator has set the necessary defaults. See also section Administration (Page 169). The unit from Teamcenter has been mapped in COMOS. See also section Mapping a unit from Teamcenter (Page 159). The settings have been checked or made as appropriate. See also section Checking and making settings (Page 159). 160 Operating Manual, 09/2011, A5E

161 COMOS interface with Teamcenter 19.3 Data transfer from Teamcenter to COMOS Procedure To synchronize the unit from Teamcenter, proceed as follows: 1. On the "Units" tab in the Navigator, right-click to select the representation of the unit from Teamcenter, e.g. "CMEPlant1". 2. Select the "Teamcenter > Synchronize plant from Tc..." command from the context menu. If there is not an existing connection to Teamcenter, the "Teamcenter login" window opens. Enter your access details and click "OK" to confirm. As soon as the connection to Teamcenter is established, the "Synchronize plant from Tc" window opens. 3. You can make the following settings in the "Synchronize plant from Tc" window: The first time the window opens, select the project corresponding to your unit in Teamcenter from the "Project selection" standard table. If called again, the previously selected project is set by default. To select a new project, show the standard table by clicking the "Project selection" button. To retain existing data, enable the "Incremental update" option. This option is only available the first time a unit is synchronized. To create transferred data on a separate working layer, enable the "Create working layer" option. 4. To perform synchronization, click "OK". Result The unit in COMOS is updated with the data from Teamcenter. See also "Synchronize plant from Tc" window (Page 155) Operating Manual, 09/2011, A5E

162 COMOS interface with Teamcenter 19.4 Data transfer from COMOS to Teamcenter 19.4 Data transfer from COMOS to Teamcenter Basic principles This section describes how to transfer data from COMOS to your unit in Teamcenter. Preparation for data transfer by the user In order to be able to start transfer for the first time, make preparations for data exchange in COMOS. See also section Checking and making settings (Page 162). If you have already performed synchronization from Teamcenter or to Teamcenter, use the settings which have been performed. Starting data transfer See also section Synchronizing a unit to Teamcenter (Page 163) Checking and making settings Aim Data for a unit in COMOS is to be synchronized to Teamcenter. Synchronization to Teamcenter requires certain settings. These settings have to be checked or made as appropriate. Procedure 1. In the Navigator, select the unit node you wish to synchronize to Teamcenter (along with its content) on the "Units" tab. 2. Check for the "CTI030 instance mapping" tab underneath the selected unit. If the tab is not there, contact your administrator. 3. Navigate to the base object via the context menu of the unit. 4. Open the base object properties. 5. To check the classification, open the "System settings" tab. Check that the "CT" entry has been set in the "Functional classification" standard table. If it has not, inform your administrator. 6. To add the Teamcenter integrator object, open the "@02 > 230 > CTI > C > TCI Teamcenter integrator" node on the "Base objects" tab in the Navigator. 7. Drag&drop the Teamcenter integrator object onto the empty bar underneath the Navigator tree. A new tab named after the object is displayed towards the bottom of the Navigator. 162 Operating Manual, 09/2011, A5E

163 COMOS interface with Teamcenter 19.4 Data transfer from COMOS to Teamcenter 8. Open the "Units" tab in the Navigator. 9. Drag&drop the Teamcenter integrator object from the detail window at the bottom of the Navigator onto the unit. Result The unit in COMOS is ready for synchronization to Teamcenter Synchronizing a unit to Teamcenter If the requirements are met, you can synchronize the unit from COMOS to Teamcenter. See also section Checking and making settings (Page 162). Procedure To synchronize the unit to Teamcenter, proceed as follows: 1. On the "Units" tab in the Navigator, right-click to select the required unit. 2. Select the "Teamcenter > Synchronize plant to Tc" command from the context menu. If there is not an existing connection to Teamcenter, the "Teamcenter login" window opens. Enter your access details and click "OK" to confirm. As soon as the connection to Teamcenter is established, the "Synchronize plant to Tc" window opens. 3. You can make the following settings in the "Synchronize plant to Tc" window: The first time the window opens, select the project corresponding to your unit in Teamcenter from the "Project selection" standard table. If called again, the previously selected project is set by default. To select a new project, show the standard table by clicking the "Project selection" button. 4. To perform synchronization, click "OK". Result The unit in Teamcenter is updated with the data from COMOS. See also "Teamcenter login" window (Page 154) Operating Manual, 09/2011, A5E

164 COMOS interface with Teamcenter 19.5 Documents for Teamcenter 19.5 Documents for Teamcenter Checking settings Basic principles The corresponding settings must have been made if you wish to publish documents. Check the relevant settings before publishing a document for the first time or if errors occur. Procedure 1. To check the settings, right-click to select the required document in the Navigator on the "Units" tab or on the "Documents" tab. 2. Navigate to the base object. 3. Open the base object properties. 4. To check the settings, open the "System" tab. 5. Check whether the "TCR" entry has been set in the "Revision type" list. If it has not, inform your administrator. 3 Step 3 4 Step 4 5 Step Operating Manual, 09/2011, A5E

165 COMOS interface with Teamcenter 19.5 Documents for Teamcenter Publishing documents Requirements Your administrator has made the necessary settings for your documents at the base object. See also section Preparations for publishing documents (Page 188). The PDF file generated is automatically published to Teamcenter when you revision and release a document of this type. Procedure To publish a document to Teamcenter, proceed as follows: 1. Seek the approval of your administrator, then select the required document in the Navigator. 2. Open the properties of the document and select the "Revisions" tab. 3. Click on the "Creates a new revision" button and confirm the "Create new revision?" prompt with "Yes". 4. Click on the arrow symbol in the "Set the next or selected revision level" button and select the "Released by" entry from the list displayed. If there is not an existing connection to Teamcenter, the "Teamcenter login" window opens. Enter your access details and click "OK" to confirm. As soon as the connection to Teamcenter is established, the document is sent to Teamcenter. Result Following publication, the document is created in Teamcenter. If there is a match in Teamcenter for the immediate primary object in COMOS (tree structure), the document is saved in the corresponding place. If the document cannot be saved in a location corresponding to the unit structure in COMOS, it is saved in the "Newstuff" folder belonging to the user whose login details were used to log in on Teamcenter. Operating Manual, 09/2011, A5E

166 COMOS interface with Teamcenter 19.6 Changes in COMOS 19.6 Changes in COMOS Creating a mapping object Aim A new mapping object is to be created in COMOS and sent to Teamcenter. A resource mapped in COMOS or a type that has been synchronized and assigned from Teamcenter must be used as the source. Procedure To take the first step and select a Teamcenter resource or a Teamcenter type for a mapping object, proceed as follows: Selecting the Teamcenter resource in COMOS and creating a representation 1. To select a resource, open one of the following nodes on the "Base objects" tab in the Navigator: "@02 > 230 > CTI > M > RL > CLR Teamcenter classified resources" "@02 > 230 > CTI > M > RL > UCL Teamcenter unclassified resources" "@02 > 230 > CTI > M > TL Teamcenter types" 2. Select a resource saved underneath this node from Teamcenter. Example: "@02 > 230 > CTI > M > TL Teamcenter types" node, underneath this the "MEStation" object. 3. Open the properties of this object. Example: "MEStation". 4. To navigate to the assigned base object, click on the "Navigate, properties" button on the "Attributes > CTI resource mapping" tab and select "Navigate > Object" from the menu. This object is to be created in the engineering view. Example: The base object "CMEStation" has been selected and marked. 5. Drag&drop this object onto the empty bar underneath the Navigator tree structure. A new tab named after the object is displayed towards the bottom of the Navigator. 6. Open the "Units" tab at the top of the Navigator. 7. Drag&drop the selected object from the bottom of the Navigator onto an existing mapping object. Example: Your unit synchronized from Teamcenter 166 Operating Manual, 09/2011, A5E

167 COMOS interface with Teamcenter 19.6 Changes in COMOS Intermediate result The new mapping object is displayed underneath the existing mapping object. Specifying the Teamcenter "Item ID", "Revision ID", and "Name" So that you can transfer the necessary attributes of the new representation during a subsequent synchronization to Teamcenter, specify the Teamcenter "Item ID", "Revision ID", and "Name". Proceed as follows: 1. Open the properties of the newly created mapping object. 2. Select the "Attributes > CTI instance mapping" tab. 3. Click on the "Instance properties..." button. The "Element properties" window opens. 4. To complete the mandatory fields "Item ID", "Revision ID", and "Name" in the "Element properties" window, click on the "Assign" button. A unique "Item ID" is requested from the Teamcenter server for this purpose. Alternatively, you can also edit these fields. See also section "Element properties" window (Page 157). 5. Click "OK". Result A Teamcenter item ID and a revision ID have been assigned to the mapped object. NOTICE Synchronization of the created objects There is a risk of data loss if you synchronize a unit from Teamcenter (note the direction) without transferring your changes to the Teamcenter server first. The objects you have created are not transferred to the Teamcenter server until the moment you synchronize the unit to Teamcenter (note the direction). To link the created objects to their matches in Teamcenter, synchronize the unit from Teamcenter afterwards. Note Objects of the "Item" type Do not create any "Item" type objects in COMOS. This type is used as the basis for creating unclassified resources in Teamcenter. If you wish to add new resources, do this in Teamcenter. Operating Manual, 09/2011, A5E

168 COMOS interface with Teamcenter 19.6 Changes in COMOS Specifying an instance assignment Aim The instance assignment for a newly created mapping object is to be modified. If you used the COMOS-internal inheritance mechanism during resource assignment, you have a means of concretizing the instance assignment. For example, you can assign multiple robots from Teamcenter to a single base object in COMOS. The first resource assigned is specified as the default value for the instance assignment. If the resource is a classification (a robot, for example), once you have created a mapping object, select a concrete classified resource (a Cartesian robot, for example). Then synchronize the superior unit to Teamcenter. Procedure To change the instance assignment for the mapping object, proceed as follows: 1. Open the properties of the mapping object on the "Units" tab. 2. Select the "Attributes > CTI instance mapping" tab. 3. To call the "Select Tc resource" window, click on the "Select Tc resource..." button. All resources assigned to the base object of the mapping object are listed in the "Select Tc resource" window. The COMOS-internal inheritance hierarchy is displayed as the tree structure. 4. You have the following options: To specify the assignment for a resource, select the required resource in the "Select Tc resource" window. To cancel the assignment for a resource, click on the "Remove pointer" button. 5. Click "OK" to confirm your selection. Result During the next synchronization to Teamcenter, the newly created mapping object is transferred in accordance with the modified instance assignment. See also Creating a mapping object (Page 166) 168 Operating Manual, 09/2011, A5E

169 COMOS interface with Teamcenter 19.7 Administration 19.7 Administration Basic principles Aim To make the link to Teamcenter 8.1 available to the user, proceed as follows: Settings for Teamcenter Make the basic settings for data exchange with COMOS once for multiple projects. See also section Teamcenter configuration (Page 174). Individual project in Teamcenter Make the settings for each project. See also section Project in Teamcenter (Page 176). Installing the buffer component for the COMOS client Installing an additional component for the COMOS client for multiple projects See also section Installing the buffer component for the COMOS client (Page 181). Settings in COMOS Make both settings for multiple projects and settings for individual projects. When settings are added to a unit in Teamcenter, they may also be applicable more than once in the context of a single project. See also section Settings in COMOS (Page 182). Note Need for reconciliation in a project The tasks assigned to a user include synchronizing units to Teamcenter or to COMOS. If resources, units of measurement, or attributes have been added to the current project in Teamcenter, you should be informed as the administrator. You make the necessary assignments in COMOS. In the absence of a matching assignment, recourse is made to the "Item" type or the "@02 > 230 > CTI > C > TCP Teamcenter Proxy" object during unit synchronization. See also Workflow overview (Page 153) Operating Manual, 09/2011, A5E

170 COMOS interface with Teamcenter 19.7 Administration Naming conventions Naming conventions in COMOS Teamcenter resources and types are mapped underneath defined nodes in COMOS using the original names from Teamcenter. The corresponding base objects must be assigned to the Teamcenter types in COMOS. See also section Assigning resources and types (Page 185). If there are no matching base objects in COMOS, create them. You find additional information in the "Basic Operation" manual, keyword "Creating objects using the static New menu". Recommendation Prefix the original name with "C" when assigning new base objects to Teamcenter types. This denotes the origin of the Teamcenter types. Example: COMOS node for assigning the Teamcenter type > 230 > CTI > M > TL > Item" New COMOS base object based on the Teamcenter type "CItem" Naming conventions in Teamcenter In Teamcenter, you create objects defining the configuration of data exchange. Recommendation When you assign names, select names that indicate the following characteristics: Project name Resources or units "Collaboration Context", "Structure Context" or "Application Interface" Consecutive numbering if necessary Examples: "AnywhereResourcesAI01" or "Anywhere_Unit_03_CC" 170 Operating Manual, 09/2011, A5E

171 COMOS interface with Teamcenter 19.7 Administration User interface reference "Teamcenter units of measurement" tab To assign units of measurement, make the necessary settings on the "Teamcenter units of measurement" tab. See also section Assigning units of measurement (Page 183). Table Column "Name" "Description" "COMOS unit" Description Field that cannot be edited. The text in this field indicates the unit of measurement used in Teamcenter. To clarify the origin, the unit of measurement from Teamcenter is prefixed with the name affix "CTI_". Field that cannot be edited. This field contains the description text saved in COMOS. Editable field designated for the unit of measurement used in COMOS. If there is an entry in this field, you have already assigned a COMOS unit of measurement to the text used in Teamcenter. If this field is empty, assign a COMOS unit of measurement to the text used in Teamcenter "CTI attribute mapping" tab To assign attributes, make your settings on the "CTI attribute mapping" tab. See also section Assigning attributes (Page 186). Button Name "Refresh values" Description When you click this button, the "Refresh values" window opens. Click "OK" to start the transfer of the values synchronized based on the attribute assignment from Teamcenter to the corresponding COMOS attributes. Operating Manual, 09/2011, A5E

172 COMOS interface with Teamcenter 19.7 Administration Table Column "Tc description" "Tc value" "Tc unit" "Attribute assignment" "Attribute unit" Description Field that cannot be edited. This field contains a short descriptive text synchronized by Teamcenter with the attribute to COMOS. Field that cannot be edited. The "Tc value" column displays the value of the attribute as it was synchronized from Teamcenter. Field that cannot be edited. The "Tc unit" column displays information about the unit of measurement as stored in Teamcenter. Optional field which can be completed to enter an attribute assignment. To assign an attribute, drag&drop it from the assigned resource or its inheritance source into the "Attribute assignment" field. Field that cannot be edited. This field displays the unit of measurement in COMOS "CTI resource mapping" tab To assign resources, make your settings on the "CTI resource mapping" tab. See also section Assigning resources and types (Page 185). Tab Control element "Assigned base object" field "Resource properties" button Description Drag&drop the required object into this field to make the assignment. The source is provided either by a suitable template from the "Units" tab in the Navigator or a base object from the "Base objects" tab. A suitable source object must contain the "CTI030 CTI instance mapping" tab. Click this button to view entries for the resource from Teamcenter. The "Element properties" window opens. See also section "Element properties" window in the base objects view (Page 172) "Element properties" window in the base objects view To view the properties of a resource, click on the "Resource properties..." button on the "CTI resource mapping" tab. See also section "CTI resource mapping" tab (Page 172). "COMOS instance" control group Field "Name" Description The name of the element is displayed in this field. 172 Operating Manual, 09/2011, A5E

173 COMOS interface with Teamcenter 19.7 Administration "Teamcenter instance" control group Name "Item ID" "Revision-ID" "Name" "Type" "Description" Description If the resource information has been synchronized, the data from Teamcenter is entered automatically in these fields "Synchronize resource info" window You start the synchronization of resource information in the "Synchronize resource info" window. See also section Synchronizing resource information (Page 187). "Project" control group Field "Server URI" "Project name" "Create working layer" Description Displays the connection to the current Teamcenter server. Displays the current project name. To create transferred data on a separate working layer, enable this option. "Status" control group See also section Status area (Page 155). "OK" button Starts synchronization "CTI instance mapping" tab To change an instance assignment, assign a different resource on the "CTI instance mapping" tab. See also section Assigning resources and types (Page 185). Operating Manual, 09/2011, A5E

174 COMOS interface with Teamcenter 19.7 Administration Tab Control element "Assigned Tc resource" field "Instance properties" button "Select Tc resource" button Description Field for displaying the assigned Tc resource. This field can be completed by clicking the "Select Tc resource" button. The user needs this button when creating an engineering object based on the reference object. See also section Creating a mapping object (Page 166). To assign a Teamcenter resource, click on the "Select Tc resource" button. Only those resources to which the reference object is assigned are listed for selection. The reference object is the object whose properties were opened previously. The default value is the first resource to which the reference object was assigned Teamcenter configuration Defining the "Application Interface" with transfer types Aim To define the type of data transfer between Teamcenter and COMOS, use the Teamcenter Environment Manager program to install the template supplied with the product. Procedure 1. Start Teamcenter Environment Manager in the Teamcenter installation directory. Relative path: ".\install\tem.bat". 2. Enable the "Configuration Manager" option under ""Maintenance"" and click "Next". 3. Enable the "Perform maintenance on an existing configuration" option under ""Configuration Maintenance"" and click "Next". 4. Click "Next" under "Configuration Selection". 5. Enable the "Add/Remove Features" option under ""Feature Maintenance"" and click "Next". 6. To read in the template with the saved settings, click "Browse" under "Select Features" and load the file supplied. Relative path on the CD: ".\Software\AddOns\Teamcenter\TeamcenterServerConfiguration\feature_comos.xml". 7. Enable the "Extensions > COMOS Interface" option in the tree structure displayed under "Select Features". 174 Operating Manual, 09/2011, A5E

175 COMOS interface with Teamcenter 19.7 Administration 8. Enable the ""Extensions > Manufacturing Process Management > Customization for em- Server Integration"" option and click "Next". This procedure installs additional components which are required to synchronize certain types from the COMOS database to Teamcenter. See also section Specifying resources and types for the assignment (Page 177). 9. Under "Teamcenter Administrative User", enter your administrator password in the "Password" field and click "Next". 10. Click "Next" under "Database Template Summary". 11. To confirm your settings and install the required components, click "Next" under "Confirm Selections". This starts a copy operation, at the end of which the definition of the "Application Interface" with the transfer types is complete Setting Teamcenter options Aim Change the "Al_request_no_dependancy" setting in the options menu of Teamcenter. Procedure 1. Call the "Edit > Options" menu command in Teamcenter. 2. Click on the "Search" button at the bottom of the window. 3. Make the following entries in the "Search On Keywords" field in the "Search Options" window: "*request*". 4. To run the search, click on the button with the magnifying glass symbol. The search results are displayed in the "Preference List" list. 5. Mark the "Al_request_no_dependancy" entry in this list. 6. Make the following entries in the "Current Values" field: "true". 7. To save your changes, click on the "Modify" button Making changes in the "Default.xml" file Edit the "Default.xml" file in the ".\soa\policies" subdirectory of the installation directory in Teamcenter and make the following addition: <ObjectType name="meplantcontext"> <Property name="configuration_context"/> <Property name="revision_rule"/> </ObjectType> Operating Manual, 09/2011, A5E

176 COMOS interface with Teamcenter 19.7 Administration Project in Teamcenter Creating the "Collaboration Context" and "Structure Context" for resources Aim To prepare Teamcenter for interaction with COMOS, start by creating "Collaboration Context" and "Structure Context" type objects. A "Collaboration Context" type object is used, from which an "Application Interface" type object is derived. Object of the "Structure Context" type: Used to reference resources and types to be synchronized to COMOS. Procedure 1. Open the "My Teamcenter" application in Teamcenter. 2. To create a new folder to save the "Collaboration Context", select the "Home" folder and click on the "File > New > Folder..." command in the menu. The "New Folder" window opens. 3. In the "New Folder" window, enter a name for the new folder in the "Name" field and an an optional description in the "Description" field. 4. Click "OK" to confirm your entries. 5. Then select the folder you have just created and click on the "File > New > Collaboration Context" command in the menu. 6. Make sure that the "CCObject" type is selected on the left-hand side of the window. 7. Choose a name with the following characteristics: Multiple projects Either resources/types or units "Collaboration Context", "Structure Context" or "Application Interface" See also section Naming conventions (Page 170). 8. Click "OK" to save your entries and close the window. 9. To create a "Structure Context" type object, select the "Collaboration Context" type object and click on the "File > New > Structure Context" command. 10. Make sure that the "MEResourceContext" type is selected on the left-hand side of the window. 11. Give the "Structure Context" type object a name and close the window by clicking "OK". 176 Operating Manual, 09/2011, A5E

177 COMOS interface with Teamcenter 19.7 Administration Specifying resources and types for the assignment Aim Resources and types used in the unit and to be synchronized to COMOS are specified here. The specified resources and types are referenced in a "Structure Context" type object for synchronization to COMOS. Requirements A "Structure Context" type object must already have been created. See also chapter Creating the "Collaboration Context" and "Structure Context" for resources (Page 176). Procedure 1. To specify the resources and types required for synchronization to COMOS, select your unit and click on the "Send to > Manufacturing Process Planner" command in the context menu. The "Manufacturing Process Planner" application opens. 2. Copy all "ItemRevision" type objects to the "Structure Context" type object in the "My Teamcenter" application. 3. To empty the "Manufacturing Process Planner" application, close and reopen this window. 4. To create a new working area, click on the "File > New > New Workarea" command in the "Manufacturing Process Planner" application. 5. If types not contained in the database supplied with the product are listed in the "New Workarea" window, create the missing types. The database supplied with the product includes the following types: "MECell" "MECompResource" "MEDepartment" "MELine" "MEPlant" "MEPrLine" "MEProcResource" Operating Manual, 09/2011, A5E

178 COMOS interface with Teamcenter 19.7 Administration "MEProductLocation" "MEPrPlant" "MEPrStation" "MEPrZone" "MESite" "MEStation" "MEWorkarea" "MEZone" 6. Copy all types to the same "Structure Context" type object as described in Step 2 of these instructions. Result All resources and types for synchronization have been selected. This must be done in order to synchronize resources. See also chapter Synchronizing resources (Page 182). Once the resources have been synchronized, the user can synchronize a unit from Teamcenter to COMOS. See also chapter Synchronizing a unit from Teamcenter (Page 160) Creating an "Application Interface" Aim An "Application Interface" type object is required for data exchange. This object is used to make the following definitions: Definition of a transfer format for the import Definition of a transfer format for the export Definition of the content of data transfer by connecting the "Application Interface" type object with a "CollaborationContext" type object History of previous data transfers 178 Operating Manual, 09/2011, A5E

179 COMOS interface with Teamcenter 19.7 Administration Requirements A "Collaboration Context" type object for resources must already have been created. See also section Creating the "Collaboration Context" and "Structure Context" for resources (Page 176). Alternatively, a "Collaboration Context" type object must have been created for a unit. This unit already exists in Teamcenter or an empty unit is created in Teamcenter for synchronization from COMOS. See also section Creating a "Collaboration Context" for an existing unit (Page 179) or section Creating a "Collaboration Context" to synchronize a unit from COMOS (Page 180). The "Application Interface" type object and transfer types must be defined. See also section Defining the "Application Interface" with transfer types (Page 174). Procedure 1. To create a new "Application Interface" type object, select the "Collaboration Context" type object and click on the Tools > Export > Objects..." command. 2. Select "AppInterface" on the left-hand side. Click the button at the top right. 3. Select "COMOS_Al" on the left-hand side and enter a name. Make sure that the following settings are used: "Import Transfer Mode Name:" "COMOS_Import" "Export Transfer Mode Name:" "COMOS_Export" 4. To make the display transparent, move the new "Application Interface" type object from the "Newstuff" folder to the same folder containing the "Collaboration Context" type object Creating a "Collaboration Context" for an existing unit Requirement A unit exists in Teamcenter. Procedure 1. Select the unit, transfer it to the "Manufacturing Process Planer", and click on "File > Save as new Collaboration Context". 2. Select the "MECollaborationContext" type. 3. Enter the name of the new "CollaborationContext". 4. Check that the entry "MEPlantContext" is selected as "Structure Context Type". 5. Click "Save" to save your entries. Operating Manual, 09/2011, A5E

180 COMOS interface with Teamcenter 19.7 Administration 6. To make the display transparent, move the "Collaboration Context" type object created from the "Newstuff" folder in "My Teamcenter" to the same folder in which the "Collaboration Context" type object is usually saved. 7. Select the "Collaboration Context" type object you just created and create an "Application Interface" type object with the "COMOS_Al" subtype. See also chapter Creating an "Application Interface" (Page 178) Creating a "Collaboration Context" to synchronize a unit from COMOS A unit has already been created in COMOS and there is no match for it in Teamcenter. To synchronize an existing unit from COMOS to Teamcenter, create a "Collaboration Context" type object in Teamcenter. Requirements You have already performed the following steps: You have created a "Collaboration Context" object for resources in Teamcenter. See also section Creating the "Collaboration Context" and "Structure Context" for resources (Page 176). You have specified resources and types for the assignment in Teamcenter. See also section Specifying resources and types for the assignment (Page 177). You have added an "Application Interface" in Teamcenter. See also section Creating an "Application Interface" (Page 178). You have synchronized resources in COMOS. See also section Synchronizing resources (Page 182). You have assigned resources and types in COMOS. See also section Assigning resources and types (Page 185). Procedure 1. Create an empty unit in Teamcenter of the type assigned to the base object in COMOS. 2. Transfer the unit to the "Manufacturing Process Planer". Select the unit and click on the "File > Save as new Collaboration Context" command. 3. To make the display transparent, move the new "Collaboration Context" type object from the "Newstuff" folder to a suitable location. 4. Create an "Application Interface" for the "Collaboration Context". 5. Switch to COMOS. 6. Start the synchronization of the unit from COMOS to Teamcenter. See also section Synchronizing a unit to Teamcenter (Page 163). 180 Operating Manual, 09/2011, A5E

181 COMOS interface with Teamcenter 19.7 Administration Installing the buffer component for the COMOS client Requirement The COMOS client and the Teamcenter installation are in use on different computers. In this case, install a Teamcenter component on the computer running the COMOS client. The Teamcenter FCC is part of the Teamcenter data storage concept. It buffers changes locally on the client before they are transferred to the server. All access to the Teamcenter server goes via this buffer. The installation file is located on the data carrier supplied with the product. Note Installing the buffer component If you are using the COMOS client and the Teamcenter installation on the same computer, you do not need the buffer component. In this context, it does not matter whether you are using the Teamcenter server or the Teamcenter client. Procedure 1. Start the COMOS CD browser on the data carrier supplied with the product. 2. Click on the "Additional Software" button. 3. Click on the "Teamcenter FCC" button. Confirm the prompt to run the file (if there is one) and follow the installation instructions. 4. Confirm the default settings. You only need to make the following settings in the "FMS Settings, Please enter Parent and Proxy settings" window. 5. To enter a link to the Teamcenter server, enter either the computer name or the IP address in the "FSC Parent Host" field of the "FMS Settings, Please enter Parent and Proxy settings" window. 6. Check whether the entry in the "FSC Parent Port" field of the "FSC Parent Settings" control group matches the Teamcenter server setting. Change the setting if necessary. The "Connect to FSC Parent Via" and "FSC Parent Port" fields are completed automatically. 7. Click "Next".. 8. Complete the installation. 9. Set the "FMS_HOME" environment variable to the directory in which you installed the buffer component. Please note that the environment variable must be set for the relevant Windows user account. 10. Enter a link to the "startfcc.bat" file in the Windows start menu under "Start > Programs > Startup". You find the file in the same directory as the one used in Step 9. Operating Manual, 09/2011, A5E

182 COMOS interface with Teamcenter 19.7 Administration Settings in COMOS Synchronizing resources The unit in Teamcenter comprises various types of object called resources and types. To synchronize the unit to COMOS, the resources and types used must be declared in COMOS. When resources are synchronized, representations of the resources and types from Teamcenter are created in COMOS. This is achieved by means of data transfer using a transfer file. This file is also used to transfer resource information. See also section Synchronizing resource information (Page 187). Following synchronization, you assign objects to the resources and types in COMOS. If you synchronize the resource information subsequently, the resource information from the transfer file is sent to all assigned COMOS objects. Procedure 1. Right-click to select the "@02 > 230 > CTI > M > RL Teamcenter resources" node on the "Base objects" tab in the Navigator. 2. Select the "Synchronize Tc resource..." command from the context menu. If there is not an existing connection to Teamcenter, the "Teamcenter login" window opens. Enter your access details and click "OK" to confirm. As soon as the connection to Teamcenter is established, the "Synchronize resources" window opens. 3. You can make the following settings in the "Synchronize Tc resources" window: The first time the window opens, select the project corresponding to the resources in Teamcenter from the "Project selection" list. If called again, the previously selected project is set by default. To select a new project, show the list by clicking on the "Project selection" button. To retain existing data, enable the "Incremental update" option. To create transferred data on a separate working layer, enable the "Create working layer" option. 4. To perform synchronization, click "OK". Result New resources are saved to various locations in COMOS dependent upon their type: Classified resources are displayed in the "@02 > 230 > CTI > M > RL > CLR Teamcenter classified resources" node Unclassified resources are displayed in the "@02 > 230 > CTI > M > RL > UCL Teamcenter unclassified resources" node 182 Operating Manual, 09/2011, A5E

183 COMOS interface with Teamcenter 19.7 Administration Types are displayed in the > 230 > CTI > M > TL Teamcenter types" node Units of measurement are displayed in the "@02 > 230 > CTI > M > UOM Teamcenter units of measurement" node Existing resources are updated in COMOS in the locations described. Note Properties of synchronized resources To view the properties of a synchronized resource, select the required resource, open its properties, and select the "Attributes > CTI resource mapping" tab. When you click on the "Resource properties" button on this tab, the "Element properties" window is displayed containing the relevant data from Teamcenter Assigning units of measurement Aim To be able to use the units of measurement used in Teamcenter in COMOS, you make an assignment in COMOS. Requirement Resources from Teamcenter have been synchronized. Attributes for assigning a COMOS unit of measurement were created automatically for the units of measurement used in the Tc resources during the synchronization of resources. See also section Synchronizing resources (Page 182). If no units of measurement are used in Teamcenter, no assignment attributes exist in COMOS. You do not need to assign any units of measurement in this case. Procedure 1. On the "Base objects" tab in the Navigator, select the "02 > 230 > CTI > M > UOM Teamcenter units of measurement" node. 2. Open the properties of the "UOM Teamcenter units of measurement" object. 3. Switch to the "Attributes > Teamcenter units of measurement" tab. A table containing columns called "Name", "Description", and "COMOS unit" is displayed. See also section "Teamcenter units of measurement" tab (Page 171). If no rows are displayed, cancel the process. Either no units of measurement are used in Teamcenter or no assignment attributes have yet been created in COMOS. Assignment attributes are created automatically when synchronizing resources to COMOS. If rows are displayed, the "Name" and "Description" fields will already have been completed. Empty cells in the "COMOS unit" column have to be completed. Operating Manual, 09/2011, A5E

184 COMOS interface with Teamcenter 19.7 Administration 4. To complete empty cells in the "COMOS unit" column, select an empty cell. 5. In the context menu, call the "Properties > Attribute" command as shown in the figure below. A window listing the properties of the attribute is displayed. 3 Step 3 4 Step 4 5 Step 5 6. Click on the "..." button next to the "Unit" field. The "Unit selection" window is displayed. 7. In the "Unit selection" window, click on the unit group matching the unit of measurement from Teamcenter under "Groups", e.g. "Length". 8. Click on the unit used in COMOS, e.g. "Meter". You find additional information in the "Properties" manual, keyword "Assigning units". 9. Save your entries. 10. Repeat Steps 4 through 9 for all empty cells in your table. Result You have assigned the units of measurement used in Teamcenter to the units of measurement used in COMOS. They are displayed in the "COMOS unit" column on the "Attributes > Teamcenter units of measurement" tab. 184 Operating Manual, 09/2011, A5E