COMOS Platform Operating Manual Trademarks 1 Task of the COMOS 2 Service-oriented architecture 3 Prerequisites 4 Installing the Enterprise Server 5 Uninstalling the Enterprise Server 6 Distribution of Windows rights 7 Capacity 8 Administration 9 The COMOS Enterprise Monitor 10 Document revision 11 Importing and exporting working layers 12 Structure of the response file 13 Log files 14 Response / Error messages 15 Participating files 16 Other 17 Example files 18 User interface reference 19 04/2012 A5E03776107-01
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 48 48 90026 NÜRNBERG GERMANY A5E03776107-01 P 05/2012 Technical data subject to change Copyright Siemens AG 2012. All rights reserved
Table of contents 1 Trademarks... 5 2 Task of the COMOS... 7 3 Service-oriented architecture... 9 4 Prerequisites... 11 5 Installing the... 13 6 Uninstalling the... 15 7 Distribution of Windows rights... 17 8 Capacity... 19 9 Administration... 21 9.1 Configuration...21 9.2 The command file...21 9.2.1 command files...21 9.2.2 Structure and configuration of the command file...22 9.2.3 MotionXFixCommand file...28 9.2.4 External filtering...28 9.3 Adapting the response file...29 9.3.1 Purpose of the response file...29 9.3.2 Adapting the response output through XML connectors...30 9.4 User Management...31 9.4.1 User folder...31 9.4.2 Service user / Default user...31 9.5 Administration of the Shared folder...32 9.5.1 Caller of the command file...32 9.5.2 Monitoring the Shared folder...32 9.6 Setting up the for print jobs...32 9.6.1 Aim...32 9.6.2 Installing a new printer...33 9.6.3 Setting the printer port of the...34 9.6.4 Configuring the printer...34 9.6.5 Storing authorized users...36 9.6.6 Using the...36 10 The COMOS Enterprise Monitor... 39 11 Document revision... 43 11.1 Command file for performing revisions on the...44 12 Importing and exporting working layers... 45 12.1 Customizing the command file...45 Operating Manual, 04/2012, A5E03776107-01 3
Table of contents 12.2 Canceling import/export... 48 13 Structure of the response file... 49 13.1 Overview... 49 13.2 The <MXEResult> node... 50 13.3 The <Protocol> node... 50 13.4 The <Status> node... 51 13.5 The <Start> node... 51 13.6 The <Action> node and its subnodes... 51 13.7 The <Stop> node... 53 14 Log files... 55 14.1 Action logs... 55 14.2 Tracing logs... 55 15 Response / Error messages... 57 16 Participating files... 59 17 Other... 61 17.1 Synchronizing the Shared folder... 61 17.2 Technical procedure... 62 17.3 The MotionX Scheduler... 63 17.3.1 Configuring the MotionX Scheduler... 63 17.3.2 Example... 64 17.4 Freely definable DLLs... 64 17.4.1 Customizing the command file for C# assembly... 64 17.4.2 Implementation interface... 65 17.4.3 Logging... 66 18 Example files... 69 18.1 Configuration file... 69 18.2 Command file... 70 18.3 Response file... 72 18.4 Action log... 72 18.5 Tracing log... 73 19 User interface reference... 75 19.1 Window "COMOS Configurator"... 75 19.2 Window "COMOS Service Installer"... 78 4 Operating Manual, 04/2012, A5E03776107-01
Trademarks 1 Trademarks Registered trademark: COMOS Operating Manual, 04/2012, A5E03776107-01 5
Trademarks 6 Operating Manual, 04/2012, A5E03776107-01
Task of the COMOS 2 Overview The COMOS is a Windows service which exchanges data with COMOS that does not require the COMOS user interface. COMOS functions are made available to other systems via a LAN. The is sometimes also referred to as MotionX Server. Main characteristics The following list describes the main characteristics of the : Service-oriented architecture Activates the interoperability between different engineering applications Data transfer between different target systems, e.g. SAP Centralized availability of all external systems Defined services for all project members, accessible via the network Increase in performance by passing resource intensive tasks to the Jobs You have the option of defining own jobs. These jobs are available to external users via the. This enables you to initiate these jobs outside of COMOS via the intranet or Internet. Configuration You configure the yourself, allowing you to control its mode of operation, for example, and to introduce working directories to it. Command files Users can pass command files to the, which then takes care of their execution. Among other things, a command file determines which XML file is processed, which adapter processes the XML file (standard adapter: XML connector), and which method is executed for the file (import or export). The exact technical procedure is described in section "Technical procedure (Page 62)". Programming You can also program and use your own application and adapter. Operating Manual, 04/2012, A5E03776107-01 7
Task of the COMOS 8 Operating Manual, 04/2012, A5E03776107-01
Service-oriented architecture 3 Overview With the COMOS, you implement a stable and service-oriented architecture into the engineering application. Various functions are made available to external users in the form of services. You access these functions from other systems via the. Functions The various functions enable you to implement the service-oriented architecture. The following table describes the individual functions: Function Description Consolidation layer Rule management for data quality check Delta management and visualization History management Data mapping User-friendly data-mapping tool Adapter Replacement adapter Adapter for direct use of COMOS functions Services Security Monitoring Different techniques for releasing adapter functions Access check and user authentication Status monitoring of the processing progress Operating Manual, 04/2012, A5E03776107-01 9
Service-oriented architecture 10 Operating Manual, 04/2012, A5E03776107-01
Prerequisites 4 The following prerequisites have to be met in order to use the : The is shipped together with COMOS. There must be a valid license available for the. As of COMOS 9.0, Windows Framework 3.5 SP1 or higher must be installed. As of COMOS 8.2, AddOn B: The "MXExec" must be located in the COMOS "Bin" directory. This is automatically done during the default installation. The "MXExec" is the application provided by Siemens AG for processing command files. Operating Manual, 04/2012, A5E03776107-01 11
Prerequisites 12 Operating Manual, 04/2012, A5E03776107-01
Installing the 5 Introduction The is installed using a setup program. Components of the setup are a program for configuration, "COMOS Configurator", and a program for service installation, "COMOS Service Installer". These programs accept data and instructions from you. These programs are activated in the setup, but you also have the option of running these programs again at a later date in order to change parameters for configuration or installation. See also chapter Configuration (Page 21) and chapter Service user / Default user (Page 31). Requirement You have already installed COMOS. If the setup program does not find a COMOS installation, an error message is displayed and setup is canceled. Procedure 1. Insert the COMOS CD. The CD browser will launch automatically. 2. Click on the "Additional Software" button. 3. Click on the "COMOS " button. 4. Run the setup. The "COMOS - InstallShield Wizard" window opens. 5. Follow the instructions in the window. Do not select the COMOS directory as the target folder for the installation. This is because the selected directory is used only to determine the location where the "COMOS Configurator" and "COMOS Service Installer" programs are installed. These programs are independent of the regular COMOS application. When the installation is complete, the window "COMOS Configurator" opens. 6. Make the desired settings in the "COMOS Configurator" window. See also chapter Window "COMOS Configurator" (Page 75). If a configuration file for the is already available, the file is read and the data is accepted. 7. Click the "OK" button. Your input is checked and stored in the configuration file. The "COMOS Configurator" window closes. The "COMOS Service Installer" window opens. Operating Manual, 04/2012, A5E03776107-01 13
Installing the 8. Make the desired settings in the "COMOS Service Installer" window. See also chapter Window "COMOS Service Installer" (Page 78). 9. In the "User" field, enter the domain and a Windows user who has administrator rights. Log the user on to the service with which the is intended to work. Since the runs as a service, it is absolutely essential that you specify which user is to use the. The user must have administrator rights both in COMOS and on the local PC. See also chapter Service user / Default user (Page 31). 10. Click the "OK" button. The "COMOS Service Installer" window closes. 11. To check the data you have input and to install the service, click "Finish" in the "COMOS - InstallShield Wizard" window. Result The is registered as a product in Windows and will appear under the list of installed programs. Once it has been successfully installed, the ComosMotionXServerManager will appear in the list of services under "System control > Management > Services". An installation directory (= target folder for the installation) is created in which the two programs "COMOS Configurator" and "COMOS Service Installer" are copied to be used again later. 14 Operating Manual, 04/2012, A5E03776107-01
Uninstalling the 6 Procedure To remove the, proceed as follows: 1. Open the Control Panel. 2. Select "Add or Remove Programs > Change or Remove Programs". 3. Remove the COMOS. Result The is uninstalled. The installation directory and its subfolders remain. Operating Manual, 04/2012, A5E03776107-01 15
Uninstalling the 16 Operating Manual, 04/2012, A5E03776107-01
Distribution of Windows rights 7 Release of folders for the network The COMOS executes file operations within the context of the domain user with which it was started. Users handing tasks to the server will only be able to process the response files generated by the without any problems if they have "Change" authorization for the following folders: The to the user assigned folder in the shared folder History folder Temp folder Recommendation Create a global group in the domain for the user concerned. Procedure In order to assign the access rights for the global group, proceed as follows: 1. Activate the "Change" right. 2. Click the "Extended" button. 3. Activate the option for spreading inheritable authorizations. 4. Save and confirm the settings. Authorization in the file system of the The "Change" right needs to be assigned in the file system of the. This eligibility contains the following rights: Rights Full access Change Read, execute List folder content Read Write Special rights Enable Deactivated Activated Activated Activated Activated Activated Activated The "Special authorizations" type of authorization contains the following rights: "Search folders", "List folders / Read data", "Read attributes", "Read extended attributes", "Create files, write data", "Create folders, attach files". Part of this is the inheritance in the file system of the : "This folder, subfolder, files". Operating Manual, 04/2012, A5E03776107-01 17
Distribution of Windows rights Extended security The allows each user to have one subfolder for saving processing tasks. The interprets this folder name as a COMOS user name and proceeds to execute the orders in the name of the user in the database used by COMOS. In order to ensure that only the authorized user saves tasks, you will need to restrict the access rights for this folder in a way that only the user to whom the folder belongs can access it. The user here requires the under "Authorization in the file system of the Enterprise Server" listed rights. In order to prevent other uses having access via group memberships, you will need to break the inheritance chain from the superordinate folder at this point. You find this option via the "Extended" button in the folder security. 18 Operating Manual, 04/2012, A5E03776107-01
Capacity 8 Integration Import and export of external data The integration platform of the COMOS is based on the COMOS MotionX technology. You can use this platform to import or export data in any format. SAP You can automatically synchronize SAP with COMOS via the. SAP adapters will then be automatically triggered via the. See also the "SAP Interface" manual. Workflow You can define and execute workflows in COMOS. You are the possibility to integrate a large number of other applications. See the "Workflow" manual. Running a workflow with an expired timer To enable several users to use a workflow in one and the same database the scanning is sourced out to the. The workflow service runs through all projects and working layers of the specified database. If workflows are enabled in the project or working layer in question, the following actions are executed: Workflows with an expired timer continue to run. Active workflows where no mandatory attribute has been set are terminated. Command files for running expired workflows. In the following you see an example of a command file: <?xml version="1.0" encoding="utf-8"?> <MXExec Version="2" CommandID="CommandID" Description="Maintain Workflows" MaxRuntime="600" > <Action ActionID="ActionID" Description=""> <Connection ConnectionString="D:\Example\ComosDB.mdb" Project="SO1" WorkingOverlay=""/> <Function Class="Comos.Workflow.ComosWorkflowEnterpriseService" Name="MaintainWorkflows"> <Parameters /> </Function> </Action> Operating Manual, 04/2012, A5E03776107-01 19
Capacity </MXExec> In this command file a project SO1 is specified because an entry is required. However, this entry has no influence on the behavior of the. Nevertheless, it will run through all projects and working layers of the specified database. The parameter element in the command file is blank because no further settings are required. Database synchronization Various branches work with a copy of the central database. Each branch accesses the data it requires. You can trigger the COMOS database synchronization function via the Enterprise Server in order to consolidate and condense databases from different locations. This ensure that the same data is available to all users. See also the "COMOS Administration" and "Basic Operation" manuals. 20 Operating Manual, 04/2012, A5E03776107-01
Administration 9 9.1 Configuration The is configured by the "COMOS Configurator" program during installation. See chapter Installing the (Page 13). You can also change the configuration at any stage by opening the program again. To start the configuration, go to the installation directory. See chapter Window "COMOS Configurator" (Page 75). The configuration data is saved in the file "ComosMotionXServerManager.config". The configuration file is available in the "config" directory. See also Configuration file (Page 69) 9.2 The command file Command are files that instruct the which commands to execute. Command files have the file ending "*.mxc". In order to execute a command file, store it in the Shared folder or in one of your user subfolders. See also section Administration of the Shared folder (Page 32). One process is started for each command file. The process runs until the file has been fully executed or the maximum runtime has been reached. If you use the uniquecommandid, a command file will be identified on the basis of the CommandID. See also section Structure and configuration of the command file (Page 22). If a process with the same CommandID has not yet been completed, this will prevent the command file from being executed. In this case an entry is created in the "Log.txt" file which shows you the command file whose execution has been prevented. The following sections explain the structure and configuration of the command file, as well as the possibility to assign filters to XML connectors via the command file. An example of a command file can be found in section "Command file (Page 70)". 9.2.1 command files MXC file To allow you to use the new functions of the, the "MXExec.exe" file was replaced with the "Comos.EnterpriseServer.Process.exe" file. You can still use all old MXC files. Operating Manual, 04/2012, A5E03776107-01 21
Administration 9.2 The command file 9.2.2 Structure and configuration of the command file Overview Each command file must have the following structure: <MXExec Version="..." CommandID="..." Description="..." MaxRuntime="..." > <Settings> <uniquecommandid> </uniquecommandid> </Settings> <Action ActionID="..." Description="..." > <Connection ConnectionString= "..." Project="..." WorkingOverlay="..." /> <Function Class="..." Name="..." > <Parameters> <!-- List with command parameters --> </Function> </Action> <Action <!--... --> </Action> </MXExec> 22 Operating Manual, 04/2012, A5E03776107-01
Administration 9.2 The command file The <MXExec> node The <MXExec> node has the following attributes: Attribute: Name Version CommandID Description MaxRuntime Attribute: Value/Purpose The version number of the MotionX command structure. Mandatory attribute The ID of the command file. Mandatory attribute Descriptive text for the command file, for administration purposes. Optional Maximum runtime in minutes that the process responsible for executing the command is allowed to run. Background: Command files that cannot be fully processed and get stuck at a certain point will thus be terminated forcibly after a certain time. Optional The <Settings> node The uniquecommandid specified here is used to prevent a command file triggering a process again as long as the process is not yet completed. The command file is deleted. A results file containing a relevant note is created. If the execution of a command file is prevented, the entry Prevented is written to the Log.txt file. The permitted values are "True" and "False". The <Action> node A MotionX command can consist of multiple actions. Accordingly, the command file can have several <Action> type nodes. Each <Action> type node has two subnodes in which the details of the action are defined: A <Connection> type node and a <Function> type node. Following applies to actions: Each action depends on the database, project, and working layer. Each action consists of a method call. Either the import or export method can be called for XML connectors. The method call takes place in a subnode of the <Action> node. The data generated by action A can be processed further by action B. Example Action A imports valves to COMOS. The XML connector addressed by action B filters the valves according to specific criteria and then exports the filtered valves. Each <Action> type node has the following attributes: Operating Manual, 04/2012, A5E03776107-01 23
Administration 9.2 The command file Attribute: Name ActionID Description Attribute: Value/Purpose The action ID. Mandatory attribute Descriptive text for the action, for administrative purposes. Optional The <Connection> node Each <Action> type node has exactly one <Connection> type node. The <Connection> node contains all information on the database to be used, the project to be used and the working layer to be used. This data is required to start a COMOS instance in the background and to execute the action there. The <Connection> node has the following attributes: Attribute: Name ConnectionString Project Working-Overlay Attribute: Value/Purpose Path to the database instance to be opened. If mapped drives are being used: refer to the information on the <DriveMappings> parameter from the configuration file. See chapter Window "COMOS Configurator" (Page 75). Examples for the three possible database types: SQL database: "[SQL - SERVER]pt_sql_server" Access database: "D:\ComosDatabases\StandardDB\ComosDB.mdb" Oracle database: "[ORACLE]pt_oracle" Mandatory attribute Name of the project to be opened. Mandatory attribute Name of the working layer to be opened. The names of nested working layers are given in full, with " " ("pipe") used as a separator. For example: Project1 Subproject1 Mandatory attribute 24 Operating Manual, 04/2012, A5E03776107-01
Administration 9.2 The command file The <Function> node Each <Action> type node has exactly one function node. The function node stipulates which method is to be executed. It has the following parameters: Attribute: Name Class Name Attribute: Value/Purpose The ProgID of the component whose method is to be executed, i.e. the adapter that processes the XML file. Standard adapter supplied with COMOS: "Comos.XMLAdapter.Adapter" (= an adapter for XML connectors) If you wish to trigger your own component via the, enter the ProgID of the class to be instanced by the here. Mandatory attribute The name of the method that is called from the component specified in Class. The standard adapter for XML connectors has two public methods: import and export. Mandatory attribute The <Parameters> node/function parameters On calling a function, parameters are passed to the function. Which parameters are passed depends on the function called. The parameters are bundled in the <Parameter> node. Each parameter is encapsulated in a <Parameters> type node. Each parameter has two mandatory attributes: one for the parameter name, the other for the parameter value. In addition, there is an optional attribute named ParamType. The import function of the standard adapter for XML connectors has the following parameters: Operating Manual, 04/2012, A5E03776107-01 25
Administration 9.2 The command file Attribute: Name XMLFile Attribute: Value/Purpose Absolute or relative path to the XML file to be processed. You define the path in the "@MotionX > XCD_G01 XML connector types" standard table in the base project. Absolute path: "C:\ComosImportExport\XMLDocs\ExportTest.xml" Relative path: The path is relative to the command file (which is located either in a user folder or directly in the Shared folder). XMLConnector RootNode XMLFileMoveTo Example: "XMLDoc\ExportTest.xml" The "ExportTest.xml" file is located in the "XMLDoc" folder alongside the command file. Mandatory parameter Path to the XML connector in the open project or working layer. The path is always specified relative to the "Documents" tab, node "@System > @MXC". You can use the additional ParamType parameter to specify whether the path is given as SystemFullName or PathFullName. (Also see the note at the end of this section.) Example: "<Parameter Name="XMLConnector" Value="Interface1 2" ParamType="SystemFullName" />" The searched-for XML connector is located in the "Documents" tab at position "@System>@MXC>Interface1>2". Mandatory parameter Path to the start object that is to be used by the XML connector. Similar to XMLConnector, specify in ParamType whether the path is given as SystemFullName or PathFullName. If you do not specify a RootNode, the XML connector is executed with the start object that is saved in its properties. The start object of the last import operation is always saved there. Path designation of a directory to which the XML file is moved after the execution. If you do not specify a value, the file is deleted. If the XML file should not be moved, delete the entry or comment it out. The path here is permitted to be absolute or relative to the SharedFolder. The path may not contain a file name. Examples: Absolute path: "C:\\XML Backup\" Relative path: "Data backup\" The following attributes correspond to the options in the COMOS "Import" window. You can find more information on this topic in the "Interfaces" manual, keyword "Triggering connectors via a script". DeleteObjects Determines whether the "Delete objects" option is activated. If it is activated, all objects that are not located in the XML file are deleted in COMOS. Value either "True" or "False". Default value: "False" 26 Operating Manual, 04/2012, A5E03776107-01
Administration 9.2 The command file Attribute: Name Versions-Administration DifferenceOnly SaveMode Attribute: Value/Purpose States whether the option "Include in version management" is active. If it is activated, the imported file is saved in COMOS and is issued with a version number. Value either "True" or "False". Default value: "False" States whether the option "Work with different objects only" is active. If it is activated, the new XML file is compared with the old file (which is already saved in COMOS) during a reimport. Only differing data is processed. Value either "True" or "False". Default value: "False" Determines whether all data changes in COMOS are saved at the end of the operation only, i.e. after all objects have been processed successfully. If an error occurs, no object is imported. Value either "0" (= False) or "1" (= True). Default value: "False" The Export function of the standard adapter for XML connectors has the following parameters: Attribute: Name XMLFile XMLConnector RootNode Attribute: Value/Purpose Analogous to the import function. Analogous to the import function. Analogous to the import function. The following attributes correspond to the option in the COMOS "Export" window. You can find more information on this topic in the "Interfaces" manual, keyword "Triggering connectors via a script". ShowFile Determines whether the exported XML file will be displayed in the Internet Explorer directly after the export. This setting is not favorable for server operation and, therefore, can be unchecked here. Value either "True" or "False". Default value: "False" VersionsAdministration Analogous to the import function. Filter Filters can be assigned to the queries of the XML connector through these parameters, This means you can modify the configuration of the XML connector from outside COMOS, without a user interface. See also chapter External filtering (Page 28). Optional parameter Information on the ParamType parameter of the XMLConnector and RootNode parameters The SystemFullName is not automatically unique. If you want to use the SystemFullName, ensure that it is unique. The PathFullName is always unique. Determine the PathFullName using the COMOS object debugger. Open the Object Debugger from the "Extra > Object Debugger" COMOS menu bar. For more information on this topic, see the manual "Class Documentation COMOS_dll". Operating Manual, 04/2012, A5E03776107-01 27
Administration 9.2 The command file 9.2.3 MotionXFixCommand file Data import via the The MotionXFixCommand file supports the data import via the without the need to adapt external systems in order to generate a command file. The MotionXFixCommand file (MXFC file) looks like any standard MotionX command file of the. You define the file in the Shared folder or in one of its subdirectories. The defined information is contained in the "XMLFile" parameters of the relevant action blocks of the MXFC file. If one of the being searched files is found in the Shared folder, it will be moved to the "Temp" directory of the. The ComosMotionXServerManager creates a MXC file with the name format "<mxfc-filename>" - "<XMLfilename>". The MXFC file remains in the shared folder after the MXC file has been executed. If a target directory has been entered in the "XMLFileMoveTo" parameter of the action block, the imported file is moved, or if there is no entry in the "XMLFileMoveTo" parameter, it is deleted from the "Temp" folder. From here the ComosMotionsXServerManager starts a new MXExec process using the created MXC file as a parameter. The MXFC file remains in the Shared folder after the MXC file has been processed. The returned MXR file is saved along with the MXFC file in the same directory, and the MXC file is moved from the "Temp" directory to the "History" folder. Overview 1. Fixed command files end with "mxfc". Files are copied to the Shared folder once and neither deleted nor moved after execution. 2. MXFC files apply only to import. 3. The path of the to be imported file is relative to the folder containing the MXFC file. 4. The in the MXC file supported function types are also supported in the MXFC file. 9.2.4 External filtering It is possible to filter the queries of the XML connector addressed by the command file from an external location, i.e. without opening the COMOS user interface (= external filtering). Filters can be defined in the command file for this purpose, these are then used to filter the results returned by the queries. A new parameter was defined within the function node for this purpose: "Name" = "Filter" Each filter can have as many item subnodes as required, one for each filter item. The filter items define which column of which query is filtered, and how. Each filter item has the following attributes: 28 Operating Manual, 04/2012, A5E03776107-01
Administration 9.3 Adapting the response file Attribute: Name "QueryName" "ColumnName" "Value" Attribute: Value/Purpose Name of query that is filtered. Mandatory attribute Name of the column that is filtered. Mandatory attribute The value that is filtered. Mandatory attribute All filters that were defined within an "<Action>" node are linked through an AND operator. The other operators that can be used when filtering via the COMOS user interface are not available. Only objects meeting all filter conditions are exported. Example <Function...> <Parameters> <Parameter Name="..."...> <Parameter Name="Filter"> <Item QueryName="Q1" ColumnName="Object" Value="ABC"/> <!-- <Item QueryName="Q2"... /> --> </Parameter> </Parameters></Function> 9.3 Adapting the response file 9.3.1 Purpose of the response file The generates the so-called response file after a response file was processed. A response file has the file ending ".mxr". It has the same name as its command file and is stored in the same directory, in which the command file was stored before. The response file logs the results or errors and warnings that are produced when processing the command file, and can be processed further by an external application. In particular, the response file serves to check whether the execution of the command file has led to the expected results. This is especially important for import operations. It is possible that the external application needs detailed information for an analysis than the automatically generated entries contained in the Response file. Therefore, the user can define so-called Check columns for the XML connector. If the Check column of an object that is processed by the XML connector is not empty (i.e., a value is entered in the Check column), then the following information is also added to the response file: the at the object in the Check column entered value the values of the other query columns, including the necessary management information (column name, mapping information, value in COMOS, XML value) Operating Manual, 04/2012, A5E03776107-01 29
Administration 9.3 Adapting the response file With the help of these values, the external application can, for example, verify whether the correct values were assigned to the objects created in COMOS during the import operation. The structure of the response file is described in detail in section "Structure of the response file (Page 49)". An example of a command file is given in section "Action log (Page 72)". 9.3.2 Adapting the response output through XML connectors In order to adapt the content of the response file, you must start COMOS and navigate to the XML connector that is addressed by your command file. Select the XML connector and, in its context menu, select the entry "XML > Configure XML connector". If a column already exists in the configuration tool which then opens, assign it the property "Check column"; or create a new column and assign this column the property "Check column": Select the "Mapping" tab. You see a table where each row corresponds to a column of the selected query. Activate the "Check column" option for the desired column: The value that is entered in the column marked as Check column when the XML connector is called can be determined by a simple value calculation. However, it is also possible to carry out a script calculation and to have the script return the value. Result: When generating the response file, it is verified for each processed object if a value is entered at the object in the Check column. If yes, a "<Check>" node is created. Under the "Check>" node, several "<Column>" subnodes are created that output the values of the remaining columns defined in the XML connector. Detailed information on the "<Check>" node is given in subsection "The <Check> node" in section "The <Action> node and its subnodes (Page 51)". You find more information on check columns and on the configuration of XML connectors in the manual, section "XML/MotionX", subsection "Free import/export ("XML connectors")", section "Further useful options in the "Mapping" tab". 30 Operating Manual, 04/2012, A5E03776107-01
Administration 9.4 User Management 9.4 User Management User management is carried out in the Shared folder. It is folder-based. 9.4.1 User folder In the Shared folder, you create a subfolder for each user who is permitted to issue a command to the. The subfolder must have the login name that the user has in COMOS. Each user should only be able to issue one command to the via their own folder. In other words, User 1 must not be able to access the folder of User 2. As the access rights to these subfolders are managed externally through the operating system administration, the administrator must ensure that each user has user rights for his own folder only. Besides, the users should not have write access to the Shared folder itself. 9.4.2 Service user / Default user The default user is the service user, i.e. the user to whom the service is registered. Rights The Default user must have admin rights, i.e. he/she must be able to start a process and create, write to, and delete folders in all directories of the. If, in addition to the service user, other users are to have authorization to transfer command files to the, the default user must have administrator rights in COMOS in order to be able to start COMOS with a different user name than the service user. In addition, a folder can then be created for the Default user in the Shared folder: Folder name: "Default" or "Default user" Changing the service user The service user is created during the installation via the "COMOS Service Installer" program. See also chapter Installing the (Page 13). You can also change the service user or their password at a later time by running the program again. Start the program from the installation directory of the. See also chapter Window "COMOS Service Installer" (Page 78). Operating Manual, 04/2012, A5E03776107-01 31
Administration 9.5 Administration of the Shared folder 9.5 Administration of the Shared folder The Shared folder contains the command files (.mxc) and the response files (.mxr). Each response file lies parallel to its command file. Moreover, user management is carried out in the Shared folder. The Shared folder name can be freely selected. We use the name "Shared folder" in this documentation because every and every user who issues a command to the can access this folder and its subfolders. (The access of the Service user is done directly via the Shared folder, access for other users via the subfolders of the Shared folder.) 9.5.1 Caller of the command file When you create a command file directly in the Shared folder or in a subfolder called "Default" or "Default user", then the Service user is the caller of the command file. If, in the Shared folder, additional folders have been created for other users alongside the folder for the Service user, these other users can also issue commands to the Enterprise Server. However, this is only possible if the Service user is a COMOS administrator. Information on which user issued a command is recorded in the log files and is also considered in COMOS (timestamp, rights administration). To identify the COMOS user, the name of the subfolder from which the command file was taken is used. 9.5.2 Monitoring the Shared folder At regular intervals (as specified in the "MonitoringTime" parameter of the configuration file), the MotionX Server recursively searches the Shared folder for command files (".mxc"). 9.6 Setting up the for print jobs 9.6.1 Aim You can set up your to send all print jobs produced by your employees to the in addition to mass transfer of revision files. This approach reduces the workload on your local computer. Opening, evaluating and sending a document to the printer then takes place on the. See also Installing a new printer (Page 33) 32 Operating Manual, 04/2012, A5E03776107-01
Administration 9.6 Setting up the for print jobs 9.6.2 Installing a new printer To set up a printer for the, first install a printer with the settings described below. Procedure 1. To add a new printer to your Windows system, open the context menu of the "Start > Settings > Printers and Faxes" window and click the "Add a printer" command. The Add Printer Wizard opens. 2. Click "Next". 3. Select the "Local printer attached to this computer" option in the "Local or Network Printer" window. 4. Disable the option "Automatically detect and install my Plug and Play printer" and click "Next". 5. Apply the default settings in the "Select the Printer Port" window. The "Use the following port" is enabled and the default setting is "LPT1: (Recommended Printer Port). 6. Select a printer driver of your choice in the "Install Printer Software" window and click "Next". This printer driver is not used later. 7. Enter a printer name of your choice in the "Printer name" field of the "Name Your Printer" window. This name must be identical to the name of the configuration document in the base project. See also chapter Configuring the printer (Page 34). This is an example for the printer name: "COMOS ES". 8. To use the the newly configured printer as the default printer, select the option "No" and click "Next". 9. In the "Printer Sharing" window, activate the option "Share name" and enter the printer name you assigned earlier in the box provided. For example, "COMOS ES". This is a prerequisite in order for the user to add the new printer. 10. Click "Next". 11. Enter the desired location details in the "Location" field of the "Location and Comment" window. The location details are also entered in the configuration file later. See also chapter Configuring the printer (Page 34). Example: Office 100, Any Street 90. 12. Click "Next". 13. Select the "No" option in the "Print Test Page" window, and click "Next". 14. To complete the printer installation, click "Finish" in the "Completing the Wizard" window. Operating Manual, 04/2012, A5E03776107-01 33
Administration 9.6 Setting up the for print jobs See also Setting the printer port of the (Page 34) 9.6.3 Setting the printer port of the Requirement You have set up a new printer to connect to the. See also chapter Installing a new printer (Page 33). Procedure 1. Open the window "Start> Settings > Printers and Faxes" in your Windows system, select the newly installed printer and click "Properties" in the context menu. 2. Open the "Ports" tab. 3. Click "Add". The "Printer Ports" window opens. Select "Local Port" from the list of available port types. 4. Click the "New Port..." button. The "Port Name" window opens. 5. As the port name, enter "ComosES" and confirm your entry. The "ComosES" name may not be changed. COMOS recognizes the upstream printer by this port name. 9.6.4 Configuring the printer You still have to publish the printers to be used by the for physical printout. Requirement You have installed a new printer. See also chapter Installing a new printer (Page 33). You have set the printer port of the printer. See also chapter Setting the printer port of the (Page 34). Procedure 1. To perform the configuration in the base project, select the command "File > Open project" in the COMOS menu bar, select the "Base objects" option in the "Open project" tab and double-click on the "S01 base project" entry in the list. 2. Go to the Base objects" tab. 34 Operating Manual, 04/2012, A5E03776107-01
Administration 9.6 Setting up the for print jobs 3. Select the "Cfg Example Configuration" object in the "@MotionX > P" node. This is a prepared configuration file in XML format. 4. Create a copy of the "Cfg Example Configuration" file and rename it to match the name of the printer. See also chapter Installing a new printer (Page 33), Step 8. 5. Open the configuration file you have created by copying in a text editor and enter your information for the attributes highlighted in red. All attributes must be set, that is, receive values. Attribute Description Example ServerPrinterNa me UNC name of the printer, i.e. \\<server \\EnterpriseServer.company.com\COMOS ES name>\<printer name> Path Name DisplayName UNCName Location Path to the DocFolder below the shared folder Name of the physical printer or a printer driver for generating files, for example, PDF files. This printer must be connected to the. For each printer you want to make available, copy the line <Printer... Do not enter the printer you have created. This is not a physical output device. The name that should appear in the user interface. This is usually identical to the name. If your printer is connected to another computer, then enter \\<computer name>\<printer name>. If the printer is installed on the Enterprise Server, this value is identical to the name. The value from the "Location" field of the "Location and Comment" window in the Windows Add Printer Wizard. See also Installing a new printer (Page 33), Step 12. \\<server name>\sharedfolder\docfolder HP Laserjet 4 HP Laserjet 4 \\EnterpriseServer.company.com\COMOS ES COMOS ES Office 100, Any Street 90 Operating Manual, 04/2012, A5E03776107-01 35
Administration 9.6 Setting up the for print jobs 9.6.5 Storing authorized users Requirement The Path specification of the "DocFolder" folder has been entered in the XML configuration file. See also chapter Configuring the printer (Page 34). Procedure Create a directory for every user that should be allowed to print below the "\\<server name>\sharedfolder\docfolder" folder. The directory name must be identical to the user name of the respective COMOS user. Example COMOS user name: "ADXOAN10" Path: "\\EnterpriseServer.company.com\SharedFolder\DocFolder\ADXOAN10" 9.6.6 Using the Requirement (administrator) The new printer is installed. See also chapter Installing a new printer (Page 33). The printer port of the is set. See also chapter Setting the printer port of the (Page 34). The printer is set in the configuration file. See also chapter Configuring the printer (Page 34). The authorized users are registered. See also chapter Storing authorized users (Page 36). Procedure (user) The user registers the as an additional printer in the Windows operating system. To use the printer, the user selects the printer from the list of available printers in the printer dialog for each print job. After clicking "OK", the user selects the physically available printer from those available in the next window. 36 Operating Manual, 04/2012, A5E03776107-01
Administration 9.6 Setting up the for print jobs Result The print job is sent to the server, which sends the document or documents to the printer that was selected in the second dialog. Operating Manual, 04/2012, A5E03776107-01 37
Administration 9.6 Setting up the for print jobs 38 Operating Manual, 04/2012, A5E03776107-01
The COMOS Enterprise Monitor 10 A tool named the COMOS Enterprise Monitor is installed with the. This tool displays all processes currently running on the s after these have started up. To enable the COMOS Enterprise Monitor to display the processes of all of the Enterprise Server's instances after they have started up, these instances must use the same log directory. Starting the COMOS Enterprise Monitor Open the COMOS installation directory "<COMOS>\Bin" and then start the file "ComosEnterpriseMonitor.exe" with a double-click. The user interface language of the Enterprise Monitor is based on the currently selected language in the COMOS user interface. Functionality Among other things, the log folder contains so-called process log files. A process log is an XML file that contains important information regarding the process. There is a process log for each process. The COMOS Enterprise Monitor displays the data of this XML file. Each row in the Monitor corresponds to a running process and, by implication, a process log. Once a process has ended, its process log file is automatically deleted from the log directory. Thus, the entry is removed from the Monitor table as well. "Show result files in list" option When this option is enabled, results are displayed in the "Status" column of the table and a progress bar is displayed. If the option is disabled and the Enterprise Monitor starts up, not all jobs are loaded. The progress bar is not displayed. Finished jobs are no longer displayed in the monitor table. To display the status and progress bar, you can retroactively enable the option. Columns in the Monitor table Column "User" "Command ID" "Command Description" "Action ID" "Action Description" Description The Service user The "CommandID" of the command file. The "Description" of the command file. The "ActionID" of the action currently being executed. The "Description" of the executed action. Operating Manual, 04/2012, A5E03776107-01 39
The COMOS Enterprise Monitor Column "Starting time" "Status" "Priority" "Last message" "Finishing time" "Command file" "Process ID" "Station" Description Starting time of process. Displays the current status of the jobs and the end result of completed jobs: Erroneous jobs Jobs that were successfully completed, although their logs contain warnings. Error-free jobs The display in this column depends on the "Show result files in list" option. Displays the priority of the pending jobs. The smallest number indicates the highest priority. You can use the "Set higher priority" and "Set lower priority" buttons to change the priority of the selected pending job. The last function called up from the query Indicates the completion time Name of the internal command file currently being processed. The processid. The name of the workstation of the Service user. When "Last message" no longer changes, this could mean that the processing is currently at a component outside the connector, such as a script, an external component or another COMOS component. Sorting The order of the columns in the Monitor table is fixed. When you click one of the column headers, the rows are sorted according to this column. Buttons The following table describes the buttons of the COMOS Enterprise Monitor: Button Description Raises the priority of the selected job. In this way you can determine the sequence of processing. Only active for pending jobs. Lowers the priority of the selected job. In this way you can determine the sequence of processing. Only active for pending jobs. One of the following actions is executed, depending on the status of the selected job: Deletes a pending job. Aborts a job that is currently running. Deletes the results file of a completed job. 40 Operating Manual, 04/2012, A5E03776107-01
The COMOS Enterprise Monitor Button Description Starts the server. You must start the on the same computer as the Enterprise Monitor. Stops the server. Updates the job list. MotionXMonitor In addition to the COMOS Enterprise Monitor, the MotionXMonitor is also available in the "Bin" directory. To start the MotionXMonitor, run the file "MotionXMonitor.exe". The COMOS Enterprise Monitor replaces MotionXMonitor. Terminating a process using the MotionXMonitor You can terminate a process from the MotionXMonitor. Click the "Terminate Process(es)" button to do so. Result: The generates a response file with the error "Process terminated without response". Attention: No rollback takes place, i.e. steps that have already been processed are not undone. Operating Manual, 04/2012, A5E03776107-01 41
The COMOS Enterprise Monitor 42 Operating Manual, 04/2012, A5E03776107-01
Document revision 11 Overview The various document tools allow you to revise multiple documents simultaneously. You find more information on this topic in the "Document management" manual, keyword "Using "All document tools"". You can outsource this bulk revision function to the to reduce the load of a workstation. Revision option To outsource bulk revisions to the, open project properties and select the option "Enable transfer of revision jobs to COMOS " in the "Revision options" tab. The shared folder is displayed in the "Shared folder" field. Create a folder called "DocFolder" directly below the Shared folder. In the "DocFolder" folder, create a subdirectory bearing the user name for every user performing document revisions via the Enterprise Server. If the user folder does not exist below the document folder, this is indicated by an error message. After you have entered these settings the revision jobs to be performed using "All document tools" are outsourced to the. Revision When you perform revisions using "All document tools" this is displayed in the "Revision" window. If you do not want revisions to be transferred to the, select the option "Execute locally". Result All error messages generated in the process of revision are forwarded to the Enterprise Server and summarized in the revision jobs response file. The response file contains the results of the revision process. Status The COMOS Enterprise Monitor may show one of the following revision statuses: "Open" "Finished" See also Command file for performing revisions on the (Page 44) Operating Manual, 04/2012, A5E03776107-01 43
Document revision 11.1 Command file for performing revisions on the 11.1 Command file for performing revisions on the Example The following shows an example of a command file for performing revisions on the : <?xml version="1.0" encoding="utf-8"?> <MXExec Version="42" CommandID="RevisionJob" Description="Server-based revision job" MaxRuntime="0"> <Action ActionID="RevisionDocuments" Description="Revision collection of documents"> <Connection ConnectionString="<DatenBank>" Project="<ProjectName>" WorkingOverlay="<leer oder WorkingOverlayID>"/> <Function Class="ComosDocumentManager.DocumentManager" Name="ESRevisionDocuments"> <Parameters> <Parameter Name="RevisionJobXML" Value="<Base64-kodiertes XML>"/> </Parameters> </Function> </Action> </MXExec> CommandID contains the entry "RevisionJob". The ActionID is "RevisionDocuments". There is only one parameter in the command file. This parameter is called "RevisionJobXML". This parameter contains a Base64-encoded XML document containing all the information required for revision. This may be the following information for example: SystemUIDs of the documents to be revised User names Revision step... 44 Operating Manual, 04/2012, A5E03776107-01
Importing and exporting working layers 12 Overview The import or export of the working layer is configured in the command file. See also chapter The command file (Page 21). Sequence As soon as the task is received by the and started, COMOS will activate the import/export process under the user account that started the task. The parameters from the command file are taken into account during this process. After the execution of the command file, a response file is created in the usual way. In this file, the final status message is saved, indicating whether the task has been completed successfully or unsuccessfully. See also chapter Structure of the response file (Page 49). Logging Debug, info, warning and error messages are stored in the tracing log. See also chapter Tracing logs (Page 55). Status and progress The current status and progress are shown in the Monitor. If the Import/Export process freezes, you are able to cancel it via the COMOS Enterprise Monitor. See also chapter The COMOS Enterprise Monitor (Page 39). 12.1 Customizing the command file The command file must contain all the necessary parameters needed by the import/export of the working layer. Operating Manual, 04/2012, A5E03776107-01 45
Importing and exporting working layers 12.1 Customizing the command file Export Parameter <MXExec Version> <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.ImportExp ortwoviaes" > <Parameter Name="Action" Value="Export" <Parameter Name=" WorkingOverlayName" Value="" Parameter Name=" ExportPath" Value="" Override Description Version "3" must be entered here. The "Assembly" parameter specifies the DLL/Assembly that is started by the Enterprise Server. The values are preset for the import/export of working layers and may not be changed. You can find more information on this topic in the "Interfaces" manual, keyword "Loading existing assemblies". Name of the action being executed: Permitted value: Export The value should be the name of the working layer to be exported. Do not specify any nesting of the working layers. The working layer must be located below the working layer defined in the node <Connection WorkingOverlay="Demo">. If the value for WorkingOverlay is empty, the working layer must be located directly below the project. Example (<Connection Project="COMOS_ET"). The value specifies the complete path where the exported working layer is saved. Specifying the file name is optional. If omitted, the name of the exported working layer is used. Permitted values "True" or "False". This information specifies whether an existing working layer with the same name is overwritten during an export. Because the file receives the name of the working layer to be exported, a multiple export may necessitate an overwrite. Example <?xml version="1.0" encoding="utf-8"?> <MXExec Version="3" CommandID="Import_Export_WO" Description="Development Test" MaxRuntime=""> <Action ActionID="Action02" Description="Location + ClassName"> <Connection ConnectionString="<Database path>" Project="<Project name>" WorkingOverlay="<Name of working layer>" /> <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.ImportExportWOViaES"> <Parameters> <Parameter Name="Action" Value="Export"/> <Parameter Name="WorkingOverlayName" Value="<Name of the working layer>" Override="True"/> <Parameter Name="ExportPath" Value="<Path of the export file>"/> </Parameters> 46 Operating Manual, 04/2012, A5E03776107-01
Importing and exporting working layers 12.1 Customizing the command file </Assembly> </Action> </MXExec> Import Parameter <MXExec Version> <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.ImportExp ortwoviaes"> <Parameter Name="Action" Value="Import" <Parameter Name=" WorkingOverlayDescription " Value="" Parameter Name="ImportPath" Value="" Description Version "3" must be entered here. The "Assembly" parameter specifies the DLL/Assembly that is started by the Enterprise Server. The values are preset for the import/export of working layers and may not be changed. You can find more information on this topic in the "Interfaces" manual, keyword "Loading existing assemblies". Name of the action being executed: Permitted value: Import Optional: Description of the new working layer to be created. The working layer is imported directly below the project or the working layer defined in the <Connection> node. If the value is empty, COMOS automatically creates a description of the format "Import on <<Date and time>>". Full path of the working layer to be imported (including database name). Example <?xml version="1.0" encoding="utf-8"?> <MXExec Version="3" CommandID="Import_Export_WO" Description="Development Test" MaxRuntime=""> <Action ActionID="Action02" Description="Location + ClassName"> <Connection ConnectionString="<Database path>" Project="<Project name>" WorkingOverlay="<Name of working layer>" /> <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.ImportExportWOViaES"> <Parameters> <Parameter Name="Action" Value="Import" /> <Parameter Name="WorkingOverlayDescription" Value="" /> <Parameter Name="ImportPath" Value="<Path of the import file>"/> </Parameters> </Assembly> </Action> </MXExec> Operating Manual, 04/2012, A5E03776107-01 47
Importing and exporting working layers 12.2 Canceling import/export 12.2 Canceling import/export Procedure If the import or export of a working layer freezes, you can cancel it via the COMOS Enterprise Monitor. See also chapter The COMOS Enterprise Monitor (Page 39). Result If you cancel the process during the export process, the exported file will be incomplete. Delete the file because a re-import may create inconsistencies. If you cancel the process during the import process, the working layer is still created, but given the description "(** Incorrectly imported **)". This can cause data inconsistencies. Depending on when you canceled the process, the new working layer may or may not already contain objects. To maintain data consistency, completely delete the created file or working layer after an aborted import or export and start the process again. 48 Operating Manual, 04/2012, A5E03776107-01
Structure of the response file 13 This section explains the structure of a response file, since an external application needs to know the structure in order to be able to process the file. The purpose of the response file and how to customize its content was already described in "Adapting the response file (Page 29)". 13.1 Overview A response file must have the following structure: <MXEresult Version="..." CommandID="..." > <Protocol> <Status Code="..." Description="..." /> <Start User="..." Station="..." DateTime="..." DateFormat="..." MXExecFile="..." /> <Action ActionID="..." > <Status Code="..." Description="..." /> <Protocol> Operating Manual, 04/2012, A5E03776107-01 49
Structure of the response file 13.2 The <MXEResult> node <!-- Warnungen und/oder Fehler --> <!-- Check-Spalten --> </Protocol> </Action> <Action... /> <Stop DateTime="..." /> </Protocol> </MXEresult> Note Most nodes and attributes are mandatory nodes / attributes. Therefore, the "Mandatory node"/"mandatory attribute" mark is left out in the following sections. If this is an optional node or an optional attribute, this will be explicitly indicated. 13.2 The <MXEResult> node The "<MXEResult>" node has the following attributes: Attribute: Name "Version" "CommandID" Attribute: Value / Purpose Version of command structure that is used in this file. The "CommandID" of the relevant command file. 13.3 The <Protocol> node Each response file can have several "<Protocol>" nodes. The "<Protocol>" node directly below the "<MXEResult>" node contains the complete protocol for the entire command file. It has the following subnodes: a "<Status>" node a "<Start>" node an "<Action>" node for each action node of the command file a "<Stop>" node In addition, each action node has a "<Protocol>" subnode. 50 Operating Manual, 04/2012, A5E03776107-01
Structure of the response file 13.4 The <Status> node 13.4 The <Status> node Each response file can have several "<Status>" nodes. The topmost "<Status>" node contains the status of the complete protocol. In addition, each action node has a "<Status>" subnode. All "<Status>" nodes have the following attributes: Attribute: Name "Code" "Description" Attribute: Value / Purpose Information whether the command file was processed successfully. "0" = successful "1": not successful For the complete protocol, "Code" can only be "0" if the status of all action nodes is also "0". If Code="0": "OK", if Code="1": "Not OK". 13.5 The <Start> node The "<Protocol>" node for the protocol of the entire response file has a subnode "<Start>". The <"Start"> node documents when command file was executed and who called it. It has the following attributes: Attribute: Name "User" "Station" "DateTime" "DateFormat" "MXExecFile" Attribute: Value / Purpose Name of the user who issued the command file Name of the computer from which the command file was issued Date and time when the processing of the command file was started. Format in which the date is specified Path to the temporary command file that is generated Optional The counterpart of the <"Start>" node is the "<Stop>" node at the end of the complete protocol. See section "The <Stop> node (Page 53)". 13.6 The <Action> node and its subnodes The <Action> node For each <"Action"> node from the command file, there is an <"Action"> node in the response file. Each <"Action"> node has an attribute: Operating Manual, 04/2012, A5E03776107-01 51
Structure of the response file 13.6 The <Action> node and its subnodes Attribute: Name "ActionID" Attribute: Value/Purpose The "ActionID" of the corresponding action from the command file. Each "<Action>" node has two direct subnodes: "<Status>" and "<Protocol>". The <Status> node Same as the "<Status>" node for the complete protocol. Specifies whether the action was processed successfully. See section "The <Status> node (Page 51)". The <Protocol> node Each "<Action>" node has a "<Protocol>" node that logs the execution of this action. This "<Protocol>" node can contain subnodes for warnings, errors, and Check columns. These nodes are optional nodes. The <Warning> node If a warning occurs, a "<Warning>" node is created. "<Warning>" has the following attributes: Attribute: Name "Code" "Description" Attribute: Value/Purpose The warning code, if available. Descriptive text. If the warning results from a COMOS object, the node "<Warning>" will have a subnode "<ComosObject>", which reads out the following object properties: SystemUID, SystemType, SystemFullName, PathFullName, Description. The <Error> node If an error occurs, an "<Error>" node is created. "<Error>" has the following attributes: Attribute: Name "Code" "Description" Attribute: Value/Purpose The warning code, if available. Descriptive text. Analogous to "<Warning>" : If the error results from a COMOS object, the node "<Error>" will have a subnode "<ComosObject>", which outputs SystemUID, SystemType, SystemFullName, PathFullName, and the object's description. The <Check> node Check columns can be defined in the XML connector (See section "Adapting the Enterprise Server response file (Page 29)"). 52 Operating Manual, 04/2012, A5E03776107-01
Structure of the response file 13.7 The <Stop> node If the Check column of an object processed by the XML connector is not empty, a "<Check>" node is created for this object. Attribute: Name "Description" Attribute: Value/Purpose The value that is input on the object in the Check column. If the XML connector has several Check columns, the values of the Check columns are appended with a semi-colon ( ; ). In addition, for every other column defined in the XML Connector, a "<Column>" subnode is created underneath the "<Check>" node. The function and content of the "<Column>" nodes are explained in the following section. The <Column> node By means of the "<Column>" node you can check if the performed operation for the current object in this column lead to the desired result. The "<Column>" node has the following attributes: Attribute: Name "Name" "MappingInfo" "ComosValue" "XMLValue" Attribute: Value/Purpose Name of the column Value given in the configuration window of the XML connector in the "XML mapping" column in the "Mapping" tab. The current value that is stated in COMOS in the column specified with "Name". The value that was passed in the XML file. As a rule, "ComosValue" and "XMLValue" must be identical. 13.7 The <Stop> node The "<Stop>" node specifies at what date and time the processing of the current action was terminated. It has the following attribute: Attribute: Name "DateTime" Attribute: Value / Purpose Date and time when the action was terminated. The information has the same DateFormat as defined in the "<Start>" node. Operating Manual, 04/2012, A5E03776107-01 53
Structure of the response file 13.7 The <Stop> node 54 Operating Manual, 04/2012, A5E03776107-01
Log files 14 There are three types of log files: Action logs, tracing logs and process logs. Of these, only action logs and tracing logs are of interest for the user. Process logs are used on the software side and, therefore, are not handled in this documentation. They must not be deleted or changed by you. The data of the process logs is displayed via the COMOS Enterprise Monitor. See chapter The COMOS Enterprise Monitor (Page 39). All three types are located in the same log directory. The log directory is specified in the configuration file via the "<LogDirectory>" parameter. 14.1 Action logs All actions of one day are logged in one file. For each started command file, two rows are added to the action log one when the execution is started, one when it ends. In addition, two rows are added to the file for each action of the command file, one upon starting the action, the other upon stopping the action. Each row contains the following information: Date and time Workstation from which the command is issued User: The Service user CommandID of the executed command file ActionID of the action (not applicable in the rows that are generated upon starting and stopping the command file) Status (only on stopping the action or the process): 0 = successful; 1 = failed Path to the command file (that was copied as temporary file to the "TmpConfigFile" ) A new file is created with each date change. The files are deleted at regular intervals, as determined in the configuration file by the "<MaxLogAge>" parameter. An example of an Action log is given in section "Action log (Page 72)". 14.2 Tracing logs All outputs of the, including the MXExec processes, are written to a Tracing log. In the configuration file, with the "<TraceLevel>" parameter, you determine which messages are recorded in the log file. Operating Manual, 04/2012, A5E03776107-01 55
Log files 14.2 Tracing logs A new log file is created for each day. The files are deleted regularly, according to the "<MaxLogAge>" configuration parameter. An example of a Tracing log is given in section "Tracing log (Page 73)". 56 Operating Manual, 04/2012, A5E03776107-01
Response / Error messages 15 Unlike COMOS, the, as a Windows service, cannot process response messages. Therefore, users have to note that the processing of XML connectors in COMOS requires no user interaction. For example, if a message box opens in COMOS, the user must confirm the box by clicking "OK". COMOS cannot continue processing until the user confirms this window. The, however, operates without a user interface. Generally, message boxes are not visible in a service environment. Thus, the user has no option to close the window with a click. Error messages and warnings that come from the COMOS kernel or the queries are redirected to the response file. User-defined messages are not redirected. For this reason, XML connectors in COMOS should not lead to messages that demand a user interaction (response message, hint, error message or similar). Operating Manual, 04/2012, A5E03776107-01 57
Response / Error messages 58 Operating Manual, 04/2012, A5E03776107-01
Participating files 16 "ComosMotionXServerManager.exe" "ComosMotionX.ServerManager.config" ".mxc" "MotionX.sync" "Comos.EnterpriseServer.Process.exe" ".txt Log files ".mxr" "ComosMotionXScheduler.exe" "ComosEnterpriseMonitor.exe" "ComosEnterpriseServerConfigurator.exe" The. A Windows service that monitors the Shared folder, reads incoming command files, and passes the commands to the application specified in the command file for execution purposes (standard application supplied: "Comos.EnterpriseServer.Process.exe"). The configuration file of the. Command files for the. See chapter The command file (Page 21). The processed files are archived. See chapter Window "COMOS Configurator" (Page 75). Is generated by an instance of the s that wants to search the Shared folder for new command files. The command files are subsequently locked and cannot be processed by other server instances. The standard application shipped with COMOS for executing command files. Uses XML connectors. Executes the current import or export of XML files, with regard to the parameters from the configuration file. Generates a response file. Action and tracing log files. Response files of the "Comos.EnterpriseServer.Process.exe". Copies predefined MotionX command files to the Shared folder at specific times. See chapter Configuring the MotionX Scheduler (Page 63). Displays all processes currently running on the active Enterprise Servers. See chapter The COMOS Enterprise Monitor (Page 39). User program for configuration of the. Is called automatically at installation and can be called explicitly by the user as needed afterwards. See chapter Window "COMOS Configurator" (Page 75). "ComosEnterpriseServerServiceInstaller.ex e" User program to generate and configure the Service Program. Is called automatically at installation and can be called explicitly by the user as needed afterwards. See chapter Window "COMOS Service Installer" (Page 78). Operating Manual, 04/2012, A5E03776107-01 59
Participating files 60 Operating Manual, 04/2012, A5E03776107-01
Other 17 17.1 Synchronizing the Shared folder The content of this section is not relevant for the normal operation of the, but instead applies to technical inspection or customizing. It is intended for users who are responsible for these tasks. The access to new command files in the Shared folder can only be carried out by means of a server. Otherwise several servers might possibly process one and the same file. To prevent this, there is the "MontionX.sync" file. This file is created by the first started server that accesses the Shared folder. The file is created with a size of 100 bytes. If a server wants to access the Shared folder to search for command files, it will first lock the "MotionX.sync" file and write its machine name to the file. When the action is terminated, it will fill the 100 bytes with zeroes, and remove the lock. This means that: command files can still be saved in the Shared folder. But as long as the "MotionX.sync" file is locked, the new command files cannot be processed. The current command file alone can be evaluated. This covers the following two cases: Case 1: Several instances access the Shared folder via the network. Case 2: Depending on the configuration, the process "Comos.EnterpriseServer.Process.exe" can be started multiple times on a PC. In this case, a second "Comos.EnterpriseServer.Process.exe" process can already process the next command file before the first "Comos.EnterpriseServer.Process.exe" process has written its response file. In this case, the procedure is: "Comos.EnterpriseServer.Process.exe" process 1 finds a command file "Comos.EnterpriseServer.Process.exe" process 1 blocks "MotionX.sync" "Comos.EnterpriseServer.Process.exe" process 1 evaluates the command file Another command file appears in the meantime "Comos.EnterpriseServer.Process.exe"process 1 deletes the command file it has processed and enables "MotionX.sync"; however, processing is not completed yet, which means no response file "Comos.EnterpriseServer.Process.exe" process 2 processes the next command file and also blocks "MotionX.sync". Process 1 and process 2 process the command files in parallel. Since synchronized access of many servers to the Shared folder occurs only very rarely, there is a special integrated test mode for this procedure. When a server finds a command file with the content <Test><Action ID="TestCriticalSection"><Time> 20 <\...> Operating Manual, 04/2012, A5E03776107-01 61
Other 17.2 Technical procedure it will pause for 20 seconds in the CriticalSection and thus refuses access to all servers during this period. Procedure for testing: Start at least two servers. Copy TestCriticalSection.mxc to the Shared folder. One of the servers will lock MotionX.sync and an appropriate message is issued in the Tracing log file. For the other servers, you will see the following entry in the Tracing log file: "Try to Enter CriticalSection." There are no more outputs until 20 seconds have passed on the first server. The next output is: "CritialSection Entered". 17.2 Technical procedure The technical procedure for the standard application and standard adapter is as follows: Executable XML connectors must be prepared in COMOS. The XML connectors are always searched for on the "Documents" tab below the node "@System > @MXC". 1. Start the (= Windows service). On startup, the configuration file is evaluated and an entry is written to the Tracing log (Service user, computer name, drives, etc.). In the shared folder the administration file "MotionX.sync" is created. 2. The monitors the Shared folder (compare section "Synchronizing the Shared folder (Page 61)"). If a command file is found there, the following steps are executed: 2.1 The evaluates the "ComosMotionXServerManager.config" file. 2.2 The command file is copied to the Temp folder and to the History folder. 2.3 The command file is deleted and the Shared folder is released again. 2.4 The command file copied to the Temp folder is evaluated. If it is valid, it is passed to the application specified in the command file (currently: the "Comos.EnterpriseServer.Process.exe"). 3. The "Comos.EnterpriseServer.Process.exe" executes the commands in the command file. For this purpose, an instance of COMOS is started in the background and the adapter specified in the command file (currently: XML connector) is called. 4. Finally, the "Comos.EnterpriseServer.Process.exe" creates a response file in the temp directory. The moves the response file to the Shared folder. 62 Operating Manual, 04/2012, A5E03776107-01
Other 17.3 The MotionX Scheduler 17.3 The MotionX Scheduler Overview The task of the MotionX Scheduler is to copy predefined MotionX command files to the Shared folder at specific times. Both the copy process itself and any errors which arise during it are logged. 17.3.1 Configuring the MotionX Scheduler Requirement The application for the MotionX Scheduler is located in the COMOS Bin directory parallel to other MotionX components. Procedure 1. Define a directory as the MotionX Scheduler folder, in which all planned command files are to be stored. 2. Enter the path to the Scheduler folder in the "ComosMotionXServerManager.config" file. 3. Schedule a task using the standard Windows Scheduler. Create a task. The bat file of the task includes the call of the MotionX Scheduler application with the corresponding parameters. Separate the parameters with a space. The MotionX Scheduler has the following parameters: Name of the command file As complete path or relative to the Scheduler folder Name of the target folder below the Shared folder If the Shared folder is addressed directly, enter a point. Result The MotionX Scheduler copies the MotionX command files to the corresponding folder under Shared folder. The following scenarios may occur: The copied file is still in the Shared folder and has not been processed yet. In this case, the Scheduler writes a corresponding message into the log file of the. The target folder or command file is not existent. An appropriate message is written to the log file. Denial of rights. An appropriate message is written to the log file. Other errors. An appropriate message is written to the log file. Operating Manual, 04/2012, A5E03776107-01 63
Other 17.4 Freely definable DLLs See also Example (Page 64) 17.3.2 Example Procedure 1. Create the directory C:\EnterpriseServer\Scheduler in which all scheduled command files are saved. 2. Open the configuration file. See chapter Configuration file (Page 69). 3. Enter the following node in the configuration file. <SchedulerFolder>C:\EnterpriseServer\Scheduler</SchedulerFolder> 4. Enter a task for the MotionX Scheduler in the Microsoft Windows Scheduled Task Wizard. Select the file ComosMotionXScheduler.exe from the COMOS Bin directory. 5. In the final step, open the extended properties of the task in the Microsoft Windows Scheduled Task Wizard. 6. Enter the parameters on the "Task" tab in the "Run" field. To copy a file from the Scheduler folder to the Shared folder: C:\Comos\BIN\ComosMotionXScheduler.exe <Name command file>. To copy a file from a separate directory to a subdirectory of the Shared folder: C:\Comos\BIN\ComosMotionXScheduler.exe <Absolute path to the command file> <Subdirectory of the Shared folder> 7. Save the task. 17.4 Freely definable DLLs 17.4.1 Customizing the command file for C# assembly Procedure 1. Increase the version number in the command file to "3". 2. Replace the relevant node Function with the following node: <Assembly Location="C:\...dll" AssemblyName=" " ClassName=" " > <Parameters. > </Assembly> 64 Operating Manual, 04/2012, A5E03776107-01
Other 17.4 Freely definable DLLs 3. To load a C# assembly, enter the file name, assembly name and class name. Entering the ProgID is not sufficient. 4. Implement the ICustomAction interface in your assembly. See also chapter Implementation interface (Page 65). Result The reads the version number and gives access to the new functions if required. VB-DLL You also have the opportunity to start VB-DLLs using Version 2 and function nodes. See also chapter Structure and configuration of the command file (Page 22). 17.4.2 Implementation interface The requires two interfaces to implement freely definable DLLs. All required interfaces and enumerations are defined in the Comos.EnterpriseServer.GlobalContracts.dll. You set the DLL as a reference so that you can subsequently create your own DLL. Interface ICustomAction The interface ICustomAction is implemented by you and has a predefined method to start the components. public interface ICustomAction { public short Execute(ref IActionEnvironment environment); } Return parameter (Execute) In this parameter, the successful call of the is reported. Value Description 0 Error-free call 1 Errors occurred during the call or the call could not be implemented. The value defines how the command file sets the status of the action. Operating Manual, 04/2012, A5E03776107-01 65
Other 17.4 Freely definable DLLs Interfaces IActionEnvironment and IESUtilities These interfaces must not be implemented because, if they are, compatibility cannot be guaranteed. They supply all required parameters and are the only parameter that is passed on to the start methods. public interface IActionEnvironment { public Plt.IComosDWorkset Workset { get; } public string ParametersNode { get; } public IESUtilities ESToolKit { get; } } Logging Freely definable DLLs possess the same logging options as an XML connector. See also Customizing the command file for C# assembly (Page 64) 17.4.3 Logging Overview The interface "IESUtilities" provides the logging capabilities of the to all components which are automated via the. public interface IESUtilities { ESTraceLevel Level { get; } void WriteProtocol(ESTraceLevel level, Plt.IComosBaseObject comosobject, string description); void TraceMessage(ESTraceLevel level, string message); void WriteMonitorInfo(string message); } 66 Operating Manual, 04/2012, A5E03776107-01
Other 17.4 Freely definable DLLs Explanations Parameter TraceLevel WriteProtocol TraceMessage WriteMonitorInfo Description Reflects the TraceLevel from the server configuration Writes a message to the result report. Only the values "Error" and "Warning" are permitted here as TraceLevel. The method creates an XML node with the predefinded scheme: <Error Warning Code="" Description=""> <ComosObject SystemUID="" SystemType="" SystemFullName="" PathFullName="" Description="" /> </Error Warning> Writes a message to the file MotionX-Trace.log For the TraceLevel, all four values are allowed. You can define the text yourself. The structure of the message corresponds to the already known scheme. Example: 2011-03-30 09:09:03.037 [1] DEBUG MXExec.MXC - MXLogger loaded: True Writes a message related to the current process into the process log. This message becomes visible in the Enterprise Monitor under the heading "LastMessage". TraceLevel The TraceLevel is managed in an enumeration: public enum ESTraceLevel { Debug = 0, Information = 1, Warning = 2, Error= 3 } This enumeration is defined in "Comos.GlobalContracts". Operating Manual, 04/2012, A5E03776107-01 67
Other 17.4 Freely definable DLLs 68 Operating Manual, 04/2012, A5E03776107-01
Example files 18 18.1 Configuration file An example of a configuration file is provided in the following: <?xml version="1.0" encoding="utf-8"?> <Config> <MotionXServer> <HistoryFolder>C:\EnterpriseServer\LogFiles\History</HistoryFolder> <LogDirectory>C:\EnterpriseServer\LogFiles</LogDirectory> <InterfaceEXE>C:\Comos\Bin\Comos.EnterpriseServer.Process.exe</Inter faceexe> <SharedFolder>C:\EnterpriseServer\SharedFolder</SharedFolder> <TmpConfigFileFolder>C:\EnterpriseServer\TempFiles</TmpConfigFileFol der> <SchedulerFolder>C:\EnterpriseServer\Scheduler</SchedulerFolder> <MaxInterfaceProcessCount>1</MaxInterfaceProcessCount> <MaxLogAge>30</MaxLogAge> <MaxNumberTrials>3</MaxNumberTrials> <MonitoringTime>5000</MonitoringTime> <TraceLevel>Warning</TraceLevel> > <DriveMappings> <!--DriveMapping LocalName="Z:" RemoteName="\\Server1\Data"\-- <DriveMapping LocalName="Z:" RemoteName="\\Cs01\PUBLIC"\> <DriveMapping LocalName="M:" RemoteName="\\Cs11\SQL_Doc"\> </DriveMappings> </MotionXServer> </Config> See also Configuration (Page 21) Window "COMOS Configurator" (Page 75) Operating Manual, 04/2012, A5E03776107-01 69
Example files 18.2 Command file 18.2 Command file Export command file An example of an export command file is provided below: <MXExec Version="2" CommandID="MX01" Description="Funct. Loc to SAP" MaxRuntime="120"> <!-- Version must have the value 2. MaxRuntime in minute--> <Settings> <uniquecommandid>true</uniquecommandid> </Settings> <Action ActionID="Exp001" Description="Export Funct. Loc to SAP"> <Connection ConnectionString="D:\2008\SAP training\sap_db_100408\standarddb.mdb" Project="SO1" WorkingOverlay=""/> <Function Class="Comos.XMLAdapter.Adapter" Name="Export"> <Parameters> <Parameter Name="XMLFile" Value="C:\Comos-SAP\Comos_Sap_0000_SAP_Response.xml"/> <Parameter Name="XMLConnector" Value="XQC4 XQC.1"/> <Parameter Name="RootNode" Value="08U9" ParamType="PathFullName"/> <!-- for Export --> <Parameter Name="ShowFile" Value="False"/> <Parameter Name="VersionsAdministration" Value="False"/> <Parameter Name="Filter"> <Item QueryName="Q1" ColumnName="Name" Value="P002" /> <Item QueryName ="Q2" ColumName ="Description" Value ="Valves"/> </Parameter> </Parameters> </Function> </Action> </MXExec> Import command file An example of an import command file is provided below: <MXExec Version="2" CommandID="MXC01" Description="for QS test" MaxRuntime="120"> <!- - Version must have the value 2 MaxRuntime in minute--> <Settings> <uniquecommandid>true</uniquecommandid> </Settings> 70 Operating Manual, 04/2012, A5E03776107-01
Example files 18.2 Command file <Action ActionID="Act01" Description="Import 1"> <Connection ConnectionString="D:\2008\SAP training\sap_db_100408\comosdb.mdb" Project="SO1" WorkingOverlay=""/> <Function Class="Comos.XMLAdapter.Adapter" Name="Import"> <Parameters> <Parameter Name="XMLFile" Value="C:\Comos-SAP\Comos_Sap_0000_SAP_Response.xml"/> <Parameter Name="XMLConnector" Value="XQC4 XQC.1"/> <Parameter Name="RootNode" Value="08U9" ParamType="PathFullName"/> <Parameter Name="XMLFileMoveTo" Value=""/> <!-- for Export --> <Parameter Name="DeleteObjects" Value="False"/> <Parameter Name="CreateWorkingOverlay" Value="True"/> <Parameter Name="VersionsAdministration" Value="False"/> <Parameter Name="DifferenceOnly" Value="False"/> <Parameter Name="SaveMode" Value="0"/> <Parameter Name="Filter"> <Item QueryName="Valves" ColumnName="Object" Value="S001" /> <Item QueryName="Q2" ColumnName="Unit" Value="XYZ" /> </Parameter> </Parameters> </Function> </Action> </MXExec> Operating Manual, 04/2012, A5E03776107-01 71
Example files 18.3 Response file 18.3 Response file Here is an example of a response file: 18.4 Action log Here is an extract of an Action log file: 72 Operating Manual, 04/2012, A5E03776107-01
Example files 18.5 Tracing log 18.5 Tracing log Here is an example of a Tracing log file: Operating Manual, 04/2012, A5E03776107-01 73
Example files 18.5 Tracing log 74 Operating Manual, 04/2012, A5E03776107-01