inubit 6.1 inubit Workbench/Process Engine System Connectors Guide

Transcription

1 inubit 6.1 inubit Workbench/Process Engine System Connectors Guide

2 Copyright Bosch Software Innovations GmbH Schöneberger Ufer Berlin Germany Phone: Fax: URL: Bosch Software Innovations GmbH 2013 Legal Provisions The information and data, including URLs and other references on an Internet basis, contained in this documentation may be changed without prior notice. The product documentation was carefully prepared. However, the information contained therein cannot be guaranteed to reflect the properties of inubit. The liability of Bosch Software Innovations GmbH encompasses only the provisions stated in the sales and delivery conditions. The users are responsible for compliance with all applicable copyrights. Regardless of applicability of the respective copyright laws, no portion of this document may be reproduced or transferred for any purpose, regardless of the means or resources used, electronically or automatically, without prior explicit written approval from Bosch Software Innovations GmbH. Bosch Software Innovations GmbH may be the owner of patents, patent applications, trademarks, copyrights or other rights of intellectual property that concern the content of this document. The provision of this document does not grant license rights to these patents, trademarks, copyrights or other intellectual property, unless this was explicitly granted by Bosch Software Innovations GmbH in a written license agreement. Software provided by Bosch Software Innovations GmbH may include software components of other producers. inubit is a registered trademark of Bosch Software Innovations GmbH. All other product and company names listed in this document may be registered trademarks of their respective owners.

3 3 Table of Contents Notes on the System Connectors Guide...15 Scope of the Documentation...15 Tips, Notes and Links in the Documentation...16 Further Information and Support System Connectors Dialog Descriptions Dialog General module properties Dialog System Connector Properties Dialog Scheduler Dialog SSL Configuration Dialog Remote Connector Configuration AS/400 Connector XPCML Input Message: Example Dialog AS/400 Connector Properties AS2 Connector Module Variables of the AS2 Connector Receiving, Sending and Verifying AS2 Messages MIME Structure Workflow examples Dialog Descriptions Dialog AS2 Configuration Dialog AS S/MIME Configuration Dialog AS2 Listener Configuration Dialog Message Archive Configuration Dialog AS MDN Validator Dialog AS2 Listener Configuration Dialog AS2 Configuration Dialog AS Message Configuration Dialog S/Mime Configuration Dialog AS MDN Configuration Dialog HTTP(S) Server Configuration Dialog AS MDN Shipping Configuration (Sending MDN with Output Connector)...41 inubit 6.1: Workbench/Process Engine: System Connectors Guide

4 4 Table of Contents 4 Backup Connector Dialog Backup Connector Properties Business Object Connector Functional Principle Using Object Mode Create/Update/Delete Operations Read Operations Using Query Mode Supported Query Attributes Saving and Importing a Database Query Updating and Deleting Master Data References Dialog Business Object Connector Settings Database Connector Querying Metadata Creating Static SQL Queries Creating Dynamic XML-Queries XML Queries: Structure and Examples Structure Select: Displaying Data Select Distinct Join: Data from Different Tables Insert: Inserting Data Sets Update: Updating Data Sets UpdateOrInsert Delete: Deleting Data Sets Multiple SQL Statements in a Single Query Passing SQL Statements Directly: Force Subqueries: Subselects Call: Calling Stored Procedures Dialog Descriptions Dialog Database Connection and Query Type Dialog Metadata Dialog Static Query Dialog Query Result Dialog Connection Pooling Properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

5 Table of Contents 5 7 Database Object Connector Inserting, Selecting, Updating and Deleting Business Objects Monitoring and Archiving Events With an Event-Listener Monitoring an Event Archive with a Archive Processor Configuration File: Field Descriptions Create Database Procedure getnewid getnewid for Oracle getnewid for MySQL Dialog Descriptions Dialog Database Configuration Dialog Database Pooling Configuration Dialog DBO Configuration File Exchange Connector Installation Requirements Using the Exchange Connector Dialog Descriptions Dialog General Settings Dialog Fetching s Dialog Moving Items Setting up all Other Actions Execution Connector Example: Reading a directory Example: Copying a file Example: Creating a directory Dialog Execution Connector Properties File Connector Module Variables of the File Connector Dialog Descriptions Dialog File(s) to read Dialog Data transfer Dialog File to write FTP(s) Connector Module Variables of Input Connectors inubit 6.1: Workbench/Process Engine: System Connectors Guide

6 6 Table of Contents 11.2 Dialog Descriptions Dialog FTP Connector Properties Dialog Executing FTP Commands Dialog Defining Input File Names Dialog Defining Output File Names HTTP Connector Defining and Displaying Parameters Defining and Displaying Headers Dialog HTTP Connector Properties inubit IS Connector Thin Clients as Clients inubit Process Engine as Client Dialog Descriptions Dialog Authentication Dialog Function Dialog Connection data Dialog Input file(s) Dialog Output File(s) ITA Connector Prerequisites for Operating the Connector: Installing Drivers Inserting Documents into the ITA Archive System Reading Documents From the ITA Archive System Dialog ITA Archive Connector JAAS Connector Example Scenario: Checking a List of User Accounts Example Scenario: Validating User Data with Task Forms Extending the JAAS Connector Dialog JAAS Connector Properties Java Reflection Connector Create Input Message Creating Your Own Method Call Example Method Call List of Attributes inubit 6.1: Workbench/Process Engine: System Connectors Guide

7 Table of Contents Dialog Java Reflection Connector Properties JCA Connector Principles of Operation Creating Input Messages Sample Input Message Dialog J2EE Connector Architecture Adapter JMS Connector Configuring the Access on the JMS based Queuing Server Using the JMS Connector in Entry, Standard or Professional Edition Using the JMS Connector in Enterprise/Enterprise Plus Edition with any other JMS based Queuing Server Dialog Descriptions Dialog Connection configuration Dialog Communication model Dialog Message selector Dialog Additional properties LDAP Connector Principles of Operation DSMLv2 Statements in Requests Modify Search Add Delete Dialog LDAP Connector Properties Livelink PDMS Connector Installing JAR Files Content and Structure of Input and Output Messages Commands Condition Entities Entity Attributes Entity Properties Entity Components Example of an Output Message inubit 6.1: Workbench/Process Engine: System Connectors Guide

8 8 Table of Contents 20.3 Dialog Livelink PDMS Connector properties Mail Connector Module Variables of the Mail Connector Dialog Descriptions Dialog Mail Connector Properties Dialog Configuring Data Transfer Dialog Message Configuration Dialog S/MIME Decryption Dialog Properties of Input Data Dialog SMTP Connector Properties Dialog S/MIME Encryption MSMQ Connector Requirements Create Input and Output Messages Dialog MSMQ Connector properties OFTP Connector Requirements Principles of Operation Data Transfer Modes rvs Monitoring Dialog Data Exchange Configuration Dialog Stations Neighbor Stations Neighbor Station over TCP/IP Neighbor Station over LU Neighbor Station over ISDN Neighbor Station over X Virtual Neighbor Station Routed Station Activating Connection Remove Receiver Configuring an X.25 Receiver Configuring an ISDN Receiver inubit 6.1: Workbench/Process Engine: System Connectors Guide

9 Table of Contents Configuring a TCP/IP Receiver Configuring an SNA LU6.2 Receiver OFTP2 Connector Requirements Principles of Operation Data Transfer Modes rvsevo Monitoring Dialog OFTP data exchange configuration Dialog Stations Local Station Neighbor Stations Neighbor Station over TCP/IP Neighbor Station over ISDN Neighbor Station over XOT Virtual Station Routed Station Activating Connection Remove Receiver Configuring a TCP/IP Receiver Configuring an ISDN Receiver Configuring an XOT Receiver Configuring a TLS Receiver OpenOffice Connector Requirement: OpenOffice Installation Functional Principle Creating an Example Workflow Convert the Document into the PDF Format Editing a Document Printing a Document Basic Settings Dialog OSCI Connector Prerequisites Functional Principle inubit 6.1: Workbench/Process Engine: System Connectors Guide

10 10 Table of Contents 26.3 Dialog Descriptions Dialog Retrieving OSCI Messages Dialog Creating OSCI Messages REST Connector REST Connector Module Variables REST Functional Principle Using HTTP Methods Offering a Resource Displaying Available Input Connectors Displaying Published Resources Calling Resources Dialog Descriptions Dialog Resource Configuration Dialog Response configuration Dialog Request configuration RFID Connector Principles of Operation Example for an XML Output Message Dialog RFID (IPort) Connector properties RosettaNet HTTPS Connector Structure and Exchange of RosettaNet Messages Example Workflow: Generating RosettaNet Messages Example Workflow: Sending a RosettaNet Message Example Workflow: Receive Message and Send Acknowledgement Dialog Descriptions Dialog RosettaNet Connector Properties General tab NoF tab New PIP tab Dialog Asynchronous receipt Dialog S/MIME Configuration Dialog Connection data for business messages Dialog Receipt Dialog S/MIME Configuration inubit 6.1: Workbench/Process Engine: System Connectors Guide

11 Table of Contents Dialog Connection data for messages disposition notifications Dialog RosettaNet connection data SAP Connector Installing the SAP Java Connector (JCo) Principles of Operation Creating XML Request/Response Dialog SAP Connector Properties Secrypt Connector Principles of Operation Example: Workflow with Secrypt Connector Module Variables Dialog Secrypt Connector Properties Security Token Service Connector Principles of Operation of the STS Connector Registering Web services providers at an STS Connector Dialog Security Token Service (WS trust) Selenium Connector Principles of Operation Error Handling Dialog Selenium Connector Properties SNMP Connector Principles of Operation Example: Medium Connector Example: Input Connector Dialog SNMP Connector Properties Solution Center Connector Functional Principle Module Properties Generating Object XML Data Using XPath Requests Aggregations, One and Two-sided Directed Associations Example: Create Object inubit 6.1: Workbench/Process Engine: System Connectors Guide

12 12 Table of Contents Generating an Object Using the Node ID Generating an Object Using an XPath Request Example: Query Object Data Retrieving Object Data Using the Node ID Retrieving Object Data Using an XPath Request Example: Update Object Data Updating Object Data Using the Node ID Updating Object Data Using an XPath Request Example: Delete Object Deleting an Object Using the Node ID Deleting an Object Using an XPath Request SC Connector Settings Dialog Solution Center Logger Functional Principle Creating Your Own Event Types Dialog SC Logger Settings TCP/IP Connector Connector types Processing IP Messages Using Start and Stop Bytes Dialog TCP/IP Connector Properties VFS Connector Module Variables of the VFS Connector Dialog Descriptions Dialog VFS Connector base configuration Dialog Input Connector Configuration Dialog Output configuration Web Application Connector Module Variables of Web Application Connector Requesting Information from Portlet Instances Dialog Descriptions Dialog Web Application Dialog Internal Resources Dialog Permission Management inubit 6.1: Workbench/Process Engine: System Connectors Guide

13 Table of Contents Web Services Connector Web Services: Principles of Operation Module Variables of the Web Services Connector Setting and Reading HTTP Header Variables Set HTTP Header Variable for a Web Service Call Read the HTTP Header after a Web Service Call Variable for HTTP Header of a Listeners Input Message Setting the HTTP Header for an Outgoing Response Message Providing a Web Service Calling a Web Service Asynchronous Web Services Offering an Asynchronous Web Service Calling an Asynchronous Web Service Securing Web Services Providers by a Security Token Service Creating Key Pairs for WS Security Creating a Self-Signed Key Pair Creating an Externally Signed Key Pair Creating Key Pairs for WS Trust Creating Self-Signed Security Token Service (STS) Key Pairs Creating a Self-Signed Key Pair Calling an STS-Secured Web Service Provider Creating Operations for a Web Service Overwriting PartnerLinks Publishing Web Services in a UDDI Listing Active Web Services Logging SOAP Messages Transferring Binary Data as Attachments with MTOM Sending Messages with Binary Attachments Receiving Messages with Binary Attachments Dialog Descriptions Dialog Provided Web Service Dialog Invoked Web Service Web Service Editor and its Tabs Provided Service Tab Invoked Service Tab XML Schemas Tab inubit 6.1: Workbench/Process Engine: System Connectors Guide

14 14 Table of Contents WSDL Editor Tab Extended Tab SOAP messages Tab Dialog Web Service Settings Dialog UDDI Browser Dialog UDDI Data Settings Dialog WS-Security Configuration Dialog WS-Security Configuration Dialog WS-ReliableMessaging Configuration Dialog Edit Namespaces WebDAV Connector Dialog WebDAV Connector WebSphere MQ Connector Requirements Dialog WebSphere Message Queue Connector X.400 SE Connector Requirements Installing Isode for Windows Sending and Fetching Read Notifications (RN) Dialog Descriptions Dialog X.400 access data Dialog Data transfer configuration Dialog Message transmission options inubit 6.1: Workbench/Process Engine: System Connectors Guide

15 Notes on the System Connectors Guide 15 Target audience This guide contains detailed information for system administrators, system integrators and developers, who manage, configure and extend inubit software (or parts thereof). Scope of the Documentation inubit provides comprehensive documentation and is available as a printed manual, a PDF file and as online help in the inubit Workbench. The documentation covers the following content: inubit - Quick Start Describes the hardware and software prerequisites, the installation and the first steps. - Migration Guide - Tutorials For novices. Using technical scenarios the tutorials detail the use of the most important components of inubit. inubit Workbench, inubit Process Engine und inubit Enterprise Portal: - User Guide Explains how to work with the inubit Workbench, the Designer, working with different diagram types, modules, with metadata and workflow variables, simulations, tests, technically-based monitoring and reporting. - Administrator and Developer Guide Administrative topics such as the configuration of inubit Process Engine, backup and restore, user administration, security aspects, monitoring and clustering, development of plug-ins and Thin Clients. - Modules Guide Use and configuration of Data Converter, Format Adapter, Utilities, Workflow and Web Service Controls. - System Connectors Guide Everything involving the use and configuration of system connectors. inubit Solution Center User Guide Information about creating business models, working with Business Solutions, creating views, integrating processes and default models and the REST interface. - Administrator Guide inubit 6.1: Workbench/Process Engine: System Connectors Guide

16 16 Explains how to backup and restore data, to install the Solution Center as a service, to adjust ports, to configure the portal, the database and HTTPS, to manage users and import diagrams. inubit WebModeler Administrator and User Guide Everything about creating and editing models, adjusting ports, configuring the database and HTTPS. You can download the most current documentation in the inubit User Portal from the software tab at Further information The following information is enclosed as a booklet with the DVD, or as files in the installation package: readme.txt Notes on the installation and migration of inubit. Read this file thoroughly before installing or updating inubit! Quick Start System requirements and installation instruction as booklet delivered with the inubit-dvd. API documentation for plug-in software development kit Found under <is-installdir>/documentation/apidoc/ index.html. JavaScript-Framework of the inubit Found under <is-installdir>/documentation/jsdoc/ index.html Tips, Notes and Links in the Documentation Tips offering useful information for working with inubit. Notes that must be read and observed. Failure to follow the instructions may lead to data loss or may cause serious system problems. References to other text locations within this or any other inubit manual are labeled with an arrow. Links to external web pages inubit 6.1: Workbench/Process Engine: System Connectors Guide

17 17 Further Information and Support Press releases and white papers are available from our website For further inquiries, please contact our support by: Telephone: SupportSystem: We wish you every success in working with inubit. Your team from Bosch Software Innovations GmbH! inubit 6.1: Workbench/Process Engine: System Connectors Guide

18 inubit 6.1: Workbench/Process Engine: System Connectors Guide

19 1 System Connectors 19 This section details the following topics: Dialog Descriptions, p. 19 Use System connectors connect source or target applications with the inubit Process Engine and generally pass on messages without transformations. In a system connector the specific protocol and authentication data for establishing the connection with the source or target applications is stored. Refer to - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) - Activating System Connectors (Workbench: User Guide, chap. 3.9, p. 122) - Integrating Systems and Automating Processes (Tutorials, chap. 4, p. 59) 1.1 Dialog Descriptions This section details the following topics: Dialog General module properties, p. 19 Dialog System Connector Properties, p. 20 Dialog Scheduler, p. 22 Dialog SSL Configuration, p. 24 Dialog Remote Connector Configuration, p Dialog General module properties Refer to Dialog General Module properties (Workbench: User Guide, chap. 3.15, p. 127). inubit 6.1: Workbench/Process Engine: System Connectors Guide

20 20 System Connectors Dialog Descriptions Dialog System Connector Properties This dialog offers the following options: Base configuration Connector type There are the following basic configuration types for system connectors. Some system connectors are not configurable in all configuration types. In this case, the corresponding options are deactivated. - Input Connector A System Connector which is configured as Input Connector fetches data from a source application and hands them over to its subsequent module. After the workflow execution the Input Connector returns the result to the source application. It is always located at the start of a workflow, i.e. it has no preceding module, only a subsequent module. - Medium Connector A Medium Connectors usually transmits a synchronous call to an application, receives the response from the application, and forwards the response to the next module in the workflow. A medium system connector is located in the middle of a workflow, i.e. it has both a preceding and a subsequent module. - Output Connector An output system connector sends data to a target application. An output system connector is located at the end of a workflow, i.e. it has a previous module but no subsequent module. For a list of symbols used for modules in Technical Workflows refer to Symbols in Technical Workflows and in the Directory Tree (Workbench: User Guide, chap , p. 323). Listener connector A System Connector can be run as a listener: - Input listeners wait for calls or data from a source application. - Output listeners provide data for a target system to collect. Connector status Active/inactive Technical workflows or BPEL diagrams can run active system connectors, only. Inactive System Connectors can only be run manually, for example for testing. Refer to Activating System Connectors (Workbench: User Guide, chap. 3.9, p. 122) inubit 6.1: Workbench/Process Engine: System Connectors Guide

21 System Connectors Dialog Descriptions 21 Remote connector When activated, the System Connector connects to a Remote Connector on a remote host. Not all types of system connectors can be used as remote connectors. This option is only active if the system connector can be used as remote connector; System connectors configured as Listeners can never be used as Remote connectors. The Configuration button opens the Dialog Remote Connector Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 25) for entering the Remote Connector s URL and the authentication data. Here, you can also start a connection test. For more information about installing and configuring a Remote Connector refer to Remote Connector (inubit Process Engine: Administrator and Developer Guide, chap. 13, p. 149). Handling of connection errors Number of retries Specifies how many times the system connector should attempt to establish a connection with the system with which it is communicating. If the connection cannot be re-established, an error is thrown. Retry interval Time period between individual retries. Timeout (in sec.)/ Default timeout Length of time in seconds the module waits for establishing the connection. If no connection can be established within the time period specified, the connection attempt and module execution are terminated and an error is thrown. If you enter 0 (null), the timeout is infinite. If you activate the option Default timeout, the module waits for 600 seconds which is the default timeout. Input/output message logging If this option is activated, the system connector s input and output messages are stored. This function is useful for debugging and testing, if, for example, messages do not reach the business partners and must be submitted again, or if a workflow was carried out faultily and needs to be restarted using the same input messages. You can restart the workflows in the Queue Manager. There, you can also display the input and output messages. Refer to - Displaying Message Logs (inubit Process Engine: Administrator and Developer Guide, chap , p. 110) inubit 6.1: Workbench/Process Engine: System Connectors Guide

22 22 System Connectors Dialog Descriptions - Restarting Processes (inubit Process Engine: Administrator and Developer Guide, chap , p. 111) Only activate the input/output message logging, if it is really needed. Otherwise the file system might fill with files from the input/output message logging, if there is only little disk space. If input/output logging is activated for multiple system connectors and/ or in the Technical Workflow itself, the smallest available specification is used. If the input/output message logging is activated, you can define how many messages are be stored: Number of messages Defines the number of messages which are stored. If this number is exceeded in the course of the workflow execution, then the oldest messages are deleted until the given number is reached again. Synchronize with system log If this option is activated, the messages are treated as defined at the option System Logging in the diagram. Refer to System logging (Workbench: User Guide, chap. 2, p. 109). If the option System Logging is not activated, the default settings are used which are defined in the file <inubit-installdir>/ server/ibis_root/conf/logsdbconfig.xml in the element dataentrieslimit Dialog Scheduler System connectors can be executed time-controlled. In this dialog you define start times or start intervals. System connectors start in accordance with a schedule only if the Technical Workflow was published and activated on a server. In local mode and in test mode, scheduled system connectors are not started at all. Schedule Scheduler activation If the option is activated, system connectors behave as follows: - Input System Connector Starts at the specified point in time at the given interval and triggers the processing of the Technical Workflow. - Output System Connector inubit 6.1: Workbench/Process Engine: System Connectors Guide

23 System Connectors Dialog Descriptions 23 Sends messages to the target application at the specified time, prior to which it buffers the messages. If a system connector is started in an interval shorter than the workflow s execution time (e. g. interval=10 s, execution=45 s), the workflow behaves as follows: - When the workflow is executed in parallel, it is started in the given interval. When the limit of parallel threads is reached, any further processing is queued. - When the workflow is not executed in parallel and is still running when called for its next execution, the workflow is not started again. Days A system connector can be activated in the following ways: Daily Weekly (select one or more weekdays) Monthly (select one or more days in a month) Time Starting time at which the process should be started on the specified day. If an interval is activated, the process takes place at defined intervals (e.g. every 5 minutes). In order to stop recurrence of the process, an end time must be defined. Time frame Time period (start and end date) during which the scheduler should be activated. Input connectors reading behavior If the scheduler is activated, workflows containing the following input connectors are started as long as data are available. - Mail Connector - inubit is Connector - JMS Connector If the scheduler is activated, the maximum number of executions per scheduled call can be configured for the following input connectors: - File Connector Refer to Dialog File(s) to read (Workbench/Process Engine: System Connectors Guide, chap , p. 120). - VFS Connector Refer to Dialog Input Connector Configuration (Workbench/ Process Engine: System Connectors Guide, chap , p. 386). inubit 6.1: Workbench/Process Engine: System Connectors Guide

24 24 System Connectors Dialog Descriptions - FTP Connector Refer to Dialog Defining Input File Names (Workbench/ Process Engine: System Connectors Guide, chap , p. 134). Medium/output connectors reading behavior Connectors, which have a predecessor, are processed exactly once at each Workflow execution. Error handling Create log-entry on every faulty call If activated, an entry is generated in the Monitoring > System Log register for every error that occurs when the system attempts to start the system connector Dialog SSL Configuration This dialog offers the following options for defining SSL settings when establishing a connection: Server authentication If selected then the server, which is the connection target, must identify itself to the system connector. If not selected, then each SSL server is regarded as reliable. The Load truststore button opens a file explorer for uploading of the truststore containing the public key of the server. Java Keystore format is accepted as truststore, PEM format or DER format are accepted as certificate. Client authentication If selected then the system connector must identify itself to the server. The Load keystore button opens a file explorer for uploading the keystore containing the private key and the public key of the server. You need to enter the password for the private key resp. keystore. The server and client authentication is displayed in the login dialog of the inubit Workbench and offered in the following system connectors: - inubit IS Connector (Workbench/Process Engine: System Connectors Guide, chap. 13, p. 147) inubit 6.1: Workbench/Process Engine: System Connectors Guide

25 System Connectors Dialog Descriptions 25 - FTP(s) Connector (Workbench/Process Engine: System Connectors Guide, chap. 11, p. 129) - HTTP Connector (Workbench/Process Engine: System Connectors Guide, chap. 12, p. 139) - AS2 Connector (Workbench/Process Engine: System Connectors Guide, chap. 3, p. 31) - RosettaNet HTTPS Connector (Workbench/Process Engine: System Connectors Guide, chap. 29, p. 297) Dialog Remote Connector Configuration For more information about installing and configuring Remote Connectors refer to Remote Connector (inubit Process Engine: Administrator and Developer Guide, chap. 13, p. 149). URL URL of the Remote Connector. Replace localhost with the name of the host on which the remote connector is installed, or by the IP address of that host. Server authentication If selected then the remote connector of the remote computer must identify itself with a certificate to the system connector, you are configuring here. If not selected, then each SSL server is regarded as reliable. The Select file button opens a file explorer for uploading of the truststore containing the public key of the remote connector. After uploading, the system displays the end date of the key's validity period. Client authentication If selected, the system connector, which you are configuring here, must identify itself to the Remote Connector with a private key or a keystore, respectively. The Load keystore button opens a file explorer for uploading the keystore containing the private key and the public key of the Client. After uploading, the system displays the end date of the key's validity period. Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

26 26 System Connectors Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

27 2 AS/400 Connector 27 This section details the following topics: XPCML Input Message: Example, p. 27 Dialog AS/400 Connector Properties, p. 28 Use You can use the AS/400 Connector to start applications on an AS/ 400 server from a Technical Workflow. To call the application and pass any existing parameters, you require an XPCML-based input message. You create this input message using an XSL converter that is activated prior to the AS/ 400 Connector. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 2.1 XPCML Input Message: Example An XPCLM-based input message contains input, throughput, and output parameters including data types and values. The AS/400 Connector always expects the following inputs: Type, value, and length of all required parameters Complete path to the AS/400 application Example The following parameters are passed to verify the contract number: Parameter 1 = Client (char, 1-place, value 1=supplierX, 2=supplier2) Parameter 2 = Contract number (char, 17-place) Parameter 3 = return code (char, 1-place, value) Executing program ContractNo.Query Request in XPCML <?xml version="1.0" encoding="utf-8"?> <xpcml xmlns:xsi=" inubit 6.1: Workbench/Process Engine: System Connectors Guide

28 28 AS/400 Connector Dialog AS/400 Connector Properties instance" xsi:nonamespaceschemalocation="xpcml.xsd" version="4.0"> <program name="contractno.query" path="/xyz.lib/myprog.lib /ContractNoQuery.pgm"> <parameterlist> <stringparm name="client" passdirection="inout" length="1"> 2 </stringparm> <stringparm name="contractno" passdirection="inout" length="17"> 110 </stringparm> <stringparm name="contractnoknown" passdirection="inout" length="1"> 0 </stringparm> </parameterlist> </program> </xpcml> 2.2 Dialog AS/400 Connector Properties This dialog offers the following options: Settings Address Server name or IP address of the AS/400 system. User User name for accessing the AS/400 system. Password Password for the AS/400 system. Name of program Name of the program (without extension) to be started. Extended debug mode If selected, the debug output of the AS/400 system is added to the debug outputs of the inubit Process Engine inubit 6.1: Workbench/Process Engine: System Connectors Guide

29 AS/400 Connector Dialog AS/400 Connector Properties 29 Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

30 30 AS/400 Connector Dialog AS/400 Connector Properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

31 3 AS2 Connector 31 This section details the following topics: Module Variables of the AS2 Connector, p. 32 Receiving, Sending and Verifying AS2 Messages, p. 33 Dialog Descriptions, p. 36 Use An AS/2 Connector sends and receives business messages and receipts in accordance with Applicability Statement 2 (AS2). In AS2 rules for the secure exchange of structured MIME business messages using the HTTP protocol in a peer-to-peer network are defined. AS2 defines how the connection is established and how business messages are validated, sent, and acknowledged using MDNs (Message Disposition Notifications). The message's ownership and authenticity is validated by using a digital signature, and data security is ensured by means of encryption. Upon receipt of the message, the sender gets a digital Message Disposition Notification (MDN) as proof of timely delivery. The messages are packaged in an envelope using standard MIME structures for sending. The business messages can exist in XML format, EDI format (e.g. in ANSI X12, UN/EDIFACT), or in any other structured format. Refer to the IETF-AS2 specification at rfc4130.txt. The AS2 Connector has been successfully tested with the following products: Compinia ComAS2 OpenAS2 IP*Works AS2 Connector Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) inubit 6.1: Workbench/Process Engine: System Connectors Guide

32 32 AS2 Connector Module Variables of the AS2 Connector 3.1 Module Variables of the AS2 Connector Variables of the AS2 Connector Name AS2Subject ASMessageMDNOptions ASMessageMIC ASMessageMICALG The table contains all variables that are set by an AS2 Connector during its execution, irrespective of whether the connector is an input or output connector. The variables area available for the rest of the workflow s execution: Value Value of the HTTP header Subject in the input message. Value of the HTTP headers for Disposition-Notification-Options in the input message. Value of the calculated check sum of the input message. Name of the algorithm which was used for calculating the check sum. Variables of the AS2 Input Connector The table contains all variables that are set by the AS2 Input Connector Module variable ASMessageID ASMessageTo ASMessageFrom ASMessageError ASMessageDate ASMessageFailure Value IS of incoming AS message AS2 ID of receiver AS2 ID of sender Error message, including one the following: authentication-failed: If the signature check for the incoming message failed. decryption-failed: If decryption failed. sender-equals-receiver: If the sender and receiver are identical. For other error messages, refer to the AS2 specification. Timestamp of receipt in the format EEE, d MMM yyyy HH:mm:ss Z. The letters signify the following: E = work day (Monday to Sunday) d = day of the month (1 to 31) M = abbrevation of the month name y = Year (0 to 9) H = hour of the day (0 to 23) m = minute (0 to 59) s = second (0 to 59) Z = time zone (specification in accordance with RFC 822) Error message. Refer to AS2 specification inubit 6.1: Workbench/Process Engine: System Connectors Guide

33 AS2 Connector Receiving, Sending and Verifying AS2 Messages 33 Module variable ASMessageWarning Value Warning. Refer to AS2 specification. Refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351). 3.2 Receiving, Sending and Verifying AS2 Messages AS2 provides secure data transmission protocols via its secure transmission loop with asymmetric encryption. Thereby, messages can be encrypted as well as signed and, additionally, acknowledgements can be requested. For encryption and decryption both sender and recipient of a message have a key pair consisting of a public and private key and have shared their public keys with each other. This means that both sender and recipient have the public key of the other communication partner and each have their own private key that they never share MIME Structure When sending a message, the structure/packaging is built according to the following procedure, which depends on the respective configuration. When sending a message, you must adhere to the sequence of the steps, whereas, when receiving a message, you can execute the steps in any order. 1. The original MIME message is compressed optionally. You can control the content transfer encoding using the hidden messageencoding property. By default, binary is set. 2. The MIME message is signed optionally. You can change the digest algorithm of the S/MIME signature using the hidden messagedigest property. SHA1 (default), SHA384, SHA512, and SHA256 are supported. 3. The MIME message is encrypted optionally. 4. The MIME message is sent using the HTTP protocol. inubit 6.1: Workbench/Process Engine: System Connectors Guide

34 34 AS2 Connector Receiving, Sending and Verifying AS2 Messages for inubit 5.3 only If no content transfer encoding is supported, as of inubit build , you can deactivate it using the module property skiphttpencoding=true Workflow examples The following workflows illustrate sending and receiving an AS2 message and its acknowledgement (Message Disposition Notification, MDN). The modules are configured as follows: 1. SendMessagesRequireMDN The Output Connector encrypts the data to be transmitted using the public key of the receiver, sends the data and requests an asynchronous MDN as signed acknowledgement of receipt of the encrypted data from the receiver. The message contains (amongst others) - an ID which is stored in a directory, because it will be required later for identifying the MDN, - the address to which the MDN is to be sent, - a check sum of the message s content. 2. ReceiveMessages The Input Listener waits for incoming messages. As soon as a message arrives, the Connector decrypts it using its private key and starts the workflow. 3. StoreMessages The File Connector saves the message on the recipient s side. 4. SendMDN The Output Connector automatically creates the MDN, if one was requested inubit 6.1: Workbench/Process Engine: System Connectors Guide

35 AS2 Connector Receiving, Sending and Verifying AS2 Messages 35 The MDN contains the ID of the message, a check sum of the message s content and a signature. The signature is created by using the private key of the message recipient and guarantees that the MDN really was send by the message s recipient. The ID, address and check sum are automatically transferred via variables from the Input to the Output Connector. The Output Connector sends the MDN back to the sender. The MDN is send back automatically synchronously or asynchronously, according to the requirements of the sender (here: Output Connector SendMessagesRequireMDN). 5. ReceiveMDN The Input Listener waits for the MDN. As soon as it arrives, the ID contained in the MDN is stored into the directory, into which the ID was already stored when sending the message. The ID is used to find the data of the corresponding AS2 message which was stored in the file system. The check sums are compared with each other in order to guarantee that the message has arrived completely and correctly at the receiver. Additionally, the sender can check the signature by using the public key of the receiver. The Input Listener generates an XML output message according to the following structure: <?xml version="1.0" encoding="utf-8"?> <MDNReport> <MDNSignature>true</MDNSignature> <MIC>true</MIC> <Error>decryption-failed</Error> </MDNReport> The elements have the following meanings: - <MDNSignature> Signature for the receipt. - true, if the signature is valid. - false, if the receipt was not signed or if the result of the signature check shows an error. - <MIC> (Message Integrity Check) True or false depending on whether the checksums and the content match. - <Error> Placeholder for the following error elements: - Failure, Error, Warning: Contain a short error message described in the AS2 specification. - FailureMessage, ErrorMessage, WarningMessage: Contain detailed error messages (rarely supported). inubit 6.1: Workbench/Process Engine: System Connectors Guide

36 36 AS2 Connector Dialog Descriptions Refer to IETF-AS2 specification Dialog Descriptions This section details the following topics: Dialog AS2 Configuration, p. 36 Dialog AS S/MIME Configuration, p. 36 Dialog AS2 Listener Configuration, p. 37 Dialog Message Archive Configuration, p. 38 Dialog AS MDN Validator, p. 38 Dialog AS2 Listener Configuration, p. 38 Dialog AS2 Configuration, p. 38 Dialog AS Message Configuration, p. 39 Dialog S/Mime Configuration, p. 39 Dialog AS MDN Configuration, p. 40 Dialog HTTP(S) Server Configuration, p. 41 Dialog AS MDN Shipping Configuration (Sending MDN with Output Connector), p Dialog AS2 Configuration (Input Listener Connector) In the AS2 configuration dialog you define whether the connector should receive messages or acknowledgements Dialog AS S/MIME Configuration (Message Receipt with Input Listener Connector) This dialog offers the following options: inubit 6.1: Workbench/Process Engine: System Connectors Guide

37 AS2 Connector Dialog Descriptions 37 Verify signature If this option is selected, then signatures of all incoming messages are verified. For verification, you need the public key of that business partner, whose message you are receiving. Upload truststore or certificate (button) Opens a file explorer for uploading the public key. After having uploaded the public key, its validity is displayed above the button. Incoming message must be signed If selected, then incoming, unsigned messages cause an error. Decryption If this option is selected, then all incoming messages are decrypted. For this, you need your private key. Upload keystore (button) Opens a file explorer for uploading the key. After having uploaded the public key, its validity is displayed above the button. Incoming message must be encrypted If selected, then incoming, unsigned messages generate an error Dialog AS2 Listener Configuration (Output Connector/Input Listener) This dialog offers the following options: Server configuration URL URL of the Server where the inubit Process Engine with the AS2 Input Connector is installed. Per default, the URL follows the pattern: IBISHTTPUploadServlet/<module name> If required, adjust the address of the server. Authentication If authentication is required for your server, specify the relevant data here. inubit 6.1: Workbench/Process Engine: System Connectors Guide

38 38 AS2 Connector Dialog Descriptions Dialog Message Archive Configuration (MDN Receipt with Input Listener) Refer to Module Variables of the AS2 Connector (Workbench/ Process Engine: System Connectors Guide, chap. 3.1, p. 32) Dialog AS MDN Validator (Output Connector/MDN Receipt with Input Listener) Refer to Module Variables of the AS2 Connector (Workbench/ Process Engine: System Connectors Guide, chap. 3.1, p. 32) Dialog AS2 Listener Configuration (Receiving MDN with Listener/Sending Messages with Output Connector) In the dialog for the configuration of the AS2 Listener you define the settings of the server to which incoming messages should be send. Server configuration URL Address of the server, for example Authentication If the servers requires an authentication, select the option and enter the login and password which you have received from your business partner Dialog AS2 Configuration (Output Connector) In the dialog for the configuration of the output connector you specify whether the output connector should send messages or message acknowledgements inubit 6.1: Workbench/Process Engine: System Connectors Guide

39 AS2 Connector Dialog Descriptions Dialog AS Message Configuration (Sending Messages with Output Connector) This dialog offers the following options: Sender/Receiver (AS ID) Specify the sender and receiver AS ID (character string with max. 128 characters). You have to agree the sender and receiver AS IDs with your business partner prior to the first exchange of messages. Subject Meaningful description of the message. Encoding Select one of the encodings which corresponds to the encoding of your AS2 messages. If you want to transmit binary files such as multimedia data, leave this blank. MIME type Select a MIME type you which corresponds to the type of your AS2 message. If the type required is not provided here, enter it manually. Refer to for a list of MIME media types. File name Optionally, you can enter a name for the message content of the AS2 message, which is integrated into the Content- Disposition HTTP header as filename parameter Dialog S/Mime Configuration (Sending Messages with Output Connector) You use the dialog for AS S/MIME configuration to define if messages are to be signed, encrypted and/or compressed. Sign If selected, then all outbound messages are signed with their private keys. Valid until Displays the key validity date after loading the key. Upload keystore (button) Opens a file explorer for loading the key. inubit 6.1: Workbench/Process Engine: System Connectors Guide

40 40 AS2 Connector Dialog Descriptions Encrypt If encryption is selected, then all outbound messages are encrypted with the public key of your business partner. If your business partner does not use the inubit AS2 Connector to receive AS2 messages, ask your business partner which encryption algorithm is used by the partner's AS2 software beforehand. This is necessary because not all products support all algorithms. Encryption algorithm For selection of the encryption algorithm. DES_EDE3_CBC is default, since this is the most common method. On the receiver side, the procedure used to encrypt the message is automatically detected. Valid until Displays the validity date after uploading the key. Upload truststore or certificate (button) Opens a file explorer for loading the public key. Compress When activated, then messages are compressed corresponding to the S/MIME specification Dialog AS MDN Configuration (Sending Messages with Output Connector) In this dialog you define if you expect acknowledgements (MDN) from the receiver. Per default, synchronous acknowledgements are required. The recipient sends synchronous acknowledgements immediately when the corresponding messages have arrived. The acknowledgements are sent via HTTP to the address which is contained in the message. The Output Connector waits until the MDN has arrived. For storing the acknowledgements, add a File Connector to the workflow behind the Output Connector. Alternatively, you can state that you rather expect asynchronous acknowledgements and/or signed acknowledgements: Signed message disposition notification required If this option is selected, the recipient must sign the MDN which is sent back and validated by the MDN listener. Asynchronous MDN Asynchronous acknowledgements are sent temporally independently from the message. For receiving the MDN you need an AS2 Input Listener inubit 6.1: Workbench/Process Engine: System Connectors Guide

41 AS2 Connector Dialog Descriptions 41 Enter the URL to which the MDN is to be sent. The URL is transmitted without encryption via HTTP together with the message Dialog HTTP(S) Server Configuration (Sending Messages with Output Connector) In this dialog, you specify settings for the server to which the AS2 message is to be sent. Server configuration URL/SSL - Address of the server, for example - For configuring server and client authentication. Opens the Dialog SSL Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 24). Authentication If authentication is required to access the server, select the checkbox and enter the login and password that your business partner gave you for the server. Refer to Configuring SSL Connections and Server Authentication (inubit Process Engine: Administrator and Developer Guide, chap. 5.1, p. 61). Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog AS MDN Shipping Configuration (Sending MDN with Output Connector) Refer to Module Variables of the AS2 Connector (Workbench/ Process Engine: System Connectors Guide, chap. 3.1, p. 32). For loading the key store you need its alias and password! inubit 6.1: Workbench/Process Engine: System Connectors Guide

42 42 AS2 Connector Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

43 4 Backup Connector 43 This section details the following topics: Dialog Backup Connector Properties, p. 43 Use The Backup Connector saves the current system status or selected users or user groups and their data. You can start the Backup Connector in accordance with a schedule to save data automatically at regular intervals. Also refer to - Backup and Restore (inubit Process Engine: Administrator and Developer Guide, chap. 10, p. 131) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 4.1 Dialog Backup Connector Properties This dialog offers the following options: Backup file name Name Enter the name of the backup file. The file is written into the directory <inubit-installdir>/ server/ibis_root/ibis_data/backup. Write to output stream If selected, the stored data is handed over to the workflow as output message, additionally. Backup level System Saves the current status of the inubit software. The following directories are always saved: - inubit configuration (<inubit-installdir>/server/ ibis_root/conf, except for the EDI rules in the edi directory) inubit 6.1: Workbench/Process Engine: System Connectors Guide

44 44 Backup Connector Dialog Backup Connector Properties - inubit Process Engine log directory <inubit-installdir>/ server/ibis_root/log - User group admin (comprises all users) Users/User groups - For saving selected users resp. user groups. All workflows, modules, users and their subgroups and (optionally) their repository files and monitoring files are backed up. - In order to save all user groups, select the group admin. Then, the Backup connector waits until all workflows have completed their current tasks. Extended backup options inubit log database - System backup: The complete logging database is saved, including statuses and timeouts of the processes (<inubit-installdir>/ server/ibis_root/log). - User/user group backup: The data of selected users/user groups is saved. Repository - System backup: All data below the level Global is saved. - User/user group backup: The data of selected users/user groups is saved. Tasks Only for system backups: Saves all tasks of all users from the task database and from the task directory <inubit-installdir>/server/ibis_root/ tasks, the messages and the variables from waiting processes, which, for example, occur at Wait modules and Multiplexers. For information about changing the inubit task database refer to Switching inubit Task Database (inubit Process Engine: Administrator and Developer Guide, chap. 8.3, p. 122). Portal Backups all organizations and communities of the Liferay portal server, which are selected in the Portal area. Portal Displays all organizations and communities which exist in the configured Liferay portal server. When backing up the system including the portal, all selected organizations and communities are saved inubit 6.1: Workbench/Process Engine: System Connectors Guide

45 5 Business Object Connector 45 This section details the following topics: Functional Principle, p. 45 Using Object Mode, p. 46 Using Query Mode, p. 49 Updating and Deleting Master Data References, p. 54 Dialog Business Object Connector Settings, p. 54 Use The Business Object Connector (BO Connector) enables you to manage XML-based business objects that are processed in your Technical Workflows in a relational database. The BO Connector takes care of the saving and loading of business objects in the database in a form that is transparent for the developer and generates suitable SQL statements for the selected database. Hence, a change of database no longer necessitates changes to the Technical Workflow; it suffices to configure a different database in the Module Wizard. Also refer to - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 5.1 Functional Principle The BO Connector maps the structures of the business objects to the relational structures of the database. For this mapping, the BO Connector needs an XML Schema which describes the structures and relationships of the XML-based business objects. The XML Schema can be addressed using the HTTP protocol or stored in the repository. When you first add a business object, tables for the business object are generated in the database according to the XML Schema. Object and query mode You can use the BO Connector in the following modes: Object mode inubit 6.1: Workbench/Process Engine: System Connectors Guide

46 46 Business Object Connector Using Object Mode The operation to be executed is specified in the BO Connector. The business object can be directly transferred to the BO Connector as a complex XML element. Refer to Using Object Mode (Workbench/Process Engine: System Connectors Guide, chap. 5.2, p. 46). Query mode In query mode, you can execute several and different types of operations for every time the connector is executed. The operations to be executed are defined in the input message of the connector. Refer to Using Query Mode (Workbench/Process Engine: System Connectors Guide, chap. 5.3, p. 49). Object identifiers The IDs for identifying the objects in the database are generated automatically. 5.2 Using Object Mode Create/Update/Delete Operations, p. 46 Read Operations, p. 48 Overview In object mode, the operation that is defined in the Module Wizard of the BO Connector is always executed. Refer to option Operation (Workbench/Process Engine: System Connectors Guide, chap. 5, p. 54) Create/Update/Delete Operations For create, update and delete operations, the BO Connector expects an XML-based business object as the input message and outputs the data of the object and namespace information. By default, the object IDs are also output but you can deactivate that. Refer to Output default identifiers (Workbench/Process Engine: System Connectors Guide, chap. 5, p. 55) inubit 6.1: Workbench/Process Engine: System Connectors Guide

47 Business Object Connector Using Object Mode 47 Prerequisites The structure of the business object is conform to the XML Schema that is defined in the BO Connector. Example of an input message Example of an output message inubit 6.1: Workbench/Process Engine: System Connectors Guide

48 48 Business Object Connector Using Object Mode Read Operations For read operations, the BO Connector expects, as the input message, the root element and ID of the business object and outputs the details of the business object incl. the namespace information. By default, the object IDs are also output but you can deactivate that. Refer to Output default identifiers (Workbench/Process Engine: System Connectors Guide, chap. 5, p. 55). Prerequisites The structure of the business object is conform to the XML Schema that is defined in the BO Connector. Example of an input message Example of an output message inubit 6.1: Workbench/Process Engine: System Connectors Guide

49 Business Object Connector Using Query Mode Using Query Mode This section details the following topics: Supported Query Attributes, p. 50 Query mode executes the operations that are defined in the input message of the BO Connector. You need an XSLT Converter to create an input message: The XSLT Converter generates the input message on the basis of a mapping template and transfers it to the BO Connector. Mapping template path In the repository, the mapping template is located in Global > System > Mapping Templates > Business Object Connector > BO_Queries.xml. Defining operations In every input message, you can define several operations, including different types of operations such as CREATE and DELETE. The operations are defined in the type attributes of the query elements. If no type attribute is specified explicitly, a READ is executed. Example of an input message The following input message is used to first read all purchase orders from the database and then delete them. <?xml version="1.0" encoding="utf-8"?> <queries> <!-- READ (default, if no type is defined) --> <query xmlns:bo=" /order </query> <!-- DELETE --> <query xmlns:bo=" type="delete"> /order </query> </queries> Prerequisites You have an XML example message that represents your business object. The structure of the business object must match the XML Schema that is specified in the Module Wizard of the BO Connector. inubit 6.1: Workbench/Process Engine: System Connectors Guide

50 50 Business Object Connector Using Query Mode Proceed as follows 1. Create an XSLT Converter. 2. Load the mapping template into the XML target file area: a. Click the arrow menu and choose Open > Repository. The Repository Browser opens. b. Navigate to the mapping template and load it. Refer to Mapping template path (Workbench/Process Engine: System Connectors Guide, chap. 5, p. 49). 3. Drag the queries element underneath the desired operation up into the XSLT stylesheet area and to the template element. 4. To have another operation executed as well, add a query element with the desired attribute. 5. Load the XML example message into the XML source file area. 6. Depending on the desired result, replace the MyObject elements of the template with the root elements of your business objects or enter an XPath expression. Refer to the mapping template for explanations on the attributes. 7. Test the XSLT file. Refer to Testing the XSLT Stylesheet (Workbench/Process Engine: Modules Guide, chap. 5.2, p. 143). 8. If the test is successful you can publish the XSLT Converter. 9. Create a BO Connector. 10. Connect the XSLT Converter to your BO Connector Supported Query Attributes You define query attributes as follows: <Attribute>="<Value>", for example: type="create". For a list of the attributes which are supported for the different operations refer to the mapping template, section Mapping template path (Workbench/Process Engine: System Connectors Guide, chap. 5, p. 49). Attribute Description Allowed Values type Defines the operation of the query. create: Create object read: Read object (default) update: Change object delete: Delete object inubit 6.1: Workbench/Process Engine: System Connectors Guide

51 Business Object Connector Using Query Mode 51 Attribute Description Allowed Values queryid outputobjects outputids commitcount pagenum PageSize order orderby outputjson outputpurejson Defines the query id which is output in the resultset for validation. Prevents the output of objects in resultsets. Suppresses the output of the technical default id bo:objectid. Defines the commit interval for batch operations. Paging: Defines the page to read in reference to the value defined in the attribute PageSize. Defines the number of entries per page for the paging. Defines the sort order within the resultset. For selected ComplexTypes the set is sorted by bo:objectid, for selected SimpleTypes the set is sorted by the Simple- Type value. The attribute order can also be used with an explicit element list. Defines the sort order within the resultset with explicit elements of the Complex- Type. All elements within the resultset are output in JSON notation. The complete output of the BO Connector is in JSON notation. Note: This attribute must be defined at the root element! Query-Id true: Output objects (default) false: Do not output objects true: Output object id (default) false: Do not output object id, e. g. for triggering Web Services. 50: Commit after 50 objects 25: Commit after 25 objects 0: Commit at the end of the module execution (default) autocommit: Commit after each operation 0: No paging (default) Positive integer value 0: No paging (default) Positive integer value Asc: Ascending Desc: Descending No attribute defined: No sorting Element Sort order Multiple sort orders are separated by commas. Example: orderby="myelement1 Desc" true: JSON notation, e. g. for AJAX responses false: XML notation (default) true: JSON notation, e. g. for AJAX responses false: XML notation (default) inubit 6.1: Workbench/Process Engine: System Connectors Guide

52 52 Business Object Connector Using Query Mode Attribute Description Allowed Values zipoutput The complete resultset is compressed with GZIP. Note: This attribute must be defined at the root element! true: compressed resultset, e. g. for backups. For restoring the backup the BO Connector can import the compressed resultset. false: uncompressed resultset (default) Saving and Importing a Database Query Use The BO Connector enables you to save and import the results of a database query including the entire database even compressed. The following use scenarios are possible: Migrating a database from one database system to another Saving a database Restoring a saved database How it works The writing BO Connector writes the result of a database query (resultset) in an output message. The reading BO Connector automatically recognizes whether an input message is the result of a database query and imports it into the specified database. All missing tables and indexes are created automatically. The imported objects are added to the database with new object IDs. You also have the option of writing the output message of the writing BO Connector to the file system via a file connector, for example to transfer a database from a test system to a production system. You import the saved file via a file connector and transfer it to the importing BO Connector. You also have the option of compressing the output message. Prerequisites Writing a database query: You have access to the database that you want to save or migrate. Importing a saved database query: - You have access to the database in which you want to save data from the output database or to which you want to migrate data inubit 6.1: Workbench/Process Engine: System Connectors Guide

53 Business Object Connector Using Query Mode 53 - You have access to the data you want to import. Creating a query as an input message Proceed as follows 1. Create and name a new XSLT Converter. 2. Go to the XSLT Converter Properties tab and activate the Ignore input message checkbox. 3. Go to the Module Editor tab and create a query like in the following example: - If you wish, set the attribute zipoutput=true to save memory space. - Set the attribute outputids=false to prevent the object IDs from being written. The object IDs are written automatically when imported into the new database. - Set the attribute order=asc to define that the oldest database objects are written first. Creating a BO Connector to write the data Proceed as follows 1. Create and name a new BO Connector. 2. Go to the Business Object Connector Settings tab. 3. Configure the persistence layer and the connection to the database whose data you want to output and write. The settings for the object mode attribute are ignored since you are using the query specified in the XSLT Converter configured above as the input message. 4. Connect the XSLT Converter created above with the BO Connector. Creating a BO Connector to read the saved data Proceed as follows 1. Create and name a new BO Connector. 2. Go to the Business Object Connector Settings tab. inubit 6.1: Workbench/Process Engine: System Connectors Guide

54 54 Business Object Connector Updating and Deleting Master Data References 3. Configure the persistence layer and the connection to the database into which you want to import data. The settings for the object mode attribute are ignored since you are using the output message of the BO Connector configured above as the input message. 4. Connect the BO Connector created above with the new BO Connector you just created. 5.4 Updating and Deleting Master Data References Master data, e.g. address data and customer data, are defined through the cardinality 0..1 oder They are treated in a specific manner. If you have not specified a specific master data for a delete or update operation for a business object, the master data will not be deleted or updated, but only the reference of the business object to the master data will be deleted or updated. 5.5 Dialog Business Object Connector Settings This dialog offers the following options: Persistence layer definition XML Schema The schema is required for creating database tables for the business objects. Enter the HTTP URL at which XML Schema can be accessed or click the button to load an XML Schema from the repository. Object identifiers The Identifier column is used for selecting an element in the XML Schema with which the business object can be identified uniquely. Object mode Operation Select the operation that the BO Connector is supposed to execute in object mode. The following operations are available: - Create: Adds a business object. - Read: Reads a business object inubit 6.1: Workbench/Process Engine: System Connectors Guide

55 Business Object Connector Dialog Business Object Connector Settings 55 - Update: Changes the details of a business object. - Delete: Deletes a business object. In query mode, the selected operation is ignored! Refer to Object and query mode (Workbench/Process Engine: System Connectors Guide, chap. 5, p. 45) Output default identifiers The standard ID you need in object mode to access a specific object (only relevant in object mode). If the option is not selected, no IDs are output. Database connection Presetting Select a pre-configured database, to fill the Dialect, Database URL and Database driver class fields with sensible entries. Dialect Select the Hibernate dialect which is suitable for your database version. Database URL Is pre-filled if you have selected a pre-configured database. Enter the host, port and database name. User/password Enter the access data to the database you have specified in the database URL field. The entry depends on your database. Connection pooling Activates connection pooling. If the connection pooling is activated, physical database connections are reused. This accelerates the processing of the SQL statements. After being used, connections are not closed but stored and thus made available for further use. So there is no need to open a new connection for each access. The Settings button opens the dialog for configuring connection pooling. Refer to Dialog Connection Pooling Properties (Workbench/ Process Engine: System Connectors Guide, chap , p. 85). Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

56 56 Business Object Connector Dialog Business Object Connector Settings inubit 6.1: Workbench/Process Engine: System Connectors Guide

57 6 Database Connector 57 This section details the following topics: Querying Metadata, p. 58 Creating Static SQL Queries, p. 58 Creating Dynamic XML-Queries, p. 59 XML Queries: Structure and Examples, p. 60 Dialog Descriptions, p. 79 Use The Database Connector establishes a connections to a database via a JDBC or ODBC interface and offers the following functionalities: Metadata queries Static database SQL queries Dynamic database XML queries No CLOBs can be passed in stored procedures! However, the Database Connector supports the sending/saving of data as CLOB data type for Oracle 9.* databases. Connector types Input Connector Sends a static SQL query or a metadata query to a database and hands the result over to its downstream module. Medium/Output Connector Sends a static SQL query, a metadata query or a dynamic XML query to the database and hands over the result to its downstream module. Dynamically created XML queries are useful, for example, if the data which must be modified is known at runtime only. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) inubit 6.1: Workbench/Process Engine: System Connectors Guide

58 58 Database Connector Querying Metadata 6.1 Querying Metadata To retrieve information about a database you create a metadata query. By doing so, you can obtain information about the data type, column width and number of decimal places of each column of all database tables or only of a selected table. Proceed as follows 1. Create a Technical Workflow containing a Database Connector. 2. At the Database Connector in the in the Function area, activate the option Read metadata. 3. Click Next. The Dialog Metadata (Workbench/Process Engine: System Connectors Guide, chap , p. 82) is displayed. 4. Define which metadata of which table should be read. To check your definitions you can display a preview of the output format in the same dialog. 5. Click Finish to close the wizard. 6. Publish and activate the Technical Workflow. 6.2 Creating Static SQL Queries Prerequisites You need the metadata of your database, at least table and column names need to be known. Refer to Querying Metadata (Workbench/Process Engine: System Connectors Guide, chap. 6.1, p. 58). Proceed as follows 1. Create a Technical Workflow containing a Database Connector. 2. At the Database Connector in the Dialog Database Connection and Query Type (Workbench/Process Engine: System Connectors Guide, chap , p. 80) in the Function area, activate the option Execute static query. 3. Click Next. The Dialog Static Query (Workbench/Process Engine: System Connectors Guide, chap , p. 83) is displayed. 4. Enter the SQL query. 5. Click Next. The Dialog Query Result (Workbench/Process Engine: System Connectors Guide, chap , p. 84) is displayed inubit 6.1: Workbench/Process Engine: System Connectors Guide

59 Database Connector Creating Dynamic XML-Queries Define how the query s result should be output. 7. Click Finish to close the wizard. 8. Publish and activate the Technical Workflow. The SQL query is send to the database when the Database Connector s is executed. 6.3 Creating Dynamic XML-Queries Overview In order to dynamically create XML queries at runtime, you need an XSLT Converter, which you connect with the Database Connector: The XSLT Converter converts the XML based input message by using an XSLT stylesheet into an XML query and hands this XML query over to the Database Connector for execution. Prerequisites The following data is required. Metadata of your database, at least table and column names are known. Refer to Querying Metadata (Workbench/Process Engine: System Connectors Guide, chap. 6.1, p. 58). Sample XML input message. Proceed as follows 1. Create a Technical Workflow containing a Database Medium or Output Connector. 2. In the Database Connector in the Dialog Database Connection and Query Type (Workbench/Process Engine: System Connectors Guide, chap , p. 80) activate the option Execute input message as query in the Function area. 3. Publish the Database Connector. 4. Add an XSLT Converter to your Technical Workflow. 5. Connect both modules. inubit 6.1: Workbench/Process Engine: System Connectors Guide

60 60 Database Connector XML Queries: Structure and Examples 6. Open the XSLT Converter for editing and display the XSLT Mapper. 7. In the XML source file area open the menu, select Open and load your sample input message. 8. Create the XML query a. In the XML target file area, open the Database Explorer: b. Let the database explorer guide you through the creation of the XML query. After finishing the Database Explorer, the XML query is displayed in the XML target file. c. Drag and drop the queries element on the xsl:template element. d. Map the elements contained in the sample input message on the query elements. Refer to XML Queries: Structure and Examples (Workbench/ Process Engine: System Connectors Guide, chap. 6.4, p. 60). In order to be able to map ResultSet entries to queries, add the attribute queryid to the query. In the ResultSet, this attribute is filled with the value of the corresponding query. 9. Publish the Technical Workflow. 6.4 XML Queries: Structure and Examples This section details the following topics: Structure, p. 61 Select: Displaying Data, p. 64 Select Distinct, p. 65 Join: Data from Different Tables, p inubit 6.1: Workbench/Process Engine: System Connectors Guide

61 Database Connector XML Queries: Structure and Examples 61 Insert: Inserting Data Sets, p. 67 Update: Updating Data Sets, p. 68 UpdateOrInsert, p. 69 Delete: Deleting Data Sets, p. 70 Multiple SQL Statements in a Single Query, p. 71 Passing SQL Statements Directly: Force, p. 73 Subqueries: Subselects, p. 74 Call: Calling Stored Procedures, p Structure The underlying XML syntax is identical for all SQL queries. <queries> Element that encloses a set of SQL statements. <query> Initial definition of an SQL statement. This can occur several times, e.g. to send several SQL statements in a single query. Attribute Mandatory field Permitted values Explanation type Yes select insert update delete call Type of SQL statement properties No force If the value force is set, an SQL statement specified in the <value> element is executed immediately. All other specifications are ignored. forceresult Nein true/false If the value true is set, stored procedures can return ResultSets. queryid Nein In the ResultSet, this attribute is filled with the value of the corresponding query. <value> For immediate passing of an SQL statement. To enable this, the properties attribute must be set to force in the <query> element. All other specifications are ignored. <tables> Introductory XML element for the definition of an SQL statement. inubit 6.1: Workbench/Process Engine: System Connectors Guide

62 62 Database Connector XML Queries: Structure and Examples <table> Introductory XML element for the definition of a single SQL statement. It can be used with the attribute type="subselect" as a subquery in a main query. It can occur multiple times. Attribute Mandatory field Permitted values Alias No Arbitrary identifier Explanation Type No subselect Specifies that it is handled as a subquery. <tablenames> Enclosing XML element for all table names queried in the SQL statement. <tablename> Table name queried in the SQL statement. It can occur multiple times. Corresponds to the FROM part of an SQL statement. Attribute Mandatory field Permitted values Explanation alias No Arbitrary identifier Alias name of the table <fields> Enclosing XML element for all column names to be used in the SQL statement. <field> XML element for the name of the table column queried in the XML statement. It can occur multiple times. Corresponds to the Select part of an SQL statement. Attribute Mandatory field Permitted values Explanation Alias No Arbitrary identifier Alias name of the column <fieldname> Name of a table column to be used in the SQL statement. <fieldvalue> Values for individual fields or the name of a subquery (only INSERT and UPDATE). Attribute Mandatory field Permitted values Explanation type No subselect, force subselect: For executing a subquery force: Automatic type recognition is disabled for this field. The text for <fieldvalue> is passed immediately to the database. This is sensible if you want to e.g. execute database functions such as AVG or MAX. <conditions> (not for INSERT) inubit 6.1: Workbench/Process Engine: System Connectors Guide

63 Database Connector XML Queries: Structure and Examples 63 Enclosing XML element for the WHERE condition of an SQL statement. Several <conditions> elements can be nested to group or parenthesize statements. <condition> Values for a criterion in the WHERE condition of an SQL statement. It can occur multiple times. Attribute Mandatory field Permitted values type Yes AND, OR, NOT, AND NOT, OR NOT <leftvalue> Explanation Column name on the left-hand side of a criterion in a WHERE condition. <operation> Operator within a criterion in a WHERE condition, e.g. =, <, >, >=, <=, IN, NOT IN <rightvalue> Contains the value on the right-hand side of a criterion in a WHERE condition. This can be a value, a column name, or the name of a Subselect. Attribute Value for linking to other criteria in further <condition> elements. AND is the default value. Mandatory field Permitted values Explanation type No subselect, force subselect: For executing a subquery force: Automatic type recognition is disabled for this field. The text for <rightvalue> is passed immediately to the database. This may for example be sensible if you want to immediately execute integrated database functions. <sortorders> (only for SELECT) Sorts the outputs in ascending or descending order in accordance with one field. <sort> Field that can be used as a sorting criterion. Attribute Mandatory field Permitted values order No ASC (ascending) DESC (descending) Explanation Sort order inubit 6.1: Workbench/Process Engine: System Connectors Guide

64 64 Database Connector XML Queries: Structure and Examples <tail> The value of the element is appended to the generated SQL request. This enables database-specific SQL extensions to be added. The figure below depicts a Select in a tree structure: Select: Displaying Data SQL SELECT name, address, phone, fax FROM addresses WHERE name = "Georg Miller" ORDER BY name ASC, address DESC XMLQuery <?xml version="1.0" encoding="iso "?> <queries> <query type="select"> <tables> <table> <tablenames> <tablename>addresses</tablename> </tablenames> <fields> inubit 6.1: Workbench/Process Engine: System Connectors Guide

65 Database Connector XML Queries: Structure and Examples 65 <field> <fieldname>name</fieldname> </field> <field> <fieldname>address</fieldname> </field> <field> <fieldname>phone</fieldname> </field> <field> <fieldname>fax</fieldname> </field> </fields> <conditions> <condition> <leftvalue>name</leftvalue> <operation>=</operation> <rightvalue>georg Miller</rightValue> </condition> </conditions> <sortorders> <sort>name</sort> <sort order="desc">address</sort> </sortorders> </table> </tables> </query> </queries> Select Distinct With a Select Distinct, all of the different values of a table are returned. SQL SELECT DISTINCT department FROM employee XMLQuery There are two ways of formulating a SELECT DISTINCT: 1. Specify DISTINCT for the column name: inubit 6.1: Workbench/Process Engine: System Connectors Guide

66 66 Database Connector XML Queries: Structure and Examples <queries> <query type="select"> <tables> <table> <tablenames> <tablename>employee</tablename> </tablenames> <fields> <field> <fieldname>distinct department</ fieldname> </field> </fields> </table> </tables> </query> </queries> 2. Use the properties="force" attribute to pass the query immediately: <queries> <query type="select" properties="force"> <value>select DISTINCT department FROM employee</value> </query> </queries> Join: Data from Different Tables A join is a query that relates the datasets of two or more different table columns with each other, for example: SQL SELECT * FROM garden furniture, categories WHERE garden furniture.categoryno = categories.categorynumber XMLQuery <?xml version="1.0" encoding="iso "?> <queries> <query type="select"> <tables> inubit 6.1: Workbench/Process Engine: System Connectors Guide

67 Database Connector XML Queries: Structure and Examples 67 <table> <tablenames> <tablename>garden furniture</tablename> <tablename>categories</tablename> </tablenames> <fields> <field> <fieldname>*</fieldname> </field> </fields> <conditions> <condition> <leftvalue>gardenfurniture.categoryno</ leftvalue> <operation>=</operation> <rightvalue>categories.categorynumber</ rightvalue> </condition> </conditions> </table> </tables> </query> </queries> Insert: Inserting Data Sets You use an INSERT to add a dataset to a table. SQL INSERT INTO addresses (name, address, phone, fax) VALUES ("Georg Miller", "Hauptstrasse 7", "253263", "253264") XMLQuery <?xml version="1.0" encoding="iso "?> <queries> <query type="insert"> <tables> <table> <tablenames> <tablename>addresses</tablename> </tablenames> inubit 6.1: Workbench/Process Engine: System Connectors Guide

68 68 Database Connector XML Queries: Structure and Examples <fields> <field> <fieldname>name</fieldname> <fieldvalue>georg Miller</fieldValue> </field> <field> <fieldname>address</fieldname> <fieldvalue>hauptstrasse 7</fieldValue> </field> <field> <fieldname>phone</fieldname> <fieldvalue>253263</fieldvalue> </field> <field> <fieldname>fax</fieldname> <fieldvalue>253264</fieldvalue> </field> </fields> </table> </tables> </query> </queries> Update: Updating Data Sets You use an UPDATE to update existing datasets in a table. SQL UPDATE addresses SET address = "Hauptstrasse 8" WHERE name = "Georg Miller" XMLQuery <?xml version="1.0" encoding="iso "?> <queries> <query type="update"> <tables> <table> <tablenames> <tablename>addresses</tablename> </tablenames> inubit 6.1: Workbench/Process Engine: System Connectors Guide

69 Database Connector XML Queries: Structure and Examples 69 <fields> <field> <fieldname>address</fieldname> <fieldvalue>hauptstrasse 8</fieldValue> </field> </fields> <conditions> <condition> <leftvalue>name</leftvalue> <operation>=</operation> <rightvalue>georg Miller</rightValue> </condition> </conditions> </table> </tables> </query> </queries> UpdateOrInsert This SQL statement represents the Insert and Update SQL statements. First, an attempt is made to update a dataset; if this is not possible because the dataset is not available, the dataset is inserted. The Update is executed first because it is less time-consuming than the Insert. <queries> <query type="updateorinsert"> <tables> <table> <tablenames> <tablename>ordertable</tablename> </tablenames> <fields> <field skip="update"> <fieldname>orderno</fieldname> <fieldvalue>customer11</fieldvalue> </field> <field> <fieldname>customer</fieldname> <fieldvalue>123</fieldvalue> </field> inubit 6.1: Workbench/Process Engine: System Connectors Guide

70 70 Database Connector XML Queries: Structure and Examples <field> <fieldname>text1</fieldname> <fieldvalue>info1</fieldvalue> </field> <field> <fieldname>text2</fieldname> <fieldvalue>info2</fieldvalue> </field> </fields> <conditions> <condition type="or"> <leftvalue>orderno</leftvalue> <operation>=</operation> <rightvalue>customer11</rightvalue> </condition> </conditions> </table> </tables> </query> </queries> Delete: Deleting Data Sets You use a Delete to delete datasets. In the example below, all data on Georg Miller is deleted. SQL DELETE FROM addresses WHERE name="georg Miller" XMLQuery <?xml version="1.0" encoding="iso "?> <queries> <query type="delete"> <tables> <table> <tablenames> <tablename> addresses </tablename> inubit 6.1: Workbench/Process Engine: System Connectors Guide

71 Database Connector XML Queries: Structure and Examples 71 </tablenames> <conditions> <condition> <leftvalue>name</leftvalue> <operation>=</operation> <rightvalue>georg Miller</rightValue> </condition> </conditions> </table> </tables> </query> </queries> Multiple SQL Statements in a Single Query If the SQL queries derive from input messages, multiple statements can also be used in a single query. This is not possible for static queries. XMLQuery <?xml version="1.0" encoding="iso "?> <queries> <query type="insert"> <tables> <table> <tablenames> <tablename>one</tablename> </tablenames> <fields> <field> <fieldname>id</fieldname> <fieldvalue>1</fieldvalue> </field> <field> <fieldname>message</fieldname> <fieldvalue>simmer steak</fieldvalue> </field> <field> <fieldname>date</fieldname> <fieldvalue> :20: inubit 6.1: Workbench/Process Engine: System Connectors Guide

72 72 Database Connector XML Queries: Structure and Examples </fieldvalue> </field> <field> <fieldname>value</fieldname> <fieldvalue>10.12</fieldvalue> </field> </fields> </table> </tables> </query> <query type="select"> <tables> <table> <tablenames> <tablename>one</tablename> </tablenames> <fields> <field> <fieldname>*</fieldname> </field> </fields> <conditions> <condition type="or"> <leftvalue>id</leftvalue> <operation>=</operation> <rightvalue>1</rightvalue> </condition> </conditions> </table> </tables> </query> <query type="update"> <tables> <table> <tablenames> <tablename>one</tablename> </tablenames> <fields> <field> <fieldname>id</fieldname> <fieldvalue>2</fieldvalue> </field> </fields> <conditions> inubit 6.1: Workbench/Process Engine: System Connectors Guide

73 Database Connector XML Queries: Structure and Examples 73 <condition type="or"> <leftvalue>id</leftvalue> <operation>=</operation> <rightvalue>1</rightvalue> </condition> </conditions> </table> </tables> </query> <query type="delete"> <tables> <table> <tablenames> <tablename>one</tablename> </tablenames> </table> </tables> </query> </queries> Passing SQL Statements Directly: Force XMLQuery <?xml version="1.0" encoding="iso "?> <xsl:stylesheet xmlns:xsl=" XSL/Transform" version="1.0"> <xsl:output method="xml" encoding="iso "/> <xsl:template match="/"> <queries> <query type="select" properties="force"> <value> create table trade_user ( id_user NUMBER(20,0) PRIMARY KEY, since_user NUMBER(15,0), lastlogin_user NUMBER(15,0), sex_user NUMBER(1,0), language_user VARCHAR2(5), title_user VARCHAR2(4000), firstname_ user VARCHAR2(200), lastname_user VARCHAR2(200), company_user NUMBER(20,0), function_user VARCHAR2(4000), street_user VARCHAR2(4000), zip_ user VARCHAR2(4000), land_user VARCHAR2(4000), city_ user VARCHAR2(4000), phone_user VARCHAR2(4000), mobile_user VARCHAR2(4000), fax_user inubit 6.1: Workbench/Process Engine: System Connectors Guide

74 74 Database Connector XML Queries: Structure and Examples VARCHAR2(4000), _user VARCHAR2(200) NOT NULL UNIQUE, web_user VARCHAR2(4000), via_user VARCHAR2(4000), enable_user NUMBER(2,0), comment_ user VARCHAR2(4000), abbo_news_user NUMBER(1,0), abbo_mail_user NUMBER(1,0), keyaccount_user NUMBER(20,0), lastforum_user NUMBER(20,0), contentarea_user VARCHAR2(4000), deliveryplace_user VARCHAR2(4000) DEFAULT '1', originplace_user VARCHAR2(4000) DEFAULT '1', sms_mail_user VARCHAR2(1900), customer_protection_user NUMBER(1,0) ) </value> </query> <query type="select" properties="force"> <value> insert into xtrade_user( id_user, firstname_user, lastname_user, company_user, _user ) values (1,'Hans','Müller',1,'h.mueller@karstadt.de') </value> </query> <query properties="force"> <value> DROP TABLE "ORATEST"".TESTTABLE" </value> </query> </queries> </xsl:template> </xsl:stylesheet> Subqueries: Subselects You can nest SQL queries to evaluate the result of a Subselect in the same Select. SQL SELECT deliverynoteid, creationdate FROM deliverynotetable WHERE factory=(select factory FROM ShippingTable WHERE status!=x AND TransportId= ) AND gate=(select gate FROM ShippingTable WHERE status!=x AND TransportId= ) AND status = F inubit 6.1: Workbench/Process Engine: System Connectors Guide

75 Database Connector XML Queries: Structure and Examples 75 XMLQuery For each Subselect, an additional table element with the attributes type="subselect" and alias=[nameofsubselects] is created. The table element must come before the main Select. The result of the Subselect is integrated into the main Select in field and/or condition elements using the type="subselect" attribute. The value of the field and/or condition element is the name of the Subselect: [ ] <tables> <table type="subselect" alias="subfactory"> <tablenames> <tablename>shippingtable</tablename> </tablenames> <fields> <field> <fieldname>factory</fieldname> </field> </fields> <conditions> <condition type="and"> <leftvalue>status</leftvalue> <operation>!=</operation> <rightvalue>x</rightvalue> </condition> <condition type="and"> <leftvalue>transportid</leftvalue> <operation>=</operation> <rightvalue> <xsl:value-of select="formprepare/ Response/Panel/Transports/SLBno"/> </rightvalue> </condition> </conditions> </table> <table type="subselect" alias="subgate"> <tablenames> <tablename>shippingtable</tablename> </tablenames> <fields> <field> <fieldname>gate</fieldname> </field> </fields> <conditions> inubit 6.1: Workbench/Process Engine: System Connectors Guide

76 76 Database Connector XML Queries: Structure and Examples <condition type="and"> <leftvalue>status</leftvalue> <operation>!=</operation> <rightvalue>x</rightvalue> </condition> <condition type="and"> <leftvalue>transportid</leftvalue> <operation>=</operation> <rightvalue> <xsl:value-of select="formprepare/ Response/Panel/Transports/SLBno"/> </rightvalue> </condition> </conditions> </table> <table> <tablenames> <tablename>deliverynotetable</tablename> </tablenames> <fields> <field> <fieldname>deliverynoteid</fieldname> </field> <field> <fieldname>creationdate</fieldname> </field> </fields> <conditions> <condition type="and"> <leftvalue>factory</leftvalue> <operation>=</operation> <rightvalue type="subselect"> subfactory </rightvalue> </condition> <condition type="and"> <leftvalue>gate</leftvalue> <operation>=</operation> <rightvalue type="subselect"> subgate </rightvalue> </condition> <condition type="and"> <leftvalue>status</leftvalue> <operation>=</operation> inubit 6.1: Workbench/Process Engine: System Connectors Guide

77 Database Connector XML Queries: Structure and Examples 77 <rightvalue>f</rightvalue> </condition> </conditions> </table> </tables> Call: Calling Stored Procedures In a stored procedure, an entire sequence of statements can be stored under the same name, made available on the database server, and executed. The example below depicts the calling of stored procedures using the <method name="name="> element, with and without the passing of parameters: XMLQuery <?xml version="1.0" encoding="iso "?> <xsl:stylesheet xmlns:xsl=" XSL/Transform" version="1.0"> <xsl:output method="xml" encoding="iso "/> <xsl:template match="/"> <queries> <query type="call"> <method name="testproc_withoutparam"/> </query> <query type="call"> <method name="testproc_in"> <parameter direction="in" type="decimal">2 </parameter> </method> </query> <query type="call"> <method name="testproc_out"> <parameter direction="out" type="varchar"/> </method> </query> <query type="call"> <method name="testproc_inout"> inubit 6.1: Workbench/Process Engine: System Connectors Guide

78 78 Database Connector XML Queries: Structure and Examples <parameter direction="inout" type="numeric"> 4 </parameter> </method> </query> <query type="call"> <method name="testproc_inout2"> <parameter direction="in" type="numeric">5 </parameter> <parameter direction="out" type="numeric">5 </parameter> </method> </query> <query type="call"> <method name="testfunc_out"> <result type="date"/> </method> </query> <query type="call"> <method name="testfunc_inout"> <parameter type="numeric" direction="in">2 </parameter> <result type="numeric"/> </method> </query> </queries> </xsl:template> </xsl:stylesheet> Using the name attribute In case no name attribute is used for the query parameters, the order of the parameters must match the order in the query. Example: <query type="call"> <method name="testproc_inout2"> <parameter direction="in" type="numeric">5</ parameter> <parameter direction="in" type="varchar">5</ parameter> inubit 6.1: Workbench/Process Engine: System Connectors Guide

79 Database Connector Dialog Descriptions 79 <parameter direction="out" type="numeric">5</ parameter> </method> </query> We recommend to use the name attribute for stored procedures and functions. A change in the order of incoming parameters does not have any negative effect on the workflow due to the fact that the paramter values are referenced the by the name attribute. Example with optional name attribute: <query type="call"> <method name="testproc_inout2"> <parameter direction="in" name="mynumericparam" type="numeric">5</parameter> <parameter direction="in" name="myvarcharparam" type="varchar">5</parameter> <parameter direction="out" type="numeric">5</ parameter> </method> </query> <parameter direction="out" type="numeric">5</ parameter> </method> </query> 6.5 Dialog Descriptions This section details the following topics: Dialog Database Connection and Query Type, p. 80 Dialog Metadata, p. 82 Dialog Static Query, p. 83 Dialog Query Result, p. 84 Dialog Connection Pooling Properties, p. 85 inubit 6.1: Workbench/Process Engine: System Connectors Guide

80 80 Database Connector Dialog Descriptions Dialog Database Connection and Query Type Database connection Presetting For selecting a preconfigured database in order to preset the Database URL and Database driver class fields. When IS Log Database is selected, the Database Connector connects to the inubit logging database. The configuration of the inubit Process Engine is used for this connection, therefore all other fields in this area are deactivated. In case, your database is not listed, select Custom and fill in the fields manually. On the Windows platform, you can switch to the JDBC-ODBC bridge. Only select JDBC-ODBC bridge if you cannot establish JDBC access to your database. A JDBC-ODBC bridge has comparably poor performance, may have restricted functional scope and automatic type recognition is significantly slower. Database URL Is pre-set if you selected a preconfigured database. Adjust the host, port, and database name. Database driver class Corresponds to the JDBC connection of the database used. To use a different database, you have to install a suitable driver. Refer to Installing Drivers (inubit Process Engine: Administrator and Developer Guide, chap. 3.4, p. 57). After installing a JDBC driver for the MS SQL server, you have to restart the inubit Process Engine. To use an Adabas database, copy the driver class directly to the <inubit-installdir>/server/jboss/server/default/ lib or <inubit-installdir>/server/webapps/ibis/ WEB-INF/lib directory. User/Password Entry depends on your database. Use special encoding If no other encoding is defined, UTF8 is used as a default. Connection Pooling Activates the connection pooling inubit 6.1: Workbench/Process Engine: System Connectors Guide

81 Database Connector Dialog Descriptions 81 If the connection pooling is activated, physical database connections are reused. This accelerates the processing of the SQL statements. After being used, connections are not closed but stored and thus made available for further use. So there is no need to open a new connection for each access. For Oracle databases, you have to check the Cache type recognition checkbox if Connection Pooling is activated. Refer to Cache type recognition (Workbench/Process Engine: System Connectors Guide, chap. 6, p. 82) The Settings button opens the dialog for configuring the connection pooling. Refer to Dialog Connection Pooling Properties (Workbench/ Process Engine: System Connectors Guide, chap , p. 85). Specific connection parameters For defining parameters like, for example, timeouts, number of open connections which are used for configuring the database connection depending on your used database. You define the parameters as name/value pairs. Connection test Test connection For testing whether the connection can be successfully established using your configuration. Function You use this selection to define which task the database connector should carry out: Execute input message as query The Database Connector executes queries contained in its input message. If possible, so-called prepared statements are generated. This involves checking the various database requests to make sure that they are structurally consistent. If the type is the same as that of an SQL statement that accesses the same columns of a table, a command that is carried out multiple times is generated on the database side. This improves performance. Refer to Creating Dynamic XML-Queries (Workbench/Process Engine: System Connectors Guide, chap. 6.3, p. 59). Execute static query The Database Connector executes a static query which you define in the Dialog Static Query (Workbench/Process Engine: System Connectors Guide, chap , p. 83). Refer to Creating Static SQL Queries (Workbench/Process Engine: System Connectors Guide, chap. 6.2, p. 58). inubit 6.1: Workbench/Process Engine: System Connectors Guide

82 82 Database Connector Dialog Descriptions Read meta data The database connector queries the structure of the database and additional information. You need this information to create requests for mapping tables and column names, for example. Refer to Querying Metadata (Workbench/Process Engine: System Connectors Guide, chap. 6.1, p. 58). Settings Automatic type recognition of database object If activated, data types are recognized automatically. This means, for example, when a date is inserted it is passed to the database correctly as a date, and not, for example, as a string. Cache type recognition Activate this checkbox to have the table definitions available. Hence, it is not necessary to query the database to receive the table definitions. Auto commit (disable transactions) During its execution, a Database Connector can carry out multiple SQL statements. With this option you define the point in time when the changes are permanently stored in the database. - If the Auto commit is active, every change request automatically initiates a Commit or Rollback (in case of errors). - If the option is inactive, all changes are carried out within one single transaction. If an error occurs during this transaction, the database request is not processes any further. All database requests that have already been executed are rolled back. - Ignore errors If activated, database requests are executed even after an error occurred. Trim the strings from query Leading and trailing whitespaces are deleted from all field and condition values. Whitespaces within a value or condition are not deleted Dialog Metadata In the metadata dialog, you define which information about the database the Database Connector should output. These metadata are output as XML message, for each metadata an XML element is created. You can define the names of these elements and of the root element inubit 6.1: Workbench/Process Engine: System Connectors Guide

83 Database Connector Dialog Descriptions 83 Names must comply with the following rules: - Names can contain letters, numbers and other characters. - Names must not start with a number or a punctuation character - Names must not start with xml, XML, Xml and so on.) - Names must not contain blanks If a name is invalid, the element is named InvalidXmlTag. The metadata are output as value of the name-attribute. By clicking the Generate Preview button a preview of the output format of the metadata is displayed. Only this table By default, the data of all tables included in the schema are read. If you select this option, you can restrict the number of tables read to only one. Enter the name of the table, depending on the database used. Root element XML root element. Data type Reads the data type of the table columns in the database. Type name Reads the table column names. Column width Specifies the maximum length of a field in the current column of the table. Decimal places Indicates the number of digits after the decimal point that values in a table with floating-point numbers may have. NULL values Reads which table columns may have blank entries. Remarks Reads which table columns have remarks Dialog Static Query In this dialog you define the static query. The request may only contain one statement. inubit 6.1: Workbench/Process Engine: System Connectors Guide

84 84 Database Connector Dialog Descriptions Dialog Query Result In the dialog for query results, you define how the query result is to be formatted. Result format Trim string values from database Leading and trailing whitespaces are deleted from string values for text fields. Whitespaces that are not at the beginning or end of a text field are ignored. Mark NULL values with an attribute This enables distinction between a blank value and a NULL value in the output message. The value NULL is indicated with the attribute Value null="true". Always wrap result with ResultSets tag If selected, the result of a simple Insert of one dataset is <ResultSets> <rows>1</rows> </ResultSets> instead of <rows>1</rows> Output time and date fields in XML schema format If selected, time and date specifications are output in the defined format and also include indication of time zones, e.g T12:25: Otherwise, date and time are output without time zone in local time. XML element names You use the text fields to determine the names of elements to be created in the XML output message. Formatting type - Uncompressed The result is encapsulated by elements. You can modify the element identifier manually. Example: <ResultSet> <Row> <Column id="1"> <Name>Street</Name> <Value>Unter den Linden</Value> </Column> </Row> - Compressed The result is encapsulated by elements (besides field names and values). You can modify the element identifier manually. Example: inubit 6.1: Workbench/Process Engine: System Connectors Guide

85 Database Connector Dialog Descriptions 85 <ResultSet> <R> <C>Street</C> </R> <R> <C>Unter den Linden</C> </R> - Names as tags The names of the columns are used as tag names. If the column names do not comply with the conventions for XML elements, InvalidXmlTag elements are created and the column name is output as the value of the Name attribute. - User-defined Enter the entire name of the relevant Java class to be used for the output. Alternatively, you can let a Java class output the SQL result sets and transform them to XML. Enter the name of the class. The class must implement the interface com.inubit.ibis.utils.query.resultsetoutput (contained in the SDK). Row number When selected, the attribute ID with the current sequential number is added as a value to the ROW and COLUMN elements, e. g.: <ResultSet> <Row id="1"> <Column id="1">name</column> <Column id="2">street</column> </Row> Preview By clicking the Generate preview button a preview of the output format of the query result is displayed Dialog Connection Pooling Properties In the dialog for database pooling properties, you configure the settings of the connection pool. inubit 6.1: Workbench/Process Engine: System Connectors Guide

86 86 Database Connector Dialog Descriptions If the connection pooling is activated, physical database connections are reused. This accelerates the processing of the SQL statements. After being used, connections are not closed but stored and thus made available for further use. So there is no need to open a new connection for each access. Reuse of the connection pool: All Database Connectors whose values for the settings URL, User and Auto Commit match use the same pool. Connection pooling Max. number of active connections in the pool Defines how many connections can be active at the same time. If there are too few connections in the connection pool, queue time might arise. However, too many connections can place unnecessary load on the database system, since the connections create a certain amount of administration effort on the database side. Max. number of inactive connections in the pool Defines how many connections in the connection pool may be inactive at the same time. Min. number of inactive connections in the pool Specifies how many inactive connections the connection pool permanently holds. Number of inactive connections to check Checks inactive connections at regular intervals to see whether these still possess the correct connection functionality. If this test fails, the connection is removed from the connection pool. Max. time the pool will wait for a connection to be returned (msec) Specify, how long the pool should wait at the most, until the Connector gets a connection from the pool. Time between checks for inactive connections (msec) Time in milliseconds between the inactive connection checks. The value -1 indicates that no check takes place. Min. time for inactive connections (msec) Duration of an unused pool connection to stay open until it is terminated. Action if pool is crowded Specifies what action is to be performed if all connections in the connection pool are in use. - Fail with exception The request for a connection from the connection pool fails, resulting in the database request failing and an error message being generated inubit 6.1: Workbench/Process Engine: System Connectors Guide

87 Database Connector Dialog Descriptions 87 - Block pool The request for a connection from the connection pool is blocked. - Create new connection Additional connections are added to the connection pool. Validation The pool uses the connection only after successful check. In case, the check fails, a new connection is created. This way, errors in the Database Connector are avoided and the stability is improved for databases under high load. Test when taking connections from the pool Tests the functionality of a database connection in the pool if the connection is being taken from the pool. Test when putting back connections into the pool Tests the functionality of a database connection in the pool if the connection is being put back into the pool. Test while the connections are inactive Tests the functionality of a database connection in the pool while it is not being used. Validation SQL query Checks and validates the connection with an SQL query. The button starts the test. Set presettings (button) Recover the provided presettings of the database pooling properties. inubit 6.1: Workbench/Process Engine: System Connectors Guide

88 88 Database Connector Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

89 7 Database Object Connector 89 This section details the following topics: Inserting, Selecting, Updating and Deleting Business Objects, p. 90 Monitoring and Archiving Events With an Event-Listener, p. 92 Monitoring an Event Archive with a Archive Processor, p. 95 Configuration File: Field Descriptions, p. 95 Create Database Procedure getnewid, p. 96 Dialog Descriptions, p. 100 Use The Database Object Connector (DBO Connector) establishes direct access to business objects in hierarchically structured database tables. Connector types A DBO Connector has the following functions, depending on its configuration: Input Connector - As event-listener a DBO Connector monitors and archives changes in business objects. Refer to Monitoring and Archiving Events With an Event- Listener (Workbench/Process Engine: System Connectors Guide, chap. 7.2, p. 92). - As archive processor a DBO Connector prevents an event archive from overflow. Refer to Monitoring an Event Archive with a Archive Processor (Workbench/Process Engine: System Connectors Guide, chap. 7.3, p. 95). Medium Connector For creating, selecting, changing or deleting one or more business objects. Inserting, Selecting, Updating and Deleting Business Objects (Workbench/Process Engine: System Connectors Guide, chap. 7.1, p. 90) Supported databases The DBO Connector supports the following databases: Oracle MySQL 5.0, 5.1 and 6 MS-SQL inubit 6.1: Workbench/Process Engine: System Connectors Guide

90 90 Database Object Connector Inserting, Selecting, Updating and Deleting Business Objects 7.1 Inserting, Selecting, Updating and Deleting Business Objects For accessing business objects you configure a DBO Medium Connector. Using the input message you define which operation the connector should execute. The communication is transactional, in principle: the complete operation is performed, always. If an error occurs then the complete operation is rolled back. The connector outputs the changed business objects after each successfully performed transaction. After a Delete, the connector passes the information on, which objects have been deleted, instead of the objects themselves. Mapping templates All input messages must comply with a given structure. Thus structure is defined in the templates included in delivery. There is an individual template for each operation: Insert (with and without primary key), Select, Update and Delete. You find all templates in the Repository in the directory Global/ System/Mapping Template/Database Object Connector. Proceed as follows 1. Create a DBO Medium Connector. 2. In the Dialog Database Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 100) configure the database connection and test it. 3. In the Plug-in ID field enter an ID. The ID must be unique per database and per inubit installation. The ID is required if you additionally use a DBO Input Connector as event listener: The event listener uses the ID for identifying the DBO Medium Connector creating the events the DBO Input Connector monitors. Refer to Monitoring and Archiving Events With an Event- Listener (Workbench/Process Engine: System Connectors Guide, chap. 7.2, p. 92). 4. Click Next. The Dialog Database Configuration (Workbench/ Process Engine: System Connectors Guide, chap , p. 100) opens and displays the configuration file template which is appropriate for your database. 5. Customizing configuration template: In the configuration file you map the database table structure onto the given XML structure. a. Defining business objects: inubit 6.1: Workbench/Process Engine: System Connectors Guide

91 Database Object Connector Inserting, Selecting, Updating and Deleting Business Objects 91 Business objects are described in the DBStructureDescription element. You can configure as many DBStructureDescription elements as needed and map any hierarchies by using sub-tables. Copy the FATHER_CHILD-DBStructureDescription element and adjust it to the structure of your tables. The example element FATHER_CHILD- DBStructureDescription shows how primarykey and ForeignKey constraints are matched in the DBStructureDescription. You can b. Optionally: Adjusting the date format for the JDBC session - MySQL: The date format xs:datetime cannot be set once for the complete session. - Oracle: The configuration file initializes the JDBC session with the date format xs:datetime (yyyy-mmdd"t"hh24:mi:ss). Refer to Configuration File: Field Descriptions (Workbench/ Process Engine: System Connectors Guide, chap. 7.4, p. 95). c. Optionally: You can store the customized configuration file into the Repository or into the file system in order to re-use the configuration file in other DBO connectors. 6. Click Finish. The wizard closes. 7. Creating the database procedure getnewid The database procedure getnewid determines the next unique business object ID. Refer to Create Database Procedure getnewid (Workbench/ Process Engine: System Connectors Guide, chap. 7.5, p. 96). 8. Creating input messages a. Create an XSLT Converter. b. In order to use one of the supplied templates as target structure, in the panel XML Target File click and select Open from > Repository. The Repository browser opens. c. Navigate to the folder /Global/System/Mapping Template/Database Object Connector/. d. Select a template and click the OK button in order to close the Repository browser. e. Adjust the template to the structure of your business object. f. Connect the XSLT Converter with your DBO Connector. inubit 6.1: Workbench/Process Engine: System Connectors Guide

92 92 Database Object Connector Monitoring and Archiving Events With an Event-Listener 7.2 Monitoring and Archiving Events With an Event-Listener As event listener a DBO Input Connector monitors the changes of business objects. For this purpose, the DBO Input Connector periodically checks whether a new event message is to be found in the event table. If this is the case then the DBO Input Connector imports the business object, which matches the event, and passes this business object on as output message. In a delete case, only the primary key is made available to the workflow as event. The processed event is moved to the event archive table. Proceeding 1. Setup the event table All events (insert, delete, update, select) which occurred in the monitored database tables are written into this table. 2. Set trigger The SQL trigger must be set on all those tables including events, which should be monitored. As soon as in a monitored table, e. g. an insert happens, the trigger releases and writes the event into the event table. 3. Create DBO Input Connector The DBO Input Connector imports the event from the event table, hands over the respective business object to the workflow and thereby triggers the workflow execution. 4. Optional: Archiving Executed events can be saved in an archive table. Proceed as follows 1. Create event table - Oracle with sequence CREATE TABLE IS_EVENTS ( ID NUMBER (10, 0) DEFAULT 0 NOT NULL, IS_PLUGIN_ID VARCHAR2(10) DEFAULT '' NOT NULL, PK1 VARCHAR2(100) DEFAULT '' NOT NULL, PK2 VARCHAR2(100) DEFAULT '' NULL, PK3 VARCHAR2(50) DEFAULT '' NULL, PK4 VARCHAR2(50) DEFAULT '' NULL, PK5 VARCHAR2(50) DEFAULT '' NULL, PK6 VARCHAR2(50) DEFAULT '' NULL, PK7 VARCHAR2(50) DEFAULT '' NULL, PK8 VARCHAR2(50) DEFAULT '' NULL, PK9 VARCHAR2(50) DEFAULT '' NULL, IS_STRUCTURE_NAME VARCHAR2(50) DEFAULT '' NOT NULL, inubit 6.1: Workbench/Process Engine: System Connectors Guide

93 Database Object Connector Monitoring and Archiving Events With an Event-Listener 93 VERB VARCHAR2(10) DEFAULT '' NOT NULL, PRIORITY NUMBER (10, 0) DEFAULT 0 NOT NULL, TIMESTAMP DATE DEFAULT SYSDATE NOT NULL, STATUS NUMBER (10, 0) DEFAULT 0 NOT NULL, RETRIEVE_TIME DATE DEFAULT SYSDATE NOT NULL ) CREATE SEQUENCE SEQ_IS_EVENTS INCREMENT BY 1 START WITH 1 NOMAXVALUE NOCYCLE CACHE 10 - MySQL CREATE TABLE IS_EVENTS ( ID NUMERIC (10, 0) DEFAULT 0 NOT NULL, IS_PLUGIN_ID VARCHAR(10) DEFAULT '' NOT NULL, PK1 VARCHAR(100) NOT NULL, PK2 VARCHAR(100), PK3 VARCHAR(50), PK4 VARCHAR(50), PK5 VARCHAR(50), PK6 VARCHAR(50), PK7 VARCHAR(50), PK8 VARCHAR(50), PK9 VARCHAR(50), IS_STRUCTURE_NAME VARCHAR(50) DEFAULT '' NOT NULL, VERB VARCHAR(10) DEFAULT '' NOT NULL, PRIORITY NUMERIC(10, 0) DEFAULT 0 NOT NULL, TIMESTAMP TIMESTAMP NOT NULL, STATUS NUMERIC(10, 0) DEFAULT 0 NOT NULL, RETRIEVE_TIME TIMESTAMP NOT NULL ) 2. Create trigger Insert triggers monitor, whether in a table FATHER business objects are created. - Oracle CREATE OR REPLACE TRIGGER FATHER_after_insert AFTER INSERT ON FATHER FOR EACH ROW BEGIN INSERT INTO is_events (id, is_plugin_id, pk1, pk2, pk3, pk4, pk5, pk6, pk7, pk8, pk9, verb,is_structure_name, priority, retrieve_ time, status,timestamp) -- '0815' ist die Plugin-ID VALUES (SEQ_IS_EVENTS.NEXTVAL,'0815', :new.fatherid, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, 'insert', 'FATHER_CHILD', 1, sysdate, 0, sysdate); inubit 6.1: Workbench/Process Engine: System Connectors Guide

94 94 Database Object Connector Monitoring and Archiving Events With an Event-Listener END; - MySQL via MySQL Administrator The database procedure getnewid must be available! Refer to getnewid for MySQL (Workbench/Process Engine: System Connectors Guide, chap , p. 99) DELIMITER $$ DROP TRIGGER IF EXISTS FATHER_after_insert $$ CREATE TRIGGER FATHER_after_insert AFTER INSERT ON FATHER FOR EACH ROW BEGIN DECLARE neweventid INT; CALL getnewid('is_events','id',neweventid ); INSERT INTO is_events (id,is_plugin_id, pk1, pk2, pk3, pk4, pk5, pk6, pk7, pk8, pk9, verb,is_structure_name, priority, retrieve_ time, status,timestamp) -- '0815' ist die Plugin-ID! VALUES (neweventid, '0815', NEW.FATHERID, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, 'insert', 'FATHER_CHILD', 1, now(), 0, now()); END $$ DELIMITER ; 3. Create and configure DBO Input Connector a. Activate the scheduler for specifying the polling interval. b. Configure the database connection in the Dialog Database Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 100) and test it. c. Enter the plugin-id of the DBO Connector, which was triggering the event. d. Select the option Event Listener for defining the use of the connector. e. Enter the name of the event table. f. Specify the archive table, if the executed events are to be archived. 4. Click Next. Another dialog is displayed. 5. Click Finish to complete the configuration of the connector inubit 6.1: Workbench/Process Engine: System Connectors Guide

95 Database Object Connector Monitoring an Event Archive with a Archive Processor Monitoring an Event Archive with a Archive Processor The DBO Connector protects an event archive against data overflow, when used as archive processor. Proceed as follows 1. Create a DBO Input Connector. 2. Activate the scheduler for specifying the polling interval. 3. Configure the database connection in the Dialog Database Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 100) and test it. 4. Enter the plugin-id of the DBO Input Connector, which is monitoring and archiving the events. 5. Select the option Archive Processor for defining the use of the connector. 6. In the field Event archive table enter the name of the archive table. 7. In the field Archive window specify how long events are to be stored. All archived events which are older are then deleted from the archive and are made available for the workflow. 8. Click Next. Another dialog opens. 9. Click Finish in order to complete the connector s configuration. 7.4 Configuration File: Field Descriptions Element Attribute Name Denotation DBStructure Description DBStructure Description DBStructure Description DBStructure Description DBStructureName mandatory Unique name of the element DeleteObsoleteChilds mandatory Obsolete child elements are to be deleted. SoftDelete mandatory Not yet supported. AutoInserUpdateConversion mandatory Not yet supported Table DBTableName mandatory Table name in the database Table TagTableName mandatory Table name in XML inubit 6.1: Workbench/Process Engine: System Connectors Guide

96 96 Database Object Connector Create Database Procedure getnewid Element Attribute Name Denotation Table DBProc_InsteadUpdate implicit StoredProcedure instead of Update Table DBProc_InsteadInsert implicit StoredProcedure instead of Insert Table DBProc_InsteadSelect implicit StoredProcedure instead of Select Table DBProc_InsteadDelete implicit StoredProcedure instead of Delete Table DBSoftDeletField implicit Not yet supported Table DBSOftDeletValue implicit Not yet supported Field DBFieldName mandatory Field name in the database Field TagFieldName mandatory Field name in XML Field DBSPParamIdx implicit StoredProcedure Parameter Index Field DBFieldType implicit Field type Field DBFieldLength implicit Field length Field DBIsPrimaryKey mandatory Primary key Field IsAutoField implicit autoident field; if true then an ID is drawn via getnewid Refer to Create Database Procedure getnewid (Workbench/Process Engine: System Connectors Guide, chap. 7.5, p. 96). Field DBForeignKey_FieldName implicit Reference on foreign key Field isrequired mandatory If true then the column must be available in the XML. Field DefaultValue implicit Default value of the field Field SelectExpression implicit =, >, <, >=, <=, like (adjacent blanks!) 7.5 Create Database Procedure getnewid This section details the following topics: inubit 6.1: Workbench/Process Engine: System Connectors Guide

97 Database Object Connector Create Database Procedure getnewid 97 getnewid for Oracle, p. 97 getnewid for MySQL, p. 99 When creating a new business object (with an INSERT), the DBO Connector calls the database procedure getnewid for those table columns, which have the attribute IsAutoField=true, in order to assign a unique ID for these table columns. getnewid() must correspond to the following structure: getnewid (i_tablename in varchar2, i_fieldname in varchar2, o_newid out number); Using the given input parameters (current table name and name of the table column), getnewid() accesses the correct database sequence and hands over the new to the DBO Connector, so that it can perform the INSERT with the new ID. The following proposals of how to implement getnewid() may change with a new release. However, you can keep the previous implementation of the procedure with a new release, too, or, alternatively, use any procedure, you have developed yourself getnewid for Oracle Listing 1 create or replace procedure getnewid ( 2 i_tablename in varchar2, 3 i_fieldname in varchar2, 4 o_newid out number 5 ) is 6 i_dotposition integer; 7 s_owner varchar2(64); 8 s_table varchar2(64); 9 begin 10 i_dotposition := instr(i_tablename,'.'); 11 if i_dotposition > 0 then 12 s_owner := substr(i_tablename, 1, i_dotposition - 1); 13 s_table := substr(i_tablename, i_dotposition + 1); 14 else 15 s_owner := null; 16 end if; /Listing (Abschnitt 1 von 2) inubit 6.1: Workbench/Process Engine: System Connectors Guide

98 98 Database Object Connector Create Database Procedure getnewid Listing 17 begin 18 if s_owner is null then 19 execute immediate 'select seq_' i_fieldname '.nextval from dual' into o_newid; 20 else 21 execute immediate 'select ' s_owner '.seq_' i_fieldname '.nextval from dual' into o_newid; 22 end if; 23 return; 24 exception 25 when others then 26 o_newid := null; 27 end; 28 begin 29 if s_owner is null then 30 execute immediate 'select seq_' i_tablename '.nextval from dual' into o_newid; 31 else 32 execute immediate 'select ' s_owner '.seq_' s_table '.nextval from dual' into o_newid; 33 end if; 34 return; 35 exception 36 when others then 37 o_newid := null; 38 end; 39 if s_owner is null then 40 raise_application_error(-20000,'getnewid: Sequence seq_' i_ fieldname ' or seq_' i_tablename ' not found'); else 41 raise_application_error(-20000,'getnewid: Sequence ' s_owner '.seq_' i_fieldname ' or ' s_owner '.seq_' s_table ' not found'); 42 end if; end; /Listing (Abschnitt 2 von 2) inubit 6.1: Workbench/Process Engine: System Connectors Guide

99 Database Object Connector Create Database Procedure getnewid getnewid for MySQL Since MySQL does not know sequences, an internal sequence table INUBIT_DBO_SEQUENCES is used. Listing 1 DELIMITER $$ 2 DROP PROCEDURE IF EXISTS getnewid $$ 3 CREATE PROCEDURE getnewid( 4 in i_tablename text, 5 in i_fieldname text, 6 out o_newid int 7) 8 BEGIN 9 DECLARE entrycount INT; 10 SELECT COUNT(*) INTO entrycount FROM INUBIT_DBO_SEQUENCES WHERE SEQUENCE_TABLE=i_tablename AND SEQUENCE_COLUMN = i_fieldname; 11 IF entrycount=0 THEN /* create entry */ 12 INSERT INTO INUBIT_DBO_SEQUENCES (SEQUENCE_TABLE,SEQUENCE_ COLUMN,SEQUENCE_VALUE) Values (i_tablename,i_fieldname,0); 13 SET o_newid = 0; 14 ELSE /* increase sequence */ 15 UPDATE INUBIT_DBO_SEQUENCES SET SEQUENCE_VALUE=last_insert_id(SEQUENCE_ VALUE+1) WHERE SEQUENCE_TABLE=i_tablename AND SEQUENCE_COLUMN = i_ fieldname; 16 SET o_newid = last_insert_id(); 17 END IF; 18 END $$ 19 DELIMITER; 20 DROP TABLE IF EXISTS INUBIT_DBO_SEQUENCES; 21 CREATE TABLE INUBIT_DBO_SEQUENCES( 22 SEQUENCE_TABLE VARCHAR(64) NOT NULL, 23 SEQUENCE_COLUMN VARCHAR(64) NOT NULL, 24 SEQUENCE_VALUE INT(10) UNSIGNED NOT NULL, 25 PRIMARY KEY(SEQUENCE_TABLE,SEQUENCE_COLUMN ) 26 ) ENGINE=MyISAM DEFAULT CHARSET=latin1; /Listing inubit 6.1: Workbench/Process Engine: System Connectors Guide

100 100 Database Object Connector Dialog Descriptions 7.6 Dialog Descriptions This section details the following topics: Dialog Database Configuration, p. 100 Dialog Database Pooling Configuration, p. 102 Dialog DBO Configuration File, p Dialog Database Configuration Database connection Presetting For selecting a preconfigured database in order to preset the Database URL and Database driver class fields. When IS Log Database is selected, the Database Connector connects to the inubit logging database. The configuration of the inubit Process Engine is used for this connection, therefore all other fields in this area are deactivated. In case, your database is not listed, select Custom and fill in the fields manually. On the Windows platform, you can switch to the JDBC-ODBC bridge. Only select JDBC-ODBC bridge if you cannot establish JDBC access to your database. A JDBC-ODBC bridge has comparably poor performance, may have restricted functional scope and automatic type recognition is significantly slower. Database URL Is pre-set if you selected a preconfigured database. Adjust the host, port, and database name. Database driver class Corresponds to the JDBC connection of the database used. To use a different database, you have to install a suitable driver. Refer to Installing Drivers (inubit Process Engine: Administrator and Developer Guide, chap. 3.4, p. 57). After installing a JDBC driver for the MS SQL server, you have to restart the inubit Process Engine. To use an Adabas database, copy the driver class directly to the <inubit-installdir>/server/jboss/server/default/ inubit 6.1: Workbench/Process Engine: System Connectors Guide

101 Database Object Connector Dialog Descriptions 101 lib or <inubit-installdir>/server/webapps/ibis/ WEB-INF/lib directory. User/Password Entry depends on your database. Connection pooling Activates connection pooling and adds a further dialog to the module wizard where you can configure connection pooling. Refer to Dialog Connection Pooling Properties (Workbench/ Process Engine: System Connectors Guide, chap , p. 85). Specific connection parameters For defining parameters like, for example, timeouts, number of open connections which are used for configuring the database connection depending on your used database. You define the parameters as name/value pairs. DBO Connector specific settings Plugin-ID - For a DBO Medium Connector: The ID identifies the respective connector and must be unique within the inubit installation and per database. - For a DBO Input Connector: ID of the DBO Medium Connectors creating the events which the DBO Input Connector should monitor. A DBO Input Connector can only receive the events from a DBO Medium Connector having the same ID like the DBO Input Connector itself. Example: You use a scenario where the DBO Medium Connector creates or modifies business objects, a DBO Input Listener monitors these events and another DBO Input Listener monitors the event archive table. In this scenario all three connectors must have the same ID. Event Listener/Archive Processor (Only for input connectors) Specifies the function of an DBO Input Connector. Refer to - Monitoring and Archiving Events With an Event-Listener (Workbench/Process Engine: System Connectors Guide, chap. 7.2, p. 92) - Monitoring an Event Archive with a Archive Processor (Workbench/Process Engine: System Connectors Guide, chap. 7.3, p. 95) Maximum read events per execution This specification defines how often a workflow is to be started per call at maximum. By setting limits you can control the system load of the inubit Process Engine. The workflow is started until inubit 6.1: Workbench/Process Engine: System Connectors Guide

102 102 Database Object Connector Dialog Descriptions - no more events can to be fetched - or the maximum number of events is reached. This entry is ignored in test mode. In test mode, the workflow is started exactly once and imports one event. Event table (Only for input connectors) Name of the table from which the events are to be fetched. Event archive table (Only for input connectors) Name of the table where the processed events are archived. If no table name is given then events are not archived. Archive window in days (Only for input connectors) All archived events, which are older than x days, are deleted from the archive and made available for the workflow. Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog Database Pooling Configuration Refer to Dialog Connection Pooling Properties (Workbench/ Process Engine: System Connectors Guide, chap , p. 85) Dialog DBO Configuration File In this dialog the configuration file of the DBO Connector is displayed. In the configuration file the structure of the relational database tables is mapped onto an XML structure. Refer to Configuration File: Field Descriptions (Workbench/ Process Engine: System Connectors Guide, chap. 7.4, p. 95). When creating a DBO Connector automatically a configuration file template is loaded which is appropriate for you selected database. You need to customize this template inubit 6.1: Workbench/Process Engine: System Connectors Guide

103 Database Object Connector Dialog Descriptions 103 You can store your customized configuration file in the Repository or in the file system in order to re-use it in other DBO connectors. inubit 6.1: Workbench/Process Engine: System Connectors Guide

104 104 Database Object Connector Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

105 8 Exchange Connector 105 This section details the following topics: Installation Requirements, p. 105 Using the Exchange Connector, p. 106 Dialog Descriptions, p. 107 Use The Exchange Connector connects a Microsoft Exchange Server with the inubit software via an intranet or the Internet. The following function of the Microsoft Exchange Server can be used: Receive/Send mails All, a specified number or only unread mails can be picked up. Get/create tasks Get mailboxes Creates a list of all existing mail boxes and reads absence notes, if available. Get/create contacts Get free/busy information Get appointment items Create appointment items Delete items Entries can be deleted immediately or moved to a folder deleted objects. Move items Items can be moved to another folder, e.g. you can move s from the inbox to another folder. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 8.1 Installation Requirements You have to install the Microsoft Exchange Server MAPI Client and Collaboration Data Objects (CDO) and J-Integra for Exchange in order to establish the communication with an Exchange Server. You obtain the software together with the license for the Exchange Connector from Bosch Software Innovations GmbH. inubit 6.1: Workbench/Process Engine: System Connectors Guide

106 106 Exchange Connector Using the Exchange Connector For detailed installation instructions refer to To ensure stable operation, Bosch Software Innovations GmbH recommends to install the CDO on another server than the Exchange Server, e.g. DCOM CDO-Server MAPI Exchange Server J-Integra Product SDK Aside from this, also note: The CDO server and the Exchange server must be part of the same domain. Outlook must not be installed on the CDO server! Outlook owns an individual CDO installation, which may cause conflicts. Multiple Exchange Connectors must not access the same CDO in parallel. The CDO is not multi-threading-safe. 8.2 Using the Exchange Connector The way in which the exchange connector is used in a Technical Workflow depends on the action that the Connector is to carry out. For most actions, the Exchange Connector requires an XML-based input message in which the action to be executed and its parameters are defined. You create the input message on the basis of one of the provided templates in an XSLT converter module that is inserted into the workflow before the exchange connector. The following table indicates for each action, whether a template is required and if so, which template: Action Receive mails Send mails Get mailboxes Template No input messages s must be in a valid MIME format. Repository > Global > System > Mapping Templates > MIME Adapter (template for IBISMIME format) No input messages inubit 6.1: Workbench/Process Engine: System Connectors Guide

107 Exchange Connector Dialog Descriptions 107 Action Template Get/create tasks Repository > Global > System > Mapping Templates > Exchange Connector, GetTasks.xsd and CreateTasks.xsd Get/create contacts Repository > Global > System > Mapping Templates > Exchange Connector, GetContacts.xsd and CreateContacts.xsd Get free/busy information Repository > Global > System > Mapping Templates > Exchange Connector > GetFreeBusy.xsd Get/Create appointment items Repository > Global > System > Mapping Templates > Exchange Connector, GetAppointments.xsd or CreateAppointments.xsd. Delete items Repository > Global > System > Mapping Templates > Exchange Connector> DeleteItems.xsd Move items Repository > Global > System > Mapping Templates > Exchange Connector> MoveItems.xsd Accessing multiple mailboxes Each exchange connector can access only one single mailbox; to read from multiple mailboxes, use variable mapping. This allows you to e. g. dynamically overwrite the exchange.getmails.mailbox property of the exchange connector (to fetch mails). Refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351). 8.3 Dialog Descriptions This section details the following topics: Dialog General Settings, p. 108 Dialog Fetching s, p. 108 Dialog Moving Items, p. 109 Setting up all Other Actions, p. 110 inubit 6.1: Workbench/Process Engine: System Connectors Guide

108 108 Exchange Connector Dialog Descriptions Dialog General Settings This dialog offers the following options: Settings Domain Name of the administrative structure in the Windows network to which you want to log in using the access data in the User and Password fields. CDO server IP address or host name of the Microsoft Windows Server on which Microsoft CDO and J-Integra for Exchange are installed. Exchange Server IP address or host name of the Microsoft Exchange Server to which the connection is to be established via the CDO. User/Password Access data for the user with which you want to log in to the domain specified above. The access user must have the authorizations required for the current action. Action Select one of the available actions. Refer to Use (Workbench/Process Engine: System Connectors Guide, chap., p. 105) Dialog Fetching s This dialog offers the following options: Get messages Mailbox Mailbox used for the action. Read Choose whether all or only unread mails are to be retrieved. After processing Define whether mails - are to be retrieved from the server and deleted on the server - or are to be retrieved from the server while the original mails are to be marked as read. - are not to be processes any further inubit 6.1: Workbench/Process Engine: System Connectors Guide

109 Exchange Connector Dialog Descriptions 109 Number of mails per call Choose one of the options: All During module execution all mails in the given mailbox are retrieved from the Exchange Server. Maximum During module execution only the given number of mails are retrieved from the Exchange Server. Filter options For defining filter criteria with which s must comply in order to be fetched from the server. Filter relation If more than one filter is defined: - AND A message must comply with all filters in order to be fetched. - OR The message must comply with at least one filter in order to be fetched. Add filter The button adds the following row: In this row, you define filter criteria: - Subject/From/To: List for selecting the field which is to be filtered. - contains: Specify that a certain string must be present in the selected field. - Entry field: For entering the string which must be present Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog Moving Items This dialog offers the following options: inubit 6.1: Workbench/Process Engine: System Connectors Guide

110 110 Exchange Connector Dialog Descriptions Move items Mailbox Mailbox or access name used for the action. To folder Name of the folder or path to the folder where the item should be moved to. Path information must be specified according to the following pattern: [folder name] >>> [folder name]. Connection test Test connection For testing whether the connection can be successfully established using your configuration Setting up all Other Actions For all actions (apart from fetching s) a dialog is displayed. In this dialog, only the mailbox needs to be entered, to which the action refers to. Connection test Test connection For testing whether the connection can be successfully established using your configuration inubit 6.1: Workbench/Process Engine: System Connectors Guide

111 9 Execution Connector 111 This section details the following topics: Example: Reading a directory, p. 111 Example: Copying a file, p. 113 Example: Creating a directory, p. 113 Dialog Execution Connector Properties, p. 114 Use You use the Execution Connector to call an external application within a workflow. You can call any application that can be started via the command line. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) Prerequisites Linux Ensure that there is enough physical memory available when executing the Execution Connector in parallel. For each inubit process twice as much memory must be available as the maximum memory that is needed for the single inubit process. 9.1 Example: Reading a directory When using the following configuration, the content of the directory / opt/data/archive is listed and wrapped into an XML structure by using ECHO statements: inubit 6.1: Workbench/Process Engine: System Connectors Guide

112 112 Execution Connector Example: Reading a directory inubit 6.1: Workbench/Process Engine: System Connectors Guide

113 Execution Connector Example: Copying a file Example: Copying a file 9.3 Example: Creating a directory The variable var.dir is used. If no directory with this name exists in var.dir, it is created: inubit 6.1: Workbench/Process Engine: System Connectors Guide

114 114 Execution Connector Dialog Execution Connector Properties 9.4 Dialog Execution Connector Properties In the dialog, you configure how the external application is called. External command External Command Path and file name of the application to be called. The called application must be installed on the same computer as the application server (JBoss/Tomcat). The path can be entered relatively to the application server or absolutely inubit 6.1: Workbench/Process Engine: System Connectors Guide

115 Execution Connector Dialog Execution Connector Properties 115 Non-closed commands can endanger the stability of the entire server! Example: cmd without /C to close the command once it has been executed. Parameters Parameters for calling the external application. Separate multiple parameters with a blank. Use the button next to the parameters field to enter the following placeholders: - {File} For passing the input message as a temporary file to the called application. After its execution the application writes the result into the same file. Use {inputfile} and {outputfile}, if two different files are to be used. {File} and {InputFile} are mutually exclusive! - {XPath:PathSpecification} Transfers a node value from the XML input message to the called application. Upon clicking this parameter, the XPath assistant opens and helps you to create XPath expressions to read nodes. Refer to XPath Assistant (Workbench: User Guide, chap. 1.17, p. 66). - {Property:PropertyName} Passes a module variable. - {ScriptFile} Passes the script defined in the Script field. - {InputFile} Passes an input message to the called application, without reading it after execution, e. g.: - Command: cmd.exe - Argument: /C {ScriptFile.cmd} {InputFile} - Script: type "%1" > inputmessageduplicated.dat - {OutputFile} Passes a temporary file to the called application, into which the application writes the result after execution. This placeholder is commonly used together with {ScriptFile}, e. g.: - Command: cmd.exe - Argument: /C {ScriptFile.cmd} {OutputFile} - Script: echo "This will be streamed into outputfile and provided to workflow" > "%1" For the parameters {File}, {ScriptFile}, {InputFile} und {OutputFile} you can set one of the file extensions.cmd and.bat, respectively, e. g. {ScriptFile.bat}. inubit 6.1: Workbench/Process Engine: System Connectors Guide

116 116 Execution Connector Dialog Execution Connector Properties Working directory For the temporary files. The Execution Connector and some applications require a working directory. If you do not specify a directory, the respective default directory for Tomcat or JBoss is used. The default working directory is Tomcat\bin or JBoss\bin or the default working directory of the used application server, in case this is neither JBoss nor Tomcat. Environment variables Environment variables are passed as pairs consisting of a variable name and value separated by an = character. Multiple environment variables are separated by line breaks. Pass system variables to process If selected, all system variables of the Process Engine s system are passed to the Execution Connector process to enable the commands and scripts to access the system variables. Script Entry field To enter a script, you must add the parameter {ScriptFile} into the Parameters field. In order to access parameters, which are defined in the field Parameters, use variables. Their syntax depends on the operation system being used: - Windows: %1 - Linux: $1 External Editor (button) For editing the script. Opens the external editor which is defined by the application profile Generic Application or Script Editor, respectively. Refer to Application Profiles (inubit Process Engine: Administrator and Developer Guide, chap. 11.1, p. 141). Alternatively, you can call an external editor with the External editor button, if the option Use output message is activated. Check return value Expected value Numerical values. If the entered and the actual return values are the same, the workflow execution is continued. If a value is returned that is different to the expected value, the program's error code is returned to the workflow (formatted in XML in the form <ExitValue>value</ExitValue>). If no return value is specified, the workflow is always continued inubit 6.1: Workbench/Process Engine: System Connectors Guide

117 Execution Connector Dialog Execution Connector Properties 117 In order to ensure that faulty executions are always reported to the workflow, specify a return value of 0. This is because error codes are never equal to null. Use of input and output message Use input message (for Medium/Output Connector, only) If this is selected, then the input message of the Execution Connector is forwarded to the external application. Use output message (for Input/ Medium Connector, only) If this is selected, then the output message of the external application is transferred to the Execution Connector and is forwarded by it to the workflow. Use error exit (for Input/ Medium Connector, only) If this is selected, then the error output message of the external application is passed to the Execution Connector and then into the workflow. Additional settings Buffer size for input message Number of bytes for the allocation of memory. The default setting is 4096 bytes (applies if the input field is left blank). The greater the value, the larger the amount of memory required when the call takes place but the faster the transmission of the input message to the calling application. A small value means that less memory is required. However, it may take some time to pass the input message if the message is much larger than the buffer and therefore has to be passed in packages the same size as the buffer. Pass back return value as XML Prerequisite: Option Use output message must be checked! The return value is embedded in an XML structure and returned. inubit 6.1: Workbench/Process Engine: System Connectors Guide

118 118 Execution Connector Dialog Execution Connector Properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

119 10 File Connector 119 This section details the following topics: Module Variables of the File Connector, p. 119 Dialog Descriptions, p. 120 Use File connectors enable communication of the inubit Process Engine with the file system. Connector types The following configuration options are available: File Input Connector Passes files and directories from the file system of the inubit Process Engine to a workflow for processing. File Output Connector Writes the result of a workflow to a file in a directory of the inubit Process Engine. If the result is a zip archive, the File Output decompresses it before storing it. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 10.1 Module Variables of the File Connector The following module variables are set, when executing a File Connector. You can read these variables at the succeeding modules of the workflow: ReadFileDate Last change date for the input file in the format dd.mm.yyyy hh:mm:ss. ReadFileName Name of the input file including the extension. ReadFileSize Size of the input file in bytes. ReadFileWildcardname inubit 6.1: Workbench/Process Engine: System Connectors Guide

120 120 File Connector Dialog Descriptions Outputs the content of the wildcard used in the file name when configuring the file connector, if the Use wildcard content of the preceding File or FTP connector option is selected. WriteFileDate Only relevant for an output connector if Data is selected as the input format. Creation date of the output file in the format dd.mm.yyyy HH:mm:ss WriteFileName Only relevant for an output connector if Data is selected as the input format. Name of the output file. WriteFileWildcardname Only relevant for an output connector if Data is selected as the input format and e.g. timestamps or wildcards are used in the file names to be generated. Specifies the content of the wildcard used in the file name when configuring the file output connector. To use the WriteFileWildcardName variable you have to map it to the ReadFileWildcardName variable. For information on other variables and their use refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351) Dialog Descriptions This section details the following topics: Dialog File(s) to read, p. 120 Dialog Data transfer, p. 123 Dialog File to write, p Dialog File(s) to read (Input Connector) This dialog offers the following options: inubit 6.1: Workbench/Process Engine: System Connectors Guide

121 File Connector Dialog Descriptions 121 Mode Specify the mode in which the file connector is to work: File mode For each execution, a file in the specified directory is read (as long as its name corresponds to the pattern entered in the File > Name field). The file that is read depends on your specifications for Read order. Directory mode All files in the specified directory are read (as long as their file names correspond to the pattern entered in the File > Name field. In directory mode, an XML output message is always generated. This means that the Technical Workflow starts in each case. This makes it e. g. possible to react to the current state of the file with a demultiplexer or similar after the file input connector. Directory Name Path to the directory from which files are to be read. The path can be entered absolutely or relatively to the directory <inubitinstalldir>/server/tomcat/bin. File Name File name. Optional wildcard or regular expression. Refer to Invert If selected, the pattern specified for the file name is inverted. As a result, all files whose name does not correspond to the pattern are read. Use wildcard If selected, you can use a wildcard (asterisk/*) or enter the complete file name. Use regular expression If selected, Perl-compliant regular expressions can be used to create character string patterns to select the files to read. Regular expressions must be delimited by forward slashes (/), e.g.: /(\d\d)\.(\d\d)\.(\d\d\d\d)/ Refer to for an overview of Perl-compliant regular expressions or inubit 6.1: Workbench/Process Engine: System Connectors Guide

122 122 File Connector Dialog Descriptions Use wildcard content of the preceding File or FTP connector Example: Test*.xml was specified in the File name field in the configuration of a previously executed file connector. A file with the name Test5.xml was passed by the file connector as an output message. In this case, the wildcard content is the digit 5. If you have also specified a wildcard in the current connector (for example, Output*.xml ), the digit 5 is inserted into the wildcard position. The output of the connector configured here is therefore Output5.xml. Delete files after reading If activated, read files are deleted after they have been read. Activate this option to process all files, one after the other, in a directory. You can also activate the Throw error if delete fails option so that an error entry is displayed in the Queue Manager for the workflow with this module if a file cannot be deleted. If an error output is configured, it is run. Otherwise, module execution is terminated. Wait for file clearance/check interval in seconds (Only in file mode.) Select this option to ensure that the file input connector does not read any files while other applications are writing to them. If this option is selected, the file input connector checks the timestamp and sizes of the files to be read at configurable intervals and compares them. The files are only read if the specifications have not changed. Max. number of executions per scheduled call You use this specification to define the maximum number of times the workflow is to be started per triggering event. The triggering event is the reaching of a particular time point (if the scheduler is activated). The workflow is then started as many times as necessary until either - there is no more data to be fetched/sent or - the number defined in "Maximum number of executions per call" has been reached By restricting the maximum number of executions, you control the system load on the server. In Test mode, this specification is ignored and the workflow is only started once. This option can only be used when the scheduler is active! (This option is only available in File mode.) Read order (Only in file mode.) inubit 6.1: Workbench/Process Engine: System Connectors Guide

123 File Connector Dialog Descriptions 123 If more than one file is transmitted, you define which files are to be transmitted first and in which order Dialog Data transfer (Input Connector) You use the dialog to configure the output of the connector. Directory configuration (If directory mode is selected) Include directories If selected, the file connector also reads the directory itself as well as the files in the specified directory. - with subdirectories If selected, the file connector also reads all subdirectories of the specified directory recursively. Delete empty directories after reading/delete files after reading Deletes empty directories once they have been read; this option is a sensible combination with the Delete files after reading option. File number limit Maximum number of files that can be read. Limit total size Maximum total size of files to be read. File check (If file mode is selected) Abort workflow if file does not exist: - In test mode: The execution of the workflow is terminated with an error if access to the specified file fails. - Scheduled input File Connector: According to the specified interval, the FTP Connector checks if a file is available. The workflow is only started if a file exists. - Input File Connector in the middle of a workflow: If the file does not exist, the execution is continued with an empty message. No entry is made in the log. Create XML output message with status information that the file exists and is empty; otherwise abort workflow inubit 6.1: Workbench/Process Engine: System Connectors Guide

124 124 File Connector Dialog Descriptions Checks whether a relevant file with size=0 exists. If yes, an XML file with the element <FileExists> and the value true is output. Otherwise, the workflow execution is terminated with an error. The input file is not output. Create XML output message with status information on whether the file exists or not Checks whether or not a relevant file is available. An XML file is output with the element <FileExists> and the value false if the specified file does not exist; if it exists, the value of the <FileExists> element is true. The input file is not output. Create XML output message with status information that the file does not exist, otherwise abort workflow Checks whether a relevant file exists. If not, an XML file with the element <FileExists> and the value false is output. Otherwise, the workflow execution is terminated with an error. The input file is not output. Data transfer (If Directory mode is selected; in File mode, only for Abort workflow if file does not exist. ) Type Defines how input messages should be passed to the workflow: - Data The input messages are forwarded in unchanged form. Select this option if the input messages are e.g. in XML format. - IBISDirectory-Xml Defines that the input messages are to be passed in IBISDirectory XML format. This involves generating an XML wrapper element for each input message. - Zip The input files are compressed in a Zip file. XML configuration (Only if data transfer type= IBISDirectory XML ) Encoding: Defines the encoding of the character set. - inclusive Data If selected, the entire file is read. If not selected, only the file metadata are read, e.g. name, file size and date. - Encode data base64 The file content is base64-encoded and is included in the XML output message. - Compress data The data are compressed in Zip file. - Store absolute path into XML inubit 6.1: Workbench/Process Engine: System Connectors Guide

125 File Connector Dialog Descriptions 125 If selected, the absolute path of the file is stored in a separate path attribute. Zip configuration (Only if data transfer type= Zip is selected.) Encoding Defines the encoding of the character set Dialog File to write (Output Connector) You use the dialog to specify the format of the input messages and define how the messages are to be written to the file system. Input format configuration Specify the format of the input messages: Data The input messages are data that should be passed without being changed. IBISDirectory XML The input messages are in IBISDirectory format. Zip The input files are compressed in a Zip file. If selected the File Connector expects a zip archive as input message. The File Connector decompresses this archive and stores the decompressed files in the given directory. Zip configuration (If Zip is the selected input format.) Encoding The selection made here defines the encoding of file and directory names. Directory Name Absolute path to the directory that the file connector is to use when writing files. In addition, you can add a date, timestamp, process ID to the file name to be generated. - Date inubit 6.1: Workbench/Process Engine: System Connectors Guide

126 126 File Connector Dialog Descriptions The date specification also has a timestamp. If you specify the file name in the format file_%timestamp%%.xml, the output file name can be, for example, file_ xml. file is the file name, followed by a two-digit day specification, two-digit month specification, four-digit year specification (ddmmyyyy). The number following the hyphen is the time in two-digit hour specification, two-digit minute specification, and two-digit second specification (HHmmss). - Timestamp The timestamp is created exactly like the date stamp (see above). A milliseconds specification is also used. If you specify the file name as file_%timestamp%ddmmyyyy-hhmmss- SSS%.xml, the following file name for example is used as the name of the output file: file_ xml. The final, three-digit specification represents milliseconds. - Process ID The process ID is the unique number created for a workflow execution. To pass the process ID of the workflow execution with the output file, enter the file name in the following format: file_pid_%processid%.xml. As a result, e.g. the following file name is used as the name of the output file: file_pid_ 18.xml. In conjunction with Generate non-existent directories, you can create a day- or month-based archive structure for messages. Generate non-existent directories Generates all non-existent directories from the path specification. File (Only for the Data input format.) Name You can also use wildcards (*) and add a timestamp and process ID in file names (refer to option Directory > Name ). Use wildcard content of the preceding file or FTP connector Example: A Test*.xml file was specified in the Directory and file name field in the configuration of a file connector that was executed previously. A file with the name Test5.xml was passed by the file connector as an output message. In this case, the wildcard content is the digit 5. If you have also specified a wildcard in the current connector (for example, Output*.xml), the digit 5 is entered in place of the wildcard. The output of the connector configured here is therefore Output5.xml. Use the file name of the previously executed file connector inubit 6.1: Workbench/Process Engine: System Connectors Guide

127 File Connector Dialog Descriptions 127 Example: A Test.xml file was specified in the Directory and file name field in the configuration of a previously executed file connector. The file connector forwards a file called Test.xml as the output message. This file name is then also used here. Add data to file Each time the workflow is executed the file to be read is appended to an existing file should one exist. This can be useful if you want to record cumulative log data in a file. This option cannot be used if wildcards are specified in the file name. Overwrite possible existing file An existing file with the same name is overwritten. Safe writing This option makes sure that the application waiting for the file fetches the file only after its completion. If selected, the data is written initially to a temporary file. When this process is completed, the temporary file is renamed according to the given file name. Creating the temporary file can take longer for larger files. Module output configuration Set input message additionally as output message If this option is selected, the input file is passed to the subsequent module. Depending on the size of the input files, this option can affect the performance of your system. Refer to Module Variables of the File Connector (Workbench/ Process Engine: System Connectors Guide, chap. 10.1, p. 119). inubit 6.1: Workbench/Process Engine: System Connectors Guide

128 128 File Connector Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

129 11 FTP(s) Connector 129 This section details the following topics: Module Variables of Input Connectors, p. 129 Dialog Descriptions, p. 130 Use The FTP connector supports the FTP, FTPS, and SFTP transfer protocols. Connector types There are the following configuration options for FTP connectors: Input Connector Fetches files from an FTP server. Output Connector Writes files to a directory on an FTP server. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 11.1 Module Variables of Input Connectors When executing an FTP connector, the following module variables are set: ReadFileDate Last change date for the input file in the format dd.mm.yyyy hh:mm:ss. ReadFileName Name of the input file including the extension. ReadFileSize Size of the input file in bytes. ReadFileWildcardname Outputs the content of the wildcard used when configuring the FTP connector in the file name. WriteFileDate Only for the FTP output connector. Date of generation of the output file in the format dd.mm.yyyy HH:mm:ss. inubit 6.1: Workbench/Process Engine: System Connectors Guide

130 130 FTP(s) Connector Dialog Descriptions WriteFileName Name of the output file. WriteFileWildcardname Only for the FTP output connector if timestamps or wildcards are used in the file names to be generated. Outputs the content of the wildcard used when configuring the FTP output connector in the file name. Refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351) Dialog Descriptions This section details the following topics: Dialog FTP Connector Properties, p. 130 Dialog Executing FTP Commands, p. 133 Dialog Defining Input File Names, p. 134 Dialog Defining Output File Names, p Dialog FTP Connector Properties The properties dialog is for querying the access data for the FTP server. Different control elements are displayed depending on the selected protocol. Basic configuration Protocol: Select one of the following protocols: - FTP (File Transfer Protocol) Between two hosts connected by TCP/IP a connection is established via two ports: - One port is used for control purposes, i.e. to exchange commands. - The other port is used for exchanging unencrypted data. This exchange is not secure. - FTPS (FTP via SSL) Extension of FTP inubit 6.1: Workbench/Process Engine: System Connectors Guide

131 FTP(s) Connector Dialog Descriptions The control port is secured by SSL. - Data exchange is not secured by default. The FTP connector enhances the FTPS protocol so that data transfer can also be secured using SSL. - SFTP (SSH FTP) Adds authentication of users and servers to the encrypted data exchange. SFTP is easier to use through NAT gateways than FTPS. Server name Domain name of an FTP server, e. g. ftp.example.com. Port - FTP and FTPS Default is port SFTP Default is port 22. If the connection test fails, ask your administrator which port should be used to reach the FTP server. You use the Default button to restore the default value following port changes. Connection mode (only for FTP/FTPS) - Active The client opens a random port and informs the server of the port number and its own IP address using the PORT command. - Passive The client sends a PASV command and the server opens a port and passes it to the client along with the IP address. - Auto In almost all cases, Auto is the correct setting. Select Active or Passive only, if your administrator has configured the FTP server accordingly. Transfer type Specify whether the files to be transferred contain binary or ASCII data. Locale Server locale. The server locale defines the choice of the character set and date specification, amongst others. Encoding Specify the encoding of the control channel for the communication connection between the connector and the FTP server. The control channel is used to send commands, including file names, as character strings. In order to make sure that special characters (e.g. Umlauts) are correctly transmitted, defining the encoding is essential since it can differ from server to server. inubit 6.1: Workbench/Process Engine: System Connectors Guide

132 132 FTP(s) Connector Dialog Descriptions Authentication (only for FTPS) If you have a separate area for the FTP server with a required login, enter the login data into the relevant fields. To access the server anonymously, click Anonymous login. This sets the user name to anonymous and the password to anonymous@example.com. SSL configuration (for FTPS) Use implicit FTPS This term describes an older FTPS version that is no longer contained in the current specification. Ask the administrator of the FTPS server whether implicit FTPS is available. This type of FTPS runs on port 990 by default. The following fields are valid both for the current version of FTPS and for implicit FTPS. Security mechanism Select a protocol for data transfer: - SSL or TLS (Secure Sockets Layer/Transport Layer Security) TLS 1.0 and 1.1 are standard further developments of SSL 3.0. Both provide FTPS security mechanisms to protect connections. - TLS_C TLS incl. compression of encrypted data. Secured data transfer By default, only transfer in the control channel is encrypted when using FTPS. The FTP connector also enables the encryption of data being transferred in the data channel. When activated, data is encrypted before exchange. SSL configuration For authenticating servers and/or clients. Opens the Dialog SSL Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 24). SSL configuration (for SFTP) Disable SHA-1 Select this option if you are using older services that do not support SHA-1 encryption. This avoids errors during the execution of the connector, thus preventing a workflow termination. Server authentication If not activated, the SFTP server of your business partner has to identify itself with your FTP connector. If activated, the given SFTP server of your business partner is always trusted. You must add the SFTP server a known_host file, upload this file into the FTP Connector and/or enter the path to this file: - Upload known_hosts file inubit 6.1: Workbench/Process Engine: System Connectors Guide

133 FTP(s) Connector Dialog Descriptions 133 Use the button to add the known_hosts file containing trusted hosts. The file is stored with the FTP Connector and is directly available each time a connection to the SFTP server is established. - Path Path to the known_hosts file. Advantage: The file remains in the file system. Changes to the known_hosts file are taken into account by the FTP Connector module for each execution. If you upload the known_hosts file and at the same time also specify a path, the path specification takes priority. Client authentication When activated, the FTP Connector must authenticate itself. To add the private key, click Upload private key. In order to load the keystore you must enter the password of the private key and keystore, respectively! Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog Executing FTP Commands Only for FTP and FTPS. You use the dialog to specify one or more commands that are to be executed before or after data transfer. For example, you can create directories or delete files before data transfer takes place. The commands must be written in uppercase. If you use multiple commands, each command has its own line. The commands must comply with standard syntax. Refer e.g. to Do not use the following commands: delete, mkdir, get, and put. These commands generate errors. Switching to another directory When you log in to an FTP server, your home directory is displayed. This is normally a directory such as /ftproot/group/username. As a user, you can only see your username directory. Some FTP inubit 6.1: Workbench/Process Engine: System Connectors Guide

134 134 FTP(s) Connector Dialog Descriptions servers are configured in such a way that absolute path specifications are required when you switch to a directory below the current directory in the hierarchy. To switch to a subdirectory such as /ftproot/ group/username/test then e.g. the following command is required ftp>cwd /ftproot/group/username/test Dialog Defining Input File Names (Input Connector) This dialog offers the following options: Mode File mode For each execution, a file in the specified directory is read (as long as its name corresponds to the pattern entered in the File > Name field). The file that is read depends on your specifications for Read order. Directory mode All files in the specified directory are read (as long as their file names correspond to the pattern entered in the File > Name field. In directory mode, an IBISDirectory XML output message is always generated. This means that the Technical Workflow starts in each case. The directory mode does not work recursively, meaning that subdirectories of the specified directory are not read. Directory Name Absolute path to the directory from which the FTP connector is to transfer files. If you want to transfer files directly from the home directory of your FTP server, leave this field blank. File With optional wildcard If you select this option, you can specify the complete file name or use a wildcard (*) in the file name. Example: If you specify *.xml, all XML files in the specified directory are transferred. With regular expression If selected, you can use regular expressions to describe a pattern that applies to file name character strings of files to be read. This provides a powerful tool for selecting files inubit 6.1: Workbench/Process Engine: System Connectors Guide

135 FTP(s) Connector Dialog Descriptions 135 Regular expressions must be delimited by forward slashes (/), e.g.: /(\d\d)\.(\d\d)\.(\d\d\d\d)/ Refer to for an overview of Perl-compliant regular expressions or Name File name. Can contain a wildcard or regular expression. Use wildcard content of the preceding file or FTP connector This option is active only if you select the With optional wildcard checkbox. If you select this option, the wildcard content generated by a previously executed file or FTP connector is used. Example: Test*.xml was specified in the File name field in the configuration of a previously executed file connector. The file connector forwarded a file with the name Test5.xml as the output message. In this case, the wildcard content is the digit 5. If you also specify a wildcard in the current connector, such as Output*.xml, the wildcard is replaced by 5 and the output of the current connector is Output5.xml. Delete files after reading If you want files to be deleted following data transfer, select this checkbox. Throw error if delete fails If an error occurs, module execution and the workflow are continued. If this option is activated and an error occurs, an error entry for the workflow with this module is displayed in the Queue Manager. If an error output is configured, it runs. Otherwise, the execution of the module is terminated. Maximum number of scheduled executions per call You use this specification to define the maximum number of times the workflow is to be started per triggering event. The triggering event is the reaching of a particular time point (if the scheduler is activated). The workflow is then started as many times as necessary until either - there is no more data to be fetched/sent or - the number defined in "Maximum number of executions per call" has been reached By restricting the maximum number of executions, you control the system load on the server. In Test mode, this specification is ignored and the workflow is only started once. inubit 6.1: Workbench/Process Engine: System Connectors Guide

136 136 FTP(s) Connector Dialog Descriptions Read order Defines the read order and sorting when reading files. File check Abort workflow if file does not exist: - In test mode: If access to the specified file fails, the workflow execution is terminated with an error. - Scheduled input FTP Connector: According to the interval specified, the FTP Connector checks if a file is available. The workflow is only started if a file exists. - Input FTP Connector in the middle of a workflow: If the file does not exist, the execution is continued with an empty message. No entry is made in the log. Create XML output message with status information on whether the file exists or not The FTP connector specifies an XML file that contains a single <FileExists> attribute. This value is false if the specified file does not exist and true if the specified file exists. Create XML output message with status information that the file does not exist; otherwise, abort workflow If the input file does not exist, the FTP connector outputs an XML file with the element FileExists="false". In all other error cases, the workflow execution terminates with an error. Directory configuration (Only if directory mode is selected) File number limit Maximum number of files that can be read. Limit total size Maximum total size of files to be read. inclusive Data If selected, the entire content of the file is read. If not selected, only the file metadata are read, e.g. name, file size and date Dialog Defining Output File Names (Output Connector) This dialog offers the following options: inubit 6.1: Workbench/Process Engine: System Connectors Guide

137 FTP(s) Connector Dialog Descriptions 137 Directory Name Specify the directory on the FTP server that the FTP connector is to use when writing files. Create non-existent directories If activated, missing directories on the FTP server are generated. File Name Name of the file the Output Connector writes. You can use an asterisk (*) in the file name to insert a counter at the position in question in order to prevent files from being overwritten. Example: /Outputdata/output*.xml. If you do so, files with the names output211.xml, output212.xml, output213.xml, and so on are generated on the FTP server. You can have a date, timestamp, or process ID added to the file name: - Date - Definition without date format file_%timestamp%%.xml generates file_ xml with file = filename, = Date formatted as ddmmyyyy, = time formatted as hhmmss - Definition with date format hh: File_%TimeStamp%hh%.xml generates File_11.xml - Definition with date format ddmm: File_%TimeStamp%ddMM%.xml generates File_2309.xml - Timestamp The timestamp additionally contains a specification in milliseconds: file_%timestamp%ddmmyyyy-hhmmss-sss%.xml results in file_ xml - Process ID file_pid_%processid%.xml Use wildcard content of the preceding file or FTP connector If you select this option, the wildcard content generated by a previously executed file or FTP connector is used. Use file name of the preceding file connector inubit 6.1: Workbench/Process Engine: System Connectors Guide

138 138 FTP(s) Connector Dialog Descriptions If you select this option, the file name used by a previously executed file connector is used. Example: Text.xml was specified in the Directory and file name field in the configuration of a previously executed file connector. The file connector forwards a file called Test.xml as the output message. This file name is also used here. If you specify an additional file name in the Name field, it is ignored. Append data to file/ Overwrite possible existing file Select one of the following options: - Append data to file: If you select this option, the output message is appended to the existing file each time the FTP connector is executed. This can be useful if you want to log cumulative log data in a file. This mechanism cannot be used if wildcards are used in file names. This mechanism cannot be applied if you use wildcards in the file name. Not all FTP servers support this mechanism. If the server in question does not support this mechanism, an exception is generated. - Overwrite possible existing file: If a file with the same name exists, it is overwritten. Pass input message additionally to output message If this option is activated, the input message is appended to the output message inubit 6.1: Workbench/Process Engine: System Connectors Guide

139 12 HTTP Connector 139 This section details the following topics: Defining and Displaying Parameters, p. 140 Defining and Displaying Headers, p. 141 Dialog HTTP Connector Properties, p. 143 Use Depending on its configuration, an HTTP Connector carries out the following tasks: Input Listener Connector Acts as HTTP server and waits for client requests. This connector type can communicate in a synchronous or asynchronous mode: - Synchronous mode An incoming request starts the workflow behind the Input Listener Connector. After the workflow execution the Input Listener Connector sends back the output message of the last module in the workflow to the client. The HTTP status in the Response can be set in the workflow by using the module variable httpstatus. - Asynchronous mode Upon receiving a request the Input Listener sends an HTTP status message back to the connector the request came from. Then, the workflow is started with the request. The workflow result is not returned. All parameters and headers which were transferred in a request are available as variables during workflow execution. Input Connector Acts as client and sends GET requests to an HTTP server in order to demand data. Parameters are handed over to the query part of the URL. The message content of the response is transferred as the output message of the module to the workflow. With status code < 200 or >= 300, an error is thrown. Medium/Output Connector These connector types send POST requests as clients to an HTTP server. Parameters and the input messages are handed over in the request body. If the response of HTTP server is a status code < 200 or >= 300, an error is thrown. Other status codes are issued by the Medium/ Output Connector as output messages. The HTTP connector supports the HTTP and HTTPs protocols. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) inubit 6.1: Workbench/Process Engine: System Connectors Guide

140 140 HTTP Connector Defining and Displaying Parameters - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) - Configuring SSL Connections and Server Authentication (inubit Process Engine: Administrator and Developer Guide, chap. 5.1, p. 61) - Defining and Displaying Parameters (Workbench/Process Engine: System Connectors Guide, chap. 12.1, p. 140) - Defining and Displaying Headers (Workbench/Process Engine: System Connectors Guide, chap. 12.2, p. 141) 12.1 Defining and Displaying Parameters Defining parameters Parameters are any name/value pairs and are passed on as follows, depending on the connector type: Connector type Method Parameter passing Input Connector GET As parameter of the server URL, e. g. servlet/ibishttpuploadservlet/ HTTPinputCon?PAR1=1234&PAR2=abc Refer to Dialog HTTP Connector Properties (Workbench/ Process Engine: System Connectors Guide, chap. 12.3, p. 143). Medium/Output Connector POST As parameter in the request body, e. g. Par1=1234&Par2=abc. You define these parameters when creating or editing a Medium or Output Connector. Refer to HTTP header configuration (Workbench/Process Engine: System Connectors Guide, chap. 12, p. 143). All parameters are available as variables during workflow execution and can be changed dynamically. The variables are named according to the pattern: <Key>=<Value>. You can modify these variables dynamically by using the variables mapping. Refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351). Displaying parameters Input Connector You can display the parameters par1=1232 and par2=abc, which were passed on by an HTTP Input Connector in a GET request to an HTTP Input Listener, at the watch point before the HTTP Input Listener: inubit 6.1: Workbench/Process Engine: System Connectors Guide

141 HTTP Connector Defining and Displaying Headers 141 Medium/Output Connector Parameters which were passed on by an HTTP Output Connector, to an HTTP Input Listener, are displayed at the watch point before the HTTP Input Listener as well: 12.2 Defining and Displaying Headers Defining headers You can define request and response headers when creating and editing an HTTP Connector. Refer to - Input Listener Connector: HTTP header configuration (Workbench/Process Engine: System Connectors Guide, chap. 12, p. 143) - Input Connector: HTTP header configuration (Workbench/ Process Engine: System Connectors Guide, chap. 12, p. 143) - Medium/Output Connector: HTTP post configuration (Workbench/Process Engine: System Connectors Guide, chap. 12, p. 145) inubit 6.1: Workbench/Process Engine: System Connectors Guide

142 142 HTTP Connector Defining and Displaying Headers Displaying headers All headers are available as variables in the workflow: Request headers can be displayed at the watch point before an HTTP Input Listener Connector: Response headers can be displayed at the watch point behind an HTTP Output Connector: Setting and overwriting headers dynamically By using the variables mapping you can dynamically overwrite headers and set new headers. Proceed as follows Define a mapping rule according to the following pattern: Source value > Target value=httpheader.<headername> Example: Refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351) inubit 6.1: Workbench/Process Engine: System Connectors Guide

143 HTTP Connector Dialog HTTP Connector Properties Dialog HTTP Connector Properties This dialog offers the following options: Base configuration Server URL - Input Listener Connector: URL of the Input Listener waiting for requests. The URL is generated automatically according to the following pattern: protocol:hostname:port:pathtoservlet_ DoNotChange_:NameOfInputListener Share the server URL with anyone who sends messages to the HTTP listener for processing. - Input Connector: URL of the server or HTTP Input Listener which the Input Connector. - Medium/Output Connector: URL of the server the connector sends its POST request to, for example Address of an HTTP input listener. SSL (button) (Input, medium and output connector only) For securing the communication with SSL. Refer to Dialog SSL Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 24). Authentication Authentication required This option defines that each client has to identify itself to the Input Listener. - Scheme: Basic authentication requires user name and password; both are transferred unencrypted. - Login name: User name for the authentication. - Password: Password for the authentication. HTTP header configuration HTTP headers are used for transferring information like, for example file size, HTTP server and user agent or MIME type between client and HTTP server. The button Header listing opens a dialog for defining headers as name/value pairs. inubit 6.1: Workbench/Process Engine: System Connectors Guide

144 144 HTTP Connector Dialog HTTP Connector Properties For information about headers refer to the HTTP specification In case a request already contains headers of the same name, these are overwritten with the values defined in the dialog. Encoding Encode/decode Base64 When activated, then incoming data is Base64-encoded before sending it. This option is useful for receiving binary data. Conversion AJAX/XML conversion When activated, then incoming AJAX requests generated by a Task Generator are converted to XML, as it is available in the output mapping. When not activated, then these requests are handed over as byte stream. Group input fields When activated, all text fields in the input message having the same index are wrapped by a Group element. This allows to iterate over groups of text fields using xsl:for-each in a subsequent XSLT Converter. Example: IN: list of text fields First name.1 Surname.1 Street.1 City.1 First name.2 Surname.2 Street.2 City.2 Out: List of groups <Group> <First name/> <Surname/> <Street/> <City/> </Group> <Group> <First name/> <Surname/> <Street/> <City/> </Group> Text fields have an index when they were generated by copying using the JavaScript function copycomponentis(). This function is available in all forms of the Task Generator. Refer to Task Generator (Data Converter) (Workbench/Process Engine: Modules Guide, chap. 4, p. 55). Convert HTTP input message to XML inubit 6.1: Workbench/Process Engine: System Connectors Guide

145 HTTP Connector Dialog HTTP Connector Properties 145 When activated, incoming HTTP or Multipart/form requests (incl. header etc.) are converted to XML. When not activated, the body of the http request is written into the output message without being converted. Multipart-MIMEs must then be parsed. Synchronous HTTP answer Activate If activated, the Input Listener receives the request, starts the workflow and waits for its result. The result is the output message of the last module in the workflow. As soon as the result is available, the Input Listener returns it to the module which called the Input Listener, together with a status message. If not activated, then the Input Listener receives a request, returns the status message immediately and then starts the workflow. No result is returned. Return error message If activated, an exception or a detailed error message is returned to the client if an internal server error (error code 500) occurs. If not activated, only error code 500 is returned, without any additional information. HTTP post configuration (Medium and output connector only) For parameter passing: Format output as HTTP Post request Activate the option to pass on parameters. If activated, input messages in the request body are URL encoded and formatted as if they were sent by a browser via an HTML form, e. g.: Post field name for data You can replace the POST field xml (s. fig. above) by an arbitrary name, e. g. Input data : inubit 6.1: Workbench/Process Engine: System Connectors Guide

146 146 HTTP Connector Dialog HTTP Connector Properties Add HTTP Post value pairs Opens a dialog where you can define parameters as name/value pairs. The parameters are added at the end of the request body, e. g.: Connection test Test connection For testing whether the connection can be successfully established using your configuration. (Input, medium and output connector only) inubit 6.1: Workbench/Process Engine: System Connectors Guide

147 13 inubit IS Connector 147 This section details the following topics: Thin Clients as Clients, p. 147 inubit Process Engine as Client, p. 148 Dialog Descriptions, p. 149 Use The inubit IS connector can receive data from a client to trigger the processing of a workflow or send messages processed by a workflow to a client. For this communication, the variables are transmitted in addition to the messages. To communicate with clients, inubit IS connectors use the Thin Client Interface. Clients can be e.g. thin clients or other inubit Process Engines. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 13.1 Thin Clients as Clients If the inubit Process Engine is located centrally on the Internet (e.g. ASP operation) or if a direct connection to enterprise applications is not possible or not desired, you can develop thin clients for communication between source and target applications with the inubit Process Engine. In this scenario, the thin client queries data from a source application and sends it to an inubit IS input listener connector, thus triggering a workflow. At the end of the workflow, an inubit IS output listener connector stores the result data in an export directory. Another thin client can fetch this data by means of a file download function and forward it to the target application. Source application Thin Client I Listener O Listener Thin Client Target application inubit 6.1: Workbench/Process Engine: System Connectors Guide

148 148 inubit IS Connector inubit Process Engine as Client 13.2 inubit Process Engine as Client In a distributed environment with multiple inubit Process Engines, the inubit Process Engines communicate with each other via inubit IS connectors. O active I Listener O Listener I active O Listener I active M active O active I Listener I Listener The graphic shows how workflows can be executed on different inubit Process Engines using a central inubit Process Engine and under the assignment of all types of inubit IS connectors. The inubit IS connectors have the following functions depending on their configuration: The inubit IS input listener connector receives data for processing from an inubit IS output connector installed on a remote inubit Process Engine. The inubit IS output listener connector stores processed data in the export directory of the workflow. An inubit IS input connector on a remote inubit Process Engine fetches this file. The inubit IS input connector fetches files from an inubit IS output listener connector on a remote inubit Process Engine using a file download function. The inubit IS output connector sends result data directly to an inubit IS input listener connector on a remote inubit Process Engine. The inubit IS medium connector sends the intermediate results of a workflow to an inubit IS input listener connector on a remote inubit 6.1: Workbench/Process Engine: System Connectors Guide

149 inubit IS Connector Dialog Descriptions 149 inubit Process Engine. The results of the workflow processes triggered there are returned to the successor of the inubit IS medium connector as an input message Dialog Descriptions This section details the following topics: Dialog Authentication, p. 149 Dialog Function, p. 149 Dialog Connection data, p. 150 Dialog Input file(s), p. 150 Dialog Output File(s), p Dialog Authentication (For Input Listener Connectors) The dialog for the configuration of input and output listener connectors queries the access data for the inubit Process Engine with which a client has to authenticate itself in order to be able to send data to the inubit IS connector. Enter any user name and a password Dialog Function In this dialog you define the connector s function. The available functions depend on the connector s configuration: Input connector: File download Medium connector: Execute workflow Listener output connector: Save as file Output connector: - Execute workflow: Data is sent and directly processed by a workflow. inubit 6.1: Workbench/Process Engine: System Connectors Guide

150 150 inubit IS Connector Dialog Descriptions - File upload: Data is loaded to the remote server and the workflow is executed later on Dialog Connection data (For medium and input connectors only) In this dialog you enter the access data for the remote inubit Process Engine from which the inubit IS connector is to fetch data. Base configuration Server URL Replace localhost with the name or IP address of the inubit Process Engine. SSL For the client and/or server authentication. Opens the Dialog SSL Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 24). Authentication Login name/password Authentication for the inubit Process Engine. Workflow Name: Name of the workflow with which the connection is to be established. System connector: Name of the system connector. Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog Input file(s) (Input connector) You can use the dialog for the configuration of the input connector to configure the reading of files from remote inubit Process Engine inubit 6.1: Workbench/Process Engine: System Connectors Guide

151 inubit IS Connector Dialog Descriptions 151 Input file(s) Directory Name of the directory from which the connector is to receive files. File name(s) Name of the file or files that the connector is to receive. You can use wildcards when specifying the file name. Example: /Inputdata/*.xml. Use wildcard content of the preceding file or FTP connector If selected, the wildcard content generated by a previously executed file or FTP connector is used. Example: Test*.xml was specified in the File name field in the configuration of a previously executed file connector. The file connector forwarded a file with the name Test5.xml as the output message. In this case, the wildcard content is the digit 5. If you have also specified a wildcard in the current connector (for example, Output*.xml), the digit 5 is entered in the position of the wildcard. Delete files after reading If selected, the files are deleted after being read. - Throw error if delete fails If selected an error item is displayed in the Queue Manager for the workflow with this module. If an error output is configured, it runs. Otherwise, the execution of the module is terminated. Max. number of executions per scheduled call Numerical value such as 100. This controls the system load on the server when file connectors are called. Read order Defines the order in which files are fetched Dialog Output File(s) (Output listener connector) You use the dialog to configure the writing of files. Output file(s) Directory Name of the directory from which the connector is to receive files. File name(s) Name of the files or files that the connector is to receive. You can use wildcards when specifying the file name. Example: / Inputdata/*.xml. inubit 6.1: Workbench/Process Engine: System Connectors Guide

152 152 inubit IS Connector Dialog Descriptions Use wildcard content of the preceding file or FTP connector If selected, the wildcard content generated by a previously executed file or FTP connector is used. Example: Test*.xml was specified in the File name field in the configuration of a previously executed file connector. The file connector forwarded a file with the name Test5.xml as the output message. In this case, the wildcard content is the digit 5. If you have also specified a wildcard in the current connector (for example, Output*.xml ), the digit 5 is entered in the position of the wildcard. Use the file name of the previously executed file connector If selected, the file name used by a previously executed file connector is used. Example: Test.xml was specified in the Directory and file name field in the configuration of a previously executed file connector. The file connector forwards a file called Test.xml as the output message. This file name is also used here. Add data to file If you select this option, the specified file is not overwritten each time the output connector is executed. Instead, the output message is appended to the file with each execution. This can be useful if you want to log cumulative log data in a file. Overwrite possible existing file This option is selected by default. If a file with the same name exists, it is overwritten. Set input message additionally to output message If selected, the input file is forwarded to the subsequent module. Depending on the size of the input files, selecting this option can affect the performance of your system inubit 6.1: Workbench/Process Engine: System Connectors Guide

153 14 ITA Connector 153 This section details the following topics: Prerequisites for Operating the Connector: Installing Drivers, p. 153 Inserting Documents into the ITA Archive System, p. 154 Reading Documents From the ITA Archive System, p. 156 Dialog ITA Archive Connector, p. 157 Use With an ITA Connector you can insert documents into an ITA archive system (produced by SER Solutions Deutschland GmbH ) and read them. The ITA archive system offers structured searching for documents. Therefore document attributes are stored and managed in the SERaTIO index database. Accordingly, the ITA Connector also supports assigning document attributes when inserting documents. Connector types An ITA Connector is always used as Medium Connector because it expects an XML formatted query as input message, receives the query result from the ITA archive system and hands it over to the next module in the Technical Workflow. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 14.1 Prerequisites for Operating the Connector: Installing Drivers To run the ITA Connector, you need to request the following *.jar files of the 5.0.x version from your ITA-Provider and to copy them into your inubit installation: blconfig.jar blmetadata.jar blueline.jar bluelineimpl.jar bluelineutil.jar jdom.jar inubit 6.1: Workbench/Process Engine: System Connectors Guide

154 154 ITA Connector Inserting Documents into the ITA Archive System The file version depends on the version of the ITA server you are using. Proceed as follows 1. Stop your inubit Process Engine. 2. Copy the *.jar files to the <inubit-installdir>/server/ Tomcat/webapps/ibis/WEB-INF/lib directory. 3. Start your inubit Process Engine Inserting Documents into the ITA Archive System The figure illustrates how a document is inserted into an ITA archive system: 1. The File Connector reads the document from the file system. 2. The XML Enveloper converts the document s contents into an XML format. 3. The XSLT Converter converts the contents of the XML formatted document into an XML based query. In this query the operation is defined the ITA Connector should execute (in this case: Insert). The query must be compliant to the XML Schema of the ITA Connector. The XML Schema is located in the Repository at Global > System > Mapping Templates > ITA Archive Connector > Query.xsd. In the same directory you also find a sample query (queryinsert.xml) for inserting a document. In this step descriptors can be added to the document. Descriptors are information about documents, as for example file names or creation dates. Refer to Example: Insert with complex descriptors (Workbench/ Process Engine: System Connectors Guide, chap. 14, p. 155) 4. The ITA Connector receives the XML based query as input message and sends it to the ITA archive system inubit 6.1: Workbench/Process Engine: System Connectors Guide

155 ITA Connector Inserting Documents into the ITA Archive System 155 The ITA archive system archives the document, adds the document s attributes to the index database and returns a copy of the document and the document ID to the ITA Connector. The ITA Connector outputs both as XML formatted output message. 5. The XSLT Converter extracts the document ID and hands it over to the File Connector. 6. The File Connector writes the document ID into the file system. Example: Simple insert You also find the following listing in the Repository under Global > System > Mapping Templates > ITA Archive Connector > QueryInsert.xml : <?xml version="1.0" encoding="utf-8"?> <Query type="insert"> <Document maskid="4711" date=" t11:45:00"> <Representations> <Representation description="std-rep" type="ascii"> <Part> <Data>MyDocument</Data> </Part> </Representation> </Representations> </Document> </Query> Example: Insert with complex descriptors The following listing shows how to add descriptors when inserting a document: <?xml version="1.0" encoding="utf-8"?> <Query type="insert"> <Document maskid="4711"> <Descriptors> <Descriptor id="1234"> <Value type="string">mydoc.txt</value> </Descriptor> <Descriptor id="2345"> <Value type="string">head</value> </Descriptor> <Descriptor id="3456"> <Value type="integer">123</value> </Descriptor> <Descriptor id="4567"> inubit 6.1: Workbench/Process Engine: System Connectors Guide

156 156 ITA Connector Reading Documents From the ITA Archive System <Value type="date"> </value> </Descriptor> </Descriptors> <Representations> <Representation type="ascii" description="invoice"> <Part> <Data>Data</Data> </Part> </Representation> </Representations> </Document> </Query> 14.3 Reading Documents From the ITA Archive System The figure illustrates how a document is read from the ITA archive system: 1. The XSLT Converter creates an XML based query. In this query the operation to be executed is defined (in this case: Select). Additionally,. the document ID must be indicated. The query must be compliant to the XML Schema of the ITA Connector. You find the XML Schema in the Repository at Global > System > Mapping Templates > ITA Archive Connector > Query.xsd. 2. The ITA Connector gets the XML base query as input message, sends it to the ITA archive system, receives the document from the ITA archive system and outputs it as XML formatted message. 3. The XSLT Converter extracts the document from the XML message. 4. The File Connector writes the document into the file system inubit 6.1: Workbench/Process Engine: System Connectors Guide

157 ITA Connector Dialog ITA Archive Connector 157 Example <?xml version="1.0" encoding="utf-8"?> <Query type="select"> <Document maskid=" "/> </Query> 14.4 Dialog ITA Archive Connector This dialog offers the following options: Basic configuration Seratio server name/port Domain or IP address of the Seratio index server. The default port number is The Default button restores the default port number. Archive server name/port Domain or IP address of the ITA archive server. Frequently, the IP addresses of the Seratio server and the archive server are the same. The default port number is The Default button restores the port number. Authentication System database name/default Name of the system database. The default name is SYSTEM. The Default button restores the default name. System name This specification is case-sensitive. Login/Password Access data for the database. Sub-stock Database name Usually, database systems are divided into segments. Enter the database name here. Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

158 158 ITA Connector Dialog ITA Archive Connector inubit 6.1: Workbench/Process Engine: System Connectors Guide

159 15 JAAS Connector 159 This section details the following topics: Example Scenario: Checking a List of User Accounts, p. 160 Example Scenario: Validating User Data with Task Forms, p. 161 Extending the JAAS Connector, p. 161 Dialog JAAS Connector Properties, p. 162 Use JAAS (Java Authentication and Authorization Service) is a Java interface that provides classes for the authentication and authorization of the user currently logged in for the Windows, Solaris, and Unix operating systems. The authentication and authorization procedure checks whether a user has access permission (authentication) and which rights that user has (authorization) if access is permitted. The JAAS Connector provides a generic container for different authentication classes. By default, a JAAS Connector offers the following functions: Authenticating user accounts in common name and directory services such as LDAP or NIS with the JNDI module (Java Naming and Directory Interface) Authenticating user accounts on Windows operating systems To enable the validation of diverse user accounts on Windows operating systems, the NTLM (Microsoft NT LAN Manager) authentication protocol is supported. It is valid for all Windows systems with an NT domain controller. User accounts of the Microsoft Active Directory service can also be authenticated in this way. Additionally, you can load any self-developed modules and use them for authenticating user accounts. Also refer to - JAAS Reference Guide: security/jaas/jaasrefguide.html - JAAS login module documentation: - JNDI overview: Connector types The JAAS Connector is used as medium connector. The JAAS Connector expects the user account data (user name/ password) which are to be validated as input message. The user account data must be handed over in unencrypted form. inubit 6.1: Workbench/Process Engine: System Connectors Guide

160 160 JAAS Connector Example Scenario: Checking a List of User Accounts The JAAS Connector hands over the user account data to the configured system which checks the authenticity of the data and returns the result to the JAAS Connector. If the validation is successful, the JAAS Connector outputs the input message without changes. If the validation fails, the JAAS Connector outputs an XML based error message. This error message contains, amongst others, an error text describing the reason why the validation failed. Additionally, the input message is added to the error message and output. If the input message was not an XML file, it is base64-encoded and output as attachment. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 15.1 Example Scenario: Checking a List of User Accounts A program regularly collects user account data (login/password) and compiles them in an XML file. The Data input File Input Connector passes this file to the Validation Demultiplexer. The Demultiplexer splits the XML file, creates a new XML file for each login/password pair, and passes the files to the Authentication JAAS Connector. The JAAS Connector validates each login/password pair. If the validation fails, an error element is added. The output file is passed to the True Failed Delivery Demultiplexer inubit 6.1: Workbench/Process Engine: System Connectors Guide

161 JAAS Connector Example Scenario: Validating User Data with Task Forms 161 The Demultiplexer is configured so that all files with an error element for which validation failed are passed to the Failed-Out File Output Connector. All other files are passed to the True-Out File Output Connector Example Scenario: Validating User Data with Task Forms The depicted workflow validates login data that has been entered in a form task. The workflow is started by the Trigger File Input Connector. The Account Validation Task Generator generates a form task that is displayed in the task list. This form task consists of input field for the user name and password and a Submit button. If you click the Submit button, the entered data is passed to the Form Validation JAAS Connector. If the form task is called again, the form is displayed again. If any of the entered data is incorrect, an error message is displayed Extending the JAAS Connector You can extend the JAAS Connector with self-developed authentication modules. To do this, you have to upload the JAR file of the authentication module to the inubit Process Engine. Proceed as follows 1. Load the JAR file into the inubit Process Engine: Refer to Installing Plug-ins (inubit Process Engine: Administrator and Developer Guide, chap , p. 284). inubit 6.1: Workbench/Process Engine: System Connectors Guide

162 162 JAAS Connector Dialog JAAS Connector Properties 2. Create a JAAS Connector. 3. In the Dialog JAAS Connector Properties (Workbench/Process Engine: System Connectors Guide, chap. 15.4, p. 162) in the Login Module field enter the class name. 4. In the Login Module Options table enter the parameters of your module and their values. 5. Click Finish to close the dialog Dialog JAAS Connector Properties You use the dialog to specify how the user account data is made available to the connector and which system should be used to validate this data. Login module com.sun.security.auth.module.jndiloginmodule For validating user account data against an LDAP or NIS directory service. org.jaaslounge.ntlm.ntlmloginmodule For validating user account data against an NT domain controller or the Microsoft Active Directory service on a Windows operating system. User name Specify how the user name is passed to the JAAS Connector: D The user name is taken from an element in the XML based input messages. The element containing the user name is selected by using an XPath expression. To select the element and display the XPath expression, click Select XML element, load a sample message and navigate to the respective element. The XPath expression is displayed in the User name field. If the XPath expression appears more than once in an XML document, only its first appearance is analyzed. Subsequent appearances are ignored. V The user name is read from a variable. You have two options: - Specify the system variable ISUserName in the User name field box inubit 6.1: Workbench/Process Engine: System Connectors Guide

163 JAAS Connector Dialog JAAS Connector Properties Use a self-.defined variable. Refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351). Fix The character string specified in the subsequent User name text box is used as the user name. You can only test the connection with the Fix option. Password The password is passed in the same way as the user name. D: The password comes from the XML-based input messages. V: The password is read from a variable. You have to create your own variable, since there is no variable for the password by default. Fix: Enter a password for testing the connection. Login module options The login module options are used to set the values that are required to connect with the system in which the specified user account is to be validated. The table contains pre-filled entries for the login modules in the standard delivery. If you are using a login module that you created yourself, you have to enter the parameters into the table manually. To edit the table, use the following buttons. Add new row Delete selected row Move selected row up one Move selected row down one As a rule, the sequence of the login module options is not important for processing; however, it does improve clarity. Connection test Test connection For testing whether the connection can be successfully established using your configuration. The connection test can only be executed successfully if you use the option Fixed and enter user name and password manually. This is inubit 6.1: Workbench/Process Engine: System Connectors Guide

164 164 JAAS Connector Dialog JAAS Connector Properties because user account data from input messages or variables are not available at the time of the test inubit 6.1: Workbench/Process Engine: System Connectors Guide

165 16 Java Reflection Connector 165 This section details the following topics: Create Input Message, p. 165 Creating Your Own Method Call, p. 166 Example Method Call, p. 168 List of Attributes, p. 171 Dialog Java Reflection Connector Properties, p. 171 Use Using a Java Reflection Connector you can access Java objects at runtime and manipulate them. The Java Reflection Connector access the Java Reflection API which allows the following: Determine properties of a class Generate objects Call methods The Java Reflection Connector supports calling of static and nonstatic methods for a Java object. Parameters can be set with primitive data types (e. g. in, long, char) and complex data types (any Java object). By using the Java Reflection Connector no Java algorithms (loops, branches, processing logic) can be executed. No inubit internal classes like, for example, ibis.jar and hence classes like Misc and Formatter can be used! Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 16.1 Create Input Message The Java Reflection connector requires an XML message with the following content as the input message: Class name of the object to be created Parameters for the constructor (types and values) Name of the method to be called inubit 6.1: Workbench/Process Engine: System Connectors Guide

166 166 Java Reflection Connector Creating Your Own Method Call Parameters of the method (types and values) The output message has the same structure as the input message. If required, the output message can contain the properties of the reflection class. Always create a serialized XML structure by using the Java Reflection Explorer, as described in the following! Manually created XML structures may not be interpreted by the Java Reflection Connector and result in an error in the module. Proceed as follows 1. Create an XSLT Converter. 2. Click the button in the panel XML Target File. A menu opens. 3. Select Open > Java Reflection Explorer. The wizard opens. The wizard guides you in the creation of the message. Refer to - Creating Your Own Method Call (Workbench/Process Engine: System Connectors Guide, chap. 16.2, p. 166) - Example Method Call (Workbench/Process Engine: System Connectors Guide, chap. 16.3, p. 168) 16.2 Creating Your Own Method Call Prerequisites To trigger the execution of a Java method with the Java Reflection connector, you have to load the JAR file containing the class to the inubit Process Engine. Refer to Installing Plug-ins (inubit Process Engine: Administrator and Developer Guide, chap , p. 284). Proceed as follows 1. Open the Java Reflection Explorer. Refer to Create Input Message (Workbench/Process Engine: System Connectors Guide, chap. 16.1, p. 165). 2. In the first dialog, select the option Define Class/Method. 3. Click the Next button. The next dialog is displayed. 4. Select the class, on which the method call should be performed inubit 6.1: Workbench/Process Engine: System Connectors Guide

167 Java Reflection Connector Creating Your Own Method Call 167 In case the desired class is not displayed in the list, enter the complete name (e. g. java.lang.stringbuffer) into the text field. 5. Click the Next button. The corresponding class is loaded (if possible). If the class could be loaded, the next dialog is displayed. 6. Enter constructor If all methods to be called are static, the selection of a appropriate constructor of this class is omitted. If at least one of the method calls is not-static, you must specify a class constructor. a. Select a node Constructor in the tree. b. Open the context menu and select Add constructor. c. Select an appropriate constructor. d. Click the OK button. The dialog closes. The constructor is inserted. The parameters are displayed below the constructor node. 7. Insert method a. Select the node Methods in the tree. b. Open the context menu and select Add method. A dialog opens. c. Select all methods, which are to be called. d. Click the OK button to get back to the tree view. The selected methods are inserted and all parameters are displayed below the method node. 8. Set parameter values In order to make a method call complete, you need to fill the parameters with specific values. a. Select a parameter. b. Open the context menu and select Set value. A dialog opens. Specify the value for the selected parameter here. The data type of the parameter is displayed for support. If the parameter is a Java object with a complex data type then the corresponding constructor for creating this Java object has to be selected first. Proceed as described in the step Enter constructor, above. 9. If the configuration is complete, finish the wizard. The input message structure is created and displayed. 10. Drag the structure into the panel XML Target on the <xsl:template> element to create the XSLT style sheet. Refer to Creating a Technical Workflow 3: Converting CSV- XML to opentrans (Tutorials, chap. 4.5, p. 67). Using XSLT you can - adapt and overwrite the parameter values at run time. - realize dynamic Java Reflection calls. inubit 6.1: Workbench/Process Engine: System Connectors Guide

168 168 Java Reflection Connector Example Method Call 16.3 Example Method Call Java code The provided example Calling a method with simple parameters on a class instance implements the following Java code: String teststring = "This is a test string to be parsed and manipulated".; String resultstring = teststring.substring( 1, teststring.length() ); Refer to - Listing (Workbench/Process Engine: System Connectors Guide, chap. 16, p. 168) - Calling a method with simple parameters on a class instance: (Workbench/Process Engine: System Connectors Guide, chap. 16, p. 168) - Create Input Message (Workbench/Process Engine: System Connectors Guide, chap. 16.1, p. 165) Result The output message contains the value of the variable resultstring: This is a test string to be parsed and manipulated. Listing Calling a method with simple parameters on a class instance: Listing 1 <?xml version="1.0" encoding="utf-8"?> 2 <reflection> 3 <!-- first declare class instance --> 4 <object name="teststring"> 5 <java.lang.string> 6 This is a test string to be parsed and manipulated. 7 </java.lang.string> 8 </object> 9 <!-- in this example java.lang.string.substring(1,$teststring.length()) is called --> 10 <!-- the result is stored in the variable resultstring --> 11 <length object="$teststring" result="stringlength"/> 12 <substring object="$teststring" result="resultstring"> 13 <param type="int"> 14 <int>1</int> 15 </param> 16 <param type="int" object="$stringlength" name=""/> 17 </substring> /Listing inubit 6.1: Workbench/Process Engine: System Connectors Guide

169 Java Reflection Connector Example Method Call 169 Listing 18 <!-- so that the result can be output afterwards or reused in another method call --> 19 <result value-of="$resultstring"/> 20 </reflection> /Listing Input and output message structure 1. Root element The Root element for all Java Reflection input messages must be named <reflection>. 2. Call constructor String TestString: This is a test string to be parsed and manipulated. The variable teststring is created at first and filled with the value: This is a test string to be parsed and manipulated. <object name="teststring"> <java.lang.string>this is a test string to be parsed and manipulated.</java.lang.string> </object> The element <object> states that this is the definition of a class instance. This depicts the creation of a Java object by using a corresponding Constructor call (child element of <object>). The attribute name="teststring" gives a name to the class instance, for reusing this class instance someplace else in the XML with the reference name. As child element of <object>, the object itself is depicted as serialized XML structure. 3. Method calls String resultstring = teststring.substring( 1, teststring.length() ); The Java code contains two method calls and must therefore be fragmented. The method call teststring.length() corresponds to the following XML structure: <length object="$teststring" result="stringlength"/> - Element name <length> corresponds to the method name, which is to be called on the class instance. - Attribute object="$teststring": States the class instance. The reference name must begin with a $ (Dollar) sign, because it is a reference. For static methods, the value of the attribute <object="" can be the name of the underlying class, e. g. object="java.lang.string". - Attribute result="stringlenght": inubit 6.1: Workbench/Process Engine: System Connectors Guide

170 170 Java Reflection Connector Example Method Call Deposits the return value of the called method in the variable with the reference name "stringlenght". These variables can be used elsewhere in the XML, like with the class instance. The method call teststring.substring() is called by the following XML structure: <substring object="$teststring" result="resultstring"> <param type="int"> <int>1</int> </param> <param type="int" object="$stringlength" name=""/> </substring> - Element name <substring>: corresponds to the method name, again, which is called on the class instance. teststring is used as class instance, here, too. - Attribute <result="resultstring">: The variable contains the result of the method call. - Element name <param>: Two more parameters are handed over to the method. - Attribute type="int": States the parameter type (here: int). The value of the parameter follows as child element: - The value of the first parameter is 1. - The value of the second parameter is not specified, instead, the value of the variable $stringlength is used. - object="$stringlength": contains the result of the previous method call. The variable is referenced with a $ (Dollar) sign and variable name, here, too. - Attribute name="": Name of the parameter, for reusing it elsewhere in the XML. Optional. Make sure that reference names are unique in an XML. If a reference name is used more than once, the content of the variable is overwritten with the next declaration. Reference names are declared globally and are available in the complete <reflection> element. 4. Result and XML output message <result value-of="$resultstring"/> inubit 6.1: Workbench/Process Engine: System Connectors Guide

171 Java Reflection Connector List of Attributes 171 The output of the Java Reflection Connector is controlled by the element <result>. The structure of the output message corresponds to the XML input message. The only difference is that all <result> elements are resolved at runtime and that the corresponding content of the referenced variables is entered. The result of the example given above looks like this: <result value-of="$resultstring"> <string> his is a test string to be parsed and manipulated. </string> </result> 16.4 List of Attributes Attribute Applicable <object> element <param> element Methods element <param> element Reference name of the class value (class instance) resp. of the method parameter (parameter value) Class name (e.g. java.lang.string) resp. reference name ($- Character + Reference Name) on which the method resp. the parameter is to be Methods element Reference name of the return value of a <param> element Declaration of the class of the method parameter type (e.g. java.lang.string) 16.5 Dialog Java Reflection Connector Properties This dialog offers the following options: Output options Results only If activated, the output message only contains the XML element <result>. The input message is not emitted. This option improves clarity and performance for large XML input messages. inubit 6.1: Workbench/Process Engine: System Connectors Guide

172 172 Java Reflection Connector Dialog Java Reflection Connector Properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

173 17 JCA Connector 173 This section details the following topics: Principles of Operation, p. 173 Creating Input Messages, p. 174 Sample Input Message, p. 176 Dialog J2EE Connector Architecture Adapter, p. 177 Use With the JCA Connector (J2EE Connector Architecture) you can integrate any applications into the inubit software. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 17.1 Principles of Operation Requirements The inubit Process Engine must be deployed in the JBoss application server. For communicating with the remote application you need a resource adapter. You will get the Resource as *.rar file from the producer of the application which you want to integrate. The resource adapter must be deployed on the same JBoss as the inubit Process Engine. For using the JCA Connector Explorer wizard, you must load the JCA library (jar file) into the inubit Process Engine. The JCA library is included in the *.rar file of the Resource Adapter. Refer to Installing Plug-ins (inubit Process Engine: Administrator and Developer Guide, chap , p. 284). inubit 6.1: Workbench/Process Engine: System Connectors Guide

174 174 JCA Connector Creating Input Messages J2EE Server JCA Connector Resource Adapter Business Software Der JCA Connector transfers parameter values with the help of the resource adapter to the remote application for processing: 1. A JCA Connector expects an input message containing parameter values. You create this input message with an XSLT Converter by using the JCA Connector Explorer. 2. The JCA Connector connects with the Resource Adapter and forwards the parameters to it. The Resource Adapter provides the JCA interface for the JCA Connector and is connected with the application which is to be integrated. 3. The Resource Adapter forwards the parameters to the application where they are processed. 4. In case the application creates return values, these are returned via the Resource Adapter to the JCA Connector. The JCA Connector finally outputs them as XML output message Creating Input Messages For creating an input message, you use the JCA Connector Explorer. When creating, you specify the InteractionSpec class and a record dataset object. Proceed as follows 1. Create an XSLT Converter. 2. In the area XML target file click the button. A menu opens. 3. Select Open from > JCA Explorer. The wizard opens. 4. Select one of the following options: - Choose JCA library (*.jar) Select this option, if you know the name of the JCA library. This selection restricts the available classes to those which the library offers and makes it easier to find matching entries inubit 6.1: Workbench/Process Engine: System Connectors Guide

175 JCA Connector Creating Input Messages Choose JCA InteractionSpec class Select this option, if you don't know the name of the JCA library. Using the InteractionSpec class, the functions which are called on the JCA Resource Adapter are specified. 5. Click Next and let the wizard guide you through the following dialogs. 6. Specify record Select the dataset type, which serves as input parameter and name it: - MappedRecord: List whose values are referenced by an alphanumerical index. - IndexedRecord: List whose values are referenced by a numerical index. 7. Add method a. In the tree, select the node Methods. b. Open the context menu and select Add method. A dialog opens. c. Select all methods which are to be called. d. Click OK to return to the tree view. The selected methods are added and all parameters below the method node are set. 8. Set parameter values For sending a complete method call, you need to fill the parameters with specific values. a. Select a parameter. b. Open the context menu and select Set value. A dialog opens. Use this dialog to set the value. For support, the data type of the parameter is displayed. If the parameter is a Java object with complex data type, then you must first select a matching constructor for creating this Java object. 9. As soon as all settings are complete, you finish the wizard. The input message structure is created and displayed. 10. Drag the structure into the XSLT template for creating the XSLT stylesheet. Refer to Creating a Technical Workflow 3: Converting CSV- XML to opentrans (Tutorials, chap. 4.5, p. 67) for more information about using the XSLT Converter. inubit 6.1: Workbench/Process Engine: System Connectors Guide

176 176 JCA Connector Sample Input Message 17.3 Sample Input Message The JCA Connector provides the variables cf and ix, which can be used within an XML input message: $cf offers access to an instance of the interface type javax.resource.cci.connectionfactory. $ix can access an instance of the interface type javax.resource.cci.interaction. For detailed information about the structure of input and output messages refer to Calling a method with simple parameters on a class instance: (Workbench/Process Engine: System Connectors Guide, chap. 16, p. 168). Input message Listing 1 <?xml version="1.0" encoding="utf-8"?> 2 <jca> 3 <!--References:--> 4 <!--cf - javax.resource.cci.connectionfactory class from JCA Connector- -> 5 <!--ix - javax.resource.cci.interaction class to execute JCA call on--> 6 <object name="ispec"> 7 <com.dsoft.jca.eis.eisinteractionspec> 8 <a>a</a> 9 <functionname>functionname</functionname> 10 <schema>schema</schema> 11 </com.dsoft.jca.eis.eisinteractionspec> 12 </object> 13 <seta object="$ispec" result=""> 14 <param type="java.lang.string" name=""> 15 <string>a</string> 16 </param> 17 </seta> 18 <getrecordfactory object="$cf" result="rf"/> 19 <createindexedrecord object="$rf" result="irec"> 20 <param type="java.lang.string"> 21 <java.lang.string>inputrecord</java.lang.string> 22 </param> 23 </createindexedrecord> 24 <execute object="$ix" result="rec"> 25 <param type="javax.resource.cci.interactionspec" object="$ispec"/> /Listing (Abschnitt 1 von 2) inubit 6.1: Workbench/Process Engine: System Connectors Guide

177 JCA Connector Dialog J2EE Connector Architecture Adapter 177 Listing 26 <param type="javax.resource.cci.record" object="$irec"/> 27 </execute> 28 <result value-of="$rec"/> 29 </jca> /Listing (Abschnitt 2 von 2) Java code When using the sample input message, the following Java code is executed: Listing 1 // following code is covered by JCA module settings 2 ConnectionFactory cf = ; 3 Connection con = cf.getconnection(); 4 Interaction ix = con.getinteraction(); 5 // following code is covered by JCA input message 6 EisInteractionSpec ispec = new EisInteractionSpec(); 7 ispec.seta("a"); 8 RecordFactory rf = cf.getrecordfactory(); 9 IndexedRecord irec = rf.createindexedrecord("inputrecord"); 10 Record rec = ix.execute(ispec, irec); /Listing Output message The output message contains the value of the variable rec Dialog J2EE Connector Architecture Adapter In this dialog you configure the JCA Connector s properties. General settings Connection factory lookup name (JNDI) Name of the JCA Adapter connection factory, e.g. java:/eis/ PropertiesFileAdapter. With the connection factory, you specify the Resource Adapter to which the connection should be established. The connection factory is provided by the Resource Adapter and registered with the JBoss via the JNDI. inubit 6.1: Workbench/Process Engine: System Connectors Guide

178 178 JCA Connector Dialog J2EE Connector Architecture Adapter Authentication Authentication required Select this option if authentication with the resource adapter is required. ConnectionSpec class name Class name of the ConnectionSpec. For passing on the authentication data to the method getconnection of the ConnectionFactory. If left blank, the connection to the Resource Adapter is established without parameters and no authentication takes place. User name Specify the user name for the resource adapter here. Password Specify the password for the resource adapter here. Connection test Test connection For testing whether the connection can be successfully established using your configuration. Output options Results only If activated, the output message only contains the XML element <result>. The input message is not emitted. Improves clarity and performance for large XML input messages inubit 6.1: Workbench/Process Engine: System Connectors Guide

179 18 JMS Connector 179 This section details the following topics: Configuring the Access on the JMS based Queuing Server, p. 180 Dialog Descriptions, p. 182 Use The JMS (Java Message Service) connector connects the inubit Process Engine with any JMS provider. Connector types The connector provides the following functions depending on its configuration: Input Connector Fetches time-driven messages from a JMS provider and passes them on to the subsequent module in the Technical Workflow. Input Listener Connector Waits for messages from a JMS provider. When these have arrived, the connector starts the Technical Workflow by handing over the messages to the subsequent module. Medium Connector Is started by receiving a message from the preceding module in the workflow, fetches messages from a JMS provider and passes them to the subsequent module in the Technical Workflow. Medium Listener Connector Is started by receiving a message from the preceding module in the workflow, and then waits for messages from the JMS Provider. As soon as a message is received, it is passed on to the subsequent module in the Technical Workflow. Output Connector Sends messages from the Technical workflow to a JMS provider. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) inubit 6.1: Workbench/Process Engine: System Connectors Guide

180 180 JMS Connector Configuring the Access on the JMS based Queuing Server 18.1 Configuring the Access on the JMS based Queuing Server Using the JMS Connector in Entry, Standard or Professional Edition, p. 181 Using the JMS Connector in Enterprise/Enterprise Plus Edition with any other JMS based Queuing Server, p. 182 Overview For deploying an JMS Connector you need a JMS based application server with queuing interface, like, for example, the JBoss integrated in an Enterprise Edition. How you configure the access on this JMS based application server, depends on the inubit Edition you are using: inubit Process Engine with Tomcat (Entry, Standard or Professional Edition) You can use the JBoss application server integrated in a remote Enterprise or Enterprise Plus Edition or any other JMS based queuing server. In both cases you need an additional *.jar file to establish the communication between your inubit Process Engine and the JMS based queuing server. Refer to Using the JMS Connector in Entry, Standard or Professional Edition (Workbench/Process Engine: System Connectors Guide, chap , p. 181). inubit Process Engine with JBoss (Enterprise/Enterprise Plus Edition) inubit 6.1: Workbench/Process Engine: System Connectors Guide

181 JMS Connector Configuring the Access on the JMS based Queuing Server 181 You can deploy the JMS Connector without further configuration, because the JMS Connector can use the queuing interface of the integrated JBoss application servers or the remote JBoss integrated on another Enterprise or Enterprise Plus Edition. Alternatively, you can deploy any other JMS based queuing server. Refer to Using the JMS Connector in Enterprise/Enterprise Plus Edition with any other JMS based Queuing Server (Workbench/ Process Engine: System Connectors Guide, chap , p. 182) Using the JMS Connector in Entry, Standard or Professional Edition If you use an Entry, Standard or Professional Edition (based on a Tomcat application server), you can either use the queuing interface of the JBoss application integrated in a remote Enterprise or Enterprise Plus Edition or you can use any other JMS based queuing server. In both cases you need an additional *.jar file to establish the communication between your inubit Process Engine and the remote queuing server. Proceed as follows 1. Request the *.jar file: - If you want to access the JBoss integrated in an Enterprise or Enterprise Plus Edition, request the file ibis_jboss_ provider.jar from the support of the Bosch Software Innovations GmbH. - If you want to access any other JMS based queuing server, request the file *-provider.jar from your JMS provider. 2. Copy the file into the directory <inubit-installdir>/ Tomcat/webapps/ibis/WEB-INF/lib. 3. Restart the Tomcat server. 4. When configuring the JMS Connector, enter the URL of the remote queuing servers in the Dialog Connection configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 182) in the field URL of JNDI server. inubit 6.1: Workbench/Process Engine: System Connectors Guide

182 182 JMS Connector Dialog Descriptions Using the JMS Connector in Enterprise/Enterprise Plus Edition with any other JMS based Queuing Server In order to use the integrated JBoss application server of your Enterprise or Enterprise Plus Edition or a remote JBoss integrated in another Enterprise or Enterprise Plus Edition as queuing interface, no further steps are required. If you wish to use the queuing interface of any other remote, JMS based queuing server, you need an additional jar file to establish the communication between your inubit Process Engine and the remote queuing server. Proceed as follows 1. Request the file *-provider.jar from your JMS provider. 2. Copy the file into the directory <inubit-installdir>server/ JBoss/server/default/deploy/ibis.ear/lib. 3. Restart the JBoss. 4. When configuring the JMS Connector, enter the URL of the remote queuing servers in the Dialog Connection configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 182) in the field URL of JNDI server Dialog Descriptions This section details the following topics: Dialog Connection configuration, p. 182 Dialog Communication model, p. 185 Dialog Message selector, p. 187 Dialog Additional properties, p Dialog Connection configuration You use this dialog to specify the properties required to connect to a JNDI (Java Naming and Directory Interface) provider. JMS uses the JNDI to find required resources inubit 6.1: Workbench/Process Engine: System Connectors Guide

183 JMS Connector Dialog Descriptions 183 Basic configuration Use default JNDI configuration Select this option if you have the jndi.properties file in your class path, and want to use the properties specified there. URL/Prefix/Naming Context Factory Default values for the most common JMS providers: - JBoss: URL = localhost:1099 Prefix = org.jboss.naming Naming Context Factory = org.jnp.interfaces.namingcontextfactory - MQSeries: URL = ldap://<name>:389/<ldap DN> The specifications mean the following: Prefix = com.ibm.jndi NamingContextFactory = com.sun.jndi.ldap.ldapctxfactory - SonicMQ: ContextProviderUrl = file://localhost/ d:sonicmq ContextUrlPrefixes = <empty> NamingContextFactory=com.sun.jndi.fscontext.Re ffscontextfactory - WebLogic: ContextProviderUrl = t3://localhost :7001 ContextUrlPrefixes = <empty> NamingContextFactory = weblogic.jndi.wlinitialcontextfactory Additional JNDI properties Enter arbitrary JNDI properties as property value pairs, e.g.: com.sonicsw.jndi.mfcontext.domain=domain2 com.sonicsw.jndi.mfcontext.idletimeout=6000 Separate multiple properties with a blank. If problems occur, contact the system administrator responsible for the installation of your JMS provider. Message type Messages can be sent/received in the following formats: - TextMessage Data is stored as a string. This message type is useful for exchanging simple text messages and for more complex character data, such as XML documents. - ObjectMessage inubit 6.1: Workbench/Process Engine: System Connectors Guide

184 184 JMS Connector Dialog Descriptions The Object message carries a serializable Java Object as its payload. It is useful for exchanging Java objects. - BytesMessage The payload is stored as an array of bytes. This message type is useful for exchanging data in an application s native format and when JMS is used as a transport between two systems, where the JMS client does not know the message payload type. - StreamMessage A Stream message is a sequence of primitive Java types. The message object keeps track of the order and the types of these primitives within the stream. Formal conversion rules apply; for example, an exception is thrown if a JMS application tries to read a double value as a short value. Refer to the Java Message Service Specification, version 1.1 for a full list of the conversion rules. Example: 21ABCDEFGH consisting of the following fields: - Integer: 21 - String: ABCDEFGH - Float: If the data structure is unknown, the generic method readobject() can be used to return the next object in the stream. If the structure of the data is known, the JMS client can be specific about the type of object being accessed. Refer to JMS Specification, Version 1.1, section Message Selector, in - MapMessage The payload of a MapMessage is stored as a set of name-value pairs. The name is defined as a string and the value is typed. The MapMessage is useful for delivering keyed data that can change from one message to the next. Example: NumberOfCopies:5 where NumberOfCopies is the key and 5 is the value. Data can be accessed by using getmapnames(), which returns a Java Enumeration object. It is possible to iterate through the MapMessage by using hasmoreelements() to retrieve the mapped name-value pairs. Character encoding Select an encoding from the list. Authentication Anonymous login Select this option when the JMS Provider does not expect the client to authenticate itself. Login/Password inubit 6.1: Workbench/Process Engine: System Connectors Guide

185 JMS Connector Dialog Descriptions 185 Login data of the client for the JMS provider. Security Use security manager For activating the security manager. The security manager is specific for JMS/JNDI providers and it should be used only when required following the JMS provider security manager s configuration. Security manager Enter the name of the class implementing the security manager. This class is included in the JMS jar files delivered by your JMS provider Dialog Communication model In This dialog you have the following options: Communication model Select one of the following models: Publish/subscribe Used for general broadcast applications where a message is sent to multiple subscribers. A message producer sends messages concerning a certain topic to all consumers which have subscribed to this topic before. Consumers do not receive the message if they are not subscribed at the point of time when the message is send. Exception Durable subscription : Consumers must have subscribed for a topic. However, they need not to wait actively for messages but can retrieve them later. Point-to-point This model is used if messages only have one consumer: Messages sent by a message producer are queued fifo. Consumers can retrieve them sequentially from the queue at a later point in time. Settings The following options are displayed, if Point to point is selected as communication model: Queue name inubit 6.1: Workbench/Process Engine: System Connectors Guide

186 186 JMS Connector Dialog Descriptions Identifies an object which was generated and registered with the JNDI server by the JMS provider. The JMS Connector searches the JNDI server for the given queue and obtains a reference to the registered object. Class for establishing the connection Name of the connection factory. The connection factory is the object that the client uses to create a connection to the JMS provider. The object was generated and registered with the JNDI server by the JMS provider. The JMS connector searches the JNDI server for the specified class and obtains a reference to the specified object. Synchronous mode If selected, messages are received from the JMS server in asynchronous mode. This implies that the receipt of a message starts the workflow, which is completely processed before the next message can be received. The running workflow processing blocks the receipt of new messages and it is only the end of the workflow processing that triggers the receipt of the next message in the queue. The JMS server can also process several messages in parallel and synchronously; see option Number of messages to import. If not selected, messages are received in asynchronous mode and are therefore handed over to the workflow once they have arrived. Number of messages to import If synchronous mode is selected, the number of messages to be imported defines how many messages can be received from the queue and can be processed in parallel and synchronously (the default value is 1). This depends on the number of parallel processes defined for the workflow. The following options are displayed, if Publish/subscribe is selected as communication model: Topic name A topic is a string describing the nature of the data being published in the publish/subscribe system. The topic name describes an object generated by the JMS provider and registered with the JNDI server. The JMS connector searches the JNDI server for the specified topic name and gets a reference to the object. Class for establishing the connection Name of a connection factory. The connection factory is the object that the client uses to create a connection to the JMS provider. The object is generated by the JMS provider and registered with the JNDI server. The JMS connector searches the JNDI server for the specified name and obtains a reference to the registered object inubit 6.1: Workbench/Process Engine: System Connectors Guide

187 JMS Connector Dialog Descriptions 187 Topic No Local Blocks the reception of messages which were delivered using the subscriber's own connection. Message acknowledgment For selecting a control level when acknowledging messages. There are the following acknowledgement types: - AUTO_ACKNOWLEDGE: The JMS session automatically acknowledges that the client has received the message, either when the client successfully executes a message receipt call or when the listener's message receipt call is executed. - CLIENT_ACKNOWLEDGE: The client acknowledges a message by calling the message acknowledgement method. In this mode, the acknowledgement takes place at session level. - DUPS_OK_ACKNOWLEDGE: If this option is selected, the JMS session is instructed to acknowledge the delivery of a message lazily. In general, this results in the delivery of an additional copy of the message when the JMS provider does not provide immediate acknowledgement. This means that it should only be used by consumers that permit message copies. Use durable subscription (Only if communication model = Publish/subscribe ) Special case within the publish/subscribe communication model. Consumers must subscribe to topics but they do not need to wait actively for messages. Instead, they can fetch them at any later point in time. Subscription ID: Client ID for the connection. Login: Client login name. Password: Client password. Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog Message selector This dialog offers the following options: inubit 6.1: Workbench/Process Engine: System Connectors Guide

188 188 JMS Connector Dialog Descriptions Use message selector A message selector allows a consumer to specify the messages in which the consumer is interested. Message selectors allow message consumers to be more selective about the messages from a topic or queue. If a message selector is specified, messages are passed on to the client only when their headers and/or properties match the message selector. Message selectors cannot access values in the messages body! A message selector is a conditional expression consisting of an identifier and an operator followed by a literal. The following table shows how message selectors are constructed: Element Identifier Valid values Property or header field reference Operator AND, OR, LIKE, BETWEEN, =, <>, <, >, <=, >=, IS NULL, IS NOT NULL Literal boolean byte short int long float double String Also refer to JMS Specification, version 1.1, section Message Selector, Dialog Additional properties The additional properties are for establishing compatibility with other message systems or creating message selectors. To add a property, click the Add Properties button. Then fill in the Name, Type, and Value input fields in the displayed dialog inubit 6.1: Workbench/Process Engine: System Connectors Guide

189 19 LDAP Connector 189 This section details the following topics: Principles of Operation, p. 189 DSMLv2 Statements in Requests, p. 190 Dialog LDAP Connector Properties, p. 193 Use You can use the LDAP connector to insert, change, delete, and search for data on a Lightweight Directory Access Protocol (LDAP) server. Connector types The LDAP connector can be configured as a medium connector or an output connector: Medium Connector As a medium connector, the LDAP connector receives a query as a DSML message from its predecessor, sends the query to the LDAP server, receives a result from the LDAP server, and forwards the result to the subsequent module. Output Connector As an output connector, the LDAP connector receives a DSML message from its predecessor and sends the query to the LDAP server. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 19.1 Principles of Operation The LDAP connector establishes the connection to an LDAP server, reads a DSMLv2 request, and converts the statements contained therein into LDAP calls. The Directory Services Markup Language (DSML) is an OASIS standard that specifies access to directories using an XML schema and SOAP transport mechanism and depicts the entire LDAP data model. To establish the connection to an LDAP server and execute queries, you have to: inubit 6.1: Workbench/Process Engine: System Connectors Guide

190 190 LDAP Connector DSMLv2 Statements in Requests 1. Create an LDAP connector with connection data for the LDAP server. 2. Use an XSLT converter to create a DSMLv2 request with the following syntax: <batchrequest xmlns="urn:oasis:names:tc:dsml:2:0:core"> <-- Every single statement must contain a DN attribute! --> <modifyrequest dn="cn=joe Smith, OU=Dev, DC=inubit, DC=com> </modifyrequest> <addrequest> </addrequest> <delrequest> </delrequest> </batchrequest> 3. The response depends on the configuration of the connector: - In the case of an output connector, error or success messages are returned. - In the case of a medium connector, the results are returned in the form of a DSMLv2 response: <batchresponse xmlns="urn:oasis:names:tc:dsml:2:0:core"> <modifyresponse> </modifyresponse> <addresponse> </addresponse> <delresponse> </delresponse> </batchresponse> 19.2 DSMLv2 Statements in Requests This section details the following DSMLv2 statements: Modify, p. 191 Search, p. 191 Add, p. 192 Delete, p. 193 For all accesses to specific entries on an LDAP server, you require the unique names (distinguished names) of the objects in question inubit 6.1: Workbench/Process Engine: System Connectors Guide

191 LDAP Connector DSMLv2 Statements in Requests 191 DN attributes in statements Each statement in a request must have a DN (distinguished names) attribute. The DN attribute is required in order to uniquely identify an entry in an LDAP directory. It describes the exact location of the entry in question in the directory hierarchy. Also refer to - DSML documentation at committees/dsml/docs/dsmlv2.doc - DSML schema at docs/dsmlv2.xsd - Complete definition of distinguished names at LDAP Schema Viewer at a practical interface for investigating standard LDAP schema objects Modify In DSMLv2, all changes to attributes are specified by appending an operation attribute to an attr element. An operation can be add, delete, or replace. Example The statement below updates the telephone number of an employee named Bob Rush: <modifyrequest dn="cn=bob Rush,OU=Dev,DC=Example,DC=COM"> <modification name="telephonenumber" operation="replace"> <value> </value> <value> </value> </modification> </modifyrequest> Search The statement searchrequest searches for data on the LDAP server. inubit 6.1: Workbench/Process Engine: System Connectors Guide

192 192 LDAP Connector DSMLv2 Statements in Requests Example Search and output The system searches for all people named John in the path ou=marketing, dc=inubit, dc=com. All found search objects are output, including all their attributes. <searchrequest dn="ou=marketing,dc=inubit,dc=com" scope="singlelevel" derefaliases="neverderefaliases" sizelimit="1000"> <filter> <equalitymatch name="cn"> <final>john</final> </equalitymatch> </filter> Example Search and limit output In the following example, the same search criteria are used as in the example above, but the output attributes are limited to the objectsid attribute only. <searchrequest dn="ou=marketing,dc=inubit,dc=com" scope="singlelevel" derefaliases="neverderefaliases" sizelimit="1000"> <filter> <equalitymatch name="cn"> <value>john</value> </equalitymatch> </filter> <attributes> <attribute name="objectsid" type="binary"/> </attributes> If binary attributes are to be read by using the LDAP Connector, these attributes must already be distinguished and masked in the input message. To do this, you must insert the additional attribute type= binary into the search request. Thus, the values for binary attributes from the LDAP system are then included in the XML output message as base64-encoded content Add You use <addrequest> to insert new objects and attributes inubit 6.1: Workbench/Process Engine: System Connectors Guide

193 LDAP Connector Dialog LDAP Connector Properties 193 Example The statement for adding the object Alice Johnson with the type Person is as follows: <addrequest dn="ou=marketing,dc=inubit,dc=com"> <attr name="objectclass"> <value>person</value> </attr> <attr name="objectclass"> <value>organizationalperson</value> </attr> <attr name="sn"> <value>johnson</value> </attr> <attr name="givenname"> <value>alice</value> </attr> <attr name="title"> <value>software Design Engineer</value> </attr> </addrequest> Delete You use the <delrequest> statement to delete data from the LDAP server. Example This statement deletes the object Alice from the LDAP database: <delrequest dn="cn=alice, ou=marketing, dc=inubit,dc=com"/> 19.3 Dialog LDAP Connector Properties In this dialog you have the following options: LDAP server URL Replace <hostname> by the name of the LDAP server. inubit 6.1: Workbench/Process Engine: System Connectors Guide

194 194 LDAP Connector Dialog LDAP Connector Properties If the connection test fails with this port number, ask the administrator of the LDAP server for the correct number. Connection Pooling Activate this option to reuse existing connections to the LDAP Server. Authentication Anonymous login Select this option if the LDAP server supports anonymous login. Login If you are not using anonymous login, enter your user ID for the LDAP server. Password Enter the password for your user ID. Naming service Class name Pre-filled with the default Java class delivered with the inubit software. To use a different class for the LDAP naming and directory service, enter the name of the class in question. Make sure that the specified class exists in the Java class path. Further Settings Referral handling Specify how referrals to other directories are to be handled. Follow Follow any referral automatically Ignore (default) Ignore referrals Connection test Test connection For testing whether the connection can be successfully established using your configuration inubit 6.1: Workbench/Process Engine: System Connectors Guide

195 20 Livelink PDMS Connector 195 This section details the following topics: Installing JAR Files, p. 195 Content and Structure of Input and Output Messages, p. 196 Dialog Livelink PDMS Connector properties, p. 203 Use You use the Livelink PDMS Connector to connect the inubit Process Engine with a Livelink Archive Server. This enables you to use the connector to access and store data and documents in the Production Document Management System (PDMS). Connector types A Livelink Connector can only be used as a Medium Connector. Refer to - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 20.1 Installing JAR Files You must install the following external *.jar files on inubit Process Engine in the directory <inubit-installdir>/ server/lib/ext. Your PDMS manufacturer will provide you with these files: dmsclient.jar iaik_javax_crypto.jar iaik_jce_full.jar iaik_jsse.jar iaik_ssl.jar ixosbase.jar ixoscat.jar jhttp.jar jiaik.jar jsec.jar ot-commons-httpclient.jar inubit 6.1: Workbench/Process Engine: System Connectors Guide

196 196 Livelink PDMS Connector Content and Structure of Input and Output Messages spheon-jsoap.jar w3c_http.jar Refer to Installing Drivers (inubit Process Engine: Administrator and Developer Guide, chap. 3.4, p. 57) Content and Structure of Input and Output Messages This section details the following topics: Commands, p. 197 Condition, p. 197 Entities, p. 198 The Livelink Connector requires an XML file with the following content as the input message: Commands for controlling actions on the Livelink Archive Server Entities as specifications for objects to be created or regarding which properties of existing entities are to be changed. Conditions for searching for specific properties, document classes or document IDs. The output message has the same structure as the input message. Input message: Structure <LivelinkArchivingConnector> <Commands> <Command Type="<!-- command-->" DetailedResult="true false"> <Entities> <Entity/> <!-- at least one entity, depending on command --> </Entities> <Condition/> </Command> </Commands> </LivelinkArchivingConnector> Output message: Structure The output message returns the entities addressed by commands. <LivelinkArchivingConnector> <Entities> <!-- entities of command 1 --> <Entity/> <!-- 0 to n entities --> inubit 6.1: Workbench/Process Engine: System Connectors Guide

197 Livelink PDMS Connector Content and Structure of Input and Output Messages 197 </Entities> <Entities> <!-- entities of command 2 etc. --> <Entity/> <!-- 0 to n entities --> </Entities> <!-- Other entities --> </LivelinkArchivingConnector> Commands Multiple commands can be transferred for each execution of the connector. They are processed in the defined sequence and as a transaction. Command types The following table gives an overview of the individual command types: Command Create CreateIfNotExists Description Creates new entities with all transferred properties on the Livelink Archive Server. Like Create, but only if entities do not yet exist. You check whether entities already exist using the condition on the Livelink Archive Server Condition Depending on the command, the input message must contain a search condition. This condition takes the form of a where clause. The Livelink PDMS Query Language is used for the where clause. For an introduction to the Livelink Query Language (LGQL), go to websbroker/sr_lql.html. Condition for a specific property <and> <equal> <property name="ixos.dms:id"/> <literal value="aaps44v2vy6uqvorzmcje3enjexgo" datatype="string"/> </equal> inubit 6.1: Workbench/Process Engine: System Connectors Guide

198 198 Livelink PDMS Connector Content and Structure of Input and Output Messages </and> Condition for a specific property and document class <and> <equal casesensitive="true"> <property name="ixos.bai:linkid"/> <literal value="$$urn$$" datatype="string"/> </equal> <isa entitytype= "siemens.ad.bereichsarchiv:dkl0007r3lieferung" /> </and> Condition for a document ID <and> <equal> <property name="ixos.dms:id"/> <literal value="aaps44v2vy6uqvorzmcje3enjexgo" datatype="string" /> </equal> </and> Entities This section details the following topics: Entity Attributes, p. 199 Entity Properties, p. 200 Entity Components, p. 200 Entities are the central elements in input and output messages and are always represented analogously in the Livelink Archive Server. In the input message, depending on the command, they function as specifications for entities to be created or define which properties of existing entities are to be changed. In the output message they are used to transfer properties. Structure of entities <Entities> <Entity> <!-- Entity properties --> inubit 6.1: Workbench/Process Engine: System Connectors Guide

199 Livelink PDMS Connector Content and Structure of Input and Output Messages 199 [<Properties/>] [<Components/>] </Entity> </Entities> [] Optional Entity Attributes Entity attributes are primary attributes of the entity, e. g.: <Entities> <Entity> <Type>siemens.ad.bereichsarchiv:Document</Type> [<Id>aabqfd4m4qsequf2heae3qmnjexgo</Id>]1) [<Version></Version>]1) <Properties/> <Notes/> <Annotations/> <Components/> </Entity> </Entities> [] Optional 1) Currently implemented as return value Entity Attribute Field Description Type Conditional The document class of the entity to be created. The type is only relevant when the entity is created ( Create* command). With the Update command, the type is not included. ID Optional Creates new entities with all transferred properties on the Livelink Archive Server. Version Optional Like Create, but only if entities do not yet exist. You check whether entities already exist using the condition on the Livelink Archive Server. inubit 6.1: Workbench/Process Engine: System Connectors Guide

200 200 Livelink PDMS Connector Content and Structure of Input and Output Messages Entity Properties Entity properties describe the entity in greater detail. The properties must be defined in the Livelink Archive Server for the corresponding document class (<Type>). You only have to execute the properties you want to transfer. <Entities> <Entity> <Properties> <Property Name="siemens.ad.bereichsarchiv:fk_systyp"> 11 </Property> Property Name="ixos.bai:LinkedIds" MultiValue="true"> <Value>gss:\\id1</Value> <Value>gss:\\id2</Value> <Value>myLink:\\foo\bar</Value> </Property> </Properties> <Notes/> <Annotations/> <Components/> </Entity> </Entities> Entity Properties Field Description Required Full name of the property. Optional Indicator that the property is comprised of multiple values. Property/Value Conditional One or more values of a multiple value property. Property Required Value of the property Entity Components Components contain the actual documents (e.g. PDF documents). Multiple components (documents) can be stored for each entity. As a rule, however, this is always the same document in different formats. An invoice, for example, can be created as a TIFF, PDF and Word document. The respective entity would then have 3 components. <Entities> <Entity> inubit 6.1: Workbench/Process Engine: System Connectors Guide

201 Livelink PDMS Connector Content and Structure of Input and Output Messages 201 <Properties/> <Notes/> <Annotations/> <Components> <Component> <Name>data</Name> <Format>application/pdf</Format> <Encoding> <CreatedBy></CreatedBy> <CreatedAt></CreatedAt> <LastModifiedBy></LastModifiedBy> <LastModifiedAt></LastModifiedAt> <Volume></Volume> <OnlineStatus></OnlineStatus> <Data> <!-- Base64 coded binary data --> </Data> </Component> </Components> </Entity> </Entities> Entity Components Field Description Name Required Name of the component. This name must be unique in the respective format. If you want to overwrite an existing document, the name and format form the decisive criterion (primary key). Format Required The MIME type of the component. If you want to overwrite an existing document, the name and format form the decisive criterion (primary key). Encoding Optional The encoding of the component. CreatedBy Conditional Value of the property. CreatedAt Conditional Read only for output message. LastModifiedBy Conditional Read only for output message. LastModifiedAt Conditional Read only for output message. Volume Conditional Read only for output message. OnlineStatus Conditional Read only for output message. Data Required Contains the actual document as base64-encoded data. The message is stored in binary form in the archive. It is only encoded with base64 before and after a save or read. inubit 6.1: Workbench/Process Engine: System Connectors Guide

202 202 Livelink PDMS Connector Content and Structure of Input and Output Messages Example of an Output Message inubit 6.1: Workbench/Process Engine: System Connectors Guide

203 Livelink PDMS Connector Dialog Livelink PDMS Connector properties Dialog Livelink PDMS Connector properties In this dialog, you configure the access data for communication between the inubit Process Engine and the Livelink Archive Server. Base configuration Protocol Select HTTP or HTTPS protocol. Server name Domain name or IP address of the target server. Port Port number for the communication to the target server, e.g. xyz.inubit.com. Domain Name of the internal domain to which you want to log on using the access data User and Password. User/Password Access data with which you want to log on to the domain specified above. inubit 6.1: Workbench/Process Engine: System Connectors Guide

204 204 Livelink PDMS Connector Dialog Livelink PDMS Connector properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

205 21 Mail Connector 205 This section details the following topics: Module Variables of the Mail Connector, p. 205 Dialog Descriptions, p. 206 Use You can use a mail connector to fetch s from a POP3, IMAP, or IMAPS server or to send s via an SMTP or SMTPS server. Connector types Input Connector Fetches s until the mailbox is empty. The Connector becomes active only, if the scheduler is activated. Output Connector Formats s in MIME format and sends them. Make sure that the SMTP server can be reached from the computer where the inubit Process Engine is installed. Check, whether mail relaying is required from the inubit Process Engine and adjust the configuration of the SMTP server accordingly. Refer to de.wikipedia.org/wiki/smtp-relay-server. In order to use the Mail Connector anonymously as mail relay, ask your mail administrator for the relay configuration. With this form of usage you cannot test the connection. Also refer to - Dialog Scheduler (Workbench/Process Engine: System Connectors Guide, chap , p. 22) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 21.1 Module Variables of the Mail Connector When executing a Mail Connector the following variables are set, which you can analyze or overwrite: Message-ID From (only input connector) Reply-To (only input connector) inubit 6.1: Workbench/Process Engine: System Connectors Guide

206 206 Mail Connector Dialog Descriptions Subject (only input connector) For more information about variables and their usage, refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351) Dialog Descriptions This section details the following topics: Dialog Mail Connector Properties, p. 206 Dialog Configuring Data Transfer, p. 207 Dialog Message Configuration, p. 209 Dialog S/MIME Decryption, p. 210 Dialog Properties of Input Data, p. 210 Dialog SMTP Connector Properties, p. 211 Dialog S/MIME Encryption, p Dialog Mail Connector Properties (Input Connector) In this dialog you specify the access data of the mail server. Base configuration options Protocol Select the protocol that the Mail Connector is to use. The protocol must be supported by your server. - POP3 POP3 enables the copying of s from a mail server to a local host. If required, the s can be deleted from the mail server. - IMAP IMAP permits access to and the administration of received e- mails. As a rule, the s remain on the mail server and are only copied to the client host on request. This enables the central management of s from different locations. - IMAPS inubit 6.1: Workbench/Process Engine: System Connectors Guide

207 Mail Connector Dialog Descriptions 207 (IMAP over SSL) As a rule, an IMAP server is regarded as trusted. Server name Name or IP address of the server. Port Port which is used for communication. The Default button restores the settings after modifications. Authentication Account User name used for accessing the account. Password Password for accessing the account. Additional options (only if IMAP and IMPAS is selected as protocol) Prevent AUTHENTICATE PLAIN command at authentication If selected, the PLAIN authentication is disabled. This option is useful for the connection to an Exchange server Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog Configuring Data Transfer (Input Connector) In this dialog you have the following options: Configuration data transfer MIME For s in MIME format. s are passed in unchanged form to the next module in the workflow. inubit 6.1: Workbench/Process Engine: System Connectors Guide

208 208 Mail Connector Dialog Descriptions The MIME specification enables the exchange of messages in languages with different character sets and s with multimedia enhancements. A MIME contains additional default fields in the header that describe the data type of the content and the structure of the message. MIME XML For sending s in MIME format. An is encoded in accordance with its MIME type and its content is converted to IBIS-MIME.XML format. For the conversion the following schema is used Global > System > Mapping Templates > MIME Adapter > IBISMIME1.0.xsd - store header names inside XML lowercase Element names which are all written in lowercase simplify the access to the elements via XPath. - Encode content always base64 For transporting binary data as for example graphics. Index of content of the mailbox as MiME XML Loads the header information from the specified mailbox and converts it to XML. As a rule, the header information contains the subject, sender, date, and priority. - including message data - Encode content always base64 For transporting binary data as for example graphics. - store header names inside XML lowercase Element names which are all written in lowercase simplify the access to the elements via XPath. Data - of the message body The message is taken from the message body (the part that usually contains the message content). - from the attachment The message is taken from the attachment. Note that some e- mail programs such as Outlook also send plain text messages as attachments. - Attachment name/number of the attachment index If you leave these fields blank, the first file attached to the e- mail is forwarded to the workflow. Only the first file is forwarded, even if the has several attachments. To forward a specific attachment for an with several attachments, specify its name or position inubit 6.1: Workbench/Process Engine: System Connectors Guide

209 Mail Connector Dialog Descriptions Dialog Message Configuration (Input Connector) In this dialog you have the following options: Delete after reading Delete If activated, the messages are copied from the mail server to the inubit Process Engine and are then deleted from the mail server. If this option is activated and the contents are empty (Body = 0 Byte), but the has an attachment, the will be deleted after being read and no workflow is started. To prevent this from happening, you must activate the MIME XML option in the Configure data transfer tab. Filter options For defining filter criteria with which s must comply in order to be fetched from the server. Filter relation If more than one filter is defined: - AND A message must comply with all filters in order to be fetched. - OR The message must comply with at least one filter in order to be fetched. Add filter The button adds a row with which you define a new filter criteria: - Subject/From/To: List for selecting the field which is to be filtered. Furthermore, you can enter arbitrary header field names directly, e.g. Message-ID. - contains/does not contain: Select whether or not a certain string must be present in the selected field. - Entry field: For entering the string which must or must not be present. Delete filter criteria Click the icon to delete a filter criteria. inubit 6.1: Workbench/Process Engine: System Connectors Guide

210 210 Mail Connector Dialog Descriptions Dialog S/MIME Decryption (Input Connector) In this dialog you have the following options: Activate decryption If the s you fetched using the Mail Connector are encrypted, check this option to decrypt them Add private key Add (button) The button opens a file explorer for loading the keystore file containing the key for decrypting the s. Before loading the keystore you must enter the alias and password of the key. Public key data Displays the public data of the certificate after loading it Dialog Properties of Input Data (Output Connector) In this dialog you have the following options: Configuration for sending MIME formatted (RCF 822) For sending Mime-formatted input messages. MIME XML For sending input messages which are formatted in accordance with the XML schema file at Global > System > Mapping Templates > MIME Adapter > IBISMime1.0.xsd. If you have selected Mime formatted or Mime XML, the content of the input messages are only utilized, if you leave the Message area in the Dialog SMTP Connector Properties (Workbench/ Process Engine: System Connectors Guide, chap , p. 211) empty. Data For sending messages in any formats. - Mime type of data Information about the type of data to be sent inubit 6.1: Workbench/Process Engine: System Connectors Guide

211 Mail Connector Dialog Descriptions Content-Transfer-Encoding For defining a secure encoding for non-ascii characters (for example special characters) and non-text parts (for example binaries) when transferring data. Guarantees a lossless data exchange. - auto: The value of the header Content-Transfer-Encoding is defined automatically according to the content-type and the data which are to be send. - base64 For transferring binary or 8-bit-encoded messages. - As attachment Sends the input message as an attachment to an . Name of the attachment For defining the name of the attachment. You can have a date, timestamp or process ID added to the name of the attachment: Date You have different options for outputting the date. As definition without date format, name_%timestamp%%.xml generates name_ xml with name = attachmentname, = Date formatted as ddmmyyyy, = time formatted as hhmmss. As definition with date format hh, name_ %TimeStamp%hh%.xml generates name_11.xml. As definition with date format ddmm, name_%timestamp%ddmm%.xml generates name_2309.xml. Timestamp The timestamp additionally contains a specification in milliseconds: name_%timestamp%ddmmyyyy-hhmmss- SSS%.xml results in name_ xml. Process ID In order to output the process ID, enter the attachment name in the following format: name_pid_%processid%.xml. - Additional text attachment You can generate an additional text attachment that you insert into the input field Dialog SMTP Connector Properties (Output Connector) You use the dialog to define the properties of the SMTP server and the message. inubit 6.1: Workbench/Process Engine: System Connectors Guide

212 212 Mail Connector Dialog Descriptions Basic settings Protocol - SMTP: Protocol for sending and forwarding s. - SMTPS: (SMTP via SSL) Encrypts the connection by using SSL. Server name URL of the SMTP server (domain name or IP address). If you do not make a specification, localhost is set automatically. Port number Preset to 25 and 465, respectively. The Default button restores the default setting after changes. Authentication Check the option if the mail server requires authentication. - Account: User name. - Password: Password you received along with the user name. Message You can leave the fields empty, if the input message is sent as XML or MIME, because then sender, recipient, and subject are normally already included. A list of recipients in the sequence TO, CC, BCC is created from the existing MIME headers. For each address in the list, an RCPT TO: command is sent to the mail server. If you fill in the fields in the Message area, then these values overwrite the values from the XML or MIME input message. From: Sender address. To: Recipient address. Separate multiple recipient addresses with commas. Cc: Additional recipient addresses; separate recipient addresses with commas. Bcc: Recipient addresses that are not visible to To and Cc recipients. Separate multiple recipient addresses with commas. Reply to: Fill in this field if the sender address is not the address to which you want recipients to reply. Subject: Specify the subject of the . You can have a date, timestamp or process ID added to the subject: Date You have different options for outputting the date. As definition without date format, subject_%timestamp%%.xml generates subject_ xml. As definition with date format hh, subject_%timestamp%hh%.xml generates subject_11.xml. As definition with date format ddmm, subject_%timestamp%ddmm%.xml generates subject_ inubit 6.1: Workbench/Process Engine: System Connectors Guide

213 Mail Connector Dialog Descriptions xml. Timestamp The timestamp additionally contains a specification in milliseconds: subject_%timestamp%ddmmyyyy-hhmmss- SSS%.xml results in subject_ xml. Process ID In order to output the process ID, enter the subject name in the following format: subject_pid_%processid%.xml. Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog S/MIME Encryption (Output Connector) In the dialog S/MIME encryption you can encrypt messages with S/ MIME. Activate encryption: Activates encryption. Add recipient's public certificate Add: Clicking on Add opens a file explorer for loading the keystore file with the key. You need to enter the alias and password used to store the certificate! Certificate data After loading the certificate its public data is displayed. inubit 6.1: Workbench/Process Engine: System Connectors Guide

214 214 Mail Connector Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

215 22 MSMQ Connector 215 This section details the following topics: Requirements, p. 215 Create Input and Output Messages, p. 216 Dialog MSMQ Connector properties, p. 217 Use Microsoft Message Queueing (MSMQ) is an implementation of message queue, amongst others for connecting to MS Navision, MS Axapta, MS CRM and MS Biztalk. MSMQ decouples sender from receiver applications in a way that the sender application can send messages and does not need to take care whether and when they are delivered to the receiver application. All messages are saved by the MSMQ in a queue and forwarded as soon as the receiver application is available. Messages are delivered reliably even if, for example, the receiver application does not run or if the computer, where the receiver application is installed, is temporarily not connected to the network. Connector types Input Listener Connector Works as receiver and waits for messages from the configured queue. Medium/Output Connector Operates as sender and writes messages into the given queue. Both connector types pass on the input messages Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 22.1 Requirements Access to an MSMQ Server Installation of J-Integra for COM J-Integra for COM must be installed on the MSMQ Server, because there, the necessary library mqoa.dll is available. inubit 6.1: Workbench/Process Engine: System Connectors Guide

216 216 MSMQ Connector Create Input and Output Messages A detailed installation guide is to be found at Installation of a DCOM surrogate For access to the MSMQ-COM component via DCOM, the DCOM surrogate must be installed on the MSMQ server using the command setdllhost.exe mqoa.dll "MSMQ". The library mqoa.dll is part of the MSMQ server. Java-Wrapper msmq.jar For access to the library mqoa.dll from the inubit software. Refer to Installing Drivers (inubit Process Engine: Administrator and Developer Guide, chap. 3.4, p. 57). You are provided with the software and the Java wrapper together with the license of the MSMQ Connector of the Bosch Software Innovations GmbH Create Input and Output Messages Create the input and output messages by using a template and an XSLT converter. Proceed as follows 1. Create an XSLT Converter. 2. Click into the panel XML Target File on the button. A menu opens. 3. Select Open > Repository. The Repository Explorer opens. 4. Open the directory Global > System > Mapping Templates > MSMQ Connector. 5. Select one of the following files: - Create input message: MSMQ_Input.xsd. - Create output message: MSMQ_Output.xsd inubit 6.1: Workbench/Process Engine: System Connectors Guide

217 MSMQ Connector Dialog MSMQ Connector properties Click the OK button. The Explorer closes and the template is displayed. 7. Map your input message to the template structure in order to create a message of the necessary format. Refer to XSLT Converter (Data Converter) (Workbench/ Process Engine: Modules Guide, chap. 5, p. 133) Dialog MSMQ Connector properties In this dialog you have the following options: Settings Server IP address or host name of the MSMQ server, which is to be connected. Queue Name of the queue on the MSMQ server. Authentication Domain Name of the administration structure in the Windows network, where you want to login using the access data of the fields User / Password. User/Password Access data of the users, who want to login on the domains named. The user must be authorized to access the queue. Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

218 218 MSMQ Connector Dialog MSMQ Connector properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

219 23 OFTP Connector 219 This section details the following topics: Requirements, p. 219 Principles of Operation, p. 220 Data Transfer Modes, p. 221 rvs Monitoring, p. 222 Dialog Data Exchange Configuration, p. 223 Dialog Stations, p. 226 Use The OFTP system connector is used to exchange business data in accordance with the Odette File Transfer Protocol (OFTP). OFTP offers the facility to re-establish a connection after it has been interrupted without transferring the entire file again. ASCII and EBCDIC files can be transferred. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 23.1 Requirements The rvs software from T-Systems International GmbH must be installed and configured in the version 5.05 or Transfer parameters must be set and station must be defined. rvs consists of the rvs middleware, the rvs server and a client component. It can be configured via the user interface of the middleware as well as via the user interface of the server. Be sure to check with Bosch Software Innovations GmbH which rvs version you require for your installation. rvsclient.jar The file rvs client/classes/rvsclient.jar of the rvs client must be uploaded as driver library into the inubit Process Engine. Refer to Installing Drivers (inubit Process Engine: Administrator and Developer Guide, chap. 3.4, p. 57). Deploy OFTP Connector in listener mode inubit 6.1: Workbench/Process Engine: System Connectors Guide

220 220 OFTP Connector Principles of Operation You need a reference in the rvs software to a script that is supplied with the inubit software. This script sends a notification to the OFTP connector when a business message has arrived. a. Set up a receive-job (resident receive entry) in the rvs GUI. b. Specify the script as a job to be started. The script can be found in the following directory: <inubit-installdir>/server/ ibis_root/conf/bin. - AIX: rvs_is_receive.pl. - Windows: rvs_is_receive.bat. For further information refer to the rvs documentation Principles of Operation GUI GUI sender station OFTP over TCP/IP RMI X.25 OFTP Connector rvs Middleware rvs Server receiver station ISDN Message flow Sending messages using an Output Connector The OFTP connector passes the business messages on the inubit Process Engine to rvs. Sending the messages can be scheduled in such a way, that messages are sent immediately it reaches the OFTP connector in the workflow, at an agreed time, or after an agreed time interval. rvs sends the messages via the agreed protocol to the station the receiver has set up. After the module is executed, the RVS Job ID is available as a workflow variable. Receiving messages - Input Connector The OFTP connector actively checks at defined intervals whether messages are present inubit 6.1: Workbench/Process Engine: System Connectors Guide

221 OFTP Connector Data Transfer Modes Input Listener Connector It waits for a message to arrive on the configured connection and retrieves the message immediately it arrives Depending on which connector type you have chosen, communications are either synchronous or asynchronous. For information on the different modes of operation refer to Data Transfer Modes (Workbench/Process Engine: System Connectors Guide, chap. 23.3, p. 221) Data Transfer Modes The OFTP Connector supports the following data transfer modes: Asynchronous transfer using Input Connector The input connector retrieves the data in accordance with the configuration that you set up in the Dialog Scheduler (Workbench/Process Engine: System Connectors Guide, chap , p. 22). rvs sends an acknowledgement (EERP), either over the existing connection, if it has not been cleared, or when the connection is next established. This corresponds to the Normal option for the EERP_out parameter. The deletion of finished jobs (receiving messages) must be suppressed (setting setparm CMDDELETE=0 in the rvs system.) For further information on the EERP_out parameter refer to Neighbor Stations (Workbench/Process Engine: System Connectors Guide, chap , p. 227). The fact that the rvs software sends the acknowledgement doesn't guarantee to the sender of the message that the message has actually been delivered to the inubit Process Engine. Watch that the database does not exceed its maximum permitted size during operation! If you want to obtain further information in addition to the file name the rvs configuration needs to be changed accordingly. Synchronous transfer by rvs using Input Listener Connector rvs confirms the receipt of a message by sending an EERP_out. As regards the OFTP connector, this process is to some degree semi-synchronous as the confirmation is sent before the OFTP connector can confirm that the message is present in the inubit Process Engine. inubit 6.1: Workbench/Process Engine: System Connectors Guide

222 222 OFTP Connector rvs Monitoring The deletion of finished jobs must be suppressed (setting setparm CMDDELETE=0 in rvs). Synchronous transfer by an Input Listener Connector The acknowledgement is sent as soon as it is arrived completely in the inubit Process Engine. The EERP_out parameter must be set to HOLD/IMMEDIATE in the neighbor station configuration. Refer to the documentation on the EERP_out parameter in Neighbor Stations (Workbench/Process Engine: System Connectors Guide, chap , p. 227). The job (receive message) remains active until the acknowledgement of receipt (EERP_out) has been sent. Synchronous transfer by an Output Connector When sending a synchronous message where the system waits for a confirmation of transmission from the receiver, a timeout needs to be set to avoid a blockage being created by the wait. Check the Timeout checkbox. By default this option is deselected and thus set to indefinite. When specifying a value, take into account the size of the message and the transfer method. In addition, take into account the configuration at the other end. A blockage can also arise if the EERP message is set to HOLD at that end. Refer to Deploy OFTP Connector in listener mode (Workbench/ Process Engine: System Connectors Guide, chap. 23, p. 219) Send Job on successful/failed transmission: rvs_is_send. Before the timeout for fetching the EERP message (minimun 60 seconds) expires, the OFTP Connector activates the partner station and tries to fetch the EERP message. Only if this fails, message sending is considered as having failed. Thus, it can be excluded that a message is considered as having failed and sent again because the EERP message could not be received due to an interrupted connection even if the message was sent correctly rvs Monitoring You can check the connection of the inubit Process Engine with the rvs server using the command line tool StartCLI inubit 6.1: Workbench/Process Engine: System Connectors Guide

223 OFTP Connector Dialog Data Exchange Configuration 223 Options Option -r,--rvs --rhost --rlogin --rmwname --rpassword Information Check the connection of the inubit Process Engine with the rvs server rvs Host rvs Login name of the rvs middleware rvs password Refer to Remote Monitoring Using the Command Line Interface (StartCLI) (inubit Process Engine: Administrator and Developer Guide, chap. 7.10, p. 113) Dialog Data Exchange Configuration The dialog for OFTP data exchange configuration takes a different form for each connector type! Basic settings Middleware server address: Enter the name of the computer or the IP-address. For example: MyServer or (omitting the quotation marks). If the RMI registry doesn't run on port 1099, specify the name of the computer and the port number, separated by a colon. For example: MyServer:1234. Middleware name: The string rvsmw is normally used here. If you have used another name for the middleware, insert that name here. Login: Enter here the user name with which you log in to the middleware. This field is case-sensitive. Password: Enter your password here. File name: This name is used for the OFTP transmission. The receiver must be told what the name is in order to access the file. You may use wildcards or regular expressions in the file name. - Wildcards The following characters are permitted as wildcards: - Question mark (?): Represents any single character. - Asterisk (*): Represents zero or more arbitrary characters. inubit 6.1: Workbench/Process Engine: System Connectors Guide

224 224 OFTP Connector Dialog Data Exchange Configuration Any number of wildcard characters may be used and in any combination. If wildcards are specified then e.g. an input connector will retrieve only files that match the specified value; all other files are ignored. To receive all files, enter *. - Regular expressions Regular expressions must be delimited by forward slashes (/), e.g.: /(\d\d)\.(\d\d)\.(\d\d\d\d)/ For more information about regular expressions, refer to or Windows: This operating system allows files to be hidden. If hidden files satisfy a wildcard criterion, they are also transferred. Make sure that the files that you can see in the Explorer directory are in fact all the files contained in that directory. To do this, show all files (in Explorer options Extras (Tools) > Folder options). Inbox subdirectory: Specify the directory name that you set up in the middleware under Inbox, in which the incoming files are to be stored. The Inbox folder is identical to the <rvs-install-dir>/ usrdat folder on the rvs server. Unless you have configured a different directory, incoming messages are stored here. Virtual file name (not for the input connector): In the virtual filename (virtual dataset name = VDSN) you can initially specify a directory name, for example, abc/123order.edi - in this case the file is stored in the following directory: <rvs-install-dir>/usrdat/inbox/ abc/ at your business partner's end. Receiver station ID (not for the input connector): A station ID (SID) may be up to 16 characters in length. This ID is only used locally. It is user-definable and may consist of numbers and alphabetic characters. This SID must first be created in the rvs software and may then be copied over to this field. Stations Before you can invoke the Stations dialog, you must first have entered valid connection data to an OFTP middleware in the Basic configurations dialog. Text file: Select this option if the OFTP connector is implemented on a different operating system to the middleware. This option activates an automatic conversion that recognizes the different operating systems and sets the required control characters. In e.g. Windows files, each line is ended with both a carriage return inubit 6.1: Workbench/Process Engine: System Connectors Guide

225 OFTP Connector Dialog Data Exchange Configuration 225 character and a line feed character, whereas in Unix systems there is only a line feed character at the end of the line. To transfer binary files you should deactivate this option! Delete file from server: If this option is selected, the file is deleted on the rvs server once it has been transferred. Synchronous: (only for output connector) Checking this checkbox activates the synchronous transfer mode. RVS Evo: Select this option if you want to use the RVS Evolution version of the rvs software in place of the Classic version. Format (only for output connector) Specify here the format information for the file that is to be transferred. Text: Text files in ASCII format Fixed records: Files containing fixed-length records Variable records: Files containing variable-length records You set the maximum record length via the RvsRecordLength module variable. Refer to rvs documentation Unstructured: Select this option if you want to transfer binary files VFType (only for output connector) Use the VFType option to specify how the files are to be converted before they are transferred. The conversion can only be applied to files with a fixed or variable format (refer to the Format option above). You can choose from three options: Text, Variable or Special. Text: The file is not converted. The format and record length of the file must already correspond to what the business partner is expecting to receive. Variable: If you select this option, the file is converted using a default value specified in rvs. Special: This option converts the file to a special format used for transfer in FT-SINIX (File Transfer Siemens UNIX) mode. Code In/Code Out (only for output connector) The Code in and Code out options allow you to convert the message to match the character set of the source or target operating system. In each case you have the choice of converting the message inubit 6.1: Workbench/Process Engine: System Connectors Guide

226 226 OFTP Connector Dialog Stations either to the ASCII or the EBCDIC character set. The ASCII character set is employed for the Windows and UNIX operating systems. EBCDIC is the standard for OS/400 and OS/390. Refer to - Dialog Stations (Workbench/Process Engine: System Connectors Guide, chap. 23.6, p. 226) - Data Transfer Modes (Workbench/Process Engine: System Connectors Guide, chap. 23.3, p. 221) 23.6 Dialog Stations This section details the following topics: Neighbor Stations, p. 227 Receiver, p. 234 Before you can invoke the Stations dialog, you must first have entered valid connection data to an OFTP middleware in the Basic configurations dialog. When you invoke the Stations dialog, the OFTP connector connects to the OFTP middleware using the basic configuration you have specified and there obtains the configuration data, which is then displayed in the Stations dialog. Note that settings in the Stations dialog change the configuration in the OFTP middleware if you exit the dialog by clicking on the OK button. LOC LOC is the local station file. If you select this entry, you can specify the configuration of the local station in the right-hand window. The configuration data must match the data that you have specified in your rvs administrator console. The local station must always have the name LOC (in uppercase). The first two option groups are as follows: Odette ID: This is a unique character string consisting of up to 25 characters, the first of which is always O. You obtain an Odette ID from Local station: Name, Telephone and Remarks are optional fields. In the Name field enter a descriptive name; the Telephone field inubit 6.1: Workbench/Process Engine: System Connectors Guide

227 OFTP Connector Dialog Stations 227 can contain the number of an administrator who looks after the configuration; Remarks can contain the user-definable name of the station. This is followed by the receivers the configurations of which are dependent on the protocol selected. If you have selected LOC, a context menu becomes available containing the following commands: Add neighbor station Add receiver Remove receiver Activating connection Neighbor Stations This section details the following topics: Neighbor Station over TCP/IP, p. 230 Neighbor Station over LU6.2, p. 230 Neighbor Station over ISDN, p. 231 Neighbor Station over X.25, p. 232 Virtual Neighbor Station, p. 233 Routed Station, p. 233 Activating Connection, p. 234 Remove, p. 234 A neighbor station is the station of a business partner with which you want to exchange messages. Add neighbor station Use this option to add a new neighbor station. This is added to a directory tree under LOC. You must know the neighbor station's configuration. If you select the newly added station, you can add the parameters on the right-hand side of the dialog. The stations can be configured for different protocols. Select one of the following: X.25, LU6.2, TCP/IP, ISDN or Virtual. Odette dialog group Odette ID: This is a unique character string consisting of up to 25 characters, the first of which is always O. Receive password: The password expected from the business partner. Send password: The password is sent to the business partner. Exchange buffer size: The size is expressed in bytes. The default is 0. If you want to set a value here, use the value of the OEXBUF inubit 6.1: Workbench/Process Engine: System Connectors Guide

228 228 OFTP Connector Dialog Stations global parameter as set out in the manual for the OFTP middleware you are using. Exchange buffer number: The default is 0. This figure determines the number of buffers sent without waiting for a response. Received blocks: OFTP messages do not need to be re-sent in their entirety following a break in the connection; instead the transmission can be re-started from so-called resume points. In this field you can specify the number of blocks to be received before such a resume point is created. The number of resume points affects performance and memory usage. For this reason, use a small number for stable connections and a large number for connections that are liable to disruption. The default is 0. If you want to set a value here, use the value of the RECVBLOCKS global parameter as set out in the manual for the OFTP middleware you are using. Sent blocks: The meaning of this field is the same as for the Received blocks option. The global parameter in this case is called SENDBLOCKS. Compression: This option is a combo box. You can select from three modes. - ODETTE: The blocks are passed to the OFTP middleware where they are compressed using the Odette file compression algorithm. - NONE: The data blocks are not compressed. - GNU: The data blocks are compressed while in the inubit Process Engine using GNU ZIP (gzip) before being passed to the OFTP middleware. VDSN character set: This option is a combo box. You can select from a number of character sets: - ALL: There are no restrictions on the character set. - ODETTE: all upper-case alphabetic characters, numerics as well as the special characters () -. / & - CHECK_RE: As with ALL, allows all characters but with the condition that a resident receive entry (RE) must be present, in which case the RE is executed. (RE stands for Residenter Empfangseintrag in German). A resident receive entry is created for a file with a specified name. If a file with this name comes in, the resident receive entry determines which action to initiate; for example, replace file, delete file or, as requested here, convert code. The OFTP middleware has a special GUI for defining resident receive entries. - OFTPUNIX: all upper-case alphabetics, numerics, plus the special characters. - (dot, minus). - UNIX: all alphabetic and numeric characters plus the special characters # _ inubit 6.1: Workbench/Process Engine: System Connectors Guide

229 OFTP Connector Dialog Stations 229 End to end response in (EERP_in): EERP (End-to-End Response) refers to an acknowledgement of receipt of the message. The EERP_in is sent by the business partner. The combo box offers the options NEVER and NORMAL. - NEVER: means that the business partner does not send an acknowledgement. The transmission ends with the correct transfer of the message. - NORMAL: means that an acknowledgement is expected. Receiving the acknowledgement forms part of the Send Request. A Send Request persists while there are further files to send or until the acknowledgement has been received. When the acknowledgement is received, the Send Request is ended. NORMAL is the default. End to end response out (EERP_out): An acknowledgement is sent from the local station to the business partner. The IMMEDIATE option is pre-selected by default. The following options are available. - NEVER: No acknowledgement is sent. - NORMAL: An acknowledgement is sent when a message is received. If a connection still exists, the acknowledgement is sent immediately. If the connection has already been released, the acknowledgement is sent when the next connection is established. - SYNC: The acknowledgement is sent over the same connection by which the message arrived. This forces the connection to be maintained. The connection cannot be closed until the successful transmission of the acknowledgement of receipt has been verified. - IMMEDIATE: The acknowledgement is sent immediately. If the connection has already been closed, it is re-established for the acknowledgement. - HOLD: The acknowledgement is only sent when it is explicitly released by an operator via the OFTP middleware. If the connection still exists, the acknowledgement is sent immediately. If the current connection has already been interrupted, the acknowledgement is sent the next time that a connection is established. The OFTP connector gives the release for the OFTP middleware itself; no operator intervention is required. - HOLD/IMMEDIATE: The acknowledgement cannot be sent until a release is obtained. If this has been given, the receipt is sent immediately over the connection. If the current connection has been interrupted, a new connection is immediately established for the purpose of sending the acknowledgement and the acknowledgement is sent. inubit 6.1: Workbench/Process Engine: System Connectors Guide

230 230 OFTP Connector Dialog Stations The OFTP connector grants the release for the OFTP middleware itself; no operator intervention is required. Neighbour Station Name, Telephone, Remarks and Network are optional fields. Use this section to enter information about who looks after the configuration of the neighbor stations. Line Type Suspended: Use this option to choose whether the connection is to be automatically ended (suspended) or not. Active connection setup: If this option is selected, the OFTP middleware automatically establishes a connection when there is a message to send. Parallel Session: The default value is 1. Selecting a value of -1 causes the value to be copied from the MAXSESSIONS global variable, as set in the OFTP middleware. Delay before dial: Enter a whole number. Specifies the number of seconds to be left between two attempts to establish a connection. The default is 0. Neighbor station protocol type The structure of the remainder of the neighbor station dialog depends on the communications protocol that you have selected Neighbor Station over TCP/IP IP Address: Specify either the name or the IP number of the computer via which the TCP/IP connection is made. Port: Specify the port number for the TCP/IP connection Neighbor Station over LU6.2 Systems Network Architecture (SNA) is a network architecture developed by IBM. Using LU Type 6.2 Logical Unit it is possible to establish parallel connections between a single logical unit and more than one application program. LU name: Name of the logical unit (LU) Network ID: The network ID (or NETID) specifies an SNA network. It is a string composed of one to eight alphanumeric characters. TP name: TP stands for Transaction Program. TP name specifies the name of an Advanced Program-to-Program inubit 6.1: Workbench/Process Engine: System Connectors Guide

231 OFTP Connector Dialog Stations 231 Communication (APPC) transaction program on a database server. For example, RVSOFTP or DB2DRDA. Mode: The name of the mode must be unique and follow the SNA naming conventions: for example, LU62PS. User ID and Password: User ID corresponds to a login name. Some SNA networks require authentication. Security: Some SNA networks require authentication. If this is required, the select box must be selected. This causes the user ID and password to be added to the transferred data. Sync Level: Permitted values in this field are 0 and 1, or NONE and CONFIRM. 0 or NONE means that processing doesn't need to be confirmed. A value of 1 or CONFIRM means that the processing is confirmed Neighbor Station over ISDN When you configure a neighbor station that is connected over ISDN, the X.25 protocol is automatically added to the configuration as ISDN on its own is insufficient for establishing an OFTP-compliant connection. ISDN Address: This refers to the last three digits of the ISDN address as defined in ITU-T Recommendation E.164. Using these last three digits as a filter allows you to distinguish between the terminals. IP Address: Enter the IP address or the computer name of your ISDN router (only needed if you are using more than one ISDN router). Type: This is normally RCAPI1. Within this expression, CAPI stands for Common ISDN Application Programming Interface; RCAPI then stands for Remote CAPI. The number indicates the number of the router controller; in this case, 1. Protocol: Enter EDSS1 here; this stands for the Euro Digital Subscriber Signaling System No. 1 signaling protocol. Packet size: A packet size of 128 is normally specified here. Facilities: The Facilities and User data fields (refer to the next field) are normally left empty. Note that any values you may want to enter in these fields must be in HEX code. These fields are normally only used for X.25 transfers over ISDN, if your ISDN provider requires this. User data: Refer to the Facilities field above. Terminal identifier: Often referred to as Terminal ID. Unique number of your ISDN terminal. inubit 6.1: Workbench/Process Engine: System Connectors Guide

232 232 OFTP Connector Dialog Stations Neighbor Station over X.25 X.25 is an international telecommunications standard adopted by the International Telecommunication Union. For further information, refer to X.25 Address: Each computer that is to communicate in an X.25 network must have an X.25-compliant address. An X.25 address is a sequence of digits. The first digits represent the country code, the following digits indicate the network within the country and the final digits indicate the computer number. Subaddress: If more than one computer is present on a single network connection (subnet), the final three digits of the X.25 address refer to the computer in the subnet. Facilities: The Facilities and User data fields (refer to the next field) are normally left empty. Note that any values you may want to enter in these fields must be in HEX code. These fields are normally only used for X.25 transfers over ISDN, if your ISDN provider requires this. User data: Refer to the Facilities field above. Timeout: The time in seconds before an attempt to establish a connection is cancelled. Session: Maximum number of receivers that may be active in parallel. Ask your business partner for this value. The default is 1. DBit: DBit stands for delivery confirmation bit. If you select this option, the sending station requires an acknowledgement of receipt. Closed user group: If a station is a member of a closed user group (CUG), messages are only sent to and received from stations that belong to the same CUG. Virtual circuit: Virtual circuits are possible in X.25 in which everything except the transfer route is fixed. This allows the route to be selected as necessary and the transfer rate to be increased by multiplexing over several channels. You can choose between the S and P parameters where S = switched (switched virtual circuit = SVC) and P = permanent (permanent virtual circuit = PVC). PVC connections are popular with banks, for example, whereas SVC connections are used where a permanent connection is not needed. If you are adding a neighbor station that communicates over X.25 no options are displayed for the ISDN protocol. For X.25, the Device name option is then added. Device name: Specifies the device name. The name you enter here is an alphanumeric string which must match the name in your business partner's configuration inubit 6.1: Workbench/Process Engine: System Connectors Guide

233 OFTP Connector Dialog Stations Virtual Neighbor Station A virtual station allows you to configure an application or a user. If a message is received for a virtual station, it is passed locally to the user or program. A virtual station can also send messages. To do this, the user or program passes the message to the OFTP middleware which sends the message and records the virtual station as the sender. Virtual stations can also be addressed uniquely as they have their unique Odette ID. To the business partner, virtual stations appear as routed stations. Since the only important information on a virtual station is the Odette ID, the Name, Telephone and Remarks fields can be used to store information that is important for administration purposes, such as the name and telephone number of the administrator Routed Station If you select a neighbor station, you can select the Add routed station option from the context menu. Messages to and from a routed station are passed on by its 'parent' neighbor station. The concrete address of a routed station is transparent to the business partner. If you create a routed station, the following parameters are displayed on the righthand side of the dialog: RvsNeighborSid: This field is defaulted to the name of the neighbor station under which the routed station was configured. Name, Telephone, Remarks: This information is optional. You could, for example, store information on an administrator in these fields. Odette ID: This is a unique character string consisting of up to 25 characters, of which the first is always O. End to end response in (EERP_in): The EERP_in is sent by the business partner. The combo box offers the options NEVER and NORMAL. End to end response out (EERP_out): An acknowledgement is sent from the local station to the business partner. The IMMEDIATE (see below) option is pre-selected by default. The following options are available. NEVER, NORMAL, SYNC, IMMEDIATE, HOLD and HOLD/IMMEDIATE. For information on the options that can be selected for the acknowledgement of receipt refer to Neighbor Stations (Workbench/Process Engine: System Connectors Guide, chap , p. 227). inubit 6.1: Workbench/Process Engine: System Connectors Guide

234 234 OFTP Connector Dialog Stations Activating Connection If you select a neighbor station, you can select the Activate connection option from the context menu. This option allows you to test whether a connection can be established with the neighbor station you have configured using the data as specified Remove If you select a neighbor station, you can select the Remove option from the context menu. If you select this option, the selected neighbor station is removed immediately without you needing to confirm the Stations dialog. This change also deletes the selected neighbor station in the rvs software Receiver This section details the following topics: Configuring an X.25 Receiver, p. 235 Configuring an ISDN Receiver, p. 236 Configuring a TCP/IP Receiver, p. 236 Configuring an SNA LU6.2 Receiver, p. 237 A receiver is a connection configuration that is based on one of the following protocols: X.25, LU6.2, TCP/IP or ISDN. If you invoke the Stations dialog then select the LOC entry on the left, a list of all the receivers is displayed on the right. You can add and remove receivers. Remove receiver Selecting this option allows you to then select from the list all the configured receivers that you want to remove. Check that no further messages are being exchanged over the receivers that you are removing. Add receiver Receivers are added to the local station. For the limit on the number of receivers that you can add, refer to the manual for the OFTP middleware that you are using inubit 6.1: Workbench/Process Engine: System Connectors Guide

235 OFTP Connector Dialog Stations 235 Receiver's protocol: A number of receivers may be added to the local station that are linked over different protocols. You can add one or more receivers of the following types: X.25, LU6.2, TCP/IP or ISDN Configuring an X.25 Receiver X.25 is an international telecommunications standard adopted by the International Telecommunication Union. For further information, refer to Vector position: The default value is 2. X.25 Address: Each computer that is to communicate in an X.25 network must have an X.25-compliant address. An X.25 address is a sequence of digits. The first digits represent the country code, the following digits indicate the network within the country and the final digits indicate the computer number. Subaddress: If more than one computer is present on a single network connection (subnet), the final three digits of the X.25 address refer to the computer in the subnet. Facilities: The Facilities and User data fields (refer to the next field) are normally left empty. Note that any values you may want to enter in these fields must be in HEX code. These fields are normally only used for X.25 transfers over ISDN, if your ISDN provider requires this. User data: Refer to the Facilities field above. Timeout: The time in seconds before an attempt to establish a connection is cancelled. Session: Maximum number of receivers that may be active in parallel. Ask your business partner for this value. The default is 1. DBit: DBit stands for delivery confirmation bit. If you select this option, the sending station requires an acknowledgement of receipt. Closed user group: If a station is a member of a closed user group (CUG), messages are only sent to and received from stations that belong to the same CUG. Virtual circuit: Virtual circuits are possible in X.25 in which everything except the transfer route is fixed. This allows the route to be selected as necessary and the transfer rate to be increased by multiplexing over several channels. You can choose between the S and P parameters where S = switched (switched virtual circuit = SVC) and P = permanent (permanent virtual circuit = PVC). PVC connections are popular with banks, for example, whereas SVC connections are used where a permanent connection is not needed. inubit 6.1: Workbench/Process Engine: System Connectors Guide

236 236 OFTP Connector Dialog Stations Device name: Specifies the device name. The name you enter here is an alphanumeric string which must match the name in your business partner's configuration. Alias: If more than one router is present on the network, specify the name or IP address of the router over which the messages are to be directed. Active: This option causes the receiver to be ready to receive immediately the OFTP middleware is started Configuring an ISDN Receiver ISDN Address: This refers to the last three digits of the ISDN address as defined in ITU-T Recommendation E.164. Using these last three digits as a filter allows you to distinguish between the terminals. IP Address: Enter the IP address or the computer name of your ISDN router. Type: This is normally RCAPI1. Within this expression, CAPI stands for Common ISDN Application Programming Interface; RCAPI then stands for Remote CAPI. The number indicates the number of the router controller; in this case, 1. Protocol: Enter EDSS1 here; this stands for the Euro Digital Subscriber Signaling System No. 1 signaling protocol. Packet size: A packet size of 128 is normally specified here. Facilities: The Facilities and User data fields (refer to the next field) are normally left empty. Note that any values you may want to enter in these fields must be in HEX code. These fields are normally only used for X.25 transfers over ISDN, if your ISDN provider requires this. User data: Refer to the Facilities field above. Terminal identifier: Often referred to as Terminal ID. Unique number of your ISDN terminal. Timeout: The time in seconds before an attempt to establish a connection is cancelled. RCV Timeout: RCV stands for Receive. The time, in seconds, to keep waiting to receive. 0 means no timeout. Active: Activates the receiver configured under LOC Configuring a TCP/IP Receiver IP Address: Enter the IP address or the computer name of your ISDN router inubit 6.1: Workbench/Process Engine: System Connectors Guide

237 OFTP Connector Dialog Stations 237 Port: Specify the number of the port on which the messages will be received. Max. incoming sessions: The maximum number of parallel incoming sessions; -1 means that the global value of the MAXSESSIONS parameter is used. Max. outgoing sessions: The maximum number of parallel outgoing sessions; -1 means that the global value of the MAXSESSIONS parameter is used. Active: Activates the receiver configured under LOC Configuring an SNA LU6.2 Receiver Using LU (Logical Unit) 6.2 it is possible to establish parallel connections between a single logical unit and more than one application program. Vector Position: A data segment in an SNA message is also known as a vector. An SNA vector consists of a length field, a field indicating the vector type, and vector-specific data. The default value is 2. LU name: Name of the logical unit (LU) Network ID: The network ID (or NETID) specifies an SNA network. It is a string composed of one to eight alphanumeric characters. TP name: TP stands for Transaction Program. Specifies the name of an Advanced Program-to-Program Communication (APPC) transaction program on a database server. For example, RVSOFTP or DB2DRDA. Mode: The name of the mode must be unique and follow the SNA naming conventions: for example, LU62PS. User ID and Password: User ID corresponds to a login name. Some SNA networks require authentication. Security: Some SNA networks require authentication. If this is required, the checkbox must be selected. This causes the user ID and password to be added to the transferred data. Sync Level: Permitted values: - 0 or NONE: Processing doesn't need to be confirmed - 1 or CONFIRM: Processing is confirmed. inubit 6.1: Workbench/Process Engine: System Connectors Guide

238 238 OFTP Connector Dialog Stations inubit 6.1: Workbench/Process Engine: System Connectors Guide

239 24 OFTP2 Connector 239 This section details the following topics: Requirements, p. 239 Principles of Operation, p. 240 Data Transfer Modes, p. 241 rvsevo Monitoring, p. 242 Dialog OFTP data exchange configuration, p. 243 Dialog Stations, p. 246 Do not use the OFTP2 Connector in combination with the OFTP Connector! Use The OFTP2 Connector is used to exchange business data in accordance with the Odette File Transfer Protocol Version 2.0 (OFTP2). OFTP2 offers the facility to re-establish a connection after it has been interrupted without transferring the entire file again. ASCII and EBCDIC files can be transferred. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 24.1 Requirements rvsevo of the company T-Systems International GmbH must be installed and configured. Transfer parameters must be set and station must be defined. rvs consists of the rvs EVO Server and a client component. It can be configured via the user interface of the client component as well as via the user interface of the rvs EVO server. Be sure to check with Bosch Software Innovations GmbH which rvs version you require for your installation. inubit 6.1: Workbench/Process Engine: System Connectors Guide

240 240 OFTP2 Connector Principles of Operation You have copied the following files of the rvs client component into the <inubit-installdir>/server/tomcat/webapps/ ibis/web-inf/lib folder of the inubit Process Engine: - rvs-identity-data-1.0.jar - rvs-util jar - rvs-client-api jar - rvs-common-exception-1.0.jar - rvs-data jar - rvs-datahelper-1.5.jar - rvs-evo-server.jar For further information refer to the rvs documentation Principles of Operation Message flow Sending messages using an Output Connector The OFTP2 Connector passes the business messages on the inubit Process Engine to rvsevo. Sending the messages can be scheduled in such a way, that messages are sent immediately it reaches the OFTP2 Connector in the workflow, at an agreed time, or after an agreed time interval. rvsevo sends the messages via the agreed protocol to the station the receiver has set up inubit 6.1: Workbench/Process Engine: System Connectors Guide

241 OFTP2 Connector Data Transfer Modes 241 After the module is executed, the RVS Job ID is available as workflow variable. Receiving messages - Input Connector The OFTP2 Connector actively checks at defined intervals whether messages are present. - Input Listener Connector The OFTP2 Connector waits for a message to arrive on the configured connection and retrieves the message immediately it arrives Depending on which connector type you have chosen, communications are either synchronous or asynchronous. For information on the different modes of operation refer to Data Transfer Modes (Workbench/Process Engine: System Connectors Guide, chap. 24.3, p. 241) Data Transfer Modes The OFTP2 Connector supports the following data transfer modes: Asynchronous transfer using input connector The input connector retrieves the data in accordance with the configuration that you set up in the Dialog Scheduler (Workbench/Process Engine: System Connectors Guide, chap , p. 22). rvsevo sends an acknowledgement (EERP), either over the existing connection or when the connection is next established. This corresponds to the Normal option for the EERP_out parameter. For information on the EERP_out parameter refer to Neighbor Stations (Workbench/Process Engine: System Connectors Guide, chap , p. 248). The fact that the rvs software sends the acknowledgement doesn't guarantee to the sender of the message that the message has actually been delivered to the inubit Process Engine. Watch that the database does not exceed its maximum permitted size during operation! If you want to obtain further information in addition to the file name the rvsevo configuration needs to be changed accordingly. inubit 6.1: Workbench/Process Engine: System Connectors Guide

242 242 OFTP2 Connector rvsevo Monitoring Synchronous transfer by rvsevo using Input Listener Connector rvsevo confirms the receipt of a message by sending an EERP_ out. As regards the OFTP connector, this process is to some degree semi-synchronous as the confirmation is sent before the OFTP connector can confirm that the message is present in the inubit Process Engine. Synchronous transfer by an Input Listener Connector The acknowledgement is sent as soon as it is arrived completely in the inubit Process Engine. The EERP_out parameter must be set to HOLD in the neighbor station configuration. Refer to the EERP_out parameter in Neighbor Stations (Workbench/Process Engine: System Connectors Guide, chap , p. 248). The job (receive message) remains active until the acknowledgement of receipt (EERP_out) has been sent. Synchronous transfer by an Output Connector When sending a synchronous message where the system waits for a confirmation of transmission from the receiver, a timeout needs to be set to avoid a blockage being created by the wait. Check the Timeout checkbox. By default this option is deselected and thus set to indefinite. When specifying a value, take into account the size of the message and the transfer method. In addition, take into account the configuration at the other end. A blockage can also arise if the EERP message is set to HOLD at that end. Send Job on successful/failed transmission: rvs_is_send rvsevo Monitoring You can check the connection of the inubit Process Engine with the rvsevo server using the command line tool StartCLI inubit 6.1: Workbench/Process Engine: System Connectors Guide

243 OFTP2 Connector Dialog OFTP data exchange configuration 243 Options Option -r,--rvs --rhost --rlogin --rmwname --rpassword Information Check the connection of the inubit Process Engine with the rvsevo server rvsevo Host rvsevo Login Name of the rvsevo servers rvsevo password Refer to Remote Monitoring Using the Command Line Interface (StartCLI) (inubit Process Engine: Administrator and Developer Guide, chap. 7.10, p. 113) Dialog OFTP data exchange configuration Basic settings rvsevo server address Enter the name of the computer or the IP-address. For example: MyServer or (omitting the quotation marks). If the RMI registry doesn't run on port 3755, specify the name of the computer and the port number, separated by a colon. For example: MyServer:1234. rvsevo name The string rvsmw is normally used here. If you have used another name for the rvsevo, insert that name here. Login User name with which you log in to the rvsevo. Case-sensitive. Password Enter your password here. File name This name is used for the OFTP2 transmission. The receiver must be told what the name is in order to access the file. You may use wildcards or regular expressions in the file name. - Wildcards The following characters are permitted as wildcards: - Question mark (?): Represents any single character. - Asterisk (*): Represents zero or more arbitrary characters. inubit 6.1: Workbench/Process Engine: System Connectors Guide

244 244 OFTP2 Connector Dialog OFTP data exchange configuration Any number of wildcard characters may be used and in any combination. If wildcards are specified then e.g. an input connector will retrieve only files that match the specified value; all other files are ignored. To receive all files, enter *. - Regular expressions Regular expressions must be delimited by forward slashes (/), e.g.: /(\d\d)\.(\d\d)\.(\d\d\d\d)/ For more information about regular expressions, refer to or Windows: This operating system allows files to be hidden. If hidden files satisfy a wildcard criterion, they are also transferred. Make sure that the files that you can see in the Explorer directory are in fact all the files contained in that directory. To do this, show all files (in Explorer options Extras (Tools) > Folder options). Inbox subdirectory Specify the directory name that you set up in the rvsevo under Inbox, in which the incoming files are to be stored. The Inbox folder is identical to the <rvsevo-installdir>/ files/inbox folder on the rvsevo server. Unless you have configured a different directory, incoming messages are stored here. Virtual file name (VDSN) (Virtual dataset name) Name used for sending the file. If no value is given, the VDSN is generated out of the original file name. File description (not for the input connector) Detailed explanation of the virtual file name. Label (not for the input connector) For labeling files which should be sent in the same group. External JobID (not for the input connector) External identifier for the job. Conversion table For selecting data formats (left: source format, right: target format) Receiver station ID (not for the input connector): A station ID (SID) may be up to 16 characters in length. This ID is only used locally. It is user-definable and may consist of numbers and alphabetic characters. This SID must first be created in the rvsevo software in the Stations dialog and may then be copied over to this field. When you select the neighbor station in the Stations dialog, its ID is taken over automatically inubit 6.1: Workbench/Process Engine: System Connectors Guide

245 OFTP2 Connector Dialog OFTP data exchange configuration 245 Stations Before you can invoke the Stations dialog, you must first have entered valid connection data to an rvsevo installation in the Basic configurations dialog. No copy When creating a send entry the file to be sent is copied as a default into the outbox folder of the rvsevo and sent from there. Using the No copy option copying can be prevented. In this case the original file is deleted after being successfully sent. This option does not have any impact when the file is sent in the U (unstructured) format using code conversion. Delete file from server If this option is selected, the file is deleted on the rvsevo server once it has been transferred. Serialization When activated the exact order of the messages to be sent is observed. Messages to be sent together must have the same label. Synchronous mode Checking this checkbox activates the synchronous transfer mode. Record mode You can choose one of the following record modes for both formats F and V. - BIN (binary) By default, all records use the maximum record length. If the last record is shorter than the maximum record length, it is filled with binary zeros. - TXT (text) - Text files in F format: Lines that are longer than the maximum record length are truncated; lines that are shorter than the maximum record length are filled with blanks. - Text files in V format: Lines that are longer than the maximum record length are truncated, lines that are shorter than the maximum record length remain unchanged. Format (Output connector only) For specifying the format information for the file that is to be transferred: Format - Text: For transferring text files in ASCII format. inubit 6.1: Workbench/Process Engine: System Connectors Guide

246 246 OFTP2 Connector Dialog Stations - Fixed records: For transferring files containing fixed-length records. - Variable records: For transferring files containing variablelength records. - Unstructured: For transferring binary files. Max record length You can define a maximum length for fixed and variable records. Security ( Output Connector only) Security features For selecting a security level. Compression For activating/deactivating the data compression. Encryption For activating/deactivating the file encryption. This is not the session encryption for TLS! For more information about the encryption refer to the rvsevo documentation. Encryption algorithm For selecting an encryption algorithm, default DES_EDE3_CBC. File signature For activating/deactivating the use of a file signature. Apply for signed EERP/NERP For applying a signed EERP/NERP Dialog Stations This section details the following topics: Local Station, p. 247 Neighbor Stations, p. 248 Receiver, p. 254 Before you can invoke the Stations dialog, you must first have entered valid connection data to the rvsevo installation in the Basic configurations dialog. When you invoke the Stations dialog, the OFTP2 Connector connects to the rvsevo installation using the basic configuration you have specified and there obtains the configuration data, which is then displayed in the Stations dialog inubit 6.1: Workbench/Process Engine: System Connectors Guide

247 OFTP2 Connector Dialog Stations 247 Note that settings in the Stations dialog change the configuration in the rvsevo installation if you exit the dialog by clicking on the OK button Local Station LOC LOC is the local station file. If you select this entry, you can specify the configuration of the local station in the right-hand window. The configuration data must match the data that you have specified in your rvsevo administrator console. The local station must always have the name LOC (in uppercase). If you have selected LOC, a context menu becomes available containing the following commands: Add neighbor station Add receiver Remove receiver Activate connection General station parameters The Local station and Neighbor station area contain the RvsSid (mandatory), information about the station like name, telephone, company, city, street, contact person or . OFTP area For configuring communication parameters for the local station and all neighbor stations. For the local station you configure only the three parameters Odette ID, PKI and CertificationValidationType. For a description of the parameters refer to the rvsevo documentation. Odette ID: This is a unique character string consisting of up to 25 characters, the first of which is always O. You obtain an Odette ID from CertificationValidationType For selecting the type of certification validation: - CERT_PATH (weak validation): Validation via the ROOT certificates and/or CA certificates. inubit 6.1: Workbench/Process Engine: System Connectors Guide

248 248 OFTP2 Connector Dialog Stations - CRL (stronger validation): Validation via the Certificate Revocation List. - OCSP (strongest validation): Validation via the Online Certificate Status Protocol. - NONE: No validation. UsePki - When activated: Existing PKI with LDAP is used. - When deactivated: Certificates from the local keystore are used. Receiver areas The receiver configurations depend on the selected protocol. Refer to Receiver (Workbench/Process Engine: System Connectors Guide, chap , p. 254) Neighbor Stations This section details the following topics: Neighbor Station over TCP/IP, p. 250 Neighbor Station over ISDN, p. 250 Neighbor Station over XOT, p. 252 Virtual Station, p. 253 Routed Station, p. 253 Activating Connection, p. 254 Remove, p. 254 A neighbor station is the station of a business partner with which you want to exchange messages. Add neighbor station Use this option to add a new neighbor station. This is added to a directory tree under LOC. You must know the neighbor station's configuration. If you select the newly added station, you can add the parameters on the right-hand side of the dialog. The stations can be configured for different protocols. Select one of the following: TCP/IP, TLS-, ISDN, XOT-, Proxy TCP/IP- or Proxy TLS. OFTP area Odette ID (mandatory): This is a unique character string consisting of up to 25 characters, the first of which is always O. Receive password: The password expected from the business partner inubit 6.1: Workbench/Process Engine: System Connectors Guide

249 OFTP2 Connector Dialog Stations 249 Send password: The password is sent to the business partner. Exchange buffer size: Maximum size of the buffer in Byte. Possible values: Exchange buffer number: Maximum number of sent blocks without expecting a receipt. Possible values: End to end response in (EERP_in): EERP (End-to-End Response) refers to an acknowledgement of receipt of the message. The EERP_in is sent by the business partner. The combo box offers the options NEVER and NORMAL. - NEVER: means that the business partner does not send an acknowledgement. The transmission ends with the correct transfer of the message. - NORMAL: means that an acknowledgement is expected. Receiving the acknowledgement forms part of the Send Request. A Send Request persists while there are further files to send or until the acknowledgement has been received. When the acknowledgement is received, the Send Request is ended. NORMAL is the default. End to end response out (EERP_out): An acknowledgement is sent from the local station to the business partner. The IMMEDIATE option is pre-selected by default. The following options are available. - NEVER: No acknowledgement is sent. - NORMAL: An acknowledgement is sent when a message is received. If a connection still exists, the acknowledgement is sent immediately. If the connection has already been released, the acknowledgement is sent when the next connection is established. - SYNC: The acknowledgement is sent over the same connection by which the message arrived. This forces the connection to be maintained. The connection cannot be closed until the successful transmission of the acknowledgement of receipt has been verified. - HOLD: The acknowledgement is only sent when it is explicitly released by an operator via the rvsevo installation. If the connection still exists, the acknowledgement is sent immediately. If the current connection has already been interrupted, the acknowledgement is sent the next time that a connection is established. The OFTP2 connector gives the release for the rvsevo installation itself; no operator intervention is required. - RoutingSync: The OFTP2 session between the router and the sender is kept open until the receipt from the receiver has arrived in order to send it back to the sender using the same OFTP2 session. inubit 6.1: Workbench/Process Engine: System Connectors Guide

250 250 OFTP2 Connector Dialog Stations Neighbor Station Name, Telephone, Remarks and Network are optional fields. Use this section to enter information about who looks after the configuration of the neighbor stations. Line Type Active connection setup: If this option is selected, the rvsevo installation automatically establishes a connection when there is a message to send. Parallel Session: The default value is 1. Security OFTP version This parameter must only be set if the partner cannot negotiate the protocol version. SFIDDESC as file name (Start File ID-Description) Used as file name for the transfer instead of the VDSN. PKI Activates/deactivates the PKI connection. Certificate validation Defines how certificates should be validated. Neighbor station protocol type The structure of the remainder of the neighbor station dialog depends on the communications protocol that you have selected Neighbor Station over TCP/IP IP Address: Specify either the name or the IP number of the computer via which the TCP/IP connection is made. Port: Specify the port number for the TCP/IP connection Neighbor Station over ISDN When you configure a neighbor station that is connected over ISDN, the X.25 protocol is automatically added to the configuration as ISDN on its own is insufficient for establishing an OFTP2-compliant connection. Number of the assigned receiver: Is assigned automatically. Type (mandatory): Not configurable. Card number (mandatory): Is assigned automatically. ISDN Address inubit 6.1: Workbench/Process Engine: System Connectors Guide

251 OFTP2 Connector Dialog Stations 251 Corresponds to the ISDN number of the partner. Type: Normally CAPI2A. ISDN Protocol: Used ISDN standard. - 1TR6: German standard. - E-DSS1: EURO-ISDN (Standard) Packet size: A packet size of 128 is normally specified here. ISDN facilities: Normally left empty. ISDN user data: Normally left empty. If you wish to enter Facilities and User data, then enter them as hex code. The data is only required for X.25 via ISDN transfers, if your X.25 provider demands them. For more information refer to the rvsevo documentation. Terminal identifier: Often referred to as Terminal ID. Unique number of your ISDN terminal. Connection timeout Time in seconds after which the attempt to build up a connection is aborted. X.25 address X.25-DTE address of the partner station. 15 digits. Information is optional. It is recommended to enter the ISDN number, because some remote stations expect a X.25 address. X.25 package size Size of the data packages when transferring them. Default: 128. X.25 facilities Special information or attachments for the X.25 transfer. X.25 user data User information for the X.25 transfer. X.25 window size The window size for the X.25/ISDN communication is the number of packages which can be sent without confirmation. The window size can be negotiated when the connection is build up. It is recommended to configure a window size which is suitable for the partner network, e. g. the value 7 for ISDN. X.25 DBit The d-bit is a field in the X.25 data package, which is used for the end-to-end-confirmation. Thus, the DTE signals if receiving an end-to-end-confirmation is required. Default: deactivated. X.25 closed user circuit ISDN and X.25 provide the opportunity to create a closed user group. All participants belonging to such a group can communicate with each other via the public telecommunication network. inubit 6.1: Workbench/Process Engine: System Connectors Guide

252 252 OFTP2 Connector Dialog Stations Connection requests from participants which are not part of the closed user group are refused by the switching center. Default: deactivated Neighbor Station over XOT XOT stands for X.25 over TCP. X.25 is an international telecommunications standard adopted by the International Telecommunication Union. Refer to Configuring an XOT Receiver (Workbench/Process Engine: System Connectors Guide, chap , p. 256). For further information, refer to X.25 Address: Each computer that is to communicate in an X.25 network must have an X.25-compliant address. An X.25 address is a sequence of digits. The first digits represent the country code, the following digits indicate the network within the country and the final digits indicate the computer number. X.25 facilities: Normally left empty. X.25 user data: Normally left empty. If you wish to enter Facilities and User data, then enter them as hex code. The data is only required for X.25 via ISDN transfers, if your X.25 provider demands them. Timeout: The time in seconds before an attempt to establish a connection is cancelled. DBit: (Delivery confirmation bit) If you select this option, the sending station requires an acknowledgement of receipt. X.25 Package size Size of the data packages when transferring them. Default: 128. X.25 window size The window size for the X.25/ISDN communication is the number of packages which can be sent without confirmation. The window size can be negotiated when the connection is build up. It is recommended to configure a window size which is suitable for the partner network, e. g. the value 7 for ISDN. X.25 DBit The d-bit is a field in the X.25 data package, which is used for the end-to-end-confirmation. Thus, the DTE signals if receiving an end-to-end-confirmation is required. Default: deactivated. X.25 Modulo When using the X.25 data transfer a method based on modulo is used for the transfer of user information using counters and a window mechanism on the security layer inubit 6.1: Workbench/Process Engine: System Connectors Guide

253 OFTP2 Connector Dialog Stations 253 For X.25 two modulo versions are known: the modulo-8-counter and the modulo-128-counter. Default: Virtual Station Use To send files to target systems ouside the OFTP network Mandatory parameter RvsSid Odette ID Refer to - Local Station (Workbench/Process Engine: System Connectors Guide, chap. 24, p. 247) - Neighbor Stations (Workbench/Process Engine: System Connectors Guide, chap. 24, p. 248) Routed Station If you select a neighbor station, you can select the Add routed station option from the context menu. Messages to and from a routed station are passed on from its 'parent' neighbor station. The specific address of a routed station is available for the business partner. If you create a routed station, the following parameters are displayed on the righthand side of the dialog: RvsNeighborSid: This field has as default value the name of the neighbor station under which the routed station was configured. Name, Telephone, Remarks: This information is optional. You could, for example, store information about an administrator. Odette ID: This is a unique character string consisting of up to 25 characters, of which the first is always O. End to end response in (EERP_in): The EERP_in is sent by the business partner. The combo box offers the options NEVER and NORMAL. End to end response out (EERP_out): An acknowledgement is sent from the local station to the business partner. The IMMEDIATE (see below) option is pre-selected by default. The following options are available: NORMAL, NEVER, HOLD, SYNC, and ROUTING_SYNC. For information about the options that can be selected for the acknowledgement of receipt refer to Neighbor Stations inubit 6.1: Workbench/Process Engine: System Connectors Guide

254 254 OFTP2 Connector Dialog Stations (Workbench/Process Engine: System Connectors Guide, chap , p. 248) Activating Connection If you select a neighbor station, you can select the Activate connection option from the context menu. This option allows you to test whether a connection can be established with the neighbor station you have configured using the data as specified Remove If you select a neighbor station, you can select the Remove option from the context menu. If you select this option, the selected neighbor station is removed after the confirmation of the message box. This change also deletes the selected neighbor station in the rvsevo software Receiver This section details the following topics: Configuring a TCP/IP Receiver, p. 255 Configuring an ISDN Receiver, p. 255 Configuring an XOT Receiver, p. 256 Configuring a TLS Receiver, p. 257 A receiver is a connection configuration that is based on one of the following protocols: TCP/IP, ISDN, XOT or TLS. If you invoke the Stations dialog then select the LOC entry on the left, a list of all the receivers is displayed on the right. You can add and remove receivers. Removing receiver Selecting this option allows you to then select from the list all the configured receivers that you want to remove. Check that no further messages are being exchanged over the receivers that you are removing inubit 6.1: Workbench/Process Engine: System Connectors Guide

255 OFTP2 Connector Dialog Stations 255 Adding receiver Receivers are added to the local station. For the limit on the number of receivers that you can add, refer to the manual for the OFTP2 middleware that you are using. Receiver's protocol: A number of receivers may be added to the local station that are linked over different protocols. You can add one or more receivers of the following types: TCP/IP, ISDN, XOT or TLS Configuring a TCP/IP Receiver VectorPosition: Not editable. Receiver number: Not editable. IP Address: Enter the IP address or the computer name of your ISDN router. Port: Specify the number of the port on which the messages will be received. Max. incoming sessions: Maximum number of parallel incoming sessions. Active: Activates the receiver configured under LOC. Timeout: Time in seconds after which the attempt to build up a connection is aborted Configuring an ISDN Receiver VectorPosition: Not editable. Type: Normally CAPI2A. ISDN Protocol: Defines the used ISDN standard: - 1TR6: German standard - E-DSS1: EURO-ISDN (default) ISDN facilities: Normally left empty. ISDN user data: Refer to the Facilities field above. X.25 packet size: A packet size of 128 is normally specified here. If you wish to enter Facilities and User data, then enter them as hex code. The data is only required for X.25 via ISDN transfers, if your X.25 provider demands them. ISDN terminal identifier: Unique number of your ISDN terminal. Receiver number: Not editable. Active: Activates the receiver configured under LOC. ISDN number: Your ISDN number. Connection timeout: The time in seconds before an attempt to establish a connection is cancelled. inubit 6.1: Workbench/Process Engine: System Connectors Guide

256 256 OFTP2 Connector Dialog Stations RCV Timeout: RCV stands for Receive. The time, in seconds, to keep waiting to receive. 0 means no timeout. Max. incoming connections: Maximum number of incoming parallel connections. X.25 facilities Special information or attachments for X.25 transfers. X.25 user data User data for X.25 transfers. X.25 window size The window size for the X.25/ISDN communication is the number of packages which can be sent without confirmation. The window size can be negotiated when the connection is build up. It is recommended to configure a window size which is suitable for the partner network, e. g. the value 7 for ISDN. X.25 closed user circuit ISDN and X.25 provide the opportunity to create a closed user group. All participants belonging to such a group can communicate with each other via the public telecommunication network. Connection requests from participants which are not part of the closed user group are refused by the switching center. Default: deactivated Configuring an XOT Receiver XOT stands for X.25 over TCP. X.25 is an international telecommunications standard adopted by the International Telecommunication Union. For further information, refer to VectorPosition: Not editable. Receiver number: Not editable. Local IP Address: IP address or name of the local computer. Local Port: Port number of the local computer, default: Router IP Address: IP address or name of your ISDN router. Router Port: Port number of your ISDN router, default: X.25 Address: Each computer that is to communicate in an X.25 network must have an X.25-compliant address. An X.25 address is a sequence of digits. The first digits represent the country code, the following digits indicate the network within the country and the final digits indicate the computer number. X.25 facilities: Normally left empty. X.25 user data: Normally left empty inubit 6.1: Workbench/Process Engine: System Connectors Guide

257 OFTP2 Connector Dialog Stations 257 If you wish to enter Facilities and User data, then enter them as hex code. The data is only required for X.25 via ISDN transfers, if your X.25 provider demands them. RvsTimeout: The time in seconds before an attempt to establish a connection is cancelled. RvsRestartTimeOut: Time in seconds after which the attempt to build up a new connection is aborted. X.25 Package size: Normally, the value is 128. X.25 window size: Number of packages which can be sent without confirmation, default: 7. Max. incoming connections Maximum number of parallel receiving processes via this channel, default: 1, maximum: 100. X.25 DBit: (Delivery confirmation bit). If you select this option, the sending station requires an acknowledgement of receipt. X.25 Modulo: Modulo version, default: 8. Refer to X.25 Modulo (Workbench/Process Engine: System Connectors Guide, chap. 24, p. 252) Configuring a TLS Receiver By using a TLS receiver (Transport Layer Security) you can communicate encryptedly. IP Address IP address of the TLS receiver. Port Port via which the TLS receiver can be reached. inubit 6.1: Workbench/Process Engine: System Connectors Guide

258 258 OFTP2 Connector Dialog Stations inubit 6.1: Workbench/Process Engine: System Connectors Guide

259 25 OpenOffice Connector 259 This section details the following topics: Requirement: OpenOffice Installation, p. 259 Functional Principle, p. 260 Creating an Example Workflow, p. 260 Convert the Document into the PDF Format, p. 263 Editing a Document, p. 264 Printing a Document, p. 266 Basic Settings Dialog, p. 267 Use With the OpenOffice Connector, you can automatically edit and convert Microsoft Word/OpenOffice Writer documents and print them on remote computers (Remote Printing Service) and maintain document templates with Office, e. g. for business cards or bills. You can automatically convert Microsoft Excel and OpenOffice Calc documents into other formats. Refer to XML schema as template for input messages (Workbench/Process Engine: System Connectors Guide, chap. 25, p. 260) Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 25.1 Requirement: OpenOffice Installation An OpenOffice.org installation of at least can be reached from the inubit software. OpenOffice has been started in the server mode: For this, you go to the OpenOffice program directory <OpenOfficeInstallDir>/App/openoffice/program and execute the following command: soffice[.exe] -headless -nofirststartwizard -accept="socket,host=localhost,port=8100;urp;staroffice.service" inubit 6.1: Workbench/Process Engine: System Connectors Guide

260 260 OpenOffice Connector Functional Principle 25.2 Functional Principle The OpenOffice Connector expects an XML input message with the following elements: Base64-coded input document Output filter (optional) Operations (change, convert or print) that are to be carried out on the document. The OpenOffice Connector opens the specified input document and carries out the operations. It then creates the target document in the specified format or sends it to the configured printer. XML schema as template for input messages You create the input messages for the OpenOffice Connector on the basis of the supplied XML schema OOC.xsd with an XSLT Converter. OOWriter node: Attributes for Word/Writer documents OOCalc node: Attributes for Excel/Calc documents You will find the XML schema in the repository in the following directory: /Global/System/Mapping Templates/OpenOffice Connector 25.3 Creating an Example Workflow You can use the following example workflow to edit, convert or print Word and Writer documents, depending on the configuration of the XSLT Converter and the File Connector: Assign module for coding as Base64 Proceed as follows 1. Create an assign module and give it a name. 2. Create a new mapping rule for the variable mapping. - Select output message as the source and binary data as the data type. - Select variable as the target inubit 6.1: Workbench/Process Engine: System Connectors Guide

261 OpenOffice Connector Creating an Example Workflow Create the variable oo.document with the type xs:base64binary. 3. Choose OK to save the mapping rule. XSLT Converter Proceed as follows 1. Create an XSLT Converter. 2. Activate the Ignore input message checkbox on the XSLT Converter Properties page. 3. In the XML target file window, open the schema file OOC.xsd. Refer to XML schema as template for input messages (Workbench/Process Engine: System Connectors Guide, chap. 25, p. 260). 4. Drag root element OpenOfficeConnector in the schema file from the XML target area onto the xsl:template element in the XML target area of the XSLT stylesheet. 5. Remove all the elements not required. To find out which elements you need, refer to the examples. Refer to - Convert the Document into the PDF Format (Workbench/ Process Engine: System Connectors Guide, chap. 25, p. 263) - Editing a Document (Workbench/Process Engine: System Connectors Guide, chap. 25, p. 264) - Printing a Document (Workbench/Process Engine: System Connectors Guide, chap. 25, p. 266) 6. Use the XSLT command assistant to insert the element param with the name=oo.document attribute above the element xls:output. 7. Assign the XSLT command value-of and the value $oo.document to the element InputDocument. You thus read the value of the variable oo.document defined in the assign module, which contains the content of the document to be processed, into the element InputDocument. 8. Click Finish. 9. Connect the assign module to the XSLT Converter. Adding the OpenOffice Connector Proceed as follows 1. Create an OpenOffice Connector. 2. Specify the system on which the OpenOffice server is installed ( Server name field) and via which port it can be reached. 3. Connect the XSLT Converter with the OpenOffice Connector. 4. Set the start point before the assign module. 5. Start the workflow with a Word/Writer file. inubit 6.1: Workbench/Process Engine: System Connectors Guide

262 262 OpenOffice Connector Creating an Example Workflow 6. Open the Watchpoint file after the OpenOffice Connector. 7. Save the Watchpoint file in the clipboard. Adding the assign module for decoding from Base64 Proceed as follows 1. Create an assign module and give it a name. 2. Create a new mapping rule for the variable mapping. a. Select input message as the source and XML as the data type. b. Click the Select XML element button at the end of the XPath row. c. Open the clipboard with the Watchpoint file you saved in step 7 when creating the OpenOffice Connector. d. Drag the text node of the OutputDocument into the XPath row. e. Choose OK to save the changes. f. Select variable as the target. g. Create the variable oo.result with the type xs:base64binary. 3. Create another mapping rule for the variable mapping. a. Select variable as the source. b. Choose the variable oo.result created in step 2 as the variable. c. Select input message as the target and UTF-8 as the coding. 4. Choose OK to save the mapping rule. 5. Connect the OpenOffice Connector with the assign module. Adding the File Connector Proceed as follows 1. Create a File Output Connector and give it a name. 2. Go to the page File to be written. 3. Select data as the input format inubit 6.1: Workbench/Process Engine: System Connectors Guide

263 OpenOffice Connector Convert the Document into the PDF Format Enter the name of the directory in which the target file is to be saved. 5. Enter the name of the target file. 6. Connect the assign module to the File Converter Convert the Document into the PDF Format Proceed as follows 1. Create an input message in an XSLT Converter. Refer to Creating an Example Workflow (Workbench/Process Engine: System Connectors Guide, chap. 25.3, p. 260). 2. Activate the Ignore input message checkbox in the XSLT Converter Properties dialog. 3. Modify the XSLT stylesheet so that the message that is a result of the mapping has the following structure: 4. Assign the value writer_pdf_export to the element outputfilter in the XSLT stylesheet. 5. In the example workflow, replace the XSLT Converter with the XSLT Converter you have just created and adjusted. 6. If applicable, adjust the file name and the directory in the File Connector on the page File to be written. inubit 6.1: Workbench/Process Engine: System Connectors Guide

264 264 OpenOffice Connector Editing a Document 7. Set the start point before the assign module at the start of the example workflow. 8. Start the workflow with the document to be converted. 9. Check whether the document was converted correctly Editing a Document Proceed as follows 1. Create a Word or Writer document with multiple bookmarks, e. g. for an address. 2. Create an input message with an XSLT Converter. Refer to Creating an Example Workflow (Workbench/Process Engine: System Connectors Guide, chap. 25.3, p. 260). 3. Activate the Ignore input message checkbox on the XSLT Converter Properties page. 4. Modify the XSLT stylesheet so that the message that is a result of the mapping has the following structure: inubit 6.1: Workbench/Process Engine: System Connectors Guide

265 OpenOffice Connector Editing a Document Depending on the type of changes desired, you can omit individual BookmarkReplace elements or add other elements in accordance with the schema file. Refer to XML schema as template for input messages (Workbench/Process Engine: System Connectors Guide, chap. 25, p. 260). 5. In the example workflow, replace the XSLT Converter with the XSLT Converter created in step If applicable, adjust the file name and the directory in the File Connector on the page File to be written. 7. Set the start point before the assign module at the start of the workflow. 8. Start the workflow with the document to be edited. 9. Check whether the document was edited correctly. inubit 6.1: Workbench/Process Engine: System Connectors Guide

266 266 OpenOffice Connector Printing a Document 25.6 Printing a Document Proceed as follows 1. Create an assign module to code the input document Base64. Refer to Assign module for coding as Base64 (Workbench/ Process Engine: System Connectors Guide, chap. 25, p. 260). 2. Create an input message with an XSLT Converter. Refer to Creating an Example Workflow (Workbench/Process Engine: System Connectors Guide, chap. 25.3, p. 260). 3. Activate the Ignore input message checkbox on the XSLT Converter Properties page. 4. Modify the XSLT stylesheet so that the message that is a result of the mapping has the following structure: 80 The only attributes permitted are the name of the printer in the attribute printername and the page(s) to be printed in the attribute pages. You use a comma to separate the individual pages to be printed. You put a hyphen between the first and last pages of a print section. 5. Connect the assign module to the XSLT Converter. 6. Create an OpenOffice Connector. 7. Connect the XSLT Converter with the OpenOffice Connector. 8. Set the start point before the assign module. 9. Start the workflow with the document to be printed. 10. Check whether the document was printed correctly inubit 6.1: Workbench/Process Engine: System Connectors Guide

267 OpenOffice Connector Basic Settings Dialog Basic Settings Dialog In this dialog, you have the following options: OpenOffice Server Server name IP address or host name of the system on which OpenOffice is installed. Port Port via which the OpenOffice Connector is accessed. Standard Resets the port to the standard value Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

268 268 OpenOffice Connector Basic Settings Dialog inubit 6.1: Workbench/Process Engine: System Connectors Guide

269 26 OSCI Connector 269 This section details the following topics: Prerequisites, p. 270 Functional Principle, p. 270 Dialog Descriptions, p. 271 Use The Online Service Computer Interface (OSCI) is a message standard and is used as the basis for legally-compliant data transfer in the egovernment sector based on a digital signature and encryption between two communication partners using a virtual post room (intermediary). Data is transferred in the form of OSCI messages. The OSCI Connector connects to a virtual post room and enables the following within a workflow: Accepting OSCI messages from a virtual post room, unpacking and decoding them and checking their signature. Creating, signing and encrypting OSCI messages for a virtual post room. Connector types The functions of the OSCI Connector depend on the actual configuration: Input Connector Retrieves OSCI messages from the virtual post room in the set interval and unpacks them. The Input Connector is only active when the Scheduler is activated. Refer to Dialog Scheduler (Workbench/Process Engine: System Connectors Guide, chap , p. 22). Medium Connector Sends encoded and signed OSCI messages to a virtual post room and forwards the response to the next module in the workflow. The current OSCI specification is available at ProfilingAndExtensionSpecification_EN.pdf. Also refer to - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) inubit 6.1: Workbench/Process Engine: System Connectors Guide

270 270 OSCI Connector Prerequisites 26.1 Prerequisites Address (URL) of intermediary is available Public key certificate *cry.cer of intermediary is available Private signature certificate is available Private key certificate is available Passwords for private certificates are available Save the certificate files in a corresponding directory. The certificates for the private keys are *.pfx files; those for the public keys are *.cer files Functional Principle You can use an OSCI Connector to receive OSCI messages, which are transported between an OSCI client as the sender, a virtual post room (VPS) as an OSCI intermediary and a recipient, with the inubit software via the intermediary or to send them via the intermediary. Data transmission OSCI is the egovernment standard for safe data transmission. Data is sent and received in the form of OSCI messages. Certificate management Certificates are used to encode and sign OSCI messages and also to address the messages inubit 6.1: Workbench/Process Engine: System Connectors Guide

271 OSCI Connector Dialog Descriptions 271 Communication process The data to be transferred is exchanged between the communication partners in the form of messages. The communication partners can be the senders as well as the recipients of messages. The data belonging to a message is electronically signed by the sender once it has been recorded. Following that, it is sent to an intermediary in OSCI format. The intermediary acts as a virtual post room (VPS). It checks the signature and the certificates, creates a check log for these and holds the message in the server inbox of the recipient. The virtual post room uses the OSCI intermediary for processing OSCI messages. The virtual post room is a solution for receiving, converting and processing encoded and signed messages that a government agency receives in a range of formats and protocols. The OSCI Connector connects to the virtual post room and can receive and send OSCI messages with the corresponding access data. The corresponding schema template is available in the inubit Repository at Global > System > Mapping Templates > OSCI Connector Dialog Descriptions This section details the following topics: Dialog Retrieving OSCI Messages, p. 271 Dialog Creating OSCI Messages, p Dialog Retrieving OSCI Messages (Input Connector) In this dialog, you specify the configuration settings of the recipient for retrieving OSCI messages from the intermediary. Since the Input Connector only retrieves messages when the Scheduler is active, you must activate the Scheduler in the Scheduler dialog in order to specify the polling interval, refer to inubit 6.1: Workbench/Process Engine: System Connectors Guide

272 272 OSCI Connector Dialog Descriptions Dialog Scheduler (Workbench/Process Engine: System Connectors Guide, chap , p. 22). Virtual post room Intermediary Enter the URL of the intermediary at which it can be reached online. Intermediary certificate Load the file with the public certificate of the intermediary; this is a *.cer file. Recipient Signature keystore Load the *.pfx file with the private key of the recipient. Password of signature key Enter the keystore password of the private key for signature verification. Encryption keystore Load the *.pfx file with the private key for decryption. Password of encryption key Enter the keystore password of the private key for decryption. Connection test Test connection Test whether the connection can be established successfully with the information you entered Dialog Creating OSCI Messages (Medium Connector) In this dialog, you specify the configuration settings of the author and recipient for creating OSCI messages at the intermediary. Virtual post room Intermediary Enter the URL of the intermediary at which it can be reached online. Intermediary certificate Load the file with the public certificate of the intermediary; this is a *.cer file inubit 6.1: Workbench/Process Engine: System Connectors Guide

273 OSCI Connector Dialog Descriptions 273 Author Signature keystore Load the *.pfx file with the certificate of the sender that is used for signing. Password of signature key Enter the keystore password of the private key for signing the created message. Encryption keystore Load the *.pfx file with the certificate of the private key of the sender for encrypting the created message. Password of encryption key Enter the keystore password of the private key for encrypting the created message. Recipient Encryption certificate Load the file with the public certificate of the recipient. Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

274 274 OSCI Connector Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

275 27 REST Connector 275 This section details the following topics: REST Connector Module Variables, p. 276 REST Functional Principle, p. 277 Using HTTP Methods, p. 280 Offering a Resource, p. 281 Displaying Available Input Connectors, p. 283 Displaying Published Resources, p. 284 Calling Resources, p. 284 Dialog Descriptions, p. 286 Use The REST Connector provides an interface for transferring data via HTTP without an additional transport layer such as SOAP. The REST Connector is used to call or provide REST-compatible Web services via a URL. Connector types The REST Connector functions depend on the actual configuration: Input Listener Connector Provides a resource under a specified URL, which can be requested by a client by means of a request. The provided resource is the result of a workflow execution. All parameters and headers that were transferred with the request are available as module variables during workflow execution. Medium/Output Connector Sends an HTTP request to an HTTP server as a client and the Medium Connector forwards the returned response (if available) to the workflow. Also refer to - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) inubit 6.1: Workbench/Process Engine: System Connectors Guide

276 276 REST Connector REST Connector Module Variables 27.1 REST Connector Module Variables When a REST Connector is executed, the following variables are set depending on the connector type and are available downstream in the workflow. Input Listener Connector The following variables are set for the data of the received request: restconnector.requestmethod Contains the name of the HTTP method of the request. restconnector.requestheaders Contains the header data of the request message. restconnector.requestqueryparams Contains the values of the query parameters from the request URL. These are converted into an XML structure and every parameter is converted into an XML element. restconnector.requestresourcepath Contains the path of the requested resource. For example, for the request URL orders/123, the variable contains the value /orders/123. restconnector.requesturitemplateparam.x Contain the contents of dynamic path components of the request URL. x always stands for the name of the path component in curly brackets within the resource URL configured on the Connector. For the resource URL users/{username}/orders/ {orderno}, for example, the variables restconnector.requesturitemplateparam.username and restconnector.requesturitemplateparam.orderno are set with the actual values from the request URL. restconnector.clientaddress Contains the IP address of the calling client. restconnector.requestauthuser Contains the name of the authenticated user, if Use portal user data was selected under authentication options. The status and header data of the response to be sent is written to the following variables: restconnector.responsestatuscode Contains the response code for the result of the sent response. restconnector.responsestatusdescription Contains the description of the response code. restconnector.responseheaders Contains the header data of the sent response message. The content of the variables corresponds to the default values configured in the connector. The variables are designed to be inubit 6.1: Workbench/Process Engine: System Connectors Guide

277 REST Connector REST Functional Principle 277 overwritten dynamically in the workflow. The value of the variable that is available at the end of the workflow is used for sending the response. Medium/Output Connector The status and header data of the response to be received is written to the following variables: restconnector.responsestatuscode Provides the response code that specifies the result of the query. restconnector.responsestatusdescription Provides the description of the response code, e.g. Internal Server Error. restconnector.responseheaders Contains the header data of the response message. Refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351) REST Functional Principle HTTP resource URLs REST (Representational State Transfer) is an architectural concept for Web services that describes how web standards can be used in a way that is appropriate for the web. REST-based Web services use the HTTP protocol and HTTP methods such as GET or POST. A basic principle of this model is that the functionality of a Web service is not mapped in its properties but in the resources of the service. The individual functions of a service are split into resources that can be individually addressed using URLs. REST thus makes it possible to address applications, for example an online shop, via a URL. In doing so, every individual object of the application, such as article or customer, represents a resource that is addressed using its own URL. Every REST resource has a generic interface via the different HTTP methods. inubit 6.1: Workbench/Process Engine: System Connectors Guide

278 278 REST Connector REST Functional Principle For the example of an online shop as a REST service, order management has, for example, a URL for the quantities of the purchase orders from every customer and a URL for every purchase order. Communication takes place only when necessary and on request. The client or connector becomes active and requests a representation of a resource from the server or modifies a resource. Resources In the example of the online shop, this shop represents a collection of resources to which HTTP messages can be sent, for example to call up a customer for a purchase order in a shopping cart. The resource is not manipulated directly because access takes place indirectly, using the URL assigned to the resource. Examples of resources Online shop as a Web service: List of all orders: Order number 1234: inubit 6.1: Workbench/Process Engine: System Connectors Guide

279 REST Connector REST Functional Principle Representations Every resource can have different representations, that is, the customer can be represented, for example, by an XML structure with customer master data or by a business card in vcard format. The client and server must have a common understanding of the meaning of the representation through the use of XML. Representations can refer to other resources, which in turn provide representations that can also refer to resources. If a client follows a link in a representation, this takes it to another resource. Examples of representations Representation of a customer through the customer's master data: <CUSTOMER> <ID>4</ID> <FIRSTNAME>John</FIRSTNAME> <LASTNAME>Smith</LASTNAME> <STREET>Elisabeth St. 13</STREET> <CITY>Sample city</city> </CUSTOMER> Representation of a customer list with links to the individual customers as additional resources: <CUSTOMERList> <CUSTOMER xlink:href=" /sqlrest/customer/1/">1 </CUSTOMER> <CUSTOMER xlink:href=" /sqlrest/customer/2/">2 </CUSTOMER> <CUSTOMER xlink:href=" /sqlrest/customer/3/">3 </CUSTOMER> <CUSTOMER xlink:href=" /sqlrest/customer/4/">4 </CUSTOMER> <CUSTOMER xlink:href=" /sqlrest/customer/29/">29 </CUSTOMER> </CUSTOMERList> inubit 6.1: Workbench/Process Engine: System Connectors Guide

280 280 REST Connector Using HTTP Methods Methods According to the REST principle, resources are to be accessed using the standard HTTP methods GET, POST, PUT and DELETE. Hence, no protocol conventions have to be known in order for client and server to be able to communicate. A request, for example for a certain purchase order always consists of a URL and an HTTP method. The HTTP methods map the basic actions on the resources. Refer to Using HTTP Methods (Workbench/Process Engine: System Connectors Guide, chap. 27.3, p. 280) Using HTTP Methods The HTTP methods that can be configured in the REST connectors cover the use cases of REST applications. HTTP method GET POST PUT DELETE OPTIONS HEAD Meaning GET queries the representation of a resource. GET requests can be sent any number of times. POST can be used to add something to a resource. For example, a material can be added to a shopping cart. New resources can be generated using PUT or the content of existing resources can be replaced using PUT. Resources can be deleted using DELETE. Returns a list of methods supported by the server. In the same way as for GET, a resource is queried. However, no content (body) is transferred in the reply but merely the response header. This enables you to, for example, query the file size before a GET request. To apply different methods to a resource, the same URL is always used because the URL is independent of the executed action inubit 6.1: Workbench/Process Engine: System Connectors Guide

281 REST Connector Offering a Resource Offering a Resource Principle You can implement a Web service in the form of a REST resource through a Technical Workflow with a REST Input Listener Connector. The REST Connector then offers a resource (e.g. an order or article list) to the outside in form of a URL. Individual resources are always offered via a single REST Input Connector. The resources are individual objects of an application that must be reachable via a URL and can be represented with a document, ideally in XML. Proceed as follows 1. Configure a resource a. Create a REST Input Listener Connector. b. In the list, under Use specifications for, choose which type of resource this connector is supposed to offer. Refer to Provided resource (Workbench/Process Engine: System Connectors Guide, chap. 27, p. 287). c. Define a URL under which the resource can be accessed. You can use curly brackets for dynamic path components, e.g. {orderid}. Here, the value of orderid is made available as a workflow variable in the workflow and can be used to determine the data of the desired order, refer to REST Connector Module Variables (Workbench/Process Engine: System Connectors Guide, chap. 27.1, p. 276). Enter * at the end of the path to support paths ending with characters of any type. d. Protect your Rest service against unauthorized access by activating the Authentication required option. e. Define the desired method of authentication and specify the access data required for a request. f. Define which operations can be executed on your resource. Not all HTTP methods are permissible for every resource type. By default, those HTTP methods that make sense for the selected resource are preselected, refer to Provided resource (Workbench/Process Engine: System Connectors Guide, chap. 27, p. 287). g. Specify the encoding for data that is received as a request in format multipart/form-data. 2. Configure a response inubit 6.1: Workbench/Process Engine: System Connectors Guide

282 282 REST Connector Offering a Resource For each permissible HTTP method with which the resource can be requested, you define the response returned by the resource. a. Configure the response data for the available request types. Refer to Dialog Response configuration (Workbench/ Process Engine: System Connectors Guide, chap , p. 288). The values configured here can be changed dynamically in the workflow by changing corresponding variables. Refer to REST Connector Module Variables (Workbench/ Process Engine: System Connectors Guide, chap. 27.1, p. 276). For resources with several supported methods, variable restconnector.requestmethod is particularly important because the value of this variable can be used to branch in the workflow in order to implement the respective method. Example of a collective resource inubit 6.1: Workbench/Process Engine: System Connectors Guide

283 REST Connector Displaying Available Input Connectors 283 Example of a single resource from a collection For incoming requests with HTML form data and content type application/x-www-form-urlencoded the form data is automatically entered into an XML document. This XML document becomes the incoming message of the workflow Displaying Available Input Connectors You can display a list of the available (active and inactive) REST Input Connectors. Proceed as follows 1. Choose a REST Input Listener Connector and open it for editing. 2. In the Dialog Resource Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 286) in the Provided resources group, click the button next to the URL. 3. Choose the List all REST Input Connectors option. A dialog appears showing a list of all created Input Connectors. The list provides the name of the connector, the corresponding workflow, the path for the resource and the HTTP methods available for the connector. inubit 6.1: Workbench/Process Engine: System Connectors Guide

284 284 REST Connector Displaying Published Resources Additionally, you can display a list of all available REST services in the web browser: Displaying Published Resources You can display a list with all published and activated resources. Proceed as follows 1. Choose a REST Input Listener Connector and open it for editing. 2. In the Dialog Resource Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 286), in the Provided resources group, click the button next to the URL. 3. Choose the option Display published resources. In the browser, a page opens showing the formatted list with all activated resources. Resources implemented with a REST Input Listener Connector are only displayed as published and activated once the corresponding Technical Workflows have been activated Calling Resources Principle You can use the REST Connector to call a resource that is available via a certain URL. You can request, for example, an article list. To do so, you first have to create and configure a REST Output or Medium Connector for sending the request and receiving the response. Medium Connector Use the Medium Connector if the called resource returns a response that is to be processed further in the workflow. Output Connector Use the Output Connector if the request to a resource is a call without output inubit 6.1: Workbench/Process Engine: System Connectors Guide

285 REST Connector Calling Resources 285 Prerequisites The URL of the resource is available Authentication data is available if the server requires authentication for the resource Proceed as follows 1. Create a new REST Medium or Output Connector. 2. Enter the URL of the resource to be called. 3. Enter the required authentication data if necessary. Refer to Use authentication (Workbench/Process Engine: System Connectors Guide, chap. 27, p. 290). 4. Choose the required HTTP method depending on the type of request. Refer to Using HTTP Methods (Workbench/Process Engine: System Connectors Guide, chap. 27.3, p. 280). 5. If you have set PUT or POST as the method, choose the respective option from the list of media types and the character set. Refer to Request data (Workbench/Process Engine: System Connectors Guide, chap. 27, p. 291). You thus specify the definition of the data that is sent. The values of the request data are copied into the content type header. 6. You can optionally make adjustments in the request header, for example if you want to specify the desired representation of the requested resource for resources that support several representations. To do so, use the Accept header: a. Click the Edit header button. A dialog opens. By default, */* is used to query an arbitrary representation of a resource. b. Double-click the Accept header. Another dialog opens: inubit 6.1: Workbench/Process Engine: System Connectors Guide

286 286 REST Connector Dialog Descriptions c. Choose a media type. You can also choose several types and a sorted list of the desired representations is returned. d. Close the dialog for editing the HTTP header by choosing OK. 7. Click Finish. 8. Publish the REST Connector. To query a resource with GET you do not need an output message because the resource is only requested and no change is made to the data. To access a resource with POST or PUT, you need an output message. If you want to, for example, add data to an article list, you can use an XSLT Converter in the workflow before the REST Connector to create an XML message and send this, e.g. <article> <description>rooibos tea</description> <price>2.80</price> <unit>100g</unit> </article> All input messages into the REST Output/Medium Connector are sent with the request. You can dynamically adjust the URL of the resource by overwriting the module property Request.URI using variable mapping, refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351) Dialog Descriptions This section details the following topics: Dialog Resource Configuration, p. 286 Dialog Response configuration, p. 288 Dialog Request configuration, p Dialog Resource Configuration (Input Listener Connector) In this dialog, you specify the path of the resource offered by the connector, the authentication and the HTTP methods inubit 6.1: Workbench/Process Engine: System Connectors Guide

287 REST Connector Dialog Descriptions 287 Provided resource Use defaults for Choose which type of resource the connector is supposed to offer. The choice of resource type also defines the preselection of the HTTP method(s) supported by default. Refer to Supported HTTP methods (Workbench/Process Engine: System Connectors Guide, chap. 27, p. 288). - Single resource (read-only) Choose this option if you only want read access to a single resource, e.g. Display order. HTTP method GET is preselected automatically. - Collection resource Choose this option if the resource is to contain, for example, a list of orders ( /orders ) and this list is to be retrieved or new entries are to be added to the list. By default, only the GET and POST methods are allowed. - Member of a collection resource Choose this option if you, for example, want to offer an individual order from an order list or an article number as a resource. These methods are supported here: GET (retrieve data), PUT (change data) and DELETE (delete data). URL URL of the Input Listener at which the listener is waiting for requests and providing its resource. By default, the URL is constructed according to the following pattern: http(s)://[servername]:[port]/ibis/rest/rc/ [NameOfInputListener] If necessary, adjust the part of the URL after rc as desired. You can use curly brackets for dynamic path components, e.g. / users/{username}/orders/{orderno}. Enter * at the end of the path to support paths ending with characters of any type. Authentication required Select this option if authentication is supposed to be required for accessing the resource. Use static login data Define a scheme to be used here and the authentication data required for access. - Scheme - Basic: User name and password are required and transferred unencrypted. To be used only if the connection between client and server can be regarded as secure! inubit 6.1: Workbench/Process Engine: System Connectors Guide

288 288 REST Connector Dialog Descriptions Supported HTTP methods - Digest: Also requires user name and password. The password is transferred in encrypted form. Used for encrypting several parameters, including randomly generated values. - User name: User name for authentication - Password: Password for authentication Use portal user data This option is only available if a portal is installed. If this option is activated, access to the resource is possible only if valid portal user data is transferred. Basic is used as the authentication scheme. The portal user name used in a call is available in variable restconnector.requestauthuser during workflow execution. Refer to REST Connector Module Variables (Workbench/ Process Engine: System Connectors Guide, chap. 27.1, p. 276). Use authentication for accessing the Process Engine (password from the portal configuration): Using the internal user (inubitisportaluser@@@intern) This is where you specify that the connector responds only to certain HTTP operations. By defining the resource type you have already automatically preset the suitable HTTP methods for the respective resource type. GET (retrieve resource data) POST (create new resource) PUT (update resource) DELETE (delete resource) Refer to Using HTTP Methods (Workbench/Process Engine: System Connectors Guide, chap. 27.3, p. 280). Processing of received data Specify the encoding for data that is received as a request in format multipart/form-data Dialog Response configuration (Input Listener Connector) In the dialog for defining the resource you specify the settings for the previously select HTTP methods supported by your connector that are to be used for a response inubit 6.1: Workbench/Process Engine: System Connectors Guide

289 REST Connector Dialog Descriptions 289 Options for GET requests This is where you define the representation of the response data for GET requests. Useful default settings have already been chosen and can be left unchanged. Media type Choose the desired media type. For information about MIME types, refer to wiki/internet_media_type and mimetypen.htm. Character set Choose the character set of the response data. Options for POST and PUT requests Start workflow asynchronously Activate this option if the Input Listener is supposed to return the HTTP status message to the client directly after it receives the request. In this case, the response is sent before the workflow starts. The result of the workflow is not returned. If this option is not activated, the workflow starts synchronously and the response is only sent to the client once the last module of the workflow has been executed. Set response data Activate this option if you do not want to return response data for a request. If you are using POST, PUT or DELETE to manipulate a resource, a response does not necessarily have to be sent once an action has been executed. A response code suffices in this case. - Media type - Character set Refer to Options for GET requests (Workbench/Process Engine: System Connectors Guide, chap. 27, p. 289). Response status code Choose what is to be received as the response status code. If you want the response to show that an error occurred because of incorrect request data, you can set the variable restconnector.responsestatuscode for the response status code to HTTP status code 400 (for Bad Request ). General options Automatically encode response data Activate this option if the response data is to be encoded automatically using a method that is known to the server and supported by the client. Edit HTTP header inubit 6.1: Workbench/Process Engine: System Connectors Guide

290 290 REST Connector Dialog Descriptions The Edit HTTP header button opens the dialog for editing the header definition for available HTTP methods. Refer to HTTP headers (Workbench/Process Engine: System Connectors Guide, chap. 27, p. 291) Dialog Request configuration (Medium/Output Connector) In the dialog for configuring the resource to be requested, you define the URL to be called, the HTTP method and, if applicable, an authentication. Base configuration URL to be called Enter the URL of the resource to which the Connector sends its request, e.g. the address of an HTTP Input Listener. - SSL Used for configuring the server or client authentication and opens the Dialog SSL Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 24). Method Enter the desired HTTP method that is used to define the action that is used on the resource. Refer to Using HTTP Methods (Workbench/Process Engine: System Connectors Guide, chap. 27.3, p. 280). Use authentication Select this option if the server requires authentication. Enter the account that the connector is supposed to use for authentication. Scheme - Basic: User name and password are required and transferred unencrypted. To be used only if the connection between client and server can be regarded as secure! - Digest: Also requires user name and password. The password is transferred in encrypted form. Used for encrypting several parameters, including randomly generated values. User name: User name for authentication. Password: Password for authentication inubit 6.1: Workbench/Process Engine: System Connectors Guide

291 REST Connector Dialog Descriptions 291 Use authentication for accessing the Process Engine (password from the portal configuration): Using the internal user Request data (only for POST and PUT) This is where you define the desired representation of the request data. To do so, choose a media type and content type from the list and define a character set. HTTP headers The information in the request header informs the server, for example about the type and configuration of the client and the document formats that the client expects or supports. This is where you define, for example, in which representation you want to receive a list with requested orders. The Edit header button opens a dialog. In the dialog you can define the request header by double-clicking the individual rows of the header list. The permissible headers are defined in the HTTP specification, refer to Test You use the Test sending of request button to test whether the connection can be established successfully with the entries made. It opens a dialog in which the configured connection can be tested and a response is displayed with status code, HTTP header and data. inubit 6.1: Workbench/Process Engine: System Connectors Guide

292 292 REST Connector Dialog Descriptions inubit 6.1: Workbench/Process Engine: System Connectors Guide

293 28 RFID Connector 293 This section details the following topics: Principles of Operation, p. 293 Example for an XML Output Message, p. 294 Dialog RFID (IPort) Connector properties, p. 295 Use The RFID (Radio Frequency Identification) Connector is a system connector able to trigger a Technical Workflow as a result of events. In this case, the trigger event is always the arrival of a message sent by an iport device from IDENTEC SOLUTIONS. Refer to Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 28.1 Principles of Operation When a transponder signal is picked up by the antennas of an iport receiver device, the device sends a message to the RFID connector so triggering the execution of the workflow into which the connector is integrated. An i-port can be linked to up to four antennas which may be located in e.g. different rooms or on different floors of a building. In this situation each antenna can receive all transponder signals. The inubit Process Engine is linked to the i-port by TCP/IP over e.g. Ethernet; the RFID connector interrogates the i-port on port 7070 of the server and passes any signal it receives on to the downstream workflow. inubit 6.1: Workbench/Process Engine: System Connectors Guide

294 294 RFID Connector Example for an XML Output Message other i-ports coaxial cable Other antenna i-port Receiver server antenna 1 TCP / IP connection antenna 2 antenna 3 antenna 4 RFID Connector other RFID Connectors signal transponder 28.2 Example for an XML Output Message An output message may take e.g. the following form: <?xml version="1.0" encoding="utf-8"?> <Event> <Mask>27</Mask> <TagID>223741</TagID> <Detection>0</Detection> <FieldStrengths_0 antenna="0"> 65 </FieldStrengths_0> <FieldStrengths_1 antenna="1"> -128 </FieldStrengths_1> inubit 6.1: Workbench/Process Engine: System Connectors Guide

295 RFID Connector Dialog RFID (IPort) Connector properties 295 <FieldStrengths_2 antenna="2"> -128 </FieldStrengths_2> <FieldStrengths_3 antenna="3"> -128 </FieldStrengths_3> <Time>Wed Apr 07 15:27:36 CEST 2004</Time> <IPortID>2</IPortID> <maxantenna>1</maxantenna> </Event> Meaning of the XML elements The various XML elements have the following meanings: TagID: ID of the sending transponder. FieldStrengths: The field strength of the received signal. The field strength is indicated by values between -128 and 128 where -128 means no signal received. Time: Indicates the date and time the signal was received. IPortID: In the RFID connector configuration you specify, by means of the server name and port number, the iport from which the signal was received. In this case, the iport has the ID Dialog RFID (IPort) Connector properties This dialog offers the following options: Configuration Server name: IP number or server name of the i-port. Port: The standard port number is inubit 6.1: Workbench/Process Engine: System Connectors Guide

296 296 RFID Connector Dialog RFID (IPort) Connector properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

297 29 RosettaNet HTTPS Connector 297 This section details the following topics: Structure and Exchange of RosettaNet Messages, p. 298 Example Workflow: Generating RosettaNet Messages, p. 300 Example Workflow: Sending a RosettaNet Message, p. 302 Example Workflow: Receive Message and Send Acknowledgement, p. 304 Dialog Descriptions, p. 305 Use The RosettaNet standard serves as a basis for the exchange of data between companies operating world-wide with the focus on the area of supply chain management. Also refer to - RosettaNet Consortium: - B2Bi am Beispiel von RosettaNet [B2Bi using the example of RosettaNet] (a lecture delivered at the University of Hamburg: sam03_rn.pdf) Functional scope The RosettaNet connector supports the following functionality from the RosettaNet specification: RosettaNet Implementation Framework (RNIF) V2.0 RNIF describes the structure of the XML messages that are used, the procedures for packing and unpacking the messages, the protocols supported, security requirements and error handling. Receiving messages asynchronously over HTTP(S) Unpacking messages received, checking their syntax and converting them to the recipient's own XML format Archiving messages Creating a valid RosettaNet message from the PIP produced in the workflow. RosettaNet Partner Interface Processes (PIP) define the business processes between partners. Sending messages and receipts asynchronously over HTTP(S) Generation and control of the message IDs used in accordance with the RNIF Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) inubit 6.1: Workbench/Process Engine: System Connectors Guide

298 298 RosettaNet HTTPS Connector Structure and Exchange of RosettaNet Messages 29.1 Structure and Exchange of RosettaNet Messages Structure The following figure illustrates the structure of a RosettaNet business message: MIME multipart / related Preamble Header Delivery Header Header Service Header Service Content (Action / Signal Message) Attachment 1 Payload Attachment n RosettaNet Business-Message Header XML metadata with information about the message. Each message must contain all three header portions exactly once. The header has the following structure: - Preamble Header Version of the RNIF to which the message conforms. The current version is RNIF Delivery Header Identifies the sender and receiver and contains a date-and-time stamp. All elements involved in the transmission of a business message, i.e. the sender, the receiver and any intermediate stations, use this information for routing purposes. - Service Header Information on the PIP as ID, on the PIP instance as ID, and the business activity involved. Payload The actual content is referred to as the payload and is XMLencoded. - Service Content inubit 6.1: Workbench/Process Engine: System Connectors Guide

299 RosettaNet HTTPS Connector Structure and Exchange of RosettaNet Messages 299 States whether the message is an action message or a signal message. The process activity of an action message is defined in the PIP (refer to Service Header). signal messages are receipts or error messages. - Attachments If the message is an action message it can contain one or more attachments. All parts of a business message are compresses using the MIME/S- MIME message format. Receipts The reception of a RosettaNet message is signaled by a receipt or an error message. Receipts can be send synchronously or asynchronously. Transport protocols The HTTP, HTTPS or SMTP protocols may be used to transport the messages. Asynchronous exchange of messages The RosettaNet specification defines the asynchronous exchange of messages which proceeds as follows: 1. Business partner A sends business partner B a RosettaNet message. This message contains a so called PIP-ID which is used for identifying the message. 2. B stores a copy of message, as evidence that it was received 3. B returns an acknowledgement of its receipt to A. 4. Now, there are two options: - A receives the acknowledgement. - A does not receive an acknowledgement within an agreed period of time. In this case, A re-sends the business message: B receives message. B checks whether this message has already been received earlier, because it must be ensured that the message is only processed exactly. To this end, the PIP-ID of the incoming message is compared with all PIP-IDs of all messages already received. Attachment handling To use RosettaNet attachments with an output connector, the attachments must be described by three variables (X) numbered consecutively starting with 0. RNAttachment.X, type: base64binary contains the attachment data RNAttachmentContent-ID.X, type: xs:string inubit 6.1: Workbench/Process Engine: System Connectors Guide

300 300 RosettaNet HTTPS Connector Example Workflow: Generating RosettaNet Messages contains the attachment s unique identifier that you can generate using com.inubit.ibis.xsltext.misc. RNAttachmentContent-Type.X, type: xs:string MIME content type of the attachment, e.g. text/xml. You can write attachments into the file system using an input connector. Refer to Attachment handling (Workbench/Process Engine: System Connectors Guide, chap. 29, p. 308) 29.2 Example Workflow: Generating RosettaNet Messages The workflow shown generates a RosettaNet message and hands it over to another workflow via the Workflow Connector SendRosettaNetMessage. Refer to Example Workflow: Sending a RosettaNet Message (Workbench/Process Engine: System Connectors Guide, chap. 29.3, p. 302). The data for the RosettaNet message are imported from an ERP system and converted into the RosettaNet structure via some XSLT Converters: 1. The XSLT Converter Create PIP-specific Payload creates the PIP-specific message (payload). 2. The XSLT Converter Create Headers generates the headers. The figure below shows an example of a possible mapping: inubit 6.1: Workbench/Process Engine: System Connectors Guide

301 RosettaNet HTTPS Connector Example Workflow: Generating RosettaNet Messages 301 The timestamp is set using the Java method jhelper:getdatetime("yyyymmdd't'hhmmss.sss'z'"). The PIP ID that is stipulated for this message (in this case: 4A5) is assigned to the GlobalProcessIndicatorCode element. In this mapping, the payload is added in the last line by means of a simple copy. inubit 6.1: Workbench/Process Engine: System Connectors Guide

302 302 RosettaNet HTTPS Connector Example Workflow: Sending a RosettaNet Message 29.3 Example Workflow: Sending a RosettaNet Message The depicted workflow sends the RosettaNet message that was created in Example Workflow: Sending a RosettaNet Message (Workbench/Process Engine: System Connectors Guide, chap. 29.3, p. 302), and receives the acknowledgement. If the message was sent for the last time and still no acknowledgement has arrived, the error branch is accessed. Sending a message The Output Connector RN-Output receives the RosettaNet business message as input and processes it as follows: 1. The preamble header is added. It contains the RNIF version the message is based on. 2. The delivery header and the service header were already created by XSLT Converters. The RosettaNet Output Connector adds the missing information to these headers. The information is copied from the configuration data that was specified when the connector was created. In addition, the instance identifier is generated and added inubit 6.1: Workbench/Process Engine: System Connectors Guide

303 RosettaNet HTTPS Connector Example Workflow: Sending a RosettaNet Message The ID generated for each message is stored in the ListofGeneratedIds.xml index file in the working directory. The Output Connector then sends the message to the configured receiver and maintains the message in the workflow until the acknowledgement is received. Sending error s The RosettaNet Output Connector's error branch is accessed if the business message has already been sent once before and again no acknowledgement has been received for the message. A message is then sent via the mail connector module indicating that the attempt to send the business message failed. DistributeRNOutput Demultiplexer In addition, the message is passed to the demultiplexer, which transfers the message either to a dummy module or to the WaitUntilAcknowledge multiplexer. If the XPath /RosettaNetConnector/ AcknowledgeReceived is non-blank, the dummy module receives the input message. This means that the acknowledgement of the message has arrived at the output connector and no further action is required. If the XPath /RosettaNetConnector/Retry is blank, the WaitUntilAcknowledge multiplexer receives the input message. This means that the acknowledgement associated with this message has not yet been received. Splitter module The splitter module receives an acknowledgement passed on by the input connector workflow and passes it both to a mail connector and to the next demultiplexer. WaitUntilAcknowledge Multiplexer The multiplexer receives messages from the DistributeRNOutput demultiplexer located upstream in the workflow and the acknowledgement messages from the splitter module and evaluates them. To do this, it compares the instance ID and the PIP number of the two messages that have come in. If they are identical, a message is passed to the output connector; this acknowledges a message sent earlier. This means that this business message need no longer be held in the output connector. This completes the Send RosettaNet Message workflow. inubit 6.1: Workbench/Process Engine: System Connectors Guide

304 304 RosettaNet HTTPS Connector Example Workflow: Receive Message and Send Acknowledgement 29.4 Example Workflow: Receive Message and Send Acknowledgement The depicted workflow receives RosettaNet messages and routes them depending from their contents. Message receive time At the start of the workflow, the RosettaNet input connector RN Input is configured as a listener and waits for messages. When a business partner sends a business message, the connector does the following: stores the message in the specified working directory, checks whether the message was already sent using the /<PIP>/ *.msg files in the working directory (if yes, the connector creates an appropriate XML message). immediately sends a (synchronous) acknowledge, Receipts can be send asynchronously as well, for example, after the waiting backend system has received the RosettaNet message. To this end, in the Input Connector in the Dialog Asynchronous receipt (Workbench/Process Engine: System Connectors Guide, chap , p. 311), activate sending asynchronous receipts and add an Output Connector to the workflow Dialog Receipt (Workbench/Process Engine: System Connectors Guide, chap , p. 313) The Output Connector sends the receipts and therefore should be added to the workflow in a position at which the waiting backend system has already confirmed the receipt of the RosettaNet message. passes the message on to the demultiplexer module inubit 6.1: Workbench/Process Engine: System Connectors Guide

305 RosettaNet HTTPS Connector Dialog Descriptions 305 Conditional forwarding of message Depending on its content, the demultiplexer located after the RosettaNet input connector in the workflow forwards the XML message to one of the downstream modules: Process_PIP4A3 If the service header contains the code 4A3 in the RosettaNetXML/ServiceHeader/ProcessControl/ pipcode/globalprocessindicatorcode element, the message is passed on to the Workflow Connector Process_PIP_ 4A3 and thus to the underlying workflow which, for the e.g., passes the message to an ERP system. Deliver_Acknowledge If there is an XPath /RosettaNetConnector/ AcknowledgeReceived in the message, it must be an acknowledgement message which is then passed to the Deliver_ Acknowledge Workflow Connector and thus to a workflow that contains a RosettaNet output connector. This RosettaNet output connector evaluates the message to determine to which of the messages it has sent this acknowledgement belongs. The receipt of this message indicates that this message doesn't need to be resent. Dummy If the message contains the string /RosettaNetConnector/ MessageAllreadyProcessed the demultiplexer passes the message to the dummy module, in which no further processing is performed. The dummy could be replaced by another functionality such as, e.g. a mail connector that informs an administrator that a message that has already been sent has been received again. The important point here is that a message that has already been sent must not be passed on to the ERP system again for processing Dialog Descriptions This section details the following topics: Dialog RosettaNet Connector Properties, p. 306 Dialog Asynchronous receipt, p. 311 Dialog S/MIME Configuration, p. 312 Dialog Connection data for business messages, p. 312 Dialog Receipt, p. 313 Dialog S/MIME Configuration, p. 313 inubit 6.1: Workbench/Process Engine: System Connectors Guide

306 306 RosettaNet HTTPS Connector Dialog Descriptions Dialog Connection data for messages disposition notifications, p. 314 Dialog RosettaNet connection data, p. 315 All name and value elements in business messages are casesensitive. Where input for fields in the connector dialog is stipulated in the RosettaNet specifications, this must be copied over in the exact form in which it is written in the specification Dialog RosettaNet Connector Properties This section details the following topics: General tab, p. 307 NoF tab, p. 309 New PIP tab, p. 309 Add Clicking on New adds another tab New PIP for the new PIP. Refer to New PIP tab (Workbench/Process Engine: System Connectors Guide, chap , p. 309). Delete a. Display the tab which you want to delete. b. Click Delete. A message is displayed. After confirming the message the PIP is deleted. General tab Refer to General tab (Workbench/Process Engine: System Connectors Guide, chap , p. 307). NoF tab (Output Connector only) Refer to NoF tab (Workbench/Process Engine: System Connectors Guide, chap , p. 309). PIP tab (After clicking New ) Refer to New PIP tab (Workbench/Process Engine: System Connectors Guide, chap , p. 309) inubit 6.1: Workbench/Process Engine: System Connectors Guide

307 RosettaNet HTTPS Connector Dialog Descriptions General tab All the data that remains constant in business messages between two business partners is specified in this tab. Working directory Path Click the Choose button on the right-hand side. A dialog opens in which you can navigate to the directory in which all the received and generated messages are stored. This directory also stores the file containing all the instance identifiers that have been generated. An instance identifier is a string that uniquely identifies each message in the context of two business partners. The instance identifier is not globally unique; to achieve that the string would need to be created in a highly complex way. The same working directory must be specified for both the RosettaNet Input and Output Connectors. DTD configuration The selection of the DTDs determines the syntactical structure of the message header. The DTDs needed can be downloaded from the RosettaNet Consortium's web pages (ZIP file of the current RNIF V2.0). Preambel DTD: Preamble_MS_V02_00.dtd Delivery Header DTD: DeliveryHeader_MS_V02_00.dtd Service Header DTD: ServiceHeader_MS_V02_00.dtd Receipt Ack. DTD: AcknowledgmentOfReceipt_MS_V02_ 00.dtd Exception DTD: Exception_MS_V02_00.dtd NoF DTD: 0A1_MS_V02_00_FailureNotification.dtd To update a file which is already loaded, you must load a file with a different name. If you load a file with the same name, the existing file is not replaced! Identification Your DUNS: Enter your own DUNS number. A DUNS number uniquely identifies business partners. You obtain DUNS numbers from the Dun & Bradstreet Corporation on Business partner DUNS: Enter the DUNS number of your business partner. Location ID: The location ID is a user-definable alphanumeric string in any format. It can be used e.g. to identify a special inubit 6.1: Workbench/Process Engine: System Connectors Guide

308 308 RosettaNet HTTPS Connector Dialog Descriptions subsidiary of a business partner. The business partners agree the location ID between themselves. Clearing message archive Delete messages after (days) Defines, after how many days the IDs of the RosettaNet messages which are already received are deleted from the file system. The IDs are stored in an XML file. When sending a very large number of messages, this file can grow so large that the performance is affected. This is why IDs are deleted in regular intervals. Retry delay Retry delay The connector waits actively the given waiting time in seconds before it retries to send the message, default: 30 seconds. Always define the product of the retry delay and the retries (refer to Retries (Workbench/Process Engine: System Connectors Guide, chap. 29, p. 310)) to be considerably smaller than the connector s timeout ( System Connector Properties tab). Attachment handling Store attachments into file system (Input Connector only) When activated, attachments are stored into variables automatically after reception. For each attachment three variables are created; if there are several attachments, the variables are numbered consecutively starting by null (X): - RNAttachment.X Contents of the attachment, base64-encoded and zipped - RNAttachmentContent-Type.X MIME type of the attachment, e. g. application/xml - RNAttachmentContent-ID.X ID of the attachment; can be used for referencing the attachment in a RosettaNet document. Error handling (Input Connector only) Individual Activate this option, if you want to carry out error handling in the workflow yourself. If this option is selected, the workflow throws an error that can be treated individually. Signal (Exception) inubit 6.1: Workbench/Process Engine: System Connectors Guide

309 RosettaNet HTTPS Connector Dialog Descriptions 309 If this option is selected, the connector sends a RosettaNet signal message containing the relevant error. The workflow is executed successfully without throwing an error NoF tab (Output Connector only) For creating a Notification of Failure (NoF). A NoF is in fact a PIP0A1 and is sent in case of an error, e. g. if timeouts occur in the process of the data exchange or if messages cannot be processed. The field names are self-explanatory New PIP tab All Partner Interface Processes (PIPs) are specified by RosettaNet in order to guarantee that sender and receiver exchange standardized messages. A PIP consists of one of eight possible clusters, each cluster consists of one or more segments and each segment contains one or more PIP descriptions. For each PIP there is a specification and a DTD. There are PIPs that are defined for a request or for a response or for both functions. The structure of each action is described in a DTD or in an XML Schema. PIP definitions (including the DTD or XML Schemas) can be downloaded on the RosettaNet website. PIP settings PIP A PIP ID, as for example 3A2, consists of the following parts: - Single digit (0 7) specifying the cluster (3=Order Management) - Upper case alphabetic (A D) indicating the segment (A=Quote and Order Entry) - One or two digits (in the range 1 20) indicating the PIP (2=Request Price and Availability) PIP version For the purpose of checking the validity of the message, a simple comparison of the strings is performed on these fields. inubit 6.1: Workbench/Process Engine: System Connectors Guide

310 310 RosettaNet HTTPS Connector Dialog Descriptions Some business partners agree not to include the last four positions in long version or release designations. If one of the business partners uses a release or version number without the last four positions while the other includes the last four positions, the message would be deemed to be invalid. The underlying PIP version is to be found in the RosettaNet specification. DTD/Schema For loading the DTD or the XML Schema, which describes the action of the PIP. Additionally, define whether you load a DTD or an XML Schema. - Input connector: Choose the Request DTD/Schema for this field so that the incoming request can be checked for correctness with this DTD. - Output connector: The DTD/Schema is used for checking the correctness of outgoing messages. To update a file which is already loaded, you must load a file with a different name. If you load a file with the same name, the existing file is not replaced! Non-repudiation of receipt (Input Connector only) When activated, a check sum of the contents of the original message is created and returned together with the acknowledgement. Thus, the sender can verify that the original message has arrived at the recipient. Retries - Input connector: For each PIP, the number of retries is defined in table 3-3 of a PIP specification in section Retry Count. For a PIP 3A2 the number of retries is 3. - Output connector: The number of retries is specified for each PIP. The value is given in table 3-3 of a PIP specification, under Retry Count. For example, for PIP 3A2 the value 3 is indicated. Role name sender/ recipient (Output Connector only) The role names are set out in the specification for each PIP. They are normally to be found in table 3-1 of the PIP specification. E.g., for PIP 3A2 the role name of the sender is Customer and that of the receiver is Product Supplier. Service name sender/recipient (Output Connector only) inubit 6.1: Workbench/Process Engine: System Connectors Guide

311 RosettaNet HTTPS Connector Dialog Descriptions 311 The names are set out in the specification for each PIP. E.g., for PIP 3A2 the values can be found in table 4-1. Business activity (Output Connector only) The designations for business activities are specified by RosettaNet and laid down for each PIP. They are normally to be found in table 3-1 of the PIP specification. For example, for PIP 3A2, it is Request Price and Availability. Business action (Output Connector only) The designations for business actions are specified by RosettaNet and laid down for each PIP. They are normally to be found in table 4-2 of the PIP specification. For example, for PIP 3A2, depending on the action, it is either Price and Availability Request Action or Price and Availability Response Action. Message usage (Output Connector only) Inserts a reference to the message type into the message. In a message's service header there is an XML element <GlobalUsageCode>. Depending on your selection in this field, either Test or Production is inserted into this tag. RosettaNet does not specify how a business partner is to proceed with this element. If business partners evaluate the Test or Production string they can decide from the value found whether the message is to go into the production environment or into a test environment, if one is available Dialog Asynchronous receipt (Input Connector only) Sending receipt asynchronously Send asynchronously Activates sending asynchronous receipts. Refer to Example Workflow: Receive Message and Send Acknowledgement (Workbench/Process Engine: System Connectors Guide, chap. 29.4, p. 304). inubit 6.1: Workbench/Process Engine: System Connectors Guide

312 312 RosettaNet HTTPS Connector Dialog Descriptions Dialog S/MIME Configuration (Input Connector) In this dialog you enter the information required for decrypting and verifying encrypted and signed input messages. You need a keystore file containing your private key and your business partner s public key. Keystore Configuration Click the button to load your Keystore. S/MIME decryption For activating and deactivating encryption. Alias: For selecting the alias under which the private key is stored in the keystore. Password: Password for the selected key. S/MIME signature check For activating and deactivating the signature check. Alias: For selecting the alias under which the public key is stored in the keystore Dialog Connection data for business messages (Input Connector) Base configuration Server URL URL and port of the servlets which is waiting for RosettaNet messages. Authentication Authentication required Activate this option if the server requires a authentication. In this case enter the account which the connector should use. Login name: User name for authentication. Password: Password for authentication inubit 6.1: Workbench/Process Engine: System Connectors Guide

313 RosettaNet HTTPS Connector Dialog Descriptions 313 HTTP header configuration HTTP headers are used for transferring information like, for example file size, HTTP server and user agent or MIME type between client and HTTP server. The button Header listing opens a dialog for defining headers as name/value pairs. For information about headers refer to the HTTP specification Dialog Receipt An Output Connector for sending asynchronous receipts can be positioned anywhere in the same workflow receiving the RosettaNet messages. The output connector fetches the required data from a variable which was filled by the RosettaNet input listener at the beginning of the workflow. Refer to Example Workflow: Receive Message and Send Acknowledgement (Workbench/Process Engine: System Connectors Guide, chap. 29.4, p. 304). Sending the receipt Send receipt Activates sending asynchronous receipts Dialog S/MIME Configuration In this dialog you enter the information required for encrypting and the output messages. You need a keystore file containing your private key. Keystore configuration Click the button to load your keystore file. inubit 6.1: Workbench/Process Engine: System Connectors Guide

314 314 RosettaNet HTTPS Connector Dialog Descriptions S/MIME encryption For activating/deactivating encryption. Alias: For selecting the alias under which the private key used for encryption is stored in the keystore. Encryption algorithm: For selecting an encryption algorithm. Encrypt payload container/encrypt payload Refer to RNIF Core Specification, page 43. S/MIME signing For activating and deactivating signing. Alias For selecting the alias under which the private key used for signing is stored in the keystore. Password Password for the private key. MIC algorithm For selecting the Message Integrity Check algorithm. The algorithm is used to generate a check sum of the output message. Using the check sum the recipient can verify whether the output message arrived unmodified Dialog Connection data for messages disposition notifications (Input Connector only) Base configuration Server URL URL and port of the servlets which is waiting for RosettaNet messages. SSL The button opens the Dialog SSL Configuration (Workbench/ Process Engine: System Connectors Guide, chap , p. 24). Authentication Authentication required Activate this option if the server requires a authentication. In this case enter the account which the connector should use. Login name: User name for authentication. Password: Password for authentication inubit 6.1: Workbench/Process Engine: System Connectors Guide

315 RosettaNet HTTPS Connector Dialog Descriptions 315 HTTP header configuration HTTP headers are used for transferring information like, for example file size, HTTP server and user agent or MIME type between client and HTTP server. The button Header listing opens a dialog for defining headers as name/value pairs. For information about headers refer to the HTTP specification Connection test Test connection For testing whether the connection can be successfully established using your configuration Dialog RosettaNet connection data (Output Connector only) Base configuration Server URL Enter the URL of the servers the connector connects itself to. SSL For configuring server and client authentication. Opens the Dialog SSL Configuration (Workbench/Process Engine: System Connectors Guide, chap , p. 24). Authentication Authentication required Activate this option if the server requires a authentication. In this case enter the account which the connector should use. Login name: User name for authentication. Password: Password for authentication. HTTP header configuration HTTP headers are used for transferring information like, for example file size, HTTP server and user agent or MIME type between client and HTTP server. The button Header listing opens a dialog for defining headers as name/value pairs. inubit 6.1: Workbench/Process Engine: System Connectors Guide

316 316 RosettaNet HTTPS Connector Dialog Descriptions For information about headers refer to the HTTP specification inubit 6.1: Workbench/Process Engine: System Connectors Guide

317 30 SAP Connector 317 This section details the following topics: Installing the SAP Java Connector (JCo), p. 318 Principles of Operation, p. 319 Creating XML Request/Response, p. 320 Dialog SAP Connector Properties, p. 324 Use The SAP Connector connects to an SAP system and offers the following modes of communication with the SAP system: BAPIs/RFCs The SAP connector can call BAPIs and RFCs in the SAP system or can be called by BAPIs/RFCs. IDocs IDocs are ASCII documents in an XML format that contain additional status information. The SAP connector uses IDocs to exchange data with the SAP system. Prerequisites To enable the communication between the inubit Process Engine and the SAP system you must install the SAP Java Connector (JCo). Refer to Installing the SAP Java Connector (JCo) (Workbench/ Process Engine: System Connectors Guide, chap. 30.1, p. 318). The user which the SAP Connector uses to connect itself via JCo with the SAP system must be created and set up on the SAP system. The gateways used to connect to the SAP system are entered as network services in the /etc/services file (Linux) or in the C:\Windows\System32\drivers\etc\services file (Windows). Depending on the gateway, the following entries are added: - sapgw /tcp - sapgw /tcp Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) inubit 6.1: Workbench/Process Engine: System Connectors Guide

318 318 SAP Connector Installing the SAP Java Connector (JCo) 30.1 Installing the SAP Java Connector (JCo) Prerequisites For downloading the installation files you need a user name and a password for the SAP OSS or for SAPNet. The SAP installation instructions state that a JDK 1.3 or higher is required. A suitable JRE has already been installed during the inubit setup. Proceed as follows 1. In a browser, open the URL 2. Select SAP Java Connector > Download. 3. Download the following libraries and decompress them: - SAP IDOC Class Library, e. g. sapidoc3_3.0.4.zip Contains sapidoc3.jar. - SAP Java Connector (suitable for your operation system), e. g. sapjco3-ntintel zip Contains - sapjco3.jar - depending on your choice e. g. sapjco3.dll (Windows) or libsapjco3.so (Linux) 4. Upload both the *.jar files to the inubit Workbench. Refer to Installing Drivers (inubit Process Engine: Administrator and Developer Guide, chap. 3.4, p. 57). If you get an error message referring to the missing middleware layer, read the SAP note (which you find in the SAP Marketplace) and apply the solution suggested there. 5. Depending on your operating system, copy the *.dll/so files into one of the following directories): - Windows - When starting the inubit Process Engine via the Start menu: <inubit-installdir>\_jvm\jre\bin - When using the inubit Process Engine as a service under tomcat: <inubit-installdir>server\tomcat\bin - Linux 32-Bit <inubit-installdir>/_jvm/jre/bin - Linux 64-Bit <inubit-installdir>/_jvm/jre/lib/amd64 You must possibly add the directory to the environment variable PATH. 6. Restart the inubit Process Engine inubit 6.1: Workbench/Process Engine: System Connectors Guide

319 SAP Connector Principles of Operation Principles of Operation Type Mode Function Input Connector (Listener) Medium/Output Connector BAPI/RFC synchronous BAPI/RFC asynchronous IDoc BAPI/RFC IDoc The SAP connector is called by a function in the SAP system. The function is executed by the SAP connector and the downstream modules. After execution, the required values are returned to the calling function in the form of a BAPI-compliant XML response. The XML response is created using an XSLT converter module and its SAP Explorer. The SAP connector is called by a function in the SAP system. The function is executed by the SAP connector and the downstream modules; any return values generated are not returned to the SAP system. The SAP connector is called by the SAP system from which it receives an IDoc; the IDoc is processed by modules downstream in the workflow. The SAP connector calls a function on the SAP system. An XSLT convertor module and the SAP Explorer are used to create the XML request that is expected by the BAPI that is to be accessed by the SAP connector. The XML request contains the name of the function to be called as well as parameters and values. The XSLT converter passes the XML request to the connector which then calls the function on the SAP system. The function is then executed on the SAP system. The result is received back by the SAP connector, which passes it to the next module downstream. The SAP connector receives one or more IDocs as input. The SAP connector connects to the SAP system and transfers the IDocs. If the return message structure of a function has been modified in SAP, the SAP Explorer still displays the old structure. A restart is required to obtain the changes on inubit side. inubit 6.1: Workbench/Process Engine: System Connectors Guide

320 320 SAP Connector Creating XML Request/Response 30.3 Creating XML Request/Response If you are using the SAP connector in a BAPI/RFC or IDoc communication mode, you need a compliant XML response or an appropriate XML request. To create these, you use an XSLT Converter module and the SAP Explorer. First, create and publish the SAP Connector in order to make sure that its connection data to the SAP system are automatically imported. Otherwise you must enter the connection data manually. Proceed as follows 1. Create an XSLT converter module. 2. Open the module for editing in the local working directory. The XSLT Converter tab is displayed. 3. Click the button in the XML target file area. A menu opens. 4. Select Open from > SAP Explorer. A dialog opens and shows the connection data to the SAP system. In the Module drop-down list, select the SAP module with the appropriate connection data or enter these connection data manually. 5. Click Next. The next dialog is displayed. Select one of the options. 6. Click Next. The following dialogs depend on the type of template selected. - If RFC/BAPI is selected: inubit 6.1: Workbench/Process Engine: System Connectors Guide

321 SAP Connector Creating XML Request/Response 321 The dialog for Search and select helps you with the selection of the function for which you require a request or response. Enter the function name or the function group or parts thereof. You can use the asterisk (*) as a wildcard. Click Search to display a list of appropriate functions. If your search returns a result, mark the function that you want to use in the table. Then indicate which type of XML template is to be created: - Response: If you are using the SAP connector as a synchronous listener - Request: When used as a medium or output connector Click Next. Continue with step 7. - If IDoc is selected: inubit 6.1: Workbench/Process Engine: System Connectors Guide

322 322 SAP Connector Creating XML Request/Response The dialog for IDoc Search helps you with the selection of the message type for which the template is being created. Enter the name of the IDoc or parts thereof. You can use the asterisk (*) as a wildcard. Click Search to display a list of appropriate IDocs. If your search returns a result, mark the IDoc that you want to use in the table. Then indicate which type of XML template is to be created: Single IDoc or Multi IDoc. Click Finish. The dialog closes and the template is displayed in the XML target area. Continue with step If you have selected BAPI the following dialog opens: inubit 6.1: Workbench/Process Engine: System Connectors Guide

323 SAP Connector Creating XML Request/Response 323 Select the checkboxes for the parameters that are to be used as elements in the XML template. If a parameter is not to be used in the template, clear the checkbox for that parameter. Indicate whether the values from the columns are to be used as attributes in the XML template in addition to the functions/ parameters. Click Finish. The dialog closes and the template is displayed in the XML target area. 8. To further edit the XML template, drag the root node of the message onto the xsl:template element. When you have done this, the stylesheet looks as follows: inubit 6.1: Workbench/Process Engine: System Connectors Guide

324 324 SAP Connector Dialog SAP Connector Properties 9. To attach values to the parameters, enter the values on the lefthand side (XML Source). In doing this, observe the limitations defined for the attributes (type/length). Now you have created a stylesheet, which generates a conform XML response resp. an XML request Dialog SAP Connector Properties The dialog offers different controls depending on the connector type and communication mode selected: Communication mode BAPI/RFC For communication using BAPIs and RFCs. If you select this communication mode in combination with an input listener, you must additionally specify whether the communication is to be synchronous or asynchronous ( Mode option). IDoc For communication using IDocs. The SAP Connector processes XML IDoc. If you want to let EDI messages read, you first must convert them using an EDI-XML Adapter to XML. Analogously, you can convert the XML IDoc output messages of the SAP Connector to EDI by using an XML- EDI Adapter inubit 6.1: Workbench/Process Engine: System Connectors Guide

325 SAP Connector Dialog SAP Connector Properties 325 System information Host name Name of the computer on which your SAP system runs. System number (2-digit) system number. Encoding (only for the BAPI/RFC communication mode) Specify the character encoding for the data that is to be communicated. Login information As of version of the SAP connector, the login information (user name/password) is case-sensitive! Client (3-digit) Client number. User User name you use to access the SAP system. Password The password associated with the user name. Language The language in which the SAP system dialog is to be displayed. Enter as a 2-digit, upper-case alphabetic string; e.g. DE, EN or FR. This field is optional. Listener settings The gateway settings are needed as the SAP system communicates with the inubit Process Engine via a gateway rather than directly. Gateway host name Name of the gateway server. Gateway service number Since more than one gateway host may be present, they are numbered. Ask your SAP administrator for this number; it may, for example, take the form sapgw00. Program ID Before creating an input listener connector, an RFC destination must have been set up in the SAP system. This has a program ID, which must be entered here. Ask your SAP administrator for this program ID. If the inubit Process Engine cannot reach the gateway, it attempts to re-connect at 660 second intervals. This default interval can be changed in the SAP connector property table (RetryInterval property, defined in seconds). inubit 6.1: Workbench/Process Engine: System Connectors Guide

326 326 SAP Connector Dialog SAP Connector Properties Mode Synchronous/Asynchronous (only when used as an input listener and BAPI/RFC communication mode): Specify whether the return values are returned to SAP (synchronous) or not (asynchronous). Additional settings Transaction handling (only with BAPI/RFC as medium/output connector): - With transaction handling The SAP connector explicitly issues a Rollback or Commit. - Without transaction handling The SAP connector doesn't issue an explicit Rollback or Commit. Error handling: - Throw exception When an error occurs an exception is thrown and the execution of the workflow is aborted. - Write to output stream When an error occurs the error message is issued as an XML file and the execution of the workflow continues. The error message can be handled by a downstream module. Multi IDoc processing (only for the IDoc communication mode) Activate this option if more than one IDoc is to be processed during the execution of a workflow. Normally, a single IDoc is processed in a workflow. In that situation, a connection to the SAP system is established via the SAP connector, the message is sent and the connection is closed. If you want to process a very large number of IDocs in a short time, it makes sense to establish the connection to the SAP system and send all the messages in one go. The IDocs that are to be sent must be gathered into a single message (Multi IDoc) with the start of each IDoc being clearly indicated by an XML element. The SAP connector splits up the Multi IDoc at this element and sends the individual IDocs, one after the other, over the same connection. XML IDoc splitting element: Enter the XML element (incl. path) that indicates the start of an IDoc message. The split includes the splitting element: i. e. an XML structure /Root/ADRMAS02/IDOC and the splitting element /Root/ADRMAS02 becomes an IDoc with the structure /ADRMAS02/IDOC inubit 6.1: Workbench/Process Engine: System Connectors Guide

327 SAP Connector Dialog SAP Connector Properties 327 The figure shows elements in a Multi IDoc (left) and elements in an IDoc (right). Connection Pool (only when used as a medium/output connector, independent of communication mode) Max. number of connections Maximum number of connections in the connection pool. Take note of OSS notes and on setting up external connections in the SAP system and/or SAP gateway. Max. waiting time for connection Specifies the maximum time (in milliseconds) to wait for an available connection. If no connection is available after the specified time period has elapsed, a JCo exception is thrown with the key JCO_ERROR_RESSOURCE. The default is milliseconds (30 seconds). Connection timeout This timeout relates only to connections that are released in the connection pool and are kept open for re-use ( pooled connections ). It does not relate to connections that are currently in use. A pooled connection is closed if it has not been activated when the specified time period expires. The period is specified in milliseconds; default is milliseconds (10 minutes). Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

328 328 SAP Connector Dialog SAP Connector Properties Metadata cache Refresh For updating the meta data cache (including all BAPI and IDoc structures). Refreshing the meta data cache will affect all SAP-system connectors using the same gateway inubit 6.1: Workbench/Process Engine: System Connectors Guide

329 31 Secrypt Connector 329 This section details the following topics: Principles of Operation, p. 329 Example: Workflow with Secrypt Connector, p. 330 Module Variables, p. 332 Dialog Secrypt Connector Properties, p. 332 Use Use the Secrypt connector to add an electronic signature to a document verify electronic signatures on documents Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) Requirements You have access to a Secrypt signature and verifier server of your own. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 31.1 Principles of Operation Signing documents The Secrypt Connector copies the document to be signed into a defined input directory on the Secrypt digiseal server. The Secrypt digiseal server signs the document then moves it to a defined output directory. The result of the action (document signed successfully/not signed successfully) is written to a variable. inubit 6.1: Workbench/Process Engine: System Connectors Guide

330 330 Secrypt Connector Example: Workflow with Secrypt Connector Verifying signatures The Secrypt Connector copies the signed document into a defined input directory for the Secrypt verifier. The verifier checks the document and places the report (checked document, result and signature) in defined output and verification documentation directories. The result is written to a variable Each time it is executed, the Secrypt Connector deletes all files that it has created itself; these are available in the input, output and verification documentation directories. If the DigiSeal Server resp. the Secrypt Verifier does not run on the same computer as the inubit Process Engine, the Secrypt Connector must be implemented as a Remote Connector. Refer to Module Variables (Workbench/Process Engine: System Connectors Guide, chap. 31.3, p. 332) Example: Workflow with Secrypt Connector In the following workflow a PDF document is first signed and then verified. Proceed as follows 1. Create a workflow with two Secrypt connector modules. - For both connectors, enter PDF as document type. - For the first connector, choose the mode sign and specify both the input and output data configurations as binary. - For the second connector, choose the mode verification, the input data configuration is to be binary. The output data (verified document and test results) are output as XML per default. 2. Start the workflow. By double-clicking any watchpoint you can display the workflow results up to that point. The result: inubit 6.1: Workbench/Process Engine: System Connectors Guide

331 Secrypt Connector Example: Workflow with Secrypt Connector 331 Watchpoint 1: The input document is a PDF document without a signature. Watchpoint 2: The resulting document is a signed PDF document. To view the PDF document in a PDF viewer, click Save result file in the View file dialog and save the file as, for example, Test.pdf. In the PDF viewer, the signature is displayed in the Signatures tab. Watchpoint 3: After verification, the input document is embedded in an XML file (element InputDocument). The result of the verification is shown in the verification result tag and stored in the secrypt.result variable. inubit 6.1: Workbench/Process Engine: System Connectors Guide

332 332 Secrypt Connector Module Variables 31.3 Module Variables When executing a Secrypt module, the following module variables are set: Module variable secrypt.result secrypt.certificationlevel= {advanced,qualified} Value Verification result Signature type 31.4 Dialog Secrypt Connector Properties In this dialog you have the following options: Basic configuration Mode Select one of the two options to define the function of the Secrypt connector: - Sign: An electronic signature is added to the document. - Verify: The document's signature is verified. Signature server path configuration Input path The path to the directory in which the signature server expects to find the documents to be signed/verified, e.g. C:\IS_ Repository\Signatur\Verifier_Input. Output path The path to the directory in which the signature server makes the signed or verified documents available, e. g. C:\IS_ Repository\Signatur\Verifier_Output The paths must be identical to the paths that were specified when the digiseal server/verifier was configured. The input and output directories must be at the same level; one must not be a sub-directory of the other. It is not valid, for example, to specify a verifier output directory as.\verifier_input\verifier_output inubit 6.1: Workbench/Process Engine: System Connectors Guide

333 Secrypt Connector Dialog Secrypt Connector Properties 333 Verification documentation directories (Only displayed for mode verify ) The Secrypt verifier requires the following directories to document the verification of the signature and the result. Verified documents directory: If the document has been successfully verified, this directory will contain the verified document, the result of the verification and the certificate. Signature failure directory: If the signature failed the check, this directory will contain the document that was checked and the result of the check. System error directory: Contains the error message if errors occurred during the verification process. Document type Type Specify the data format in which the documents are passed on to the Secrypt connector to be signed or verified. If you choose p7s as document type in the verify mode, XML is automatically defined as the only possible format for the input data configuration. Thus, the connector expects an input message in XML format observing the following structure: <PKCS7> <Content> [ Content of ABC.txt, base64 encoded ] </Content> <Signature> [ Content of ABC.txt.p7s, base64 encoded ] </Signature> </PKCS7> Input data configuration To ensure proper processing you must specify the form that the input messages take: Binary data For reading in binary input documents such as, for example, PDF files. Base64 Select this option if the documents are base64-encoded having been, for example, extracted from XML. Signed MIME (Only for mode verify ) Select this option if the input data consists of signed MIME messages as defined in RFC XML For reading in input documents that are embedded in XML files. inubit 6.1: Workbench/Process Engine: System Connectors Guide

334 334 Secrypt Connector Dialog Secrypt Connector Properties Specify the XPath to the XML node that contains the document. Alternatively, you can use the Choose XML node button to navigate to this node in the XML document. Output data configuration (Displayed only when signing input documents) To ensure proper processing, you must specify how the signed documents are to be output: Binary data: Outputs the input document as binary. base64: Outputs the input document is base64-encoded. XML: Embeds the input document in an XML file. Server-side validation of directories Verify: Checks whether the specified paths and directories are present and read/writeable inubit 6.1: Workbench/Process Engine: System Connectors Guide

335 32 Security Token Service Connector 335 This section details the following topics: Principles of Operation of the STS Connector, p. 336 Registering Web services providers at an STS Connector, p. 338 Dialog Security Token Service (WS trust), p. 339 Use For many Web services it is important for the service provider to recognize the users of the services, e.g. to be able to bill usage or to prevent unauthorized access. In the WSDL file in the interface description of their Web service, service providers can thus specify that computers have to authenticate themselves towards the Web service. If a larger number of Web services is to be managed, it makes sense to externalize the authentication and to use a central authentication, a so called Security Token Service. An STS (Security Token Service) acts as a central security gateway for communication between service consumers and service providers in terms of message and transport security. Connector types An STS Connector is always used as an Input Listener Connector. It validates incoming authentication requests and returns tokens if the validation was successful. Standards The STS Connector implements the following standards: WS-Security Standard for message-level security. It defines how SOAP messages must be signed and encrypted and how security tokens are transferred. WS-Security: download.php/16790/wss-v1.1-spec-os- SOAPMessageSecurity.pdf WS-Trust Defines a specially-designed Web service, the SecurityTokenService, for outputting, exchanging and validating security tokens. WS-Trust: Also refer to - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) inubit 6.1: Workbench/Process Engine: System Connectors Guide

336 336 Security Token Service Connector Principles of Operation of the STS Connector - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 32.1 Principles of Operation of the STS Connector Securing the communication between service consumers and providers via an STS works as follows: 1. Service provider offers Web service and uses STS The service provider offers a service via a Web service. This Web service is secured via an STS. A Web service request is valid only, if it contains a valid token of the STS. Each time the provider receives a request from a consumer, it first checks the token s validity. Depending on the token type the provider checks the certificate s validity. 2. Service consumer requests using service To be able to call up the service the consumer needs the service s interface description, the so called WSDL file. This WSDL file can be requested directly from the service provider or from a directory service like UDDI. In the WSDL file the security requirements are described which the consumer must meet to be able to use the service. Amongst others, it is defined against which STS the consumer must authenticate itself. Now, that the consumer knows the STS address, it can call up the STS and authenticate itself against it inubit 6.1: Workbench/Process Engine: System Connectors Guide

337 Security Token Service Connector Principles of Operation of the STS Connector STS provider checks request of the service consumer The STS provider checks the consumer request on basis of the included characteristics. These may be username/password or the certificate, the request is signed with. If the check was successful, the STS generates two tokens: - For the first token the following applies: - It includes a session key with the information, whether the consumer has authenticated itself successfully. - The token is encrypted with the public key of the service provider. This guarantees that nobody except the service provider can read the session key. - The token is signed by the STS in order to assure that the STS has issued this token. - The second token is a test token, for which the following applies: - The test token also includes the session key. This is necessary so that the consumer can sign a Web service call. - The test token is encrypted by the public key of the consumer so that the consumer can seize the session key. The STS sends token and test token to the consumer. 4. Service consumer calls up service provider The consumer receives both tokens and extracts the session key from the test token. It creates the Web services call and signs the call using the session key. Then the consumer sends the call and the STS token to the service provider. 5. Service provider checks the signature of the token The service provider checks the token s signature with the public key of the STS to verify whether the tokens really originates from the STS. Then, the provider decrypts the token with its private key and thus obtains the session key and the information included within about the consumer s identity. On basis of the session keys the provider checks the Web service request s signature. At this point in time only the STS, the consumer and the service provider know the session key, thus the service provider can assume that it is really the consumer, for whom the STS has issued the token, who has signed the service request. Now the service provider only needs to check whether the STS has integrated the required certificates into the token. 6. Service provider sends service response or error message If the required certificates are integrated into the token, the service request is executed, the service response is encrypted, signed and send to the consumer. If the certificates are missing an error is returned. inubit 6.1: Workbench/Process Engine: System Connectors Guide

338 338 Security Token Service Connector Registering Web services providers at an STS Connector 32.2 Registering Web services providers at an STS Connector This section explains how to register any Web services providers at an STS Connector, in order to secure them. Prerequisites The Web services that are to be secured are available and their URL are known. The truststore containing the public key for each Web service provider that is to be secured is available. Proceed as follows 1. Create an STS Connector or open it for editing. 2. In the Dialog Security Token Service (WS trust) (Workbench/ Process Engine: System Connectors Guide, chap. 32.3, p. 339) in the Secured service providers area, click Add. The following dialog opens: 3. In the Provider endpoint URI field, enter the URL of the Web service provider. 4. Click Add truststore or certificate to add the certificate of the Web service provider with the public key. 5. Close the dialog with OK. 6. In the WSDL file, enter the alias of the added Web service s certificate. The illustration depicts the element that must be adapted: inubit 6.1: Workbench/Process Engine: System Connectors Guide

339 Security Token Service Connector Dialog Security Token Service (WS trust) 339 For each service Web service provider an individual tc:serviceprovider element is created. Pay special attention to the endpoint attribute in order to change the correct alias. 7. Click Finish to store the changes. 8. If your Web services provider was created in the inubit software you need to configure its communication with the STS. Refer to Securing Web Services Providers by a Security Token Service (Workbench/Process Engine: System Connectors Guide, chap. 40.7, p. 420) Dialog Security Token Service (WS trust) You use this dialog to configure the authentication possibilities for the Security Token Service and to add service providers. Service name Name used by the STS to offer its service. By default the name of the connector is used. You can change this value. inubit 6.1: Workbench/Process Engine: System Connectors Guide

340 340 Security Token Service Connector Dialog Security Token Service (WS trust) WSDL file WSDL file containing the interface description for the STS, the paths to the keystore of the STS and to the truststore of the secured service provides and the corresponding passwords and aliases. Transport security For selecting an encryption method: XML-Encryption The data contained in the transmitted message are encrypted with the XML Encryption standard. Refer to SSL The SSL protocol facilitates an encrypted data transmission connection. STS authentication For adding the keystore: Password Keystore password. Keystore/ Select file (button) For importing the keystore. After successful import the validity of the key is indicated. Consumer authentication X.509 Authentication by means of an X.509 certificate. The file containing the certificates can be imported by clicking the Truststore button. Username/password Authentication by means of a username/password validation which validates against a user administration. If you select both options, then both user administrations are checked. The validation is regarded as successful, if username/ password match to the values in one of the user administrations. - Internal user administration Authentication is only possible for consumers that are listed as inubit user. - Authentication by workflow Authentication of consumers is provided by the workflow against a backend system to validate, e.g., against an LDAP directory. You need to create the workflow yourself. If a workflow is defined, the last module of the workflows generates an output message containing a SAMLAssertion workflow variable. This variable contains authorization data. The data is transferred to the Web service provider and can be used for implementations based on authorizations inubit 6.1: Workbench/Process Engine: System Connectors Guide

341 Security Token Service Connector Dialog Security Token Service (WS trust) 341 Secured service providers Used for registering Web services. Provider endpoint URI Specifies the URL of the registered Web service. Public Key is valid until Specifies the validity of the public key that is stored in the X.509 certificate and which is added here when registering a service provider. Key information Lists all additional information contained in the certificate. inubit 6.1: Workbench/Process Engine: System Connectors Guide

342 342 Security Token Service Connector Dialog Security Token Service (WS trust) inubit 6.1: Workbench/Process Engine: System Connectors Guide

343 33 Selenium Connector 343 This section details the following topics: Principles of Operation, p. 344 Error Handling, p. 346 Dialog Selenium Connector Properties, p. 347 Use The Selenium connector connects the Selenium test framework with the test environment of the inubit software. The connector s function is to trigger from within Technical Workflows automated test cases and test suites of web applications created with a selenium framework. It can be used to test e.g. portal functions of the inubit Process Cockpit. User-specific extensions enabling the definition and storage of specific test commands in the user-extensions.js are not supported. Connector types A Selenium connector can be used as a medium or an output connector: Medium Connector Sends XML-based test data to the Selenium Remote Control Server and receives log data from the Selenium server, which are forwarded to the subsequent module in the workflow. Output Connector Sends XML-based test data to the Selenium Remote Control Server and receives log data from the Selenium server, which are passed on to a target application. Requirements The complete Selenium test framework must be installed. A Selenium Remote Control server must be installed. A Web browser must be installed. For further information about Selenium refer to the following links: - Selenium download: - Selenium Remote Control Server: 05_selenium_rc.html. - Selenium documentation: - Selenium reference detailing all test commands: release.seleniumhq.org/selenium-core/0.8.2/reference.html Also refer to - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) inubit 6.1: Workbench/Process Engine: System Connectors Guide

344 344 Selenium Connector Principles of Operation - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 33.1 Principles of Operation The Selenium connector connects to the Selenium Remote Control server to control a Web browser installed on a local or remote host. The server starts, stops the browser and acts as the HTTP proxy for the browser. Input message The Selenium connector requires an XML input message that can look like the example below: <?xml version="1.0" encoding="utf-8"?> <script> <base-url> <suite> <command> <action>setspeed</action> <target>500</target> <value /> </command> <command> inubit 6.1: Workbench/Process Engine: System Connectors Guide

345 Selenium Connector Principles of Operation 345 <action>open</action> <target>/</target> <value /> </command> <command> <action>type</action> <target>q</target> <value>inubit</value> </command> <command> <action>clickandwait</action> <target>btng</target> <value /> </command> </suite> </script> In the input message, you must define the base-url of the test application: this URL must be specified in order to indicate that all test commands apply to relative paths meaning that test cases can be run across different domains. To ensure a correct performance, both domains specified in the baseurl element and in the open-element must be the same. Refer to Error Handling (Workbench/Process Engine: System Connectors Guide, chap. 33.2, p. 346). You can find templates for input and output messages in the repository at Global > System > Mapping Templates > Selenium Connector. Processing The Selenium connector passes the input message to the Selenium server which executes the test commands and returns a compilation of test results to the connector. These log data are contained in the output message of the Selenium connector Output message Below you find an example for an XML output message: <result> <suite> <command display="setspeed(500)" duration="31">ok </command> <command display="open(/)" duration="813">ok </command> inubit 6.1: Workbench/Process Engine: System Connectors Guide

346 346 Selenium Connector Error Handling <command display="type(q)" duration="500">ok </command> <command display="clickandwait(btng)" duration="1062">ok </command> </suite> <lastlogs> <lastlog>![cdata[13:24: INFO [10] org.mortbay.util.container - Starts ]]> </lastlog> [ ] </lastlogs> </result> 33.2 Error Handling Error Cause Solution You appear to be changing domains from to Connection refused: connect If no base-url is specified, the inubit software uses a preselection of the RC server. Some browsers interpret the change from the preselection to the URL indicated in the open element as crosssite scripting and prevent further processing or provoke an error. The Remote Control server does not run or the indicated server-/port address is not correct. Specify a base-url in the base-url element of the input message, e.g. <base-url> </base-url> Then, the open element must be identical with the base-url to prevent the error from occurring again. Check the availability of the Selenium RC server by pressing the Connection Test button in the dialog. The server is running if the response is Connection test was executed successfully and if a Firefox instance opens on the host where the RC server is installed. For further information about the base-url problem and cross-site scripting, refer to and inubit 6.1: Workbench/Process Engine: System Connectors Guide

347 Selenium Connector Dialog Selenium Connector Properties Dialog Selenium Connector Properties You use the dialog for connection details to enter access data for the Selenium Remote Control server and to configure connection details. Selenium Remote Control Server Server IP address or name of the Selenium Remote Control server Port The Selenium Remote Control server uses port Browser Browser that you want to open, including *. For an overview of the different browsers supported by Selenium, refer to Timeout (ms) Execution time in milliseconds. After expiration of the specified time period the test is aborted. Default value: ms. If you enter no value in the input field, the connector automatically adopts the default value. A test suite requiring a very long time span to run is disrupted prematurely by the timeout limitation specified here. Capture screenshot in case of error If selected and an error occurs, a screenshot (base64-coded png file) is written as an error-screenshot element in the XML output message. If you insert e.g. a Decoder module as the subsequent module in the workflow, you can convert the base64-encoded screenshot file in a binary format and can, thus, forward it directly to a target application by using a File Output Connector. Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

348 348 Selenium Connector Dialog Selenium Connector Properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

349 34 SNMP Connector 349 This section details the following topics: Principles of Operation, p. 349 Example: Medium Connector, p. 351 Example: Input Connector, p. 353 Dialog SNMP Connector Properties, p. 353 Use Using the SNMP connector, network components such as servers, routers, switches or printers can be monitored and configured by a central SNMP server. When monitoring network components, error detection and error reporting are configurable. Connector types The functions of the SNMP connectors depend on the configuration: Input Connector Transmits static OID value pairs from a table. Medium Connector Transmits dynamic OID value pairs from the XML input message. Also refer to - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 34.1 Principles of Operation Many network components contain programs that enable SNMP communication to take place. These programs, known as agents and running directly on the monitored device, can transmit the state of the device and receive and apply data for configuring the network components. Communication An SNMP server is employed to monitor components in simple and complex IT networks. The agents running on the network components communicate with the server over SNMP. Communication over SNMP is based on the connectionless User Datagram Protocol (UDP) which simply adds the addressing data to the SNMP data packets and thus inubit 6.1: Workbench/Process Engine: System Connectors Guide

350 350 SNMP Connector Principles of Operation requires very little bandwidth. By default, the agents communicate through port 161 while the SNMP Manager communicates through port 162. The structure of the SNMP data packets is transparent when using the SNMP connector. To configure the connector, all you need to know is the connection data, the type of the data packet and the OID. Data packets Only four of the six different data packets that are defined in the standard are needed for the SNMP connector. The data packets are named after the methods that are executed with them. The SNMP connector supports the GET, GETNEXT, SET and TRAP operations. OID Each agent is aware of the value of the parameters of its network components. This can be used to either issue a status message (Trap) or to change the configuration. These parameters are known as managed objects. All managed objects are held in a tabular list (not in a database). This list is called the Management Information Base, abbreviated to MIB. An object identifier, abbreviated to OID, is assigned to each managed object in the MIB. The object identifier is a string composed of numbers and dots. The structure of this string follows a structure that is composed of the socalled MIB tree. For an illustration of the MIB tree, refer to SNMP. This numeric code also contains a portion that indicates the company. Bosch Software Innovations GmbH has been assigned the code for its inubit software. Thus, the start of the OID looks like this: in plain text: iso.org.dod.internet.private.enterprise.inubit. as an OID: The OID has only been standardized as far as the Private Enterprise Code. The composition of the remainder of the OID is not standardized. It is up to the system administrators to create an internal company system that covers all network components and assigns these numbers. A number must also be allocated to each of the managed objects associated with the devices. The values of the managed objects, i.e. of the events that can be monitored and configured by SNMP, are device-dependent and can only be found in the manufacturer s manual in each case OIDs as constants and variables The rules for constructing the OID string out of digits and dots are frequently not followed since the OIDs are only used within the company and thus there is no need for uniqueness compared to the IT environment of other companies inubit 6.1: Workbench/Process Engine: System Connectors Guide

351 SNMP Connector Example: Medium Connector 351 If a trap or a configuration instruction is to be sent, it normally consists of an OID and a value. Variable: Each OID can get only the values that are specified in the manufacturer s data for the network component. Constants: In some cases just an OID is transmitted, without a value. This is the case if a managed object can only communicate a state via an OID. Community SNMP offers the facility to transmit a so-called community string when communicating. Only components that belong to the same community react to traps or configuration commands. The community string is transmitted unencrypted Example: Medium Connector An ISDN connection is to be established in the workflow through an SNMP connector via a router. Subsequently, at the end of the workflow, a message is to be sent over this connection to an FTP connector. With the SNMP medium connector, tables of tuples consisting of the OID and a value cannot be specified. Instead, the relevant value pairs are expected in the XML input message. An OID can either contain: no value specification, in which case the OID itself is the instruction for the configuration, or an integer, in which case the configuration is dependent on the value of the number, or a value in the form of a text string. In an XML input message, these three different cases have the following format. The OIDs and values are examples. <Property name=" "/> <Property name=" " type="integer"> 2 </Property> <Property name=" "> UID_name </Property> inubit 6.1: Workbench/Process Engine: System Connectors Guide

352 352 SNMP Connector Example: Medium Connector The router is configured dynamically during the execution of the workflow. The required values are read from the input message, turned into an XML message by an XSLT converter and are then passed to the SNMP connector. The following figure shows the mapping in the XSLT converter. The abbreviations are explained as follows: PPP = Point-to-Point Protocol PAP = Password Authentication Protocol The following lines show the XML message that is passed to the SNMP medium connector as a result of the mapping: <?xml version="1.0" encoding="iso "?> <SNMPVarBinds version="4.0"> <Property name=" " type="integer">2</property> <Property name=" "/> <Property name=" "/> <Property name=" "/> </SNMPVarBinds> inubit 6.1: Workbench/Process Engine: System Connectors Guide

353 SNMP Connector Example: Input Connector Example: Input Connector This example relates to the medium connector example. If the router s ISDN connection always uses the same data, this connection can be configured right at the start of the workflow with a static OID table. To do this an SNMP input connector is configured as follows: 34.4 Dialog SNMP Connector Properties In this dialog you have the following options: Basic configuration SNMP version The configuration of the SNMP message depends on whether version 1 or 2c is selected. Ask your administrator which version of SNMP is used in your company network. Server name inubit 6.1: Workbench/Process Engine: System Connectors Guide

354 354 SNMP Connector Dialog SNMP Connector Properties Enter the server name here. Either a plain text name or an IP address can be entered. Port The default port is 161. If SNMP communication runs through a different port, ask your administrator for the port number. Click the Default button to reset the port number to the default value of 161. Community This is an editable combo box. The community string public is often used as a default. If another string is used, enter it here. Modern network components can belong to more than one community. Ask your administrator for the valid community string. Configuration of the variable binding Operation: Four different operations are available GET: requests a record. The record contains the data on the configuration of a network component. The SNMP connector returns the data that is specified for this event in the manual for the network component. GETNEXT: Continues requesting records until the end of a list of records is reached. This operation is used when the configuration of a network component extends over more than one record. SET: Sends a record to configure a network component. The network component responds with a record containing the result of the configuration. TRAP: Automatically triggered notification of an event occurring to a monitored component. For the purpose of variable binding, a table of pairs is built, each pair consisting of an OID and a value. This table is only available for the SNMP input connectors. Table Offers a context menu for adding and deleting OIDs. Ask your administrator for the OID and value for the desired action or get them from the manual for the particular network component. Trap configuration (For operation TRAP only) Sender IP IP address or name of the host which sends SNMP traps. Sender OID inubit 6.1: Workbench/Process Engine: System Connectors Guide

355 SNMP Connector Dialog SNMP Connector Properties 355 OID of the device which generates the trap. The OID defines the type of the SNMP device. Refer to OID (Workbench/Process Engine: System Connectors Guide, chap. 34, p. 350). Generic ID Generic TrapID. Select the relevant ID from the list of possible TrapIDs. If you use an enterprise-specific ID, enter this in the following field Specific ID. Specific ID Enter an enterprise-specific TrapID, if required. If necessary, ask your administrator for the OID and other Traprelated specifications. Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

356 356 SNMP Connector Dialog SNMP Connector Properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

357 35 Solution Center Connector 357 This section details the following topics: Functional Principle, p. 357 Module Properties, p. 358 Generating Object XML Data, p. 359 Using XPath Requests, p. 359 Example: Create Object, p. 361 Example: Query Object Data, p. 363 Example: Update Object Data, p. 366 Example: Delete Object, p. 368 SC Connector Settings Dialog, p. 370 Use With the Solution Center Connector you can read- and write-access business objects of a business solution laying in an Solution Center from technical workflows of the inubit software. Also, refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) Prerequisites You have successfully installed and configured the Solution Center. You have configured the connection of the inubit Workbench to the Solution Center Functional Principle 1. The Solution Center Connector read- or write-accesses the business object in your business solution in the Solution Center. - Changing, reading, and deleting: The business object is defined by means of the node ID or an XPath query. - Creating: The Solution Center Connector receives an input message in which the object to be created is defined. The father node under which the object is to be created, is defined by means of the node ID or an XPath query. inubit 6.1: Workbench/Process Engine: System Connectors Guide

358 358 Solution Center Connector Module Properties 2. The Solution Center Connector returns the data of the business object with the transferred node ID or XPath query from the business solution. The business object can be further processed in subsequent modules. You can overwrite module properties via mapping of variables to set the node ID from a previous object query dynamically, for example Module Properties The Solution Center Connector sets the following module properties: Name Request.Method NodeID XPath ContextNodeID createemptyobject returnoutput OutputDepth Explanation Mode of the connector. Possible values: GET: Query object data POST: Create object PUT: Update object data DELETE: Delete object ID of the node (or parent node when creating an object). XPath query to select the node (or parent node). This XPath query is executed on the object structure of the Solution Center. Usually, you enter a node ID here. In connection with the XPath parameter only. ID of a Solution Center node. The XPath query is executed relatively to this node. create new object (only when creating a new object) Returning node information. Via this switch, you suppress returning the object data changed when creating, updating, or deleting an object. Number of returned node levels inubit 6.1: Workbench/Process Engine: System Connectors Guide

359 Solution Center Connector Generating Object XML Data Generating Object XML Data When creating a Business Object Diagram (BOD), the inubit software automatically generates an XSD schema of the diagram and saves it in the SolutionCenter/BODSchemas/ repository folder of the user who created the BOD. You can use this schema to create an input message for creating or updating an object with an XSLT Converter Using XPath Requests Use Flexible access to data of a Business Solution or Process Solution in the Solution Center. Call up XPath request using the Solution Center Connector Set the parameters on the SC-Connector settings tab. - XPath Enter the XPath directly in the XPath field and select the desired node. The correct XPath is automatically entered in the XPath field. - Use context node/node ID You have the option to choose a context node. The node ID is entered automatically. The XPath request is executed from this node. XPath request using the module properties of the Solution Center Connector Configure the Solution Center Connector. Set the module properties XPath, returnoutput, and OutputDepth to overwrite certain values using variable mapping. Refer to Module Properties (Workbench/Process Engine: System Connectors Guide, chap. 35.2, p. 358). inubit 6.1: Workbench/Process Engine: System Connectors Guide

360 360 Solution Center Connector Using XPath Requests Your XPath requests use XPath 1.0 with the following restrictions/ recommendations: Try to avoid // and wildcards /* in requests. Use the context node information to speed up the request Aggregations, One and Two-sided Directed Associations You can use XPath requests to address not just aggregations (parentchild relationship) but also one and two-sided directed associations. In an aggregation, you navigate from the parent node to the child node. Example:../fpm:Fleet/fpm:Vehicle (all vehicles of the fleet) In a one-sided directed association, you navigate from the source node to the target node. Example:../fpm:Employee/fpm:IsDriverOf (employee is driver of vehicle) In a two-sided directed association, you can navigate from the source node to the target node as well as from the target node to the source node. Example:../fpm:Employee/fpm:IsHasDriver (employee is driver of vehicle)../fpm:vehicle/fpm:ishasdriver (vehicle has employee as driver) inubit 6.1: Workbench/Process Engine: System Connectors Guide

361 Solution Center Connector Example: Create Object Example: Create Object This section details the following topics: Generating an Object Using the Node ID, p. 361 Generating an Object Using an XPath Request, p. 361 Use Address the parent node and optionally return the new node content as an XML structure Generating an Object Using the Node ID Proceed as follows 1. In a Technical Workflow, create a Solution Center Connector and give it a name. 2. Go to the page SC Connector Settings. 3. Select the mode Create object. 4. Click the Select node button at the end of the Node field. 5. Specify the father node under which you want to create a new node. 6. In the field Empty object of type, enter the type of the new object or select it using the button Select XML element. The type of the specified father node must support child nodes of the specified type being created under the father node. Alternatively, you can already define the attributes of the object when creating it via an input message. 7. Set the start point before the Solution Center Connector. 8. Start the test without a file Generating an Object Using an XPath Request Proceed as follows 1. Use the XSD schema of your Business or Process Solution to create an XML structure, e.g. via an XSLT Converter. inubit 6.1: Workbench/Process Engine: System Connectors Guide

362 362 Solution Center Connector Example: Create Object XPath with context node 2. Create a Solution Center Connector. 3. Configure the general module properties and the system connector properties of the Solution Center connector. 4. Go to the SC-Connector Settings tab. 5. Choose the Create object mode. 6. Specify under which node the new object is supposed to be created. 7. Choose the Reference via XPath option. a. Activate the Use context node option. b. Click the icon at the end of the Context node ID row. c. In the Solution Center explorer, navigate to the parent node under which the new node is supposed to be created and confirm the selection by choosing OK. The context node type is automatically set depending on the context node. XPath without context node d. Now enter e.g. bfm3:initiator in the XPath field. Processing a request without a context node can take significantly longer than a request with context nodes, especially when large amounts of data are involved. a. Deactivate the Use context node option. b. Click the icon next to the XPath field and choose Select node inubit 6.1: Workbench/Process Engine: System Connectors Guide

363 Solution Center Connector Example: Query Object Data 363 c. In the Solution Center explorer, navigate to the parent node under which the new node is supposed to be created and confirm the selection by choosing OK. 8. Enter the desired value in the Number of node levels field. Refer to Number of node levels (Workbench/Process Engine: System Connectors Guide, chap. 35, p. 372) 9. Set the start point in front of the XSLT Converter and start the test without a file. 10. In the result file or in the Solution Center explorer, check whether the object has been created correctly Example: Query Object Data This section details the following topics: Retrieving Object Data Using the Node ID, p. 363 Retrieving Object Data Using an XPath Request, p. 364 Use Address a node, an attribute, or an association and return the node contents or the attribute as an XML structure or XML element with data type Retrieving Object Data Using the Node ID Proceed as follows 1. In a Technical Workflow, create a Solution Center Connector and give it a name. 2. Go to the page SC Connector Settings. inubit 6.1: Workbench/Process Engine: System Connectors Guide

364 364 Solution Center Connector Example: Query Object Data 3. Select the mode Query object data. 4. Click the Select node button at the end of the Node field. 5. In your business solution, navigate to the node that you want to read. 6. Click Finish. 7. Set the start point before the Solution Center Connector. 8. Start the test without a file Retrieving Object Data Using an XPath Request Proceed as follows 1. Create a Solution Center Connector. 2. Configure the general module properties and the system connector properties of the Solution Center connector. 3. Go to the SC-Connector Settings tab. 4. Choose the Query object data mode. 5. Click the icon next to the XPath field. 6. In the Solution Center explorer, navigate to the desired node and confirm the selection with OK inubit 6.1: Workbench/Process Engine: System Connectors Guide

365 Solution Center Connector Example: Query Object Data Click Finish. 8. Set the start point before the Solution Center Connector. 9. Start the test without a file. 10. Open the result file after the Solution Center Connector. The result file should look like this: inubit 6.1: Workbench/Process Engine: System Connectors Guide

366 366 Solution Center Connector Example: Update Object Data If you have created a Process Solution and created the classes in the Transaction data area of the process BOD, the class names do not appear directly as a tag but in the xsi:type attribute. This also applies to abstract classes Example: Update Object Data This section details the following topics: Updating Object Data Using the Node ID, p. 367 Updating Object Data Using an XPath Request, p. 367 Use Address a node and optionally return the changed node content as an XML structure With this operation, you can also use the XSD schema to create new objects underneath the addressed object and associations between these in one step inubit 6.1: Workbench/Process Engine: System Connectors Guide

367 Solution Center Connector Example: Update Object Data 367 Prerequisites You have determined the data of the node to be changed, e. g. using a Solution Center Connector. Refer to Example: Query Object Data (Workbench/Process Engine: System Connectors Guide, chap. 35.6, p. 363). You have saved the data as an XML structure Updating Object Data Using the Node ID Proceed as follows 1. In a Technical Workflow, create a Solution Center Connector and give it a name. 2. Go to the page SC Connector Settings. 3. Select the mode Update object data. 4. Click the Select node button at the end of the Node field. 5. In your business solution, navigate to the node that you want to update. 6. Click Finish. 7. Create a new mapping rule for the variable mapping. a. Select static value as the source. b. Open the saved data of the node query for the node to be changed as an XML structure. c. Edit the attributes to be changed. d. Select input message as the target and UTF-8 as the coding. e. Choose OK to save the changes. 8. Set the start point before the Solution Center Connector. 9. Start the test without a file Updating Object Data Using an XPath Request Proceed as follows 1. Use the XSD schema of your Business or Process Solution to create an XML structure with the attributes of the node you want to change, e.g. via an XSLT Converter. inubit 6.1: Workbench/Process Engine: System Connectors Guide

368 368 Solution Center Connector Example: Delete Object 2. Create a Solution Center Connector. 3. Configure the general module properties and the system connector properties of the Solution Center connector. 4. Go to the SC-Connector Settings tab. 5. Choose the Update object data mode. 6. Specify the node whose object data is supposed to be updated. Refer to step 7 in the Generating an Object Using an XPath Request (Workbench/Process Engine: System Connectors Guide, chap. 35, p. 361) section. Instead of the parent node, choose the node you want to edit. 7. Activate the Return object data option. 8. Enter the desired value in the Number of node levels field. See Number of node levels (Workbench/Process Engine: System Connectors Guide, chap. 35, p. 372) 9. Set the start point in front of the XSLT Converter and start the test without a file. 10. In the result file or in the Solution Center explorer, check whether the object data has been changed correctly Example: Delete Object This section details the following topics: Deleting an Object Using the Node ID, p. 369 Deleting an Object Using an XPath Request, p inubit 6.1: Workbench/Process Engine: System Connectors Guide

369 Solution Center Connector Example: Delete Object 369 Use Address and delete a node and optionally return the data of the parent node of the deleted object Deleting an Object Using the Node ID Proceed as follows 1. In a Technical Workflow, create a Solution Center Connector and give it a name. 2. Go to the page SC Connector Settings. 3. Select the mode Delete object. 4. Click the Select node button at the end of the Node field. 5. In your business solution, navigate to the node that you want to delete. 6. Click Finish. 7. Set the start point before the Solution Center Connector. 8. Start the test without a file Deleting an Object Using an XPath Request Proceed as follows 1. Create a Solution Center Connector. 2. Configure the general module properties and the system connector properties of the Solution Center connector. 3. Go to the SC-Connector Settings tab. 4. Choose the Delete object mode. 5. Click the icon next to the XPath field. 6. In the Solution Center explorer, navigate to the desired node and confirm the selection with OK. 7. Enter the desired value in the Number of node levels field. Refer to Number of node levels (Workbench/Process Engine: System Connectors Guide, chap. 35, p. 372) 8. Start the test without a file. 9. In the result file, check whether the data of the parent node was returned correctly and in the Solution Center explorer check whether the object was deleted correctly. inubit 6.1: Workbench/Process Engine: System Connectors Guide

370 370 Solution Center Connector SC Connector Settings Dialog 35.9 SC Connector Settings Dialog In this dialog, you configure the mode and the nodes that are to be queried, created, changed, or deleted. Mode Query object data To read a business object of a business solution. Create object To create a business object of a business solution. Update object data To update a business object of a business solution. Delete object To delete a business object of a business solution. Object node (For mode = Query object data, Update object data, Delete object) To determine the desired node. Two procedures are available: Reference by node ID To enter or select the node ID of the node in the business solution that you want to read, update, or delete. The node ID determined then appears in the Node field. Reference by XPath For performance reasons, you should use a context node from which the XPath search begins. - Use context node Activate this checkbox to be able to enter the context node ID. First, select the context node ID so that the context node type is set automatically. - Context node ID: ID of the node from which the XPath query begins. - Context node type: The type of the context node is determined automatically when you determine the context node ID. - XPath XPath expression that is used for the XML structure of your business solution. You can use workflow variables within the expression. With the XPath expression, you can reference a business object or an attribute of a business object of your business solution. If you have specified a context node, the XPath expression is executed relatively to the node specified inubit 6.1: Workbench/Process Engine: System Connectors Guide

371 Solution Center Connector SC Connector Settings Dialog 371 Generating XSD schemas makes it easier to create new nodes, change, or delete existing nodes and their attributes and associations. Refer to Using XPath Requests (Workbench/Process Engine: System Connectors Guide, chap. 35.4, p. 359). Object to be created area (For mode = Query Create object) In the Object to be created area, you specify how the object is to be created. Two procedures are available: From an input message Activate this checkbox if you want to create the new object using an XML structure transferred to the Solution Center Connector. Empty object of the type To specify the type of the new, empty object. Object parent node area (For mode = Create object) In the Parent node area, you specify the node under which you want to create the new object. Two procedures are available: Reference by node ID To enter or select the node ID of the parent node in the business solution under which you want to create the new object. The ID determined for the parent node then appears in the Parent node field. Reference by XPath For performance reasons, you should use a context node from which the XPath search begins. - Use context node Activate this checkbox to be able to enter the context node ID. First, select the context node ID so that the context node type is set automatically. - Context node ID: ID of the node from which the XPath query begins. - Context node type: The type of the context node is determined automatically when you determine the context node ID. - XPath With this XPath expression, you can reference the father node of a new business object. You can use workflow variables within the expression. inubit 6.1: Workbench/Process Engine: System Connectors Guide

372 372 Solution Center Connector SC Connector Settings Dialog If you have specified a context node, the XPath expression is executed relatively to the node specified. Generating XSD schemas makes it easier to create new nodes, change, or delete existing nodes and their attributes and associations. Refer to Using XPath Requests (Workbench/Process Engine: System Connectors Guide, chap. 35.4, p. 359). Return object data area Specify whether object data is supposed to be returned. In Retrieve object data mode, you cannot deactivate this option. Two options are available: Number of node levels Specify how many node levels are supposed to be returned underneath the created, updated, or deleted object. - 0: Return only the attributes br:id, br:association and xsi:type of the edited object. - 1: All attributes and properties of the edited object are returned n: All data of the edited object as well as specified levels underneath the edited object are returned. - -1: is automatically set if the Return complete structure option is selected. Return complete structure returns the complete XML structure of all objects inubit 6.1: Workbench/Process Engine: System Connectors Guide

373 36 Solution Center Logger 373 This section details the following topics: Functional Principle, p. 373 Creating Your Own Event Types, p. 374 Dialog SC Logger Settings, p. 374 Use Creating event objects at certain locations in a process solution. See also - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 36.1 Functional Principle Adding a Solution Center logger - During the deployment of a Solution Center process model BPD, a Solution Center logger is created for each start, intermediate, and end event when the workflow is generated. - You can insert a Solution Center logger into the workflow after any module. Configuring a Solution Center logger The attributes of the event object to be created can be configured using the module properties in the wizard or using variable mapping. Automatic creation of event objects - A Solution Center logger creates an event object during every run. - The event objects appear in the Solution Center directly beneath the process object of the process solution. inubit 6.1: Workbench/Process Engine: System Connectors Guide

374 374 Solution Center Logger Creating Your Own Event Types 36.2 Creating Your Own Event Types Proceed as follows 1. Open the associated BOD of your process solution for editing. 2. Open the Base schemas tab on the External elements docking window. 3. Drag one of the bfm3:businessevent or bfm3:milestone classes into the Transactional data frame. 4. Create other event classes. 5. Use a generalization to connect the new classes with the respective parent class ( bfm3:businessevent or bfm3:milestone ). 6. Publish the BOD. 7. Deploy the BOD in the Solution Center by clicking the icon. After deployment of the BOD, the new event types are available in the Solution Center logger. Refer to Event type (Workbench/Process Engine: System Connectors Guide, chap. 36, p. 374) Dialog SC Logger Settings You configure the Solution Center logger in this dialog. Target nodes Node ID Select a node under which the new event object is to be created. This node is generally an instance of bfm3:processbo. Set new status content Activate this option and enter the desired status message in the adjacent field in order to assign the status attribute of the node specified above. Event data Event type - bfm3:businessevent Creates an event object of the bfm3:businessevent class with the attributes Title, Description, Actor, and Action Date. - bfm3:milestone inubit 6.1: Workbench/Process Engine: System Connectors Guide

375 Solution Center Logger Dialog SC Logger Settings 375 Creates an event object of class bfm3:milestone derived from the bfm3:businessevent class with the additional attributes Position and Status. Refer to Event data mapping (Workbench/Process Engine: System Connectors Guide, chap., p. 375). You can create you own event types. Refer to Creating Your Own Event Types (Workbench/Process Engine: System Connectors Guide, chap. 36.2, p. 374). Event data mapping Title Designation of the event object, copied from the name of the event in the BPD Description Description of the event object Actor User who created the event object Action Date Date on which the event object was created Position (only for the event type bfm3:milestone ) Position number of a milestone Status (only for the event type bfm3:milestone ) Status of the milestone For self-defined event types, you can define other attributes and set them using the module properties in the wizard or using variable mapping. inubit 6.1: Workbench/Process Engine: System Connectors Guide

376 376 Solution Center Logger Dialog SC Logger Settings inubit 6.1: Workbench/Process Engine: System Connectors Guide

377 37 TCP/IP Connector 377 This section details the following topics: Connector types, p. 377 Processing IP Messages Using Start and Stop Bytes, p. 379 Dialog TCP/IP Connector Properties, p. 380 Use The TCP/IP Connector establishes a socket connection between the inubit software and other programs, in order to send or receive messages via the TCP/IP protocol. Because the TCP/IP Connector can be used universally you should use it with deep expert knowledge 37.1 Connector types A TCP/IP Connector can be used in the following configurations: Input Listener Connector The connector provides server functionality within a workflow and establishes a service on the given IP address and port that waits for a client messages. Once the module or workflow is activated, the socket will be opened. As soon as a message arrives the subsequent workflow modules are processed. - Start/stop sequence is configured: a. Searching for the message and analyzing start/stop bytes Refer to Processing IP Messages Using Start and Stop Bytes (Workbench/Process Engine: System Connectors Guide, chap. 37.2, p. 379). b. Removing the start/stop bytes if the (first) message is completely received. Using the start/stop byte sequence an arbitrary number of future messages can be received. Thus a sequential request response connection is enabled. c. For each message the workflow is executed once. d. At the end of the workflow, data are returned to the calling client. - Start/stop sequence is not configured: a. Message contains all incoming bytes. Closing the connection by the client marks the end of the message. inubit 6.1: Workbench/Process Engine: System Connectors Guide

378 378 TCP/IP Connector Connector types b. The message is passed to the subsequent workflow modules to be further processed. Deactivating the workflow will close the socket. Medium Connector Connector establishes a connection using the host name and port configured. - Start/stop sequence is configured: a. The connector sends the message of the previous module in the workflow with start/stop bytes to the host and port configured. Refer to Processing IP Messages Using Start and Stop Bytes (Workbench/Process Engine: System Connectors Guide, chap. 37.2, p. 379). b. Searching for the message in the host s response and analyzing start/stop bytes c. The start/stop bytes are removed from the incoming message. d. The pay load contained in the message is passed to the subsequent workflow modules and the execution of the workflow is continued. e. The socket is closed. - Start/stop sequence is not configured: a. The connector sends the message of the previous module in the workflow (client) to the host and port configured without start/stop bytes. b. The client closes the connection. c. The server sends the message without start/stop bytes and it also closes the connection. d. The client recognizes as end of the message if the server has closed the connection. e. The message is passed to the subsequent workflow modules and the execution of the workflow is continued. f. The socket is closed. Output Connector The connector establishes a connection to the host name and port configured. - Start/stop sequence is configured: a. The connector sends the message of the previous module in the workflow (client) with start/stop bytes to the host and port configured. Refer to Processing IP Messages Using Start and Stop Bytes (Workbench/Process Engine: System Connectors Guide, chap. 37.2, p. 379). b. The socket is closed. - Start/stop sequence is not configured: inubit 6.1: Workbench/Process Engine: System Connectors Guide

379 TCP/IP Connector Processing IP Messages Using Start and Stop Bytes 379 a. The connector sends the message of the previous module in the workflow (client) without start/stop bytes to the hots and port configured. b. The socket is closed. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 37.2 Processing IP Messages Using Start and Stop Bytes For generic use, the Connector can process IP messages marked uniquely using start and stop bytes. The following graphic depicts such a message structure: Start and stop bytes are not part of the message but part of the lower layer communication protocol. You can define any byte sequences. Check the Test start and stopbytes checkbox to configure the values in the configuration dialog of the connector. Refer to Test start and stop bytes (Workbench/Process Engine: System Connectors Guide, chap. 37, p. 381). Proceed as follows 1. Open the desired TCP/IP Connector for editing. 2. Open the TCP/IP Connector Properties dialog. 3. Check the Test start and stopbytes checkbox in the Configuration section. 4. Enter the byte sequence that indicates the beginning of the desired IP message, e.g. 0x0b as the HL7 start byte sequence. 5. Enter the byte sequence that indicates the end of the desired IP message, e.g. 0x1c0x0d as the HL7 end byte sequence. 6. Click Finish to close the dialog. inubit 6.1: Workbench/Process Engine: System Connectors Guide

380 380 TCP/IP Connector Dialog TCP/IP Connector Properties 7. Publish the connector to save the settings. Receive HL7 messages You can use the TCP/IP Connector to receive HL7 messages by checking the Test start and stopbytes checkbox. To process HL7 messages you can use an EDI Format Adapter as the subsequent module after the TCP/IP Connector in the workflow. Refer to EDI Adapter (Format Adapter) (Workbench/Process Engine: Modules Guide, chap. 7, p. 157). An HL7 message consists of a header (MSH) and data segments. Start and stop bytes delimit the HL7 bitstream that is necessary because the end of file does not necessarily mark the end of the message. To separate HL7 messages the following default start and stop bytes are used: Start: 0x0b Stop: 0x1c0x0d 37.3 Dialog TCP/IP Connector Properties This dialog offers the following options: Configuration Server name - Input Listener Connector: IP address of the network interface at which the TCP/ IP Connector should listen. - Medium/Output Connector: IP address of the inubit Process Engine to which the message should be sent. Port Number of the port over which the messages are to be exchanged; by default this is port Port numbers larger than must not be used. To revert to the default port setting, click the Default button. Ensure both that no other application accesses the specified port and that the port is not blocked by a firewall inubit 6.1: Workbench/Process Engine: System Connectors Guide

381 TCP/IP Connector Dialog TCP/IP Connector Properties 381 Test start and stop bytes Check this option to process IP messages using start and stop byte sequences. Refer to Processing IP Messages Using Start and Stop Bytes (Workbench/Process Engine: System Connectors Guide, chap. 37.2, p. 379). - Start byte sequence: Enter the byte sequence that marks the beginning of the IP message. - Stop byte sequence: Enter the byte sequence that marks the end of the IP message. Connection test Test connection For testing whether the connection can be successfully established using your configuration. inubit 6.1: Workbench/Process Engine: System Connectors Guide

382 382 TCP/IP Connector Dialog TCP/IP Connector Properties inubit 6.1: Workbench/Process Engine: System Connectors Guide

383 38 VFS Connector 383 This section details the following topics: Module Variables of the VFS Connector, p. 383 Dialog Descriptions, p. 384 Use A VFS (Virtual File System) Connector enables communication of the inubit Process Engine with local and remote file systems such as Windows Shared directories or the local repository. The connector supports the CIFS/Samba and the repository protocol. Connector types The following configuration options are available: Input connector Imports files from a virtual directory structure and forwards them to a workflow for processing. Output connector Writes the result of a workflow to a file in a virtual directory. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) 38.1 Module Variables of the VFS Connector When executing a VFS connector, module variables are set. Input Connector The following variables are available if a file is read and if DATA is selected as output format. ReadFileDate Last change date for the input file in the format yyyy-mm-dd't' HH:mm:ss. ReadFileName Name of the input file including the extension. ReadFileSize Size of the input file in bytes. inubit 6.1: Workbench/Process Engine: System Connectors Guide

384 384 VFS Connector Dialog Descriptions Output Connector The following variables are available if a file is written and if DATA is selected as input format. WriteFileDate Creation date of the output file in the format yyyy-mm-dd't' HH:mm:ss. WriteFileName Name of the output file. WriteFileDir Name of output directory WriteFileSize Size of output file For information about other variables and their use refer to Workflow Variables and Mappings (Workbench: User Guide, chap. 14, p. 351) Dialog Descriptions This section details the following topics: Dialog VFS Connector base configuration, p. 384 Dialog Input Connector Configuration, p. 386 Dialog Output configuration, p Dialog VFS Connector base configuration (Input and output connectors) In this dialog, you configure the basic settings of the VFS Connector. Protocol Protocol Possible values: - cifs (Common Internet File System) Protocol for remote access to file systems via networks. - repository To access the local inubit Repository. - ftp (File Transfer Protocol) inubit 6.1: Workbench/Process Engine: System Connectors Guide

385 VFS Connector Dialog Descriptions 385 Protocol to access files via IP networks. Authentication Type - If no authentication is required to access the server, select Anonymous. - If you have chosen the repository protocol, the With user/ group of the workflow type is also available. Then, the VFS Connector authenticates with the login data of the workflow. Login/Password If your server requires an authentication, enter the necessary login data here. Usually, server and client negotiate the desired type of password transfer. If required, you can manually disable the support of plain-text passwords for all cifs connections. To do this, you must create the additional Java System Property jcifs.smb.client.disableplaintextpasswords and assign the value true to it, refer to Java System Properties (inubit Process Engine: Administrator and Developer Guide, chap , p. 44). Note that if the server explicitly requires a plain-text password afterwards, an error message is thrown. Host configuration Host Host name or domain address of the server, e.g. xyz.inubit.com. Port - cifs: The default port number is ftp: The default port number is 21. Default - cifs: Restores the default port number 445, if required. - ftp: Restores the default port number 21, if required. Windows domain (cifs only) Name of the Windows domain if the server runs in a Windows domain. Connection mode (FTP only) - Active The client opens the configured port and informs the server of the port number and of its own IP address using the PORT command. - Passive The client sends a PASV command and the server opens the configured port and passes it to the client along with the IP address. - Default inubit 6.1: Workbench/Process Engine: System Connectors Guide

386 386 VFS Connector Dialog Descriptions The client uses the server settings. Transfer type Specify whether the files to be transferred contain binary or ASCII data. Select default in order that the client uses the server settings. Locale Server locale. The server locale defines the choice of the character set and date specification, amongst others. Encoding Specify the encoding of the control channel for the communication connection between the connector and the FTP server. The control channel is used to send commands, including file names, as character strings. In order to make sure that special characters (e.g. Umlauts) are correctly transmitted, defining the encoding is essential since it can differ from server to server Dialog Input Connector Configuration In this dialog, you configure the input messages of the connector. Directory Path Absolute path to the directory from which files are to be read. When accessing files from the repository, use the path that is indicated in the Details tab of the respective file. Refer to Details (Workbench: User Guide, chap , p. 482). You can use the following wildcards, e.g. to read out files from directories with changing names or from any directory depth. - * (one asterisk): for filtering directory names or parts thereof. You can also use several wildcards in one name. Examples: - /*/bar searches /foo/bar - /*oo/bar searches /foo/bar or also /goo/bar - /*o*/bar searches /foo/bar or also /goa/bar - ** (two asterisks): for filtering the directory name or parts thereof, for any deeply nested structures: /**/bar searches /foo/bar and /xyz/gfd/bar When using cifs the share name has to be prepended to the path. Delete empty directories inubit 6.1: Workbench/Process Engine: System Connectors Guide

387 VFS Connector Dialog Descriptions 387 When selected empty directories are deleted, if the path containes wildcards. File Name File name. Use wildcard If selected, you can use a wildcard (asterisk *). Use regular expression If selected, you can use Perl-compliant regular expressions to create character string patterns to select the files to be read. Refer to for an overview of Perl-compliant regular expressions or to Invert selection If selected, the pattern specified for the file name by using a wildcard or a regular expression is inverted. As a result, all files whose names do not correspond to the pattern are read. Delete files after reading: If selected, read files are deleted after they have been read. Max. number of executions per scheduled call You use this specification to define the maximum number of times the workflow is to be started per triggering event. The triggering event is the reaching of a particular time point (if the scheduler is activated). The workflow is then started as many times as necessary until either - there is no more data to be fetched/sent or - the number defined in "Maximum number of executions per call" has been reached By restricting the maximum number of executions, you control the system load on the server. In Test mode, this specification is ignored and the workflow is only started once. This option can only be used when the scheduler is active! Reading order If more than one file is transmitted, you can define if files are to be transmitted in a sorted way and if yes, in which order. Limits Max. number files Maximum number of files that can be read. Default value is 1. Max. total size inubit 6.1: Workbench/Process Engine: System Connectors Guide

388 388 VFS Connector Dialog Descriptions Cumulative maximum size up to which files are read during workflow execution. Default value is 10 MB. If selected, the VFS Connector goes on reading files until, by accumulation, the defined total size is reached. If DATA is selected as the output format, as a rule, only one file is read until the defined maximum size for this single file is reached. If the limits value has been set to less-than-or-equal 0, the restriction is unlimited. Module output configuration DATA The output message consists of data that are forwarded in unchanged form. XML Defines that the output message is forwarded in IBISDirectory XML format. You find the XML schemas in the inubit Repository under Global > System > mapping Templates > File Connector. ZIP The output message is compressed in a Zip file. For XML/Zip output: If you have configured wildcards in the directory name, the read data in the XML or Zip are output in a tree structure. Examples: The directory name is /foo/bar/*/blub. The subdirectories starting with /foo/bar are read out. The directory name is /foo/bar/xyz/blub. The directory /xyz/ blub is read out. XML configuration (Only if XML is selected as output format.) Inclusive directories: If selected, in addition to the files the output message contains the directories. Inclusive data: If selected, the entire file is read and its base64- encoded content is included in the XML output message. If not selected, only the file metadata are read, e.g. name, file size and date. Zip configuration (Only if ZIP is selected as output format.) Inclusive directories: If selected, in addition to the files the output message contains the directories. Encoding: Defines the encoding of file and Zip directory names inubit 6.1: Workbench/Process Engine: System Connectors Guide

389 VFS Connector Dialog Descriptions Dialog Output configuration (Output Connector) You use this dialog to configure the output of the connector. Input format DATA The input message consists of data that are forwarded in unchanged form. Select this option if the input message is e.g. in XML format. XML Defines that the input message is available in IBISDirectory XML format. ZIP The input files are compressed in a Zip file. Encoding (Only if ZIP is selected as input format) Encoding Defines the encoding of file and Zip directory names. Directory Path Absolute path to the directory that the VFS connector is to use when writing files. Must be based on the pattern /Root/AB_ TestGroup/AB_Testdata/. Create non-existent directories Creates all non-existent directories from the path specification. File (Only for DATA input format.) Name File name. Optional wildcard or regular expression. Overwrite existing file If selected, an existing file with the same name is overwritten. Append data to file If selected, each time the workflow is executed the file to be read is appended to an existing file, should one exist. This can be useful if you want to record cumulative log data in a file. This option cannot be used if wildcards are specified in the file name. Throw error, if file exists inubit 6.1: Workbench/Process Engine: System Connectors Guide

390 390 VFS Connector Dialog Descriptions If selected, an error item is displayed in the Queue Manager for the workflow containing this VFS Connector if a file with the same name exists. If an error output is configured, it runs. Otherwise, the execution of the module is terminated inubit 6.1: Workbench/Process Engine: System Connectors Guide

391 39 Web Application Connector 391 This section details the following topics: Module Variables of Web Application Connector, p. 392 Requesting Information from Portlet Instances, p. 392 Dialog Descriptions, p. 394 Use The Web Application Input Connector is used to make the functionality of the underlying Technical Workflow available as a portlet in a portal server. When configuring this connector, you specify various settings, such as the following: Deployment of the portlets: title, timeout Trace Level JavaScript functions and CSS classes, which are available in all the task generator forms downstream in the workflow. Portlet permissions High user numbers and high availability can be achieved by activating and configuring load balancing across a number of identical inubit Process Engines. Also refer to - Creating Modules (Workbench: User Guide, chap. 3.3, p. 117) - System Connectors (Workbench/Process Engine: System Connectors Guide, chap. 1, p. 19) - Technical Workflow Diagrams (Workbench: User Guide, chap. 12, p. 287) - Developing a Web Application in inubit Workbench (Tutorials, chap. 5, p. 81) inubit 6.1: Workbench/Process Engine: System Connectors Guide

392 392 Web Application Connector Module Variables of Web Application Connector 39.1 Module Variables of Web Application Connector The following module variables are set by the Web Application Connector: Name ISPortalUser ISWebAppTimeout ISWebAppName Description Login name of the currently logged in portal user. Timeout in seconds; is defined in the Dialog Web Application (Workbench/Process Engine: System Connectors Guide, chap , p. 394) in the option Timeout. Name of the Web Application Connector Refer to Defining module variables (Workbench: User Guide, chap , p. 354). In addition, a Web Application Connector gives information about portlet instances, refer to Requesting Information from Portlet Instances (Workbench/Process Engine: System Connectors Guide, chap. 39.2, p. 392) Requesting Information from Portlet Instances You can request any of the following information items from any portlet instance: ISSession ID Unique ID of the current session. ISPortletNamespace Unique ID of the used portlet class. ISUserName Name of the user who is specified in the inubit Workbench > Configuration > General Settings > Portal > Server configuration > Portal login option. ISPortletActionUrl Unique ID of the portlet instance inubit 6.1: Workbench/Process Engine: System Connectors Guide

393 Web Application Connector Requesting Information from Portlet Instances 393 The portlet instance is necessary e.g. to create a multi-client capable portlet which targets different systems according to the community which it belongs to. To do this, the Technical Workflow implementing the portlet must be informed about the context out of which the portlet instance is called. ISWebLanguage Language of the portlet instance ISPortalUser Login name of the currently logged in portal user. ISWebContextPath Current virtual path of the portlet. ISParameters List of URL parameters that are transferred to the portal The information is included in the input message of the Web Application Connectors and is output as XML structure. Prerequisites The Technical Workflow that implements the portlet has already been published, activated and deployed. Proceed as follows 1. In the inubit Workbench, display the Technical Workflow that implements the portlet. 2. Activate the watch mode. Refer to Using the Watch Mode (Workbench: User Guide, chap. 16.2, p. 408). 3. Add the portlet to the desired page and community. In the inubit Workbench, watchpoints are displayed. 4. To display the information about the portlet instance, open the watchpoint in front of or behind the Web Application Connector, e.g.: inubit 6.1: Workbench/Process Engine: System Connectors Guide

394 394 Web Application Connector Dialog Descriptions The information about the portlet instance is displayed Dialog Descriptions This section details the following topics: Dialog Web Application, p. 394 Dialog Internal Resources, p. 397 Dialog Permission Management, p Dialog Web Application In this dialog you have the following options: Miscellaneous settings Category Specifies the category in which the portlet is listed on the inubit Enterprise Portal. In the Liferay Portal, a list of portlet categories is presented when adding a portlet to a page inubit 6.1: Workbench/Process Engine: System Connectors Guide

395 Web Application Connector Dialog Descriptions 395 Default portlet title For setting the portlet title in the default languages, German and English. You can add further languages using the table's context menu. Timeout For defining the period after which inactive users must login to the portlet again. Extended settings Use JSR-168 CSS classes If this checkbox is selected, JSR 168-compliant class names are used for CSS classes of the portlet components. The portlet components automatically adapt to the theme that is currently selected in the inubit Enterprise Portal because JSR 168- compliant class names are used for displaying the themes. Portlet components are e.g. buttons, groups or input fields. Otherwise inubit's own internal CSS classes are used. Refer to index.html, paragraph "CSS Style Definitions. Include CSS If the option is selected, CSS classes of the inubit software are included dynamically (Layout.css and CustomLayout.css in the <inubit-installdir>/server/ibis_root/conf/ form/)directory. Otherwise you must include the CSS classes manually in the header of the displayed portal page. Bosch Software Innovations GmbH recommends selecting this option when using the inubit Process Engine with JBoss based on Liferay. Include JavaScript Similar to including CSS classes: If the option is selected, the provided JavaScript files of the inubit software are included dynamically (Script.js, GcScript.js and AjaxScript.js in the <inubit-installdir>/server/ibis_root/conf/ form/) directory). Otherwise you must include the JavaScript files manually in the header of the displayed portal page. Bosch Software Innovations GmbH recommends selecting the option when using the inubit Process Engine with JBoss based on Liferay Do not cache forms in portlet session Reduces memory use during the portlet s session. Trace level inubit 6.1: Workbench/Process Engine: System Connectors Guide

396 396 Web Application Connector Dialog Descriptions Specifies the depth of the logging. Portlets write their information to log files, which are managed in the <inubit-installdir>/ ibis_root/log directory. You can use the log files to investigate portlet errors and exceptional conditions, to test portlets and to resolve errors. Interportletcommunication ID Unique identifier for the portlet that you are configuring. The ID is needed to identify the portlet uniquely during communication between portlets. This ID is automatically assigned when creating a Web Application Connector but it can be manually overwritten. Interportletcommunication target Unique identifier for the portlet to which the source portlet's data is to be available (the source portlet is set in the Interportletcom. ID field above). Data from a portlet can either be made available to all portlets or just to a selected portlet on the same portal page. To make the data of all portlets available on the same portal page, enter no ID here. Parameter delimiter By default, parameter/value pairs in a URL are delimited by? and &, e.g. inubit.com/ search?parameter1=wert1&parameter2=wert2. When using other portal servers than Liferay as included in the inubit software, different characters may be needed. Load balancing Enables load balancing across more than one inubit Process Engine. The URL of the inubit Process Engines SOAP servlets must be specified. The URL of the SOAP servlets follows the pattern: <computername>:8000/ibis/servlet/ibissoapservlet and correspond to the URLs displayed in the inubit Workbench when logging in. The same Technical Workflow that the portlet calls must be present on each of the inubit Process Engines. Workflow execution is then assigned to the indicated computers on a round-robin basis. In this process, each new session is passed on to the next computer. Refer to - Activating and Configuring Server Traces (inubit Process Engine: Administrator and Developer Guide, chap , p. 22) for more information about logging levels. - Exchanging Data between Portlets: Inter-Portlet Communication (Workbench: User Guide, chap , p. 525) inubit 6.1: Workbench/Process Engine: System Connectors Guide

397 Web Application Connector Dialog Descriptions Dialog Internal Resources In this dialog you have the following options: Resource You can select one of the following options from the list: - LoginPage/ErrorPage Displays the provided default error and login page for web applications. You can edit and, if necessary, restore the default pages. The LoginPage is only useful if you do not use the inubit Enterprise Portal. When using the inubit Enterprise Portal, the login is provided by the portal. - CustomScript Displays a simple JavaScript editor for programming JavaScript functions. These JavaScript functions can be used in all Task Generator forms referring to the Web Application Connector in the Permissions Dialog (Workbench/Process Engine: Modules Guide, chap , p. 127). In the form mapping of the Task Generator for example, you add the onclick attribute to a button and enter the function name as value, including one or more parameters, if necessary. When clicking this button in the portal, the referenced function is executed. Refer to the documentation of the inubit JavaScript framework in <inubit-installdir>/documentation/ jsdoc/index.html, if you have installed the inubit documentation. Or simply call the documentation directly. - CustomLayout Shows a simple editor for defining CSS classes. The CSS classes can be used in all Task Generator forms referring to the Web Application Connector in the Permissions Dialog (Workbench/Process Engine: Modules Guide, chap , p. 127). For information about the format definition syntax for classes refer to Refer to Designing Forms with CSS (Workbench/Process Engine: Modules Guide, chap , p. 61) Dialog Permission Management In this dialog you define permissions. inubit 6.1: Workbench/Process Engine: System Connectors Guide

398 398 Web Application Connector Dialog Descriptions Permissions of this web application To create a permission, enter a character string in the input field, then click the Plus button. The permission is displayed in the upper area. To delete a permission, select the permission then click the Minus button. The permission is removed from the display area. The permissions are assigned to individual controls on forms (e.g. to buttons, drop-down lists or input fields). When the web application connector is deployed to the inubit Enterprise Portal these are transferred across and assigned to roles. This allows you to tightly control which roles are permitted to display and edit selected form elements. Refer to Displaying Form Elements Dependent upon User Rights (Web Applications only) (Workbench/Process Engine: Modules Guide, chap , p. 67) inubit 6.1: Workbench/Process Engine: System Connectors Guide

399 40 Web Services Connector 399 This section details the following topics: Web Services: Principles of Operation, p. 400 Module Variables of the Web Services Connector, p. 402 Setting and Reading HTTP Header Variables, p. 403 Providing a Web Service, p. 405 Calling a Web Service, p. 409 Asynchronous Web Services, p. 413 Securing Web Services Providers by a Security Token Service, p. 420 Creating Key Pairs for WS Security, p. 421 Creating Key Pairs for WS Trust, p. 423 Calling an STS-Secured Web Service Provider, p. 425 Creating Operations for a Web Service, p. 426 Overwriting PartnerLinks, p. 429 Publishing Web Services in a UDDI, p. 430 Listing Active Web Services, p. 430 Logging SOAP Messages, p. 431 Transferring Binary Data as Attachments with MTOM, p. 432 Dialog Descriptions, p. 437 Use The Web Services Connector is a central component of an SOA. The ways in which a Web Services Connector can be used depend on its configuration. Input Listener Connector Offers the functionality of a Technical Workflow externally as a Web Service. As input listener, the Web Services Connector is suitable for integrating legacy systems that typically do not have Web Service interfaces available. For that purpose, the legacy systems interface is transformed into a Web Service in the Technical Workflow and made available as a service by using an Input Listener. The input listener connector receives a request, starts the workflow, waits for the workflow result, and then sends the result and the HTTP status message 200 back. Refer to Providing a Web Service (Workbench/Process Engine: System Connectors Guide, chap. 40.4, p. 405). Medium Listener Connector Waits for the answer of a Web Service that was called asynchronously. inubit 6.1: Workbench/Process Engine: System Connectors Guide

400 400 Web Services Connector Web Services: Principles of Operation A medium listener connector is thus always positioned in a workflow after a medium connector calling an asynchronous Web Service. Refer to Calling an Asynchronous Web Service (Workbench/ Process Engine: System Connectors Guide, chap , p. 417). Medium/Output Connector The Connector sends a request to an external Web Service or to a Web Services Input Listener and waits for the response. As soon as the connector receives the response, it passes the response on to the subsequent module in its workflow and fills the variables ISHttpResponseCode (e. g. with value 200 if ok) and ISHttpResponseText. You can define the list of OK codes yourself before the Connector s execution by adding the element <Property name="ishttpstatuscodesok"> to the Properties tab of the module and enter all HTTP codes which must not cause an exception. Enter the HTTP codes as a comma-separated list Metro The inubit Web Services technology is based on the Axis Web Services server. Axis is an open-source product from the Apache Software Foundation and is supplied with the inubit software. Refer to Web Services: Principles of Operation Web services are applications using open and XML-based standards and transport protocols for exchanging data with clients. Providing and requesting Web Services Service providers provide descriptions of their Web Services as WSDL file. The WSDL file describes the operations, data and exchange protocols the Web Service offers. This information is machine readable inubit 6.1: Workbench/Process Engine: System Connectors Guide

401 Web Services Connector Web Services: Principles of Operation 401 Based on this WSDL file service consumers create a SOAP request in order to access one of the Web Service s operations. The Web Service processes the SOAP request and returns the result as SOAP response to the service consumer. Providing and requesting Web Services via UDDI Alternatively, Web Services can also be provided and requested via a service directory (UDDI): A service provider publishes the descriptions of its Web services as WSDL file in a UDDI: The WSD file describes the functions, data and exchange protocols that the service offers. These information are machine readable. The UDDI acts as service broker and permits service consumers to find Web services. The service consumer 1. searches the UDDI and selects the required service. 2. is then bound dynamically to the service provider. 3. generates on basis of the WSDL file a SOAP-formatted request in order to access the methods that the service offers. The Web service processes the SOAP request and returns the result as SOAP response to the service consumer. inubit 6.1: Workbench/Process Engine: System Connectors Guide

402 402 Web Services Connector Module Variables of the Web Services Connector 40.2 Module Variables of the Web Services Connector Web Services Input Listener Connector A Web Services Input Listener Connector sets the following module variables: Name httpheader.request.soapaction httpheader.request.remoteaddress WSServerNameAndPort Explanation Purpose of the request IP address of the caller URL or IP address and port used to call the service Web Services Output Connector A Web Services Output Connector sets the following module variable: Name ISHttpResponseCode Explanation HTTP response code Handle attachments and binary data A Web Services Connector sets or reads the following module variables if one of the following options is set: Enable MTOM attachments for the outgoing response message Extract binary data from the response message and set it as variable values Name WSAttachmentFileName.<number> WSAttachment.<number> WSAttachmentName.<number> Explanation File names of the particular attachments Number of the attachment Name of the attachment These variables are set for both the input connector and the output connector. The value of number starts with inubit 6.1: Workbench/Process Engine: System Connectors Guide

403 Web Services Connector Setting and Reading HTTP Header Variables 403 Web Services Input Connector A Web Services Input Connector sets the following module variables if the option Extract binary data from the response message and set it as variable values is activated: Name WSAttachmentNumber WSAttachmentContent-ID.<number> WSAttachmentContent-Type.<number> Explanation Total number of attachments Unique ID of the attachment Type of the attachment The value of number starts with 0. Refer to Defining module variables (Workbench: User Guide, chap , p. 354) Setting and Reading HTTP Header Variables This section details the following topics: Set HTTP Header Variable for a Web Service Call, p. 404 Read the HTTP Header after a Web Service Call, p. 404 Variable for HTTP Header of a Listeners Input Message, p. 405 Setting the HTTP Header for an Outgoing Response Message, p. 405 Use You can transfer additional header information, e.g. a session ID, to a calling web service via a variable. These addidtional header information are inserted into the HTTP request header and sent to the web service called. The HTTP response headers set in the response message are written to a variable. The incoming HTTP headers at a Web Service Listener Connector are written to a variable. To set your own HTTP headers in the response message created by the listener connector you can set a variable slated for them in the workflow. inubit 6.1: Workbench/Process Engine: System Connectors Guide

404 404 Web Services Connector Setting and Reading HTTP Header Variables Set HTTP Header Variable for a Web Service Call You can set HTTP header information via the following XML variables of the is:anyelement type. For the outgoing request, you define the WSCaller.requestHeaders variable and its contents is inserted to the HTTP headers. The variable is to be structured as follows. Variant 1: <RequestHeaders> <x-test>request header set at Web Service Connector</x-test> </RequestHeaders> Variant 2: <RequestHeaders> <Header name="x-test">request header set at Web Service Connector </Header> </RequestHeaders> The header information are taken form the child element of the root element RequestHeaders. The header name is taken from the name attribute (if available) or from the element name. The header value results from the element content Read the HTTP Header after a Web Service Call The HTTP header at a calling Web Services Medium/Output Connector is written as an XML structure to the WSCaller.responseHeaders varibale as follows: <ResponseHeaders> <Transfer-encoding>chunked</Transfer-encoding> <Content-type>text/xml;charset=utf-8</Content-type> <Server>Apache</Server> <Date>Mon, 16 Apr :07:11 GMT</Date> <Vary>Accept-Encoding</Vary> <X-test>Test</X-test> </ResponseHeaders> inubit 6.1: Workbench/Process Engine: System Connectors Guide

405 Web Services Connector Providing a Web Service Variable for HTTP Header of a Listeners Input Message The HTTP headers of an incoming web service call at a Web Service Listener are written as an XML structure to the WSListener.requestHeaders varibale as follows: <RequestHeaders> <Cache-control>no-cache</Cache-control> <Host>localhost:8000</Host> <Content-type>text/xml;charset=utf-8</Content-type> <Content-length>324</Content-length> <Connection>keep-alive</Connection> <Pragma>no-cache</Pragma> <Authorization>(removed)</Authorization> <X-test>Test</X-test> <User-agent>JAX-WS RI 2.2-hudson-752-</User-agent> <Accept>text/xml, multipart/related</accept> <Soapaction>"testOperation"</Soapaction> </RequestHeaders> Setting the HTTP Header for an Outgoing Response Message To set your own HTTP header for the Web-Services (Listener) response use the WSListener.responseHeaders variable. The structure corresponds to the one of the WSCaller.requestHeaders variable (root elelement ResponseHeaders ). Refer to Set HTTP Header Variable for a Web Service Call (Workbench/Process Engine: System Connectors Guide, chap , p. 404) Providing a Web Service Overview In the inubit software, a Web service provider is modeled by using a Web Services Input Listener Connector in a Technical Workflow. The Web Services Input Listener Connector offers the functionality of an underlying Technical Workflow externally as a Web service. inubit 6.1: Workbench/Process Engine: System Connectors Guide

406 406 Web Services Connector Providing a Web Service The following example illustrates the essential modules for a Web service provider (from left to right): 1. Web Services Listener Connector ProvideWebService The Web Services Input Listener Connector provides amongst others the operation SayHello and waits for SOAP requests from other Web services. As soon as a SOAP request arrives, it is passed on to the following module, the Demultiplexer, and the workflow is started. 2. Demultiplexer Demux (optional) With one SOAP request, exactly one operation of a Web service can be called, although the Web service offers several operations. You use a Demultiplexer to specify on basis of the XML element contained in the request which operation is to be executed. The Demultiplexer passes on the request into the appropriate branch of the workflow where the request is processed further. In the example above, the Empty modules DoSomething and DoSomethingElse are dummy modules representing additional processing modules. 3. XSLT Converter CreateResponse The processing result, the SOAP response, is passed on by the last module in the Technical Workflow in a Web service-compliant form to the requesting Web service. This SOAP response is generated by using an XSLT Converter. Proceed as follows 4. Configure a Web Services Input Listener Connector a. Create a Technical Workflow. b. Add a Web Services Input Listener Connector. During properties configuration, specify that the definition of the called Web service is stored with the module. Refer to Dialog Provided Web Service (Workbench/ Process Engine: System Connectors Guide, chap , p. 437). c. Open the context menu of the connector and select Edit to display the Web Service Editor inubit 6.1: Workbench/Process Engine: System Connectors Guide

407 Web Services Connector Providing a Web Service 407 d. Click Add Operation. The following dialog opens: mmp e. Assign a name to the operation, e.g. SayHello. f. In the Style field, select Request/Response. This specifies that your Web service returns a SOAP response to the requesting Web service, instead of only processing the request. g. Click OK to close the dialog. After closing the dialog, your specifications are converted into the WSDL of your Web service which defines e.g. the structures of the SOAP Request and Response. You can display the WSDL in the WSDL editor tab and the SOAP Requests/Responses in the SOAP messages tab. h. Publish the connector. 5. Create SOAP Response a. Create an XSLT Converter, add it to the Technical Workflow and connect it to the Web Services Input Listener Connector. b. Open the XSLT Converter for editing. The result of the workflow execution must be structured in a WSDL-compliant form as a SOAP Response before it can be passed back to the requesting Web service. c. In this example, no processing took place, therefore you only create an output mapping. To do this, click in the XML target file area and select Open from > Web Services Explorer. A dialog opens. d. In the Module field, select your Web Services Input Listener and in the Operation field, select SayHello [Response]: inubit 6.1: Workbench/Process Engine: System Connectors Guide

408 408 Web Services Connector Providing a Web Service e. Click Finish. The structure of the SOAP message is displayed. f. Drag the root element of the generated SOAP message in the upper XML target area on to the xsl:template element and adapt the value of the sayhelloresponse element: p inubit 6.1: Workbench/Process Engine: System Connectors Guide

409 Web Services Connector Calling a Web Service 409 g. Publish the XSLT Converter. 6. Testing Create a second Web service that calls your just newly created Web service. Refer to Calling a Web Service (Workbench/Process Engine: System Connectors Guide, chap. 40.5, p. 409). 7. Publish the Technical Workflow. You can make the created Web service available to other users by means of a UDDI registry. Refer to Publishing Web Services in a UDDI (Workbench/Process Engine: System Connectors Guide, chap , p. 430) Calling a Web Service Overview The example shows the two most relevant modules for calling a Web service: XSLT Converter for creating the Web service request Web Services Medium or Output Connector for sending the request and for receiving the result (if there is any): - A Medium Connector can be used if the Web service returns a result that is to be processed further in the workflow. The Medium Connector sends the request, waits for the result and hands it over to the subsequent module in the workflow. In this way, the result be written, for example, into a database or processed for other systems. - Using an Output Connector makes sense, if the request calls up a one-way operation without any return value and no further processing is required. Technically, an Output Connector reacts in the same way as a Medium Connector, which means that the Output Connector also waits for a result and keeps it. inubit 6.1: Workbench/Process Engine: System Connectors Guide

410 410 Web Services Connector Calling a Web Service Proceed as follows 1. Configuring the Web Services Connector a. Create a Web Services Output Connector. When configuring it, define that the definition of the Web service that is to be called is stored directly at the module. Refer to Dialog Invoked Web Service (Workbench/Process Engine: System Connectors Guide, chap , p. 439). b. In the Web Services Editor specify where to load from the WSDL of the invoked Web service and load the WSDL. For testing you may use the Web service which is described in section Providing a Web Service (Workbench/Process Engine: System Connectors Guide, chap. 40.4, p. 405). If this Web service exists and is published, do the following: In the Invoked Service Tab (Workbench/Process Engine: System Connectors Guide, chap , p. 440) at the right end of the row click the button and select Show published services. A list of all Web services is displayed in the Web browser. Click the link [NameofYourWebService]. The WSDL is displayed. Copy its URL into the clipboard and insert it in the Invoked Service tab into the URL field. c. Publish the connector. d. Create a Technical Workflow and insert the Web Services Output Connector. 2. Creating the SOAP request a. Create an XSLT Converter. When configuring it, select the option Ignore input message. b. Add the XSLT Converter to the Technical Workflow. c. Open the XSLT Converter for editing. d. In the XML target file area, click and select Open from > Web Services Explorer. The following dialog opens up: inubit 6.1: Workbench/Process Engine: System Connectors Guide

411 Web Services Connector Calling a Web Service 411 e. Select the Web Services Connector and the operation which you want to call (relating to Request ). Click Finish to close the dialog. The structure of the SOAP requests, which the Web Service expects, is displayed. f. Drag the root element of the SOAP messages up onto the xsl:template element. g. Adjust the values in the XML source area, for example: inubit 6.1: Workbench/Process Engine: System Connectors Guide

412 412 Web Services Connector Calling a Web Service h. Publish the XSLT Converter. 3. Testing a. In the Technical Workflow define a start point at the XSLT Converter. b. From the context menu select Start test without file. After the test is finished open the watchpoint behind the Web Services Connector to display the result, the SOAP response. To create dynamic Web service calls, add other modules before the XSLT Converter, which, for example, read the Web services parameter from a database and hand them over to the XSLT Converter. The, in the XSLT Converter map these parameters onto parts of the SOAP message inubit 6.1: Workbench/Process Engine: System Connectors Guide

413 Web Services Connector Asynchronous Web Services 413 Setting (session) cookies If the web service response contains a set cookie header, its contents are written in the XML variable WSCallerCookies using the following structure: <Cookies> <Cookie uri=" name="vmware_soap_session" domain=" " path="/" version="0">678e5bdc-52fc-4e38-b af6fa</cookie> </Cookies> uri URL called (without path) name name of the cookies domain domain name the cookie is valid for path path/path prefix the cookie is valid for ports comma-separated port list (not set by default) version - 0 using the Netscape syntax - 1 using the syntax based on RFC 2965/2109 (default) The following web services calls read the WSCallerCookies variable. For web service calls, the corresponding cookies are set automatically. The cookies' domain/path must match exactly the web services called. If you have implemented workflows with several consecutive web service calls, and these calls need session cookies, you have to ensure that the WSCallerCookies variable is passed to the next module Asynchronous Web Services This section details the following topics: Offering an Asynchronous Web Service, p. 415 Calling an Asynchronous Web Service, p. 417 inubit 6.1: Workbench/Process Engine: System Connectors Guide

414 414 Web Services Connector Asynchronous Web Services Use In an asynchronous Web Service, the sending of the request message and the receipt of the response message are uncoupled. The two messages are sent using separate HTTP connections. Thus the processing of the request can take longer without the connection being terminated due to a timeout. Asynchronous Web Services are therefore suitable in particular for long-running services. The communication process for an asynchronous service call is outlined below. In this example, both communication partners are implemented using Technical Workflows. Of course, this does not have to be the case in real life. Functional principle A workflow that requests an asynchronous Web Service is processed up to a callback listener. The workflow of the called Web Service generates the response in the meantime. A Reply module at the end of the called workflow sends the response to the calling workflow. The callback listener in the calling workflow receives the response and continues the workflow. Prerequisites To call an asynchronous Web Service with any Web Service client, the client must support WS addressing and use a non-anonymous reply address (wsa:replyto) inubit 6.1: Workbench/Process Engine: System Connectors Guide

415 Web Services Connector Asynchronous Web Services 415 An asynchronous Web Service that expects a non-anonymous reply address (wsa:replyto) must be called using a medium Web Service Connector Offering an Asynchronous Web Service A workflow that is supposed to offer an asynchronous Web Service must consist of the following modules at minimum: Asynchronous Web Service listener XSLT Converter for creating the response Reply module for sending the response to the callback listener Creating an asynchronous Web Service listener This listener receives the requests, processes them and forwards them to the next module in the workflow. 1. In a new workflow, create a new Web Services Connector, give it a name and click Next to get to the System Connector properties tab. 2. On the System Connector properties tab, choose the entry Receive Web Service requests (provide a Web Service) as the Usage. 3. Choose Active as the Connector status and click Next to go to the Provided Web Service tab. 4. Choose a WSDL binding or New, the type and the new binding style. If necessary, adjust the namespace and the settings for the binding. 5. Click Next to get to the Module Editor tab. 6. If appropriate, go to the Provided Web Service tab and click the Add operation button. 7. Name the operation (e.g. SayHello ) and choose the type Request/Response as appropriate. 8. Click OK. 9. On the Extended tab, activate the Support asynchronous response transmission checkbox. Saving a SOAP message 1. Go to the SOAP message tab. 2. When configuring the asynchronous Web Service listener, choose the defined operation (e.g. SayHello ) and the input message generated for that purpose. 3. Click Show to load the message in the editor. 4. Save the SOAP input message as a file in your file system. inubit 6.1: Workbench/Process Engine: System Connectors Guide

416 416 Web Services Connector Asynchronous Web Services 5. Click Finish. 6. Publish the module. Configuring the XSLT Converter for creating the response This XSLT Converter uses the output message of the Web Service to generate a response message and transfers it to the Reply module. 1. Create a new XSLT Converter and give it a name. Click Next twice to get to the Module Editor. You do not have to make any adjustments on the XSLT Converter Properties tab. 2. In the XML target file window section, open a Web Services Explorer. 3. As the module, choose the Web Services listener defined above and choose the response operation as the operation. 4. Drag the root element of the generated message from the targetnamespace area (in the schema view) onto the xsl:template element in the XML Target area. 5. In the XML source area (top left), enter the text of the response message. 6. Publish the module. 7. Connect the Web Service listener to the XSLT Converter you just created. Configuring the Reply module for sending the response The Reply Module sends the response message generated by the XSLT Converter to the Web Service caller/client. If you have implemented the Web Service caller using a Technical Workflow, then this is the callback listener of the calling workflow. As an alternative to a Reply module, you can configure a medium/ output Web Services Connector so that it sends the asynchronous response of a Web Service to a callback listener. For more information, refer to Invoked Service Tab (Workbench/Process Engine: System Connectors Guide, chap , p. 440). Proceed as follows 1. Create a new Reply module and give it a name. 2. Leave all default values unchanged. 3. Click Finish. 4. Publish the module. Connect the XSLT Converter to the Reply module. Once you have configured and connected all three modules, publish the workflow. Next, create a workflow to call an asynchronous web service inubit 6.1: Workbench/Process Engine: System Connectors Guide

417 Web Services Connector Asynchronous Web Services Calling an Asynchronous Web Service A workflow that is supposed to request an asynchronous Web Service must consist of the following modules at minimum: Module for creating the call, e.g. an XSLT Converter or variable mapping Asynchronous Web Service medium connector for sending the call Web Services callback listener for asynchronous receiving of the response sent by the called Web Services. You can insert any modules you wish between the calling Web Services Connector and the Web Services callback listener. You must create the modules of the calling and the called Web Service in two different workflows. Configuring the XSLT Converter for creating a request This XSLT Converter generates requests for a Web Service. Proceed as follows 1. In a new workflow, create a new XSLT Converter and give it a name. 2. Click Next to get to the XSLT Converter Properties tab. 3. Activate the Ignore input message checkbox. 4. Click Next to get to the module editor. 5. In the XML target file window section, open a Web Services Explorer. 6. As the module, choose the Web Services Listener defined above and choose the request operation as the operation. 7. Drag the root element of the imported message from the targetnamespace area (in the schema view) onto the xsl:template element in the XML Target area at top right. 8. In the line with the XML target element wsc:<name of your operation> in the XML Source area (top left), enter the text of the request message. 9. Publish the module. Creating an asynchronous Web Service medium connector This Web Service medium connector sends the calls generated by the XSLT Converter you just created to a Web Service. Proceed as follows 1. Create a new Web Services Connector, give it a name and click Next to get to the next tab. 2. On the System Connector Properties tab, choose the Invoke Web Service entry as the Usage. inubit 6.1: Workbench/Process Engine: System Connectors Guide

418 418 Web Services Connector Asynchronous Web Services 3. Choose Active as the Connector status and click Next twice to get to the Module Editor tab. 4. In the WSDL data area, enter the URL for the service to be called for WSDL. a. On the Invoked service tab on the right end of the line, click and choose Show published services. In the Web browser, a list of all Web Services opens. b. Click the link with the name of the required Web Service. The WSDL is displayed. c. Copy the URL to the clipboard. d. In the Invoked service tab, enter the URL in the URL field. e. Click the Load WSDL file button. The Receive response asynchronously/send separate reply address checkbox is activated automatically. The Reply URL (wsa:replyto) field is automatically set to the correct value. The policies in WSDL are decisive for that. 5. Click Finish. 6. Publish the module. 7. Connect the request XSLT Converter to the Web Services medium Connector. Creating additional modules While the Web Service processes the request and generates the response, the calling workflow continues. The workflow stops immediately before the callback listener. 1. Create several modules according to your requirements. 2. Connect the modules and to the calling Web Services Connector. Creating a callback listener connector This Web Services medium listener Connector waits for the response from the Web Service. The workflow stops immediately before this connector and is continued only once the response has arrived. If the response is already available before the workflow reaches the callback listener, it is saved to the clipboard inubit 6.1: Workbench/Process Engine: System Connectors Guide

419 Web Services Connector Asynchronous Web Services Create a new Web Services Connector, give it a name and click Next to get to the next tab. 2. On the System Connector Properties tab, choose the Receive asynchronous response messages (callbacks) entry as the Usage. The Medium connector (middle of workflow) option and the Wait for data input (Listener connector) checkbox are activated automatically. 3. Click Next to get to the Provided Web Service tab. 4. In the Callback Listener-specific settings area, in the Import WSDL from related caller module line, click. 5. Choose the calling Web Services Connector that you created at the start of this workflow. You cannot change the other information on the Provided Web Service tab because it is preset automatically. 6. Click Next to display the Module Editor tab. 7. Show the Extended tab. 8. In the Callback Listener-specific settings area, activate the Listener receives response messages (instead of request messages) checkbox if it has not already been activated automatically. 9. Click Finish. 10. Open the Web Service Settings dialog using the context menu of the Web Services Connector in the workflow designer. 11. In the Mode are, activate the Receive asynchronous callback and resume workflow option. 12. Now connect the last of the additional modules configured further up with the Callback Listener Connector you just created. Once you have configured and connected all modules, publish the workflow. inubit 6.1: Workbench/Process Engine: System Connectors Guide

420 420 Web Services Connector Securing Web Services Providers by a Security Token Service 40.7 Securing Web Services Providers by a Security Token Service This section explains how you secure a Web services provider by a Security Token Service (STS). Prerequisites The Web service provider that is to be secured was generated using the inubit software. Its URL is known. The following data is available: - A keystore with the private key of the Web service to be secured, - a truststore with the public key of the STS. Proceed as follows 1. Open the Web Services Connector for editing. 2. In the Extended tab in the W3C Standards area, activate the WS-Security option and click the Settings button. The WS-Security configuration dialog opens. 3. In the Service authentication area, enter the keystore password and import the keystore. 4. In the Consumer authentication area, under Security mechanism, choose the Security Token Service issued Token with service certificate (STS) option. 5. In the Consumer authentication area, in the STS address field, enter the URL of the STS that is supposed to secure your Web service. 6. Specify how the communication of your Web service provider with the STS is supposed to be secured: Choose X.509 and import the truststore containing the public key of the STS. The result looks like this: 7. Click Finish. 8. Publish and activate the module as well as the relevant workflow, if it exists. As the result of this configuration, the WSDL security policies of the Web service provider describe how and on which STS consumers have to authenticate. If this has not happened yet, you have to register your Web service provider with the STS. For notes on registering at an inubit-internal STS refer to Registering Web services providers at an STS Connector (Workbench/Process Engine: System Connectors Guide, chap. 32.2, p. 338) inubit 6.1: Workbench/Process Engine: System Connectors Guide

421 Web Services Connector Creating Key Pairs for WS Security Creating Key Pairs for WS Security This section details the following topics: Creating a Self-Signed Key Pair, p. 421 Creating an Externally Signed Key Pair, p. 422 Use Securing a Web service provider without a Security Token Service Refer to Creating Key Pairs for WS Trust (Workbench/Process Engine: System Connectors Guide, chap. 40.9, p. 423). Authenticating a client with a Web service provider without a Security Token Service Authentication is performed once per session via a self- or externally-signed key pair directly in the Web service Creating a Self-Signed Key Pair Proceed as follows 1. Generate a key pair with the extension SubjectKeyIdentifier. Set the options according to your requirements: openssl req -x509 -days 365 -nodes -newkey rsa:2048 -subj "/C=myCountry/ ST=myState/L=myCity/O=myOrganization/OU=myDepartment/CN=myServerName" -keyout selfsigned.key -out selfsigned.crt -extensions v3_ca 2. Convert the key pair generated in step 1 into the PKCS12 format in order to enable import into the Java keystore. You must assign a password. openssl pkcs12 -export -in selfsigned.crt -inkey selfsigned.key -out selfsigned.p Import the PKCS12 file into the Java keystore. keytool -importkeystore -srckeystore selfsigned.p12 -srcstoretype pkcs12 -srcalias 1 -srcstorepass inubit -destkeystore selfsigned.keystore.jks -destalias tomcat -deststorepass <yourpassword> keytool.html inubit 6.1: Workbench/Process Engine: System Connectors Guide

422 422 Web Services Connector Creating Key Pairs for WS Security 4. Generate a JKS truststore with the service certificate. Enter the password assigned in step 2 as the password. keytool -importcert -keystore selfsigned.truststore.jks -file selfsigned.crt -alias tomcat -storepass <yourpassword> keytool.html Creating an Externally Signed Key Pair Proceed as follows 1. Generate a keystore with an automatically generated certificate. Set the options according to your requirements: keytool -genkey -keyalg RSA -dname "CN=myServerName, O=myCompany IS, C=de" -validity 999 -keystore private.keystore -keypass <yourpassword> -storepass <yourpassword> -alias tomcat keytool.html 2. Export the certification request using the private key. keytool -certreq -v -alias tomcat -keystore private.keystore -storepass <yourpassword> -file server_request.csr 3. Transmit the certification request to one of the certificate authorities (CA), e.g. D-Trust. The certificate authority returns a signed certificate for the Web service (in this case CAcert.cer) and your own public key (in this case public.cer). 4. List all information on the service certificate. 509v3 and SubjectKeyIdentifier must be displayed. keytool -printcert -v -file public.cer 5. Import the CA certificate to the private keystore. keytool -import -trustcacerts -alias cacert -file CAcert.crt -keystore private.keystore -storepass <yourpassword> 6. Import the public key to the private keystore. keytool -import -trustcacerts -alias tomcat -file public.cer -keystore private.keystore -storepass <yourpassword> 7. Generate the truststore with the public key. keytool -import -alias tomcat -file public.cer -keystore public.keystore -storepass <yourpassword> inubit 6.1: Workbench/Process Engine: System Connectors Guide

423 Web Services Connector Creating Key Pairs for WS Trust Import the CA certificate to the truststore to check the certificate chain. keytool -import -alias cacert -file CAcert.crt -keystore public.keystore -storepass <yourpassword> 40.9 Creating Key Pairs for WS Trust This section details the following topics: Creating Self-Signed Security Token Service (STS) Key Pairs, p. 423 Creating a Self-Signed Key Pair, p. 424 Use Securing (generally) multiple Web services through a Security Token Service (STS) with two key pairs Key for authentication of a client on the STS server Key for authentication of a client on the Web services How it works In the initial call of a Web service, the client authenticates itself first on the STS. After successful authentication, the calling service receives the public key of the Web service from the STS, which enables access to the Web service. Authentication on the STS is done with WS-Secure-Conversation just once. To enable access to multiple Web services with a one-time authentication on the STS, all Web services in the group must use the same key pair Creating Self-Signed Security Token Service (STS) Key Pairs Use Authentication of a client on a Security Token Service inubit 6.1: Workbench/Process Engine: System Connectors Guide

424 424 Web Services Connector Creating Key Pairs for WS Trust Proceed as follows 1. Generate a key pair with the extension SubjectKeyIdentifier. Set the options according to your requirements: openssl req -x509 -days nodes -newkey rsa:2048 -subj "/C=myCountry/ ST=myState/L=myCity/O=myOrganization/OU=myDepartment/CN=myServerName" -keyout STS.key -out STS.crt -extensions v3_ca 2. Convert the key pair generated in step 1 into the PKCS12 format in order to enable import into the Java keystore. You must assign a password. openssl pkcs12 -export -in STS.crt -inkey STS.key -out STS.p12 3. Import the PKCS12 file into the Java keystore. keytool -importkeystore -srckeystore STS.p12 -srcstoretype pkcs12 -srcalias 1 -srcstorepass <yourpassword> -destkeystore STS.keystore.jks -destalias tomcat -deststorepass <yourpassword> keytool.html 4. Generate a JKS truststore with the service certificate. Enter the password assigned in step 2 as the password. keytool -importcert -keystore STS.truststore.jks -file STS.crt -alias tomcat -storepass inubit Creating a Self-Signed Key Pair Use Authentication of a client on a Security Token Service-protected Web service Proceed as follows 1. Generate a key pair with the extension SubjectKeyIdentifier. Set the options according to your requirements: openssl req -x509 -days nodes -newkey rsa:2048 -subj "/C=myCountry/ ST=myState/L=myCity/O=myOrganization/OU=myDepartment/CN=myServerName" -keyout SecuredService.key -out SecuredService.crt -extensions v3_ca inubit 6.1: Workbench/Process Engine: System Connectors Guide

425 Web Services Connector Calling an STS-Secured Web Service Provider Convert the key pair generated in step 1 into the PKCS12 format in order to enable import into the Java keystore. You must assign a password. openssl pkcs12 -export -in SecuredService.crt -inkey SecuredService.key -out SecuredService.p12 3. Import the PKCS12 file into the Java keystore. keytool -importkeystore -srckeystore SecuredService.p12 -srcstoretype pkcs12 -srcalias 1 -srcstorepass inubit -destkeystore SecuredService.keystore.jks -destalias tomcat -deststorepass <yourpassword> Calling an STS-Secured Web Service Provider This section explains how you configure a Web service consumer so that it can call an STS-secured Web service provider. Refer to Principles of Operation of the STS Connector (Workbench/Process Engine: System Connectors Guide, chap. 32.1, p. 336).. Prerequisites You need a truststore with the public key of the STS or its certificate. Both Web services and the STS are implemented in the inubit software. To call a Web service that is secured using an STS of the inubit software with an external consumer, configure its security settings according to the provider instructions. Proceed as follows 1. Open the Web Services Connector of your Web Service Consumer for editing. 2. In the Invoked Service tab, enter the URL under which the WSDL of the STS-secured Web service is available: inubit 6.1: Workbench/Process Engine: System Connectors Guide

426 426 Web Services Connector Creating Operations for a Web Service 3. Load the WSDL. 4. In the Extended tab, in the W3C Standards area, click the WS Security button. The WS-Security configuration dialog opens. 5. Import the truststore of the STS or its certificate. The public key of the STS contained herein is required to read the token signed by the STS. With the signature, the STS ensures that the token was actually issued by the STS. After the successful import, the validity of the key is displayed. 6. In the Consumer authentication area, specify how your consumer is supposed to authenticate with the STS to secure communication with the STS. The consumer sends this user name/password combination to the STS as part of its security token request. In addition, you can specify a X.509 keystore for extra security. In this case you must specify the valid password and the alias of a key pair contained in the keystore. 7. Click Finish. 8. Publish and activate the workflow Creating Operations for a Web Service Prerequisites Web Services Input Listener Connector with a WSDL file which is stored at the module itself inubit 6.1: Workbench/Process Engine: System Connectors Guide

427 Web Services Connector Creating Operations for a Web Service 427 Templates (optionally) XML Schema file or WSD file with operations which are similar to those you want to create. The WSD file must use the same binding style which you have defined when configuring the Web service in the Provided Service Tab (Workbench/Process Engine: System Connectors Guide, chap , p. 439). Proceed as follows 1. In the Web Service Editor, display Provided service tab. 2. Add operations Do one of the following: - Click the Add operation button. - Select the root element, open the context menu and select Add operation. A dialog opens. a. Enter an appropriate name for the operation. b. Select the type of operation: - Request/Response: Elements for the input and the output of the operation are added. - Request: Only an element for the input is added. c. Click OK to close the dialog. The operation is displayed with the defined name and the selected input/output parameters below the root element. 3. Add message part - Binding style document/literal When creating the operation, message parts have been added automatically for the input and output message. You can adjust the message part type, if necessary. - Binding style RPC/encoded and RPC/literal You need to define message parts for input and output messages. Proceed as follows: a. In the tree view, select the parameter, to which you want to add a message part. b. Open the context menu and select Add message part. A dialog opens. c. Enter the name and type. d. Close the dialog. The message part is displayed below its corresponding parameter, for example: inubit 6.1: Workbench/Process Engine: System Connectors Guide

428 428 Web Services Connector Creating Operations for a Web Service 4. Using a template (optionally) For typifying parameters, you can use simple or complex data types from an existing Schema file by drag'n'drop. You can also take over operations from other WSDL files by drag'n'drop. Click the Template button at the bottom of the editor. The template docking windows opens: Insert more operations and message parts corresponding to the functionality the Web service provides inubit 6.1: Workbench/Process Engine: System Connectors Guide

429 Web Services Connector Overwriting PartnerLinks Overwriting PartnerLinks You can change the address of the Web service you want to call dynamically while at runtime by using the Variables Mapping. Proceed as follows 1. At the Web Services Connector, open the Variables Mapping dialog. 2. As target, select the PartnerLink containing the address of the Web service to be called. 3. As a source, select for example Static value : 4. Click and select Create example contents for target type : 5. Change the address of the wsa:address element. The WSDL of the endpoint as inserted as metadata into the XML structure beneath wsa:metadata. In case the WSDL must not be changed you can remove the wsdl:definitions element. inubit 6.1: Workbench/Process Engine: System Connectors Guide