COMOS. Platform COMOS Enterprise Server. Task of the COMOS Enterprise Server 1. Service-oriented architecture 2

Transcription

1 COMOS Platform Operating Manual Task of the COMOS Enterprise Server 1 Service-oriented architecture 2 Prerequisites 3 Installing the COMOS Enterprise Server 4 Removing the COMOS Enterprise Server 5 Assigning Windows rights 6 Capacity 7 Administration 8 Using the COMOS Enterprise Monitor 9 Document revision 10 Editing working layers 11 Structure of the response file 12 Log files 13 Response / Error messages 14 Participating files 15 Other 16 Example files 17 User interface reference 18 09/2014 A5E AC

2 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 indicates that minor personal injury can result if proper precautions are not taken. NOTICE indicates that property damage can result if proper precautions are not taken. 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: Trademarks 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. 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 AC P 08/2014 Subject to change Copyright Siemens AG All rights reserved

3 Table of contents 1 Task of the Service-oriented architecture Prerequisites Installing the Removing the Assigning Windows rights Capacity Processes Administration Configuration command file command files Structure and configuration of the command file MotionXFixCommand file External filtering Adapting the response file Structure of the response file Adapting the response output through XML connectors User management User folder Creating a service user / default user Administration of the Shared folder Caller of the command file Monitoring the Shared folder Setting up the for print jobs Aim Installing a new printer Setting the printer port of the Configuring the printer Storing authorized users Using the printer Using the COMOS Enterprise Monitor Document revision Command file for performing revisions on the Editing working layers Requirements for releasing and deleting working layers...45 Operating Manual, 09/2014, A5E AC 3

4 Table of contents 11.2 Customizing the command file Canceling the process Structure of the response file Overview of the structure of the response file <MXEResult> node <Protocol> node <Status> node <Start> node The <Action> node and its subnodes <Stop> node Log files Action logs Tracing logs Response / Error messages Participating files Other Synchronizing the Shared folder Technical procedure MotionX Scheduler Configuring the MotionX Scheduler Example of the MotionX Scheduler configuration Freely definable DLLs Customizing the command file for C# assembly Implementation interface Logging Example files Example of configuration file Example of a command file Example of a response file Example of an action log Example of a tracing log User interface reference Window " Configurator" Window " Service Installer" Operating Manual, 09/2014, A5E AC

5 Task of the 1 Overview The is a Windows service which exchanges data with COMOS without the COMOS user interface. COMOS functions are made available to other systems via a LAN. The is 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 COMOS Enterprise Server Jobs You can define own jobs. These jobs are available to external users via the COMOS Enterprise Server. You can initiate these jobs outside of COMOS via the Intranet or Internet. Configuration You configure the yourself, thus controlling, for example the operation mode of the and make working directories known to the. Command files You can transfer command files that the executes to the COMOS Enterprise Server. A command files specifies, among others, the following: Which XML file is processed. Which adapter processes the XML file (default adapter: XML Connector). Which method is executed for the file, for example import or export. See also section Technical procedure (Page 64) Operating Manual, 09/2014, A5E AC 5

6 Task of the Programming You can program and use a custom application and adapter. See also Service-oriented architecture (Page 7) Prerequisites (Page 9) 6 Operating Manual, 09/2014, A5E AC

7 Service-oriented architecture 2 Overview With the, you implement a service-oriented architecture into the engineering application. Various functions are made available in the form of services. You access these functions from other systems via the. Functions You can use the various functionalities to implement service-based 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 Different techniques for releasing adapter functions Security Access check and user authentication Monitoring Status monitoring of the processing progress See also Task of the (Page 5) Prerequisites (Page 9) Operating Manual, 09/2014, A5E AC 7

8 Service-oriented architecture 8 Operating Manual, 09/2014, A5E AC

9 Prerequisites 3 The following requirements must be met in order to use the : The is supplied together with COMOS. A valid license is available for the. As of COMOS 9.0, Windows Framework 3.5 SP1 or higher is installed. Operating Manual, 09/2014, A5E AC 9

10 Prerequisites 10 Operating Manual, 09/2014, A5E AC

11 Installing the 4 Introduction You can install the using a setup program. The setup has the following components: Program for configuration: Configurator Program for service installation: Service Installer These programs accept data and instructions from you. The programs for configuration and service installation are launched during the setup on the one hand. On the other hand, you can also launch these program later and change parameters. See also sections Configuration (Page 21) and Creating a service user / default user (Page 32). Requirement COMOS is installed. You can find additional information on this topic in the "Readme", keyword "Installing COMOS and additional software". If the setup program does not find a COMOS installation, an error message is displayed and the setup is canceled. Procedure 1. Insert the COMOS CD. The CD browser will launch automatically. 2. Click the "Main Products" button. 3. Click on the "" button. 4. Run the setup. Note Windows 7 If you are using Windows 7, start the installation of the Enterprise Server as an administrator. The " - InstallShield Wizard" window opens. 5. Follow the instructions in the window. 6. Do not select the COMOS directory as the target folder for the installation. The " Configurator" and " Service Installer" programs are installed in the selected destination folder. These programs are independent of the regular COMOS application. The " Configurator" window opens. Operating Manual, 09/2014, A5E AC 11

12 Installing the 7. Specify the desired settings in the " Configurator" window. See also section Window " Configurator" (Page 77). If a configuration file for the already exists, the file is read and the data applied. 8. Click the "OK" button. The entries are checked and stored in the configuration file. The " Configurator" window closes. The " Service Installer" window opens. 9. Specify the desired settings in the " Service Installer" window. See also section Window " Service Installer" (Page 80). 10.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 works. Since the runs as a server, you have to specify the user that the uses. The user must have administrator rights both in COMOS and on the local PC. See also section Creating a service user / default user (Page 32). 11.Click the "OK" button. The " Service Installer" window closes. 12.To check the data you have entered and to install the service, click "Finish" in the "COMOS Enterprise Server - 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 installed, the ComosMotionXServerManager will appear in the list of services under "Control Panel > Management > Services". An installation directory is created. The " Configurator" and " Service Installer" programs are copied in the installation directory for future use. See also Removing the (Page 13) Assigning Windows rights (Page 15) 12 Operating Manual, 09/2014, A5E AC

13 Removing the 5 Procedure 1. Open the Control Panel. 2. Select the command "Add or Remove Programs > Change or Remove Programs". 3. Remove the. Result The is removed. The installation directory and its subfolders remain. See also Installing the (Page 11) Operating Manual, 09/2014, A5E AC 13

14 Removing the 14 Operating Manual, 09/2014, A5E AC

15 Assigning Windows rights 6 Release of folders for the network The executes file operations within the context of the domain user. In order to edit the response files generated by the, users the "Change" permission 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. Assigning access rights for global groups 1. Activate the "Change" permission. 2. Click the "Extended" button. 3. Activate the option for spreading inheritable permissions. 4. Save and confirm the settings. Permission in the file system of the The "Change" permission needs to be assigned in the file system of the COMOS Enterprise Server. This permission includes the following rights: Permissions Full access Change Read, execute List folder content Read Write Special permissions Enable Deactivated Activated Activated Activated Activated Activated Activated The "Special permissions" contains the following rights: Searching through a folder Listing folders / reading data Reading attributes Reading extended attributes Operating Manual, 09/2014, A5E AC 15

16 Assigning Windows rights Creating files, writing data Creating folders, attaching files This includes the inheritance in the file system of the : "This folder, subfolder, files". Extended security The allows each user to have one subfolder for saving processing tasks. The interprets the folder name as a COMOS user name and executes the tasks in the name of the user in the COMOS database. Limit the access rights for a folder to the authorized user so that only the authorized user can store processing tasks in this folder. The user requires the rights listed under "Authorization in the file system of the ". Interrupt the inheritance chain from the higher-level folder so that other users do not have access to the folder through group memberships. You can find this option via the "Extended" button in the folder security. See also Administration (Page 21) 16 Operating Manual, 09/2014, A5E AC

17 Capacity 7 Integration Import and export of external data The integration platform of the 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 are then automatically triggered via the. You can find additional information on this topic in the "COMOS Platform Interfaces" manual, keyword "Configuring a SAP interface". Workflow You can define and execute workflows in COMOS. You can also integrate other applications. You can find additional information on this topic in the "COMOS Platform Administration" manual, keyword "Engineering data: Administering or automating workflows". 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 performed: Workflows with an expired timer continue to run. Active workflows where no mandatory attribute has been set are terminated. Operating Manual, 09/2014, A5E AC 17

18 Capacity 7.1 Processes Command files for running expired workflows. 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\NewDB.mdb" Project="SO1" WorkingOverlay=""/> <Function Class="Comos.Workflow.ComosWorkflowEnterpriseService" Name="MaintainWorkflows"> <Parameters /> </Function> </Action> </MXExec> In this command file a project SO1 is specified because an entry is required. This entry has no influence on the behavior of the. The COMOS Enterprise Service runs 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 required data. Trigger the COMOS functionality for database synchronization via the COMOS Enterprise Server. Distributed databases are consolidated and compacted. This ensures that the same data is available to all users. You can find additional information on this topic in the "COMOS Platform Administration" manual, keyword "Database synchronization". 7.1 Processes Sequence As soon as the task is received by the and started, COMOS triggers the process under the user account that started the task. The parameters from the command file are taken into account during this process. Once the command file has been executed, a response file is created. The status message indicating whether or not the task has been completed successfully is saved in the response file. See also section Structure of the response file (Page 51). Logging Debug, info, warning and error messages are stored in the tracing log. See also section Tracing logs (Page 58). 18 Operating Manual, 09/2014, A5E AC

19 Capacity 7.1 Processes Status and progress The current status and progress are shown in the Monitor. If the process no longer responds, you can cancel this process by using the COMOS Enterprise Monitor. See also section Using the COMOS Enterprise Monitor (Page 39). Operating Manual, 09/2014, A5E AC 19

20 Capacity 7.1 Processes 20 Operating Manual, 09/2014, A5E AC

21 Administration Configuration The is configured by the " Configurator" program during installation. See also section Installing the (Page 11). You can change the configuration later as you like. Start the program again. You apply the configuration from the installation directory. See also section Window " Configurator" (Page 77). The configuration data is saved in the file "ComosMotionXServerManager.config". The configuration file is available in the "config" directory. See also Example of configuration file (Page 71) command file (Page 21) 8.2 command file Command files are files that instruct the about the commands to execute. Command files have the file extension "*.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 33). One process is started for each command file. The process runs until the command file has been fully executed or the maximum runtime has been reached. If you use the uniquecommandid, a command file is 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 made in the "Log.txt" file. This entry specifies the command file that should be prevented from execution. 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. See also section Example of a command file (Page 72). Operating Manual, 09/2014, A5E AC 21

22 Administration 8.2 command file command files MXC file The "MXExec.exe" file was replaced with the "Comos.EnterpriseServer.Process.exe" file to use the new functions of the. You can still use all old MXC files. See also Structure and configuration of the command file (Page 22) 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="..." 22 Operating Manual, 09/2014, A5E AC

23 Administration 8.2 command file Name="..." > <Parameters> <!-- List with command parameters --> </Function> </Action> <Action <! > </Action> </MXExec> <MXExec> node The <MXExec> node has the following attributes: Attribute: Name Version CommandID Description MaxRuntime Attribute: Value / Purpose Version number of the MotionX command structure Mandatory attribute 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 are forced to terminate after a certain time. Optional <Settings> node The uniquecommandid specified is used to prevent a command file from triggering a process again before it has completed. The command file is deleted. A results file containing a relevant note is created. If execution of a command file is prevented, the "Prevented" entry is written to the "Log.txt" file. The permitted values are "True" and "False". <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 the following subnodes in which the details of the action are defined: Nodes of the type <Connection> Nodes of the type <Function> The following applies to actions: Operating Manual, 09/2014, A5E AC 23

24 Administration 8.2 command file 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 exports the filtered valves. Each <Action> type node has the following attributes: Attribute: Name ActionID Description Attribute: Value / Purpose ID of the action Mandatory attribute Descriptive text for the action, for administrative purposes Optional <Connection> node Each <Action> type node has exactly one <Connection> type node. The <Connection> node contains information about the following objects that are used: Database Project Working layer This data is required to start a COMOS instance in the background and to execute the action. 24 Operating Manual, 09/2014, A5E AC

25 Administration 8.2 command file The <Connection> node has the following attributes: Attribute: Name ConnectionString Project Working-Overlay Attribute: Value / Purpose Path to the database instance If mapped drives are used: refer to the information on the <DriveMappings> parameter from the configuration file. See also section Window " Configurator" (Page 77). Examples for the three possible database types: SQL database: "[SQL - SERVER]pt_sql_server" Access database: "D:\ComosDatabases\Example \NewDB.mdb" Oracle database: "[ORACLE]pt_oracle" Mandatory attribute Name of the project Mandatory attribute Name of the working layer The names of nested working layers are given in full, with " " ("pipe") used as a separator Example: Project1 Subproject1 Mandatory attribute <Function> node Each <Action> type node has exactly one function node. The function node stipulates which method is to be executed. The Function mode has the following parameters: Attribute: Name Class Name Attribute: Value / Purpose ProgID of the components, the methods of which are to be executed (adapter that processes the XML file) Standard adapter supplied with COMOS: "Comos.XMLAdapter.Adapter" (adapter for XML connectors) If you want to trigger your own component via the, enter the ProgID of the class to be instanced by the. Mandatory attribute The name of the method that is called from the component specified in the "Class" attribute. The standard adapter for XML connectors has two public methods: Import Export Mandatory attribute <Parameters> node / function parameters On calling a function, parameters are passed to the function. Which parameters are passed depends on the function called. Operating Manual, 09/2014, A5E AC 25

26 Administration 8.2 command file The parameters are bundled in the <Parameter> node. Each parameter is encapsulated in a <Parameters> type node. Each parameter has two mandatory attributes: Attribute for the parameter name Attribute 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: Attribute: Name XMLFile XMLConnector Attribute: Value / Purpose Absolute or relative path to the XML file: The path is specified in the base project in the following standard table: "Y10 > M02 > A10 > Y10M02N00003 XML connector types" Absolute path: "C:\ComosImportExport\XMLDocs\ExportTest.xml" Relative path: The specification is relative to the command file located in a user folder or in the Shared folder Example: "XMLDoc\ExportTest.xml" The "ExportTest.xml" file is located in the "XMLDoc" folder parallel to the command file. Mandatory parameter Path to the XML connector in the open project or working layer. The path is specified relative to the "Documents" tab, in the following node: "@30 > M02 > A90 > A10 Enterprise Server XML connectors" You can use the additional ParamType parameter to specify whether the path is given as "SystemFullName" or "PathFullName". If ParamType has the value "SystemUID", the attribute ObjectSystemType is evaluated. The attribute contains the system type of the start object. The system type is output in two variants: SystemType / Number SystemTypeName / String Example: "<Parameter Name="XMLConnector" Value="Interface1 2" ParamType="SystemFullName" />" The XML connector sought is located in the "Documents" tab at the following position: "@MXC > Interface1 > 2" 26 Operating Manual, 09/2014, A5E AC

27 Administration 8.2 command file Attribute: Name RootNode XMLFileMoveTo Attribute: Value / Purpose Path to the start object that is used by the XML connector Similar to XMLConnector, specify in ParamType whether the path is given as SystemFull Name 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 is always stored in the properties of the XML Connector. Path specification 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 you do not want to move the XML file, delete the entry or comment it out. Both absolute paths and paths relative to the SharedFolder are allowed. The path may not contain a file name. Examples: Absolute path: "C:\Enterprise Server\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 "COMOS Automation Interfaces" manual, keyword "Triggering connectors via a script". Attribute: Name DeleteObjects Versions- Administration DifferenceOnly SaveMode Attribute: Value / Purpose Specifies whether the "Delete objects" option is activated. If the "Delete objects" option is activated, all objects that are not in the XML file are deleted. Value: "True" or "False" Default value: "False" Note: The parameter DeleteObjects with the value "True" is only evaluated if the query has the appropriate rights. Otherwise, the user will receive unexpected results. Specifies whether the option "Include in version management" is activated. If the option "Include in version management" is activated, the imported file is saved in COMOS and is issued with a version number. Value: "True" or "False" Default value: "False" Specifies whether the option "Consider different objects only" is activated. If the option "Consider different objects only" is activated, the new XML file is compared with the XML file already stored in COMOS during reimporting. Only differing data is processed. Value: "True" or "False" Default value: "False" The activated option "Consider different objects only" is only evaluated if the "DifferenceOnly" parameter has the value "True". Specifies whether all the data changes are stored in COMOS at the end of the operation. If an error occurs, no object is imported. Value: "0" (= False) or "1" (= True) Default value: "False" Operating Manual, 09/2014, A5E AC 27

28 Administration 8.2 command file 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 "COMOS Automation Interfaces" manual, keyword "Triggering connectors via a script". Attribute: Name ShowFile VersionsAdministration Filter Attribute: Value / Purpose Specifies whether the exported XML file is displayed in the Internet Explorer directly after the export. This setting is not optimal for server operation and can therefore be deactivated. Value: "True" or "False" Default value: "False" Analogous to the import function Filter for queries of the XML Connector You can modify the configuration of the XML connector from outside COMOS without a user interface. See also section External filtering (Page 29). Optional parameter Information about the "ParamType" parameter of the "XMLConnector" and "RootNode" attributes The "SystemFullName" is not automatically unique. If you want to use the "SystemFullName", ensure that the "SystemFullName" is unique. The "PathFullName" is always unique. Determine the "PathFullName" using the COMOS object debugger. Open the object debugger from the "Extra > Object Debugger" menu bar. You can find additional information on this topic in the "Class Documentation COMOS_dll" manual, keyword "SystemFullName" and "PathFullName". See also MotionXFixCommand file (Page 28) MotionXFixCommand file Data import via the The MotionXFixCommand file imports data via the. You do not have to adapt external systems in order to generate a command file. The MotionXFixCommand file (MXFC file) looks like a MotionX command file of the COMOS Enterprise Server. You define the file in the Shared folder or in one of its subdirectories. The 28 Operating Manual, 09/2014, A5E AC

29 Administration 8.2 command file defined information is contained in the "XMLFile" parameters of the relevant action blocks of the MXFC file. If one of the sought files is found in the Shared folder, it is 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 was specified in the "XMLFileMoveTo" parameter of the action block, the imported file is moved. If there is no entry in the "XMLFileMoveTo" parameter, the imported file in the "Temp" folder is deleted. The ComosMotionXServerManager starts a new MXExec process with the generated 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 stored parallel to the MXFC file in the same directory. The MXC file is moved from the "Temp" directors into the "History" folder. Overview Fixed command files end with "mxfc". The files are copied to the Shared folder and are not deleted or moved after execution. MXFC files apply only to import. The path of the import file is specified relative to the folder containing the MXFC file. The in the MXC file supported function types are also supported in the MXFC file. See also External filtering (Page 29) External filtering You can filter the queries of the XML connector addressed by the command file from an external location without opening the COMOS user interface. Filters can be defined in the command file for this purpose, these are 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: Attribute: Name QueryName ColumnName Value Attribute: Value / Purpose Name of the query that is filtered Mandatory attribute Name of the column that is filtered Mandatory attribute The value that is filtered Mandatory attribute Operating Manual, 09/2014, A5E AC 29

30 Administration 8.3 Adapting the response file All filters that were defined within an "<Action>" node are linked through an AND operator. The other operators that you can use 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> 8.3 Adapting the response file Structure of the response file The generates the response file after a command file was processed. A response file has the file extension "*.mxr". The response file has the same name as its command file. The response file is stored in the same directory in which the command file was located. The response file logs the results, errors or warnings that arise during the processing of the command file. The response file can be processed by an external application. The response file is used to check whether the execution of the command file has led to the expected results. This is important for import operations. In some cases, the external application requires more detailed information for the analysis than the automatically generated entries in the response file. Therefore, the user can define Check columns for the XML connector. If the Check column of an object processed by the XML Connector contains a value, the following information is additionally included in the response file: The value entered at the object in the Check column The values of the remaining columns of the object query with the following required management information: Column name Mapping information Value in COMOS XML value With the help of these values, the external application can verify whether the correct values were assigned to the objects created in COMOS during the import operation, for example. See also sections Structure of the response file (Page 51) and Action logs (Page 57). 30 Operating Manual, 09/2014, A5E AC

31 Administration 8.3 Adapting the response file See also Example of an action log (Page 75) Adapting the response output through XML connectors (Page 31) Adapting the response output through XML connectors Procedure 1. Start COMOS. 2. Navigate to the XML Connector that was addressed by your command file. 3. Select the "XML > Configure XML connector" command in the context menu for the XML connector. The configuration tool opens. 4. Assign the "Check column" property to an existing column. 5. Alternatively, you can create a new column and assign the "Check column" property to this column. Select the "Mapping" tab. A table is displayed in which each row corresponds to a column of the selected query. Activate the "Check column" option for the desired column. You can determine the value that is entered in the Check column when the XML Connector is opened as follows: Through a value calculation Through a script calculation Result When generating the response file, each processed object is checked to determine if a value is entered at the object in the Check column. If a value is entered, 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. Operating Manual, 09/2014, A5E AC 31

32 Administration 8.4 User management See also section The <Action> node and its subnodes (Page 54). You can find additional information on this topic in the "COMOS Platform Administration" manual, keyword "Configuring XML Connectors". See also Structure of the response file (Page 51) 8.4 User management You manage users in the Shared Folder directory. See also User folder (Page 32) User folder Folder-based user management 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 of the user in COMOS. Each user may only issue a command to the through his or her folder. For example, User 1 may not access the folder of User 2. You manage the access rights to the subfolders externally through the operating system management. Ensure the following: The users only have rights for their own folders. The users do not have write access to the Shared Folder directory. See also Creating a service user / default user (Page 32) Creating a service user / default user Introduction The default user is the service user. The Service is logged on at the service user. 32 Operating Manual, 09/2014, A5E AC

33 Administration 8.5 Administration of the Shared folder The default user has to have administrator rights for the following: To start a process To create, process or delete a folder 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 user name other than the service user. In addition, a folder can be created for the default user in the Shared folder: "Default" or "Default user" Procedure 1. Create the service user during the installation via the " Service Installer" program. See also section Installing the (Page 11). 2. To change the service user or his password later, start the " Service Installer" program in the installation directory of the. See also section Window " Service Installer" (Page 80). See also Administration of the Shared folder (Page 33) 8.5 Administration of the Shared folder You manage the following in the Shared folder: Command files "*.mxc" and response files "*.mxr" Each response file is located parallel to its command file. Users You can freely choose the name for the Shared folder. We use the name "Shared folder" in this documentation because every COMOS Enterprise Server and every user who issues a command to the can access this folder and its subfolders. The access of the service user is made directly via the Shared folder: other users access via the subfolders of the Shared folder. See also Caller of the command file (Page 34) Monitoring the Shared folder (Page 34) Operating Manual, 09/2014, A5E AC 33

34 Administration 8.6 Setting up the for print jobs 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", 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 COMOS Enterprise Server. However, this is only possible if the Service user is a COMOS administrator. Information on the user issuing a command to the is recorded in the log files and is also included in COMOS (timestamp, rights administration). The name of the subfolder from which the command file was taken is used to identify the COMOS user. See also Creating a service user / default user (Page 32) Monitoring the Shared folder (Page 34) Monitoring the Shared folder A recursive search is made in the Shared folder for command files "*.mxc" at regular intervals as specified in the "MonitoringTime" parameter of the configuration file. 8.6 Setting up the for print jobs Aim You set up the for print jobs so that the print jobs of your employees can be transferred to the. When you set up the for print jobs, the work load of the local computers is reduced. The respective document is opened, evaluated and sent to the printer on the. See also Installing a new printer (Page 35) 34 Operating Manual, 09/2014, A5E AC

35 Administration 8.6 Setting up the for print jobs Installing a new printer Procedure 1. To add a new printer to the Windows system, open the printer installation wizard. 2. Click "Next". The "Local printer or network" window opens. 3. Activate the "Local printer attached to this computer" option. 4. Disable the option "Automatically detect and install my Plug and Play printer" and click "Next". The "Select printer port" window opens. 5. Accept the default settings. The "Use the following port" option is enabled and the default setting is "LPT1" (recommended printer port). 6. Click "Next". The "Install printer software" windows opens. 7. Select a printer driver and click "Next". This printer driver is not used later. The "Name printer" window opens. 8. Enter a printer name in the "Printer name" field, for example "COMOS ES". This name must be identical to the name of the configuration document in the base project. See also section Configuring the printer (Page 36). 9. To use the the newly configured printer as the default printer, select the option "No" and click "Next". The "Printer sharing" window opens. 10.Activate the "Share name" option and enter the printer name in the "Printer name" field, for example "COMOS ES". This is required in order for the user to add the new printer. 11.Click "Next". The "Location and comment" window opens. 12.Enter the desired location in the "Location field, for example "Office 100, 90 Station Road". The location details are entered in the configuration file later. See also section Configuring the printer (Page 36). 13.Click "Next". The "Print Test Page" window opens. 14.Activate the "No" option and click the "Next" button. The "Completing the wizard" window opens: 15.Click the "Finish" button. See also Setting the printer port of the (Page 36) Operating Manual, 09/2014, A5E AC 35

36 Administration 8.6 Setting up the for print jobs Setting the printer port of the Requirement The printer is installed. See section Installing a new printer (Page 35). Procedure 1. In the "Printers and Faxes" window in your Windows system, select the installed printer and click "Properties" in the context menu. 2. Select the "Ports" tab and click "Add". The "Printer ports" window opens. 3. From the list of possible port types, select the entry "Local Port" and click "New Port...". The "Port name" window opens. 4. Enter "ComosES" as the port name and confirm your entry. You cannot change the port name "ComosES". COMOS recognizes the upstream COMOS Enterprise Server printer by this port name. See also Configuring the printer (Page 36) Configuring the printer Publish the printer from which printing can be carried out physically from the COMOS Enterprise Server printer. Requirement The new printer is installed. See section Installing a new printer (Page 35). The printer port of the is set. See section Setting the printer port of the (Page 36). Procedure 1. To configure the printer in the base project, select the command "File > Open project" in the menu bar. The "Open project" tab opens. 2. Activate the "Base objects" option and double-click the entry "S01 Base project" in the list. The base project opens. 3. Select the "Base objects" tab in the Navigator. 36 Operating Manual, 09/2014, A5E AC

37 Administration 8.6 Setting up the for print jobs 4. Select the following node: > A30 > M02 > A10 > A10 Example Configuration" This is a prepared configuration file in XML format. 5. Create a copy of the "Example Configuration" file and rename the copy to match the name of the printer. See also section Installing a new printer (Page 35). 6. Open the configuration file you have created by copying in a text editor and enter the desired information for the attributes highlighted in red. All the attributes have to contain values. Attribute Description Example ServerPrinterNa me UNC Name of the printer: \\<Server-Name> \<PrinterName> \\EnterpriseServer.company.com \COMOS ES Path Path to the DocFolder below the Shared folder \\<server name>\sharedfolder \DocFolder Name Name of the physical printer or a printer driver for HP Laserjet 4 generating files, for example, PDF files. This printer must be connected to the. For each printer you make available, copy the line <Printer...>. Do not enter the printer you have created. This printer is not a physical output device. DisplayName The name that is displayed in the user interface. This is usually identical to the name. HP Laserjet 4 UNCName Location UNC name of the printer. If your printer is connected to another computer, enter \\<computer name>\<printer name>. If the printer is installed on the COMOS 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 35). \\EnterpriseServer.company.com \COMOS ES COMOS ES Office 100, Any Street 90 Operating Manual, 09/2014, A5E AC 37

38 Administration 8.6 Setting up the for print jobs Storing authorized users Requirement The Path specification of the "DocFolder" folder is entered in the XML configuration file. See section Configuring the printer (Page 36). Procedure 1. Create a directory for every user 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" See also Using the printer (Page 38) Using the printer Requirement The new printer is installed. See section Installing a new printer (Page 35). The printer port of the is set. See section Setting the printer port of the (Page 36). The printer is configured. See section Configuring the printer (Page 36). The authorized users are configured. See section Storing authorized users (Page 38). Procedure 1. Select the printer for the printing process in the printer dialog from the list of printers offered. 2. Click "OK" and select the desired physical printer. Result The print job is sent to the server that forwards the document to the physical printer. 38 Operating Manual, 09/2014, A5E AC

39 Using the COMOS Enterprise Monitor 9 Introduction The COMOS Enterprise Monitor is installed together with the. This displays all processes currently running on the started instances of the COMOS Enterprise Server. In order to display the running processes of the started instances, these instances have to use the same log directory. Starting the COMOS Enterprise Monitor 1. Open the "<COMOS>\Bin" COMOS installation directory. 2. Double-click the file "ComosEnterpriseMonitor.exe". The user interface language of the COMOS Enterprise Monitor is based on the language currently selected in the COMOS user interface. Functionality Among other things, the log folder contains process log files. A process log is an XML file that contains 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. This removes the entry from the monitor table. "Show result files in list" option When you enable the "Show result files in a list" option, results are displayed in the "Status" column of the monitor table and a progress bar is displayed. If you disable the "Show result files in a list" option and start the COMOS Enterprise Monitor, not all jobs are loaded. The progress bar is not displayed. Finished jobs are not displayed in the monitor table. To display the status and progress bar, activate the "Show result files in a list" option retroactively. Columns in the monitor table Column "User" "Command ID" "Command Description" "Action ID" "Action Description" "Starting time" Description Service user. "CommandID" of the command file. "Description" of the command file. "ActionID" of the executed action. "Description" of the executed action. Starting time of process. Operating Manual, 09/2014, A5E AC 39

40 Using the COMOS Enterprise Monitor Column "Status" "Priority" "Last message" "Finishing time" "Command file" "Process ID" "Station" Description 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. Last function that was called from within the query. Indicates the completion time. Name of the internal command file that is currently being processed. "ProcessID". Computer name of the service user. When the "Last message" option no longer changes, the processing is being performed in a component outside the connector, such as in a script, an external component or other COMOS components. 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. You can use this button to determine the order of execution. Only active for pending jobs. Lowers the priority of the selected job. You can use this button to determine the order of execution. Only active for pending jobs. Deletes or aborts a job. 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, 09/2014, A5E AC

41 Using the COMOS Enterprise Monitor Button Description Starts the server. Start the on the same computer as the COMOS Enterprise Monitor. Stops the server. Updates the job list. Starting MotionXMonitor In addition to the COMOS Enterprise Monitor, the MotionXMonitor is also available in the "Bin" directory. 1. Double-click the file "MotionXMonitor.exe". The COMOS Enterprise Monitor replaces MotionXMonitor. Terminating the process using the MotionXMonitor 1. Click the "Terminate Process(es)" button. The generates a response file with the error "Process terminated without response". Note No rollback when a process is terminated If you terminate a process, the steps already executed are not reversed. Operating Manual, 09/2014, A5E AC 41

42 Using the COMOS Enterprise Monitor 42 Operating Manual, 09/2014, A5E AC

43 Document revision 10 Introduction You revision documents in bulk in the "All document tools" function. You can find more information on this topic in the "COMOS Platform Operation" manual, keyword "Working with the tool "All document tools"". You can transfer this bulk revision to the. This reduces the work load on the workstations. Transferring a bulk revision to the 1. Open the project properties. 2. Select the "Revision options" tab. 3. Activate the "Enable transfer of revision jobs to " option The shared folder is displayed in the "Shared folder" field. 4. Create a "DocFolder" folder directly below the Shared folder. 5. In the "DocFolder" folder, create a subdirectory bearing the user name for every user performing document revisions via the. If the user folder does not exist below the document folder, this is indicated by an error message. After you have carried out these settings, the revision jobs to be performed using "All document tools" are outsourced to the. Revisioning using the "All document tools" function When you perform revisions using "All document tools" this is displayed in the "Revision" window. 1. To prevent revisioning of the documents at the, activate the "Execute locally" option. Result All error messages generated in the process of revision are forwarded to the COMOS Enterprise Server and summarized in the revision jobs response file. The response file contains the results of the revision process. The COMOS Enterprise Monitor may show one of the following revision statuses: "Open" "Finished" Operating Manual, 09/2014, A5E AC 43

44 Document revision 10.1 Command file for performing revisions on the See also Command file for performing revisions on the (Page 44) 10.1 Command file for performing revisions on the COMOS Enterprise Server Example The following shows an example of a command file for performing revisions on the COMOS Enterprise Server: <?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 includes the following information for example: SystemUIDs of the documents to be revised User names Revision step 44 Operating Manual, 09/2014, A5E AC

45 Editing working layers 11 Introduction You configure the following editing options for the working layer in the command file: Import Export Release Delete See also section command file (Page 21). See also Customizing the command file (Page 45) 11.1 Requirements for releasing and deleting working layers Requirements for release The working layer exists. The linked working layer corresponds to the linked working layer of the working layer above it. No users are logged on at the working layer. Requirements for deletion The working layer exists. No projects or working layers are linked in a working layer in the base project. No users are logged on at the working layer. No objects are present which prevent deletion Customizing the command file The command file must contain all the necessary parameters needed for the respective editing process for the working layer. Operating Manual, 09/2014, A5E AC 45

46 Editing working layers 11.2 Customizing the command file Export Parameter <MXExec Version> <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.Impo rtexportwoviaes" > <Parameter Name="Action" Value="Export" <Parameter Name=" WorkingOverlayName" Value="" Parameter Name=" ExportPath" Value="" Override Description Enter Version "3" here. Specifies the DLL/assembly that is started by the. The values are specified for importing / exporting working layers. You cannot change these values. You can find more information on this topic in the "COMOS Platform Interfaces" manual, keyword "Loading existing assemblies". Name of the action being executed. Permitted value: "Export" Name of the export working layer. Do not enter 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". Complete path under which the exported working layer is stored. Specifying the file name is optional. If omitted, the name of the exported working layer is used. Specifies whether an existing working layer with the same name is overwritten during an export. Since the file receives the name of the export working layer, a multiple export may necessitate overwriting. Permitted values: "True" or "False" 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> </Assembly> 46 Operating Manual, 09/2014, A5E AC

47 Editing working layers 11.2 Customizing the command file </Action> </MXExec> Import Parameter <MXExec Version> <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.Impo rtexportwoviaes"> <Parameter Name="Action" Value="Import" <Parameter Name=" WorkingOverlayDescription " Value="" Parameter Name="ImportPath" Value="" Description Enter Version "3" here. Specifies the DLL/assembly that is started by the. The values are specified for importing / exporting working layers. You cannot change these values. You can find more information on this topic in the "COMOS Platform Interfaces" manual, keyword "Loading existing assemblies". The entry ImportExportWOViaES must be replaced when working layers are released and deleted. You can also replace it with ActionDeligation when importing and exporting working layers. 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>>". Complete path of the import working layer, with 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, 09/2014, A5E AC 47

48 Editing working layers 11.2 Customizing the command file Release Parameter Connection ClassName Action HistoryEntryDescription Description The node Connection defines the working layer (WorkingOverlay) to be released. Specifies the DLL/assembly that is started by the. The values are specified for releasing working layers. You cannot change these values. You can find more information on this topic in the "COMOS Platform Interfaces" manual, keyword "Loading existing assemblies". You control the functional scope via the parameter Action. The following values are possible: Release: This value starts the release of the required working layer. ReleaseAndDelete: When the working layer is successfully released, the command to delete the working layer is executed as well. The parameter HistoryEntryDescription contains the name of the history entry. If this parameter is not available, the name is formed from the current date and time. This is only the case if the working layer is released in the released area and the corresponding project option is enabled. Example Example of the node Action: <Action ActionID="ReleaseWO"> <Connection ConnectionString="C:\DB\ComosDB101.mdb" Project="COMOS_ET" WorkingOverlay="WOP01 WOC12"/> <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.ActionDelegation"> <Parameters> <Parameter Name="Action" Value="Release ReleaseAndDelete"/> <Parameter Name= HistoryEntryDescription Value= //Freely selectable// /> </Parameters> </Assembly> </Action> Delete Parameter <Connection [ ] WorkingOverlay="WOP01"/> Description You define the name of the working layer to be deleted using the node Connection. Example Example of the node Assembly: <Assembly Location="" AssemblyName="Comos.ImportExportWO" ClassName="Comos.ImportExportWO.ActionDelegation"> <Parameters > 48 Operating Manual, 09/2014, A5E AC

49 Editing working layers 11.3 Canceling the process <Parameter Name="Action" Value="Delete"/> </Parameters> </Assembly> See also Canceling the process (Page 49) 11.3 Canceling the process Procedure 1. If a process no longer responds, cancel this process by using the COMOS Enterprise Monitor. See also section Using 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 inconsistencies can occur when the file is re-imported. If you terminate the process during the import process, the working layer is created. However, the working layer contains the description "(** Incorrectly imported **)". Data inconsistencies can arise. 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. If you terminate the process during the release process, the working layer receives the status "Incorrect release". You can start the release of the working layer again. If you end the process during the deletion process, the objects are still in the database, but are no longer visible. Therefore, do not cancel the deletion process. Operating Manual, 09/2014, A5E AC 49

50 Editing working layers 11.3 Canceling the process 50 Operating Manual, 09/2014, A5E AC

51 Structure of the response file 12 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. See also section Adapting the response file (Page 30) Overview of the structure of the response file 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> <!-- Warnungen und/oder Fehler --> Operating Manual, 09/2014, A5E AC 51

52 Structure of the response file 12.3 <Protocol> node <!-- 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, it is explicitly indicated. See also <MXEResult> node (Page 52) <Protocol> node (Page 52) <Status> node (Page 53) <Start> node (Page 53) The <Action> node and its subnodes (Page 54) <Stop> node (Page 56) 12.2 <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. "CommandID" of the executed command file. See also Overview of the structure of the response file (Page 51) 12.3 <Protocol> node Each response file can have several "<Protocol>" nodes. 52 Operating Manual, 09/2014, A5E AC

53 Structure of the response file 12.5 <Start> node The "<Protocol>" node directly below the "<MXEResult>" node contains the complete protocol for the entire command file. This "<Protocol>" node has the following subnodes: "<Status>" node "<Start>" node "<Action>" node for each action node of the command file "<Stop>" node Each action node has a "<Protocol>" subnode <Status> node A response file contains several "<Status>" nodes: The topmost "<Status>" node contains the status of the complete protocol. Each action node contains a "<Status>" subnode. All "<Status>" nodes consist of the following attributes: Attribute: Name Code Description Attribute: Value / Purpose Indicates whether the command file was processed successfully: "0" = successful "1" = not successful For the complete protocol, the "Code" attribute can only be "0" if the status of all action nodes is also "0". Description if the command file was processed successfully: If "Code" = "0", "Description" = "OK" If "Code" = "1", "Description" = "Not OK" 12.5 <Start> node The "<Protocol>" node for the protocol of the entire response file contains a subnode "<Start>". The <"Start"> node documents when the command file was executed and who called the command file. The "<Start>" node consists of 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 Operating Manual, 09/2014, A5E AC 53

54 Structure of the response file 12.6 The <Action> node and its subnodes The counterpart of the "<Start>" node is the "<Stop>" node at the end of the complete protocol. See also section <Stop> node (Page 56) The <Action> node and its subnodes <Action> node A response file contains an "<Action>" node for each "<Action>" node from the command file. Each "<Action>" node consists of an attribute: Attribute: Name ActionID Attribute: Value / Purpose "ActionID" of the corresponding action from the command file. Each "<Action>" node has two direct subnodes: <Status> <Protocol> <Status> node The "<Status>" node specifies whether the action was processed successfully. See also section <Status> node (Page 53). <Protocol> node Each "<Action>" node contains a "<Protocol>" node that logs the execution of this action. This "<Protocol>" node can contain subnodes for warnings, errors, and Check columns. These subnodes are optional nodes. <Warning> node If a warning occurs, a "<Warning>" node is created. All "<Warning>" nodes consist of the following attributes: Attribute: Name Code Description Attribute: Value / Purpose Warning code, if available. Descriptive text. If the warning results from a COMOS object, the "<Warning>" node will have a "<ComosObject>" subnode. The "<ComosObject>" node reads out the following object properties: SystemUID SystemType 54 Operating Manual, 09/2014, A5E AC

55 Structure of the response file 12.6 The <Action> node and its subnodes SystemFullName PathFullName Description <Error> node If an error occurs, an "<Error>" node is created. The "<Error>" node consists of the following attributes: Attribute: Name Code Description Attribute: Value / Purpose Warning code, if available. Descriptive text. If the error results from a COMOS object, the "<Error>" node receives a "<ComosObject>" subnode. The "<ComosObject>" node consists of the following object properties: System-UID SystemType SystemFullName PathFullName Description <Check> node Check columns can be defined in the XML connector. See section Adapting the response file (Page 30). If a value is entered in a Check column of an object processed by the XML connector, a "<Check>" node is created for this object. Attribute: Name Description Attribute: Value / Purpose The value that is entered at the object in the Check column. If the XML connector contains several Check columns, the values of the Check columns are sequenced with a semi-colon ( ; ). In addition, for every further column defined in the XML Connector, a "<Column>" subnode is created below the "<Check>" node. <Column> node You can use the "<Column>" node to check if the performed operation for the current object in this column leads to the desired result. Operating Manual, 09/2014, A5E AC 55

56 Structure of the response file 12.7 <Stop> node The "<Column>" node consists of the following attributes: Attribute: Name Name MappingInf 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 entered in COMOS in the "Name" column. The value that was passed in the XML file. As a rule, "ComosValue" and "XMLValue" are identical <Stop> node The "<Stop>" node specifies at what date and time the processing of the current action was terminated. The "<Stop>" node consists of 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. See also <Start> node (Page 53) 56 Operating Manual, 09/2014, A5E AC

57 Log files 13 Types of log files There are the following three types of log files: Action logs Tracing logs Process logs Process logs are used on the software side and, therefore, are not handled in this documentation. It is prohibited to delete or edit the process logs. The data of the process logs is displayed via the COMOS Enterprise Monitor. See section Using the COMOS Enterprise Monitor (Page 39). Specifying the log directory All log files are located in the same log directory. 1. Specify the log directory in the configuration file via the "<LogDirectory>" parameter. See also Example of configuration file (Page 71) 13.1 Action logs All actions of one day are logged in one file. Two rows are written into the action log for each started command file: Row when starting Row when stopping Two rows are also added for each action of the command file: Row when starting Row when stopping Each row contains the following information: Information Description Date and time - Workstation Displays the workstation from which the command was issued. User Shows the service user. Operating Manual, 09/2014, A5E AC 57

58 Log files 13.2 Tracing logs Information CommandID ActionID Status Path Description Shows the "CommandID" of the relevant command file. Shows the "ActionID" of the action. The "ActionID" is not applicable in the rows that are generated while starting and stopping the command file. Shows the status of the action. The "Status" is only shown when the action and the process are stopped: "0" = Action successful "1" = Action unsuccessful Shows the path to the command file that was copied as a temporary file to the "TmpConfigFile". A new file is created with each date change. The files are deleted at regular intervals. You specify the service life of the action log in the configuration file via the "<MaxLogAge>" parameter. See also Example of an action log (Page 75) 13.2 Tracing logs All outputs of the, including the MXExec processes, are written to a tracing log. You specify the messages included in the log file in the configuration file via the "<TraceLevel>" parameter. A new log file is created for each day. The files are deleted at regular intervals. You specify the service life of the tracing log in the configuration file via the "<MaxLogAge>" parameter. See also Example of a tracing log (Page 76) 58 Operating Manual, 09/2014, A5E AC

59 Response / Error messages 14 Unlike COMOS, the is a Windows service and does not process response messages. Therefore, 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 does not continue until the user confirms this window. The operates without a user interface. Generally, message boxes are not displayed in a service environment. The user cannot close the window with a button. Error messages and warnings that originate from the COMOS kernel or the queries are redirected to the response file. User-defined messages are not redirected. Therefore, ensure that the XML connectors in COMOS do not lead to messages that require user interaction, such as prompts, hints, or error messages. Operating Manual, 09/2014, A5E AC 59

60 Response / Error messages 60 Operating Manual, 09/2014, A5E AC

61 Participating files 15 ComosMotionXServerManager.exe ComosMotionX.ServerManager.config *.mxc MotionX.sync Comos.EnterpriseServer.Process.exe *.txt *.mxr ComosMotionXScheduler.exe "ComosEnterpriseMonitor.exe ComosEnterpriseServerConfigurator.ex e ComosEnterpriseServerServiceInstalle r.exe. 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. Supplied standard application: "Comos.EnterpriseServer.Process.exe" Configuration file of the. Command files for the. See also section command file (Page 21). The processed files are archived. See also section Window " Configurator" (Page 77). Generated by an instance of the that searches 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 COMOS Enterprise Server 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. See also section Log files (Page 57). Response files of the "Comos.EnterpriseServer.Process.exe". See also section Structure of the response file (Page 51). Copies predefined MotionX command files to the Shared folder at specific times. See also section Configuring the MotionX Scheduler (Page 65). Displays all processes currently running on the active COMOS Enterprise Servers. See also section Using the COMOS Enterprise Monitor (Page 39). User program for configuring the. Is called automatically at installation and can be called explicitly by the user as needed afterwards. See also section Window " Configurator" (Page 77). User program to generate and configure the Service Program. Called automatically at installation and can be called explicitly by the user as needed afterwards. See also section Window " Service Installer" (Page 80). Operating Manual, 09/2014, A5E AC 61

62 Participating files 62 Operating Manual, 09/2014, A5E AC

63 Other Synchronizing the Shared folder The content of this section is not relevant for the normal operation of the COMOS Enterprise Server. It applies instead to technical inspection or customizing. It is intended for users who are responsible for these tasks. New command files in the Shared folder may only be accessed by one server. Otherwise, several servers can process the same file. The "MontionX.sync" file ensures that several servers do not access the Shared folder simultaneously. 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 first locks the "MotionX.sync" file and write its machine name to the file. When the action is terminated, the server fills the 100 bytes with zeroes and removes the lock. The command files can still be saved in the Shared folder. As long as the "MotionX.sync" file is locked, the new command files cannot be processed. Only the current command file can be evaluated. This covers the following two cases: Several instances access the Shared folder via the network. 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 process the next command file before the first "Comos.EnterpriseServer.Process.exe" process has written its response file. The procedure is as follows in this case: "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 An additional command file is created in the meantime "Comos.EnterpriseServer.Process.exe"process 1 deletes the command file it has processed and enables "MotionX.sync". However, processing of the command file is not yet completed. A response file is not yet created. "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. Enter the following content in the corresponding command file: <Test><Action ID="TestCriticalSection"><Time> 20 <\...> Operating Manual, 09/2014, A5E AC 63

64 Other 16.2 Technical procedure When the server reads this line, it pauses for 20 seconds in the "CriticalSection", thus refusing access to all servers during this period. Procedure for testing: Start at least two servers. Copy the "TestCriticalSection.mxc" file into the Shared folder. One of the servers locks MotionX.sync and a corresponding message is issued in the Tracing log file. For the other servers, the following entry is displayed in the Tracing log file: "Try to Enter CriticalSection." No more outputs are displayed until 20 seconds have passed on the first server. Afterwards, the output "CritialSection Entered" is displayed. See also Technical procedure (Page 64) 16.2 Technical procedure Introduction This section describes the technical procedure for the standard application or the standard adapter. Requirement XML connectors are prepared in COMOS. The XML connectors are always sought in the "Documents" tab below the node "@System Refer to section Technical procedure 1. Start the. The following is carried out during the start: The configuration file is evaluated. An entry is written in the tracing log file, for example, service user, computer name or drive. In the shared folder the administration file "MotionX.sync" is created. 2. The monitors the Shared folder. See also section Synchronizing the Shared folder (Page 63). 64 Operating Manual, 09/2014, A5E AC

65 Other 16.3 MotionX Scheduler 3. If a command file is found in the Shared folder, the following steps are taken: The evaluates the "ComosMotionXServerManager.config" file. The command file is copied to the Temp directory and to the History directory. The command file is deleted and the Shared folder is released again. The command file copied to the Temp directory is evaluated. If the command file is valid, the command is transferred to the application that is specified in the command file. The command file is transferred at this time to the application "Comos.EnterpriseServer.Process.exe". 4. The "Comos.EnterpriseServer.Process.exe" application executes the commands in the command file. For this, an instance of COMOS is started in the background and the adapter specified in the command file is called up. The adapter "XML Connector" is currently specified in the command file. 5. Then the "Comos.EnterpriseServer.Process.exe" application creates a response file in the Temp directory. The moves the response file to the Shared folder MotionX Scheduler The MotionX Scheduler copies 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. See also Configuring the MotionX Scheduler (Page 65) Configuring the MotionX Scheduler Requirement The application for the MotionX Scheduler is located in the COMOS Bin directory. Procedure 1. Create a directory as the MotionX Scheduler folder, in which the planned command files are stored. 2. Enter the path to the MotionX Scheduler folder in the "ComosMotionXServerManager.config" file. Operating Manual, 09/2014, A5E AC 65

66 Other 16.3 MotionX Scheduler 3. Create a task using the standard Windows Scheduler. The bat file of the task includes the call of the MotionX Scheduler application with the corresponding parameters. 4. Separate the parameters with a space: 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 dot. Result The MotionX Scheduler copies the MotionX command files to the corresponding folder under the Shared folder. The following cases may occur: The copied file is still in the Shared folder and has not been processed yet. The target folder or command file is not existent. Denial of rights Other faults In this case, the MotionX Scheduler writes a corresponding message into the log file of the. See also Example of the MotionX Scheduler configuration (Page 66) Example of the MotionX Scheduler configuration Procedure 1. Create the directory C:\EnterpriseServer\Scheduler" in which the scheduled command files are saved. 2. Open the configuration file. See also section Example of configuration file (Page 71). 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. 5. Select the "ComosMotionXScheduler.exe" file from the COMOS Bin directory. 6. In the final step, open the extended properties of the task in the Microsoft Windows Scheduled Task Wizard. 7. Select the "Task" tab. 66 Operating Manual, 09/2014, A5E AC

67 Other 16.4 Freely definable DLLs 8. Enter the parameters in the "Run" field. To copy a file from the Scheduler folder to the Shared folder, enter the following: "C:\Comos\BIN\ComosMotionXScheduler.exe <Name command file>" To copy a file from a separate directory to a subdirectory of the Shared folder, enter the following: "C:\Comos\BIN\ComosMotionXScheduler.exe <Absolute path to the command file> <Subdirectory of the Shared folder>" 9. Save the task. See also Configuring the MotionX Scheduler (Page 65) 16.4 Freely definable DLLs 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> 3. To load a C# assembly file, enter the file name, the assembly name and the class name. Entering the "ProgID" is not sufficient. 4. Implement the ICustomAction interface in your assembly file. See also section Implementation interface (Page 67). Result The reads the version number and allows access to the new functions as required. You can also start VB DLLs using Version 2 and function nodes. See also section Structure and configuration of the command file (Page 22) Implementation interface Introduction The requires two interfaces to implement freely definable DLLs. Operating Manual, 09/2014, A5E AC 67

68 Other 16.4 Freely definable DLLs All the required interfaces and enumerations are defined in the "Comos.EnterpriseServer.GlobalContracts.dll" file. 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) A successful call of the is reported in this parameter. Value Description 0 Error-free call. 1 Errors occurred during the call or the call could not be implemented. The value specifies to the command file how the command file has to set the status of the action. Interfaces IActionEnvironment and IESUtilities You are not allowed to implement the interfaces IActionEnvironment and IESUtilities. If they are implemented, compatibility cannot be guaranteed. These interfaces supply all required parameters and are the only parameter that is passed on to the start method. 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. 68 Operating Manual, 09/2014, A5E AC

69 Other 16.4 Freely definable DLLs See also Customizing the command file for C# assembly (Page 67) Logging (Page 69) Logging Introduction The interface "IESUtilities" provides the logging capabilities of the COMOS Enterprise Server 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); } Explanations Parameter TraceLevel WriteProtocol 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> Operating Manual, 09/2014, A5E AC 69

70 Other 16.4 Freely definable DLLs Parameter TraceMessage WriteMonitorInfo Description Writes a message to the file "MotionX-Trace.log". For the TraceLevel, all four values are allowed. You define the text yourself. Example of the message structure: :09: [1] DEBUG MXExec.MXC - MXLogger loaded: True Writes a message on the current process into the process log. This message in displayed in the COMOS Enterprise Monitor under "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". 70 Operating Manual, 09/2014, A5E AC

71 Example files Example of configuration file <?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</ InterfaceEXE> <SharedFolder>C:\EnterpriseServer\SharedFolder</SharedFolder> <TmpConfigFileFolder>C:\EnterpriseServer\TempFiles</ TmpConfigFileFolder> <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 " Configurator" (Page 77) Operating Manual, 09/2014, A5E AC 71

72 Example files 17.2 Example of a command file 17.2 Example of a command file Export command file <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 <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> 72 Operating Manual, 09/2014, A5E AC

73 Example files 17.2 Example of a command file <Action ActionID="Act01" Description="Import 1"> <Connection ConnectionString="D:\2008\SAP training \SAP_DB_100408\StandardDB.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, 09/2014, A5E AC 73

74 Example files 17.3 Example of a response file 17.3 Example of a response file 74 Operating Manual, 09/2014, A5E AC

75 Example files 17.4 Example of an action log 17.4 Example of an action log Operating Manual, 09/2014, A5E AC 75

76 Example files 17.5 Example of a tracing log 17.5 Example of a tracing log 76 Operating Manual, 09/2014, A5E AC