4 - Pipe Component Reference Guide

This chapter contains a reference guide to OpenSyncro's default Pipe Components. Along with a brief description of component's function, component's parameters are explained.

4.1 - Source Components

4.1.1 - DirectorySource

Reads files from a directory in the local file system. Files can be selected by specifying an optional file name filter regular expression. By default, DirectorySource reads all files in the directory. Subdirectories are not scanned for files.

DirectorySource component works in iteration mode; files are sent one-by-one through the Pipe, instead of concatenating their contents to a single data block.
DirectorySource parameters

DirectoryFull path to the directory - without trailing slash ('/') character.
File name filter regular expressionRegular expression for selecting which files from the specified directory will be read. If left empty, all files are read. (Optional)
CharsetCharacter encoding of the file(s). This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.

4.1.2 - FTPSource

Retrieves data from a file located on an FTP server.
FTPSource parameters

HostHost name or IP address of the FTP server.
PortPort number of the FTP server.
UserUsername to log in with.
PasswordPassword for the User.
Beginning of the file nameFull path to the file and the filename itself (for example "/var/test/sourcefile.txt").
Format of the date included in the file nameIf the filename ends with the current date, the date format can be specified here according to Java SimpleDateFormat syntax (for example "yyyyMMdd"). This parameter may be left empty. (Optional)
File extensionFilename suffix (for example "txt"), without the leading dot. This parameter is intended to be used together with "Format of the date included in the file name" option and may be left empty. (Optional)
File typeChooses the FTP file transfer mode to be used, either Binary (recommended) or ASCII.
Add/subtract days from the current dateAmount of days to add to the current date. Use e.g. -1 for yesterday and 1 for tomorrow.
CharsetCharacter encoding of the file to get.

4.1.3 - HTTPSource

Sends a request to an HTTP server and returns the server response body. It can be used for example to simulate web form submission (GET and POST methods).
HTTPSource parameters

HostHost name or IP number of the HTTP server.
PortPort number of HTTP server (default: 80).
DirectoryDirectory path for the file to be retrieved. With a leading slash ('/'). (Optional)
Filename/QueryName of the file to be retrieved. HTTP GET query parameters can appended to the filename.
UserUser name to be used for protected sites. (Optional)
PasswordPassword to be used for protected sites. (Optional)
Request methodRequest method to use. POST and GET methods are available.
Request protocolRequest protocol to use: either HTTP or HTTPS.
Request parametersRequest parameters to be used in the request. (Optional)
Choose charset to use in reading the responseCheck to activate the "Charset used to read the response" setting. If not activated, the HTTP(S) response is assumed to be in ISO-8859-1 charset.
Charset used to read the responseCharacter set to decode the HTTP(S) response with. Requires the checkbox "Choose charset to use in reading the response" to be selected - otherwise this setting is ignored.
Note: Parameters specified in the Request parameter field have to be name value pairs, where names and values are separated by "=" and pairs themselves are separated by a newline. For example:
lang=en
req=orders
would result (in case GET method is used) in a request: http://host:port/directory/query?lang=en&req=orders.

4.1.4 - IteratingFileSource

Reads contents of a file from the local file system. The file is divided to components that are sent through the Pipe one-by-one.

IteratingFileSource can be used for example to read a CSV table file, one row at time. CSV table rows spanning multiple text lines are supported.
IteratingFileSource parameters

DirectoryFull path to the directory containing the file - without trailing slash ('/') character.
File nameName of the file (without path).
DelimiterThe delimiter that is used to divide the file into data components. For example to split a CSV table file to individual rows, you can use \n .
Quote characterIf the quote character is defined, delimiters inside quoted regions are ignored. For example " . (Optional)
Escape characterIf the escape character is defined, quote chars preceded by an (unescaped) escape char are ignored. For example \ . (Optional)
Block sizeBlock size tells how many pieces one iteration block contains (at most). Must be a positive integer, at least 1.
CharsetCharacter encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.

4.1.5 - IteratingXMLFileSource

Reads contents of an XML file from the local file system and sends it through the Pipe in user definable fragments. Each fragment contains one or more elements extracted at a certain level in the XML element hierarchy. IteratingXMLFileSource can be set to read the immediate child elements of the root tag, one by one, enabling processing of arbitrarily large XML files. Only the current XML fragment needs to fit into the main memory.

IteratingXMLFileSource outputs well-formed XML fragments, preserving all parent elements' start and end tags. Each fragment begins with XML declaration from the input file.

The name of the XML file may contain an optional timestamp between the file name prefix and extension.
IteratingXMLFileSource parameters

DirectoryFull path to the directory containing the file - without trailing slash ('/') character.
File name (prefix)Name of the file (without path) or a file name prefix if Timestamp and File extension parameters are given.
Date formatIf specified, a timestamp will be appended to the File name prefix. The date format must conform to Java SimpleDateFormat syntax (for example "yyyyMMdd"). (Optional)
File extensionFile name suffix, which is appended to File name prefix and the optional timestamp. (Optional)
Block sizeBlock size tells how many XML elements to read at each iteration step. Must be a positive integer, at least 1.
Chop depthSpecifies the hierarchy level at which XML elements are extracted. Must be an integer, at least 0. 0 iterates over root level elements, 1 selects the immediate children of the root element(s) and so on.
CharsetCharacter encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.

Note: The encoding attribute of the XML declaration is not read from the file. Character encoding of the XML file must match with this parameter.

4.1.6 - JDBCSource

Sends an SQL select query to database and returns the query results in XML. The SQL query is read as a parameter from the input form. The input form may contain only one SQL select query.

The XML results may be returned in blocks. Number of results per block is set as a parameter. If set to 0, all results are returned at once.

It is possible to choose whether to include the XML declaration line at the beginning of each returned result block or not.
JDBCSource parameters

JDBC URLFull JDBC URL (consult your JDBC driver's documentation), including the database's name and type. MySQL example: jdbc:mysql://localhost/testdatabase
User nameName of the user to login with
PasswordPassword of the user
JDBC driver class nameJava class name of the JDBC driver to be used for connecting. For example for MySQL Connector/J try com.mysql.jdbc.Driver . The JDBC driver must be included in the Java classpath of OpenSyncro webapp.
CharsetCharacter encoding for result XML.
Number of results to return at one iteration stepNumber of query results JDBCSource returns at each iteration step. If set to 0, all results are returned at once (=iteration disabled).
Output XML declaration line at each iterationShould each result start with the XML declaration line or not.
SQL select queryA free SQL select query to be executed to retrieve data from the database. Note: only one Select statement is allowed.

4.1.7 - LocalFileSource

Reads contents of a file from the local file system.
LocalFileSource parameters

DirectoryFull path to the directory containing the file - without trailing slash ('/') character.
File nameName of the file (without path).
CharsetCharacter encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.

4.1.8 - RemoteCustomerSource

RemoteCustomerSource exports customers from Smilehouse Workspace in WS OpenInterface XML format. If no customers matching the selection criteria are found, Pipe execution is aborted.
RemoteCustomerSource parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Customer IDMatch customer with this customer ID number. (Optional)
Customer ID greater thanMatch customers with ID number greater than the specified integer. (Optional)
Customer ID less thanMatch customers with ID number smaller than the specified integer. (Optional)
Customer ID inRetrieve customers with ID matching one of the integers in a comma separated list. (Optional)
Primary customer groupMatch customers with primary customer group name equal to this string. (Optional)
Customer groupMatch customers with customer group name equal to this string. (Optional)
Customer created afterMatch customers created after the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Customer created beforeMatch customers created before the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Last visit afterMatch customers with last visit after the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Last visit beforeMatch customers with last visit before the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Customer modified afterMatch customers which have been modified after specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Customer modified beforeMatch customers which have been modified before specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Admin modified afterMatch customers which have been modified by administrator after specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Admin modified beforeMatch customers which have been modified by administrator before specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Operation between customer and admin modified rangeOperation defines how customer and admin modified ranges (after-before) are related to each other ('OR','AND'). If there is not enough information on ranges then this operation will be ignored. By default 'OR' is selected.
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

4.1.9 - RemoteOrderSource

RemoteOrderSource exports purchase orders from Smilehouse Workspace in WS OpenInterface XML format. If no orders matching the selection criteria are found, Pipe execution is aborted.
RemoteOrderSource parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Order ID greater thanMatch orders with ID number greater than the specified integer. (Optional)
Order ID less thanMatch orders with ID number smaller than the specified integer. (Optional)
Order ID inRetrieve orders with ID matching one of the integers in a comma separated list. (Optional)
Sum greater thanMatch orders with total sum of items greater than the specified number. (Optional)
Sum less thanMatch orders with total sum of items smaller than the specified number. (Optional)
Handling status inMatch orders with handling status matching one of the comma separated list of names. (Optional)
Payment status inMatch orders with payment status matching one of the comma separated list of names. (Optional)
New handling statusChange the handling status of retrieved orders in WS to the specified name. This status name must be defined in WS, otherwise the status change will have no effect. New status is set only after the exported orders have been processed through the Pipe without errors. (Optional)
Customer ID inMatch orders with customer ID matching one of the comma separated list of integers. (Optional)
AfterMatch orders created after the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
BeforeMatch orders created before the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

4.1.10 - StringSource

Simply sends a user defined static text data to the Pipe.
StringSource parameters

Source data for pipeString (text data) to output.

4.1.11 - TimestampFileSource

Reads contents of a local file with timestamp in the filename. The timestamp pattern should conform to java.text.SimpleDateFormat.
TimestampFileSource parameters

DirectoryFull path to the directory containing the file - without trailing slash ('/') character.
File name prefixBeginning of the filename, before the automatically generated Date.
Date formatDate format according to Java SimpleDateFormat syntax (for example "yyyyMMdd").
File extensionFilename suffix (for example "txt") without the leading dot. This parameter may be left empty.
CharsetCharacter encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.

4.1.12 - WorkspaceHQLOrderSource

Exports order data from a Smilehouse Workspace webshop by performing a Hibernate v3 (http://hibernate.org) Select query. The query results are returned in OpenInterface XML format, inside a <result/> root element.

WorkspaceHQLOrderSource extends WorkspaceHQLSource by adding order handling status and payment status updating options. The HQL query should select full order objects for the status updating functionality to work. The exported XML data is scanned for order ID numbers with an XPath query "//order/@id" and these extracted order ID's are used to create order status update requests back to Workspace. If you need to export other XML objects than orders, we recommend the generic WorkspaceHQLSource component.

This component supports iteration and it can be set to return any amount of query results at once. Iteration can also be disabled by telling WorkspaceHQLOrderSource to return all results at the first iteration step (see parameter "Number of results to return at one iteration step").

If the HQL query returns empty result, the Pipe execution is aborted.
WorkspaceHQLOrderSource parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
HQL Select query for Workspace databaseA free HQL query to be executed by Workspace's OpenInterface to retrieve order data from the webshop. Note: the query must not end in semicolon (';') character, otherwise an error will occur.
Timeout for the query iteratorMaximum time in milliseconds OpenInterface will keep an inactive iterator connection open between OpenSyncro and Workspace. The connection timeout value should be large enough for all components in the Pipe to finish execution.

Also if the "New order handling status" or "New order payment status" options are set, the timeout should include the amount time needed by Workspace to update the order status information (this is due to a limitation of OpenInterface: updating order statuses must be done outside the HQL iterator connection).

The smaller the timeout value the less system resources Workspace's OpenInterface uses. For example, start with 10000 (ten seconds) and increase it if you get "HQL iterator has been closed" errors.
Number of results to return at one iteration stepNumber of query results Workspace OpenInterface returns at each iteration step. If set to 0, all results are returned at once (=iteration disabled).
Output XML declaration line at each iterationShould each result start with the XML declaration line or not.
New order handling statusOrder handling status that will be set to exported orders in Workspace. A new order history entry is also created. New status is set only after the exported orders have been processed through the Pipe without errors. (Optional)
New order payment statusOrder handling status that will be set to exported orders in Workspace. A new order history entry is also created. New status is set only after the exported orders have been processed through the Pipe without errors. (Optional)
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

Creating HQL queries for Workspace requires expert knowledge of OpenInterface and Workspace's data model. A few example queries with explanations are listed here:
Example HQL Select queries

from OrderRetrieves all orders.
from Order o where o.handlingStatus.name = 'Received' and o.paymentStatus.name = 'Order paid'Retrieves orders which have handling status set to 'Received' and payment status 'Order paid'.
from Order o where timestamp(o.creationTime) >= timestampadd(day,-7,now())Retrieves orders which have been created during the last 7 days (or today). Note: Uses timestamp functions specific to MySQL 5.0+.
select o from Order o inner join o.answers as oa where oa.version.question.typeId=2 and oa.value='12345'Retrieves orders with postal code 12345 in the address. Please refer to Customer XML schema in Workspace OpenInterface documentation for questionType numbers.

4.1.13 - WorkspaceHQLSource

Exports product, customer and order data from a Smilehouse Workspace webshop by performing a Hibernate v3 (http://hibernate.org) Select query. The query results are returned in OpenInterface XML format, inside a <result/> root element.

This component supports iteration and it can be set to return a certain amount of query results at once. Iteration can also be disabled by telling WorkspaceHQLSource to return all results at the first iteration step (see parameter "Number of results to return at one iteration step").

If the HQL query returns empty result, the Pipe execution is aborted.
WorkspaceHQLSource parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
HQL Select query for Workspace databaseA free HQL query to be executed by Workspace's OpenInterface to retrieve data from the webshop. Product, Customer and Order objects are supported by Workspace as of v1.10. Note: the query must not end in semicolon (';') character, otherwise an error will occur.
Timeout for the query iteratorMaximum time in milliseconds OpenInterface will keep an inactive iterator connection open between OpenSyncro and Workspace. The connection timeout value should be large enough for all components in the Pipe to finish execution. On the other hand, the smaller the timeout value the less system resources Workspace's OpenInterface uses. For example 10000 (ten seconds).
Number of results to return at one iteration stepNumber of query results Workspace OpenInterface returns at each iteration step. If set to 0, all results are returned at once (=iteration disabled).
Output XML declaration line at each iterationShould each result start with the XML declaration line or not.
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

Creating HQL queries for Workspace requires expert knowledge of OpenInterface and Workspace's data model. A few example queries with explanations are listed here:
Example HQL Select queries

from OrderRetrieves all orders.
from ProductRetrieves all products.
from CustomerRetrieves all customers.
from Order o where timestamp(o.creationTime) >= timestampadd(day,-7,now())Retrieves orders which have been created during the last 7 days (or today). Note: Uses timestamp functions specific to MySQL 5.0+.
from Product p where timestamp(p.lastModified) >= timestampadd(day,-3,now())Retrieves products which have been modified during the last 3 days (or today). Note: Uses timestamp functions specific to MySQL 5.0+.
select o from Order o inner join o.answers as oa where oa.version.question.typeId=2 and oa.value='12345'Retrieves orders with postal code 12345 in the address. Please refer to Customer XML schema in Workspace OpenInterface documentation for questionType numbers.
select p from Basket b, Product p where b.itemCode = p.itemCode and not b.parent is nullRetrieves all products that have been ordered from the shop. We choose only those Basket objects which are linked to an existing Order (Basket.parent is not null).
from Product p where p.inventory.amount < p.inventory.alarmLimitRetrieves products with free stock amount below the product's stock alarm limit.
select p from Product p inner join p.parentsHibernate as ph inner join ph.productGroup as pg where p.visible is true and pg.name = 'Software'Retrieves all products with visibility status set to true from a product group called Software.
select p from Product p inner join p.parentsHibernate as ph inner join ph.productGroup as pg where p.visible is false and pg.groupCode in ('PG1234', 'XYZ1000')Retrieves all hidden products from product groups with groupcode either PG1234 or XYZ1000.
select c from Customer c inner join c.groups as cg where cg.name = 'b-to-c new customers' and c.primaryGroup.name = 'b-to-c new customers'Retrieves customers which belong to customer group "b-to-c new customers", which is also set as the primary customer group of the customer.
select c from Customer c inner join c.answers as ca where ca.question.typeId = 12 and ca.value = 'John'Retrieves customers whose first name is "John". Please refer to Customer XML schema in Workspace OpenInterface documentation for questionType numbers.
from Customer c where timestamp(c.modifiedByCustomer) >= timestampadd(hour,-24,now()) or timestamp(c.modifiedByAdmin) >= timestampadd(hour,-24,now())Retrieves customers whose data has been modified during the last 24 hours either by the customer herself or by the webshop administrator. Note: Uses timestamp functions specific to MySQL 5.0+.

4.2 - Converter Components

4.2.1 - ASCIItoXMLConverter

Converts ASCII data to XML, based on a "conversion script" consisting of XML element names and Java regular expressions used to capture data into the XML elements. Each script line has 3 columns separated by a single space character:

Third (rightmost) column specifies the regular expression which should contain at least one capture group (i.e. a part of the regular expression in parentheses). The capture groups will save data matched by the regular expression so that it can be assigned an XML element name in the second column.

The second column contains a comma separated (no spaces) list of XML element names for each capture group, in the same order the capture groups appear in the regular expression.

First column specifies the parent XML element name which will contain all the elements listed in the second column. From here it is possible to refer to any of the second column XML element names on the preceding lines, in order to parse already extracted capture group value using another regular expression.
# This is a comment line.
record name,address regexp_that_captures_(name)_and_(address)
name firstname,lastname regexp_for_(firstname)_and_(lastname)
ASCIItoXMLConverter parameters

Conversion scriptThe script with XML element names and regular expressions.
XML root element nameName of the XML element that will contain the actual result data.
XML header lineXML declaration line. This text will be inserted to the beginning of result data, before the root element. (Optional)

4.2.2 - CSVtoXMLConverter

Converts CSV table data to XML.
CSVtoXMLConverter parameters

CSV column separator characterCharacter that appears between the table columns, separating the column contents. For example: ;. Escape sequences \t, \n, \r, \0, \b and \f are supported.
CSV quote characterCSV table column values may be contained in quotes. Specify the quote character here, e.g. ". Escape sequences \t, \n, \r, \0, \b and \f are supported. (Optional)
XML root element nameName for the XML element which will contain all data from the CSV table.
XML record element nameName for the XML element which will contain a single CSV table row. For example: record.
Prefix/basename for generating missing field namesIn case a CSV table row contains more columns that have been assigned a name (in "XML element names"), CSVtoXMLConverter will generate missing column names on the fly by appending the column number to a basename. This basename is specified here. For example: column_ .
XML element namesA comma separated list (no spaces) of XML element names for CSV table columns. Set or prefix an element name with a '-' (dash) character to exclude the column from output XML.
Use CSV column titles as XML element namesIf the checkbox is checked, CSVtoXMLConverter will attempt to use column values of the first CSV table row as XML element names. If you choose this option, you will likely need to use also the "Skip the first CSV table row" option - otherwise the column title row will also appear as column contents in the output XML.
Skip the first CSV table rowIf the checkbox is checked, CSVtoXMLConverter leaves out the first CSV table row contents from the output.
XML header lineXML declaration to start the output XML with. May also contain XML elements or data. (Optional)
XML footer lineData to be appended after the XML output. (Optional)
String to be appended after the result XML table"Footer" text to insert at the end of the XML output. May contain XML elements or data. (Optional)

4.2.3 - HTTPConverter

Sends a request to an HTTP server and returns the server response body. It can be used for example to simulate web form submission (GET and POST methods), to upload a file (PUT method) or to send a SOAP message. The component's functionality and parameters are identical to those of the HTTPDestination component.
HTTPConverter parameters

HostHost name or IP number of the HTTP server.
PortPort number of HTTP server (default: 80).
PathDirectory path for the file to be retrieved. With a leading slash ('/'). (Optional)
Query/FilenameName of the file to be retrieved. HTTP GET query parameters can appended to the filename.
UserUser name to be used for protected sites. (Optional)
PasswordPassword to be used for protected sites. (Optional)
Request methodRequest method to use. POST, GET, PUT and SOAP methods are available. SOAP method posts the component's input data to the server as Content-Type: text/xml.
Request protocolRequest protocol to use: either HTTP or HTTPS.
SOAPAction headerSOAPAction header to send with a SOAP request. (Optional)
Accept self-signed certificates (HTTPS)Check to allow connections to servers using a self-signed SSL certificate. By default self-signed certificates are not trusted and the connection is aborted. This setting is ignored if Request protocol is not set to HTTPS.
Content typeContent-Type value for POST and SOAP (=POST) type requests. If left empty, "text/xml" is used by default. Note: character encoding information ("; charset=Charset") is automatically appended to the value given here, so the charset info should not be written to this field.
Request parametersParameters to be used in the request. (Optional)
Disable response status code checkCheck to ignore error codes in the HTTP response and pass the response body normally to the next Pipe component.
Write server response to application logCheck to log server responses to requests in OpenSyncro's log file. (Optional)
CharsetCharacter encoding to send the HTTP request in. Only affects the SOAP Request method.
Choose charset to use in reading the responseCheck to activate the "Charset used to read the response" setting. If not activated, the HTTP(S) response is assumed to be in ISO-8859-1 charset.
Charset used to read the responseCharacter set to decode the HTTP(S) response with. Requires the checkbox "Choose charset to use in reading the response" to be selected - otherwise this setting is ignored.
Request parameters can be specified in two ways. When using GET or POST methods, input data from previous components must be name value pairs separated by "=" and "&". For example:
id=500&encoding=UTF-8
Parameters specified in the Request parameter field have to be name value pairs, where names and values are separated by "=" and pairs themselves are separated by a newline. For example:
lang=en
req=orders
Two supplied sets of parameters will be combined (in case GET method is used) in a request: http://host:port/directory/query?id=500&encoding=UTF-8&lang=en&req=orders.

If PUT method is used the Request parameter field must be left empty. Input data from previous components is sent as the body in the PUT request.

Using SOAP method allows you to send component's input data in the body of the request and the data does not need to be name=value pairs. To send SOAP messages, the component's input data has to be a complete SOAP XML message including the env:Envelope and env:Body elements (where xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"). The component simply HTTP POSTs the data as-is without performing XML validation, well-formedness or any other checks.

You can specify additional request parameters in the Request parameter field. The SOAPAction header field can be used to specify the SOAPAction header when sending SOAP requests.

Responses to requests can be logged to OpenSyncro's log file. For this the Write server response to application log checkbox should be checked. Both the response's HTTP headers and reponse body will be logged.

4.2.4 - JDBCConverter

Sends an SQL select query to database and returns the query results in XML. The SQL query is read from the input data. The input data may contain only one SQL select query.

Results for an example query "select Name, StreetAddress, Phone from SomeCustomerTable;" might look like this:
<?xml version="1.0" encoding="UTF-8"?>
<Results>
    <Row>
        <Name>John Row</Name>
        <StreetAddress>7th Avenue</StreetAddress>
        <Phone>555-12345678</Phone>
    </Row>
    <Row>
        <Name>Jane Row</Name>
        <StreetAddress>&lt;unknown&gt;</StreetAddress>
        <Phone>555-87654321</Phone>
    </Row>
<!-- ... -->
</Results>
JDBCConverter parameters

HostHost name or IP address of the database server
PortNumber of the port database server accepts connections to
UsernameName of the user to login with
PasswordPassword of the user
Database nameName of the database to login at the server
JDBC driver class nameJava class name of the JDBC driver to be used for connecting. For example for MySQL Connector/J try com.mysql.jdbc.Driver . The JDBC driver must be included in the Java classpath of OpenSyncro webapp.
Database typeType of the database, e.g. mysql .
CharsetCharacter encoding for result XML.

4.2.5 - JoinConverter

Joins multiple data parts into one. To be used after components that output multiple strings, such as the SplitConverter.
JoinConverter parameters

Delimiter string to be inserted between joined stringsString to be appended after each data part when joining the parts into one string. This parameter can be left empty. (Optional)

4.2.6 - LocalFileReadConverter

Reads contents of a file from the local file system. To be used for replacing or appending input data in the middle of a Pipe.
LocalFileReadConverter parameters

DirectoryFull path to the directory containing the file - without trailing slash ('/') character.
File nameName of the file (without path).
CharsetCharacter encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.
Append to input dataIf true, contents of the file are appended to the component's input data.

4.2.7 - LocalFileWriteConverter

Writes the data to a file in the local file system. Can be used to capture data at different points in a Pipe.
LocalFileWriteConverter parameters

DirectoryFull path to the directory the file will be created (or overwritten). No trailing slash ('/') character.
File nameName of the file (without path).
CharsetCharacter encoding to be used in the file.
File write typeOutput write method used to create file. There are three options available: Always append, overwrite at first iteration, otherwise append, always overwrite. By default always overwrite is selected.

4.2.8 - RemoteOrderConverter

Imports XML sales order data to Workspace through OpenInterface. Refer to Workspace OpenInterface API documentation for XML schema and data examples. The component will always return an empty string as a result. The component's functionality and parameters are identical to those of the RemoteOrderDestination component.
RemoteOrderConverter parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Import modeChoose one of the following Workspace OpenInterface import methods:

Insert or update - Insert if the order does not exist in the database or update if it does exist.

Only insert - Do not update any existing orders in the database, only insert new orders.

Only update - Update if the order exists in the database, otherwise do nothing.
Invoke 'Received' events for inserted ordersIf this checkbox is checked, each new order inserted to Workspace will launch actions associated with the 'Received' event.
Additive answer updateIf this checkbox is checked, the existing list of customer answers is not cleared when updating an order. New answers will be appended to the list.
Additive basket updateIf this checkbox is checked, the existing list of baskets (=order rows, products) is not cleared when updating an order. New baskets will be appended to the list.
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

4.2.9 - SplitConverter

Splits data into multiple parts around matches of a regular expression.

Note: SplitConverter outputs multiple data parts. All Converter Components after SplitConverter as well as the Destination Component will be executed once for each data part.
SplitConverter parameters

Regular ExpressionThe input data will be splitted at each occurrence of a pattern matching this regular expression.
String to be inserted at the beginning of each partInsert this string ("header") at the beginning of each splitted data part. (Optional)
String to be appended to the end of each partAppend this string ("footer") at the end of each splitted data part. (Optional)
Don't output empty partsIf the input data contains a) more than one Regular Expression match in a sequence without any other data in-between, or b) Regular Expression match immediately at the beginning of the input, SplitConverter would output empty parts (consisting of only the optional header & footer strings) by default. Check this checkbox to disable outputting empty parts.
Don't prefix the first partCheck this checkbox to disable inserting the "header" string at the beginning of the first data part that will be output.

4.2.10 - WorkspaceHQLResultConverter

Extracts a list of values from the input XML by running an XPath 1.0 query and then proceeds to export all Smilehouse Workspace webshop's (Product or Order) HQL objects that match one of the extracted, unique values. The XPath query, the HQL object name (e.g. "Product") and the object's property name (e.g. "itemCode") to match against the extracted values are given as parameters. From these an HQL query of the following form is generated and sent to Workspace's OpenInterface:
from <hqlObjectName> s1 where s1.<hqlPropertyName> in ( <extractedValueList> )
References to values through value collections are also supported in the form ":hqlProperty1:hqlProperty2.hqlProperty3", where hqlProperty1 is a collection type property directly under the queried HQL object, hqlProperty2 is a collection type property of hqlProperty1 and hqlProperty3 is a regular (non-collection type) property of hqlProperty2.

If a property name part begins with a colon character, it will be "inner joined" either with the selected HQL object, or with preceding property name part(s). For example a webshop product with a certain item code assigned to one of its product options will be found with HQL object name "Product" and HQL object's property name field value ":options:choices.itemCodeChange". This generates an HQL query with form:
select s1 from Product s1 inner join s1.options as s2 inner join s2.choices as s3 where s3.itemCodeChange in ( <extractedValueList> )
Another example, to select products by their inventory shelf name, would be property name "inventory.shelf". No colon characters in this one, since in Workspace there is only one "inventory" connected to "Product" object and in the inventory record there is only one "shelf". Generated HQL query will be simply
from Product s1 where s1.inventory.shelf in ( <extractedValueList> )
It should be noted that creating HQL queries for Workspace requires expert knowledge of Workspace's data model.

The HQL query results are returned in OpenInterface XML format. WorkspaceHQLResultConverter passes through its Input XML data and appends the HQL query results to the result XML. The final output has the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<root>

   <!-- The input XML data is passed through here -->

   <result>

      <!-- OpenInterface query results here (Product or Order elements) -->

   </result>

</root>
WorkspaceHQLResultConverter parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Timeout for the query iteratorMaximum time in milliseconds OpenInterface will keep an inactive iterator connection open between OpenSyncro and Workspace. For example 10000 (=ten seconds). Does not affect the result data.
Number of results to request from Workspace at onceNumber of query results the component asks from Workspace OpenInterface at once. Does not affect the result data.
XPath 1.0 query for selecting HQL query valuesXPath 1.0 query to extract values from input XML. The query's result set is filtered to contain unique values.
HQL object name to queryWorkspace's HQL object name to query. For example Product or Order.
HQL object's property to match against the value list returned by XPath queryHQL object's property to match the extracted values against. With Product object try e.g. itemCode.
Name of the XML root element to contain input XML and HQL query resultName of the root element to contain result XML. For example root. (Optional)
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

4.2.11 - XMLGroupExpander

Expands the input XML so that in the output there's one copy of Parent element for every occurrence of a "Child element".

XMLGroupExpander parameters

Parent elementName of the XML element which will be output once with each Child element. Parent element will contain the Child element.
Grouping elementName of the element that contains the Child elements in the input XML.
Child elementName of the Child elements to be output with the Parent element.
Retain grouping elementsCheck this checkbox to pass the Grouping elements from input data to output. By default the Grouping elements are filtered out.
XMLGroupExpander is used to create copies of an XML element and its child elements, so that one child element value is different in each copy. For example, the following input XML:
<parentElement name="George">
	<someElement>
		<anotherElement>some text</anotherElement>
	</someElement>
	<groupingElement>
		<childElement name="Frederik"/>
		<childElement name="Bill"/>
	</groupingElement>
	<someElement>
		<anotherElement>some text</anotherElement>
	</someElement>
</parentElement> 
... produces XML output like this:
<parentElement name="George">
	<someElement>
		<anotherElement>some text</anotherElement>
	</someElement>
	<groupingElement>
		<childElement name="Frederik"/>
	</groupingElement>
	<someElement>
		<anotherElement>some text</anotherElement>
	</someElement>
</parentElement>
<parentElement name="George">
	<someElement>
		<anotherElement>some text</anotherElement>
	</someElement>
	<groupingElement>
		<childElement name="Bill"/>
	</groupingElement>
	<someElement>
		<anotherElement>some text</anotherElement>
	</someElement>
</parentElement>


Parameter settings for the above example were:

4.2.12 - XSLTConverter

Performs an XSL Transformation for XML data using Xalan Java XSLT 1.0 processor.
XSLTConverter parameters

XSL transformationXSLT 1.0 compatible XSL transformation script to be executed.

4.2.13 - XSLT20Converter

Performs an XSL Transformation for XML data using Saxon Java XSLT 2.0 processor. XSLT20Converter includes the Saxon SQL Extension, which allows an XSLT script to perform SQL select queries and other standard operations in JDBC compatible databases.

All xsl:message texts from the XSLT script are redirected to OpenSyncro's Transfer log as debug level messages (verbosity level = "All"). It is also possible for the XSLT script to stop the Pipe execution by throwing an error message as follows:
<xsl:message terminate="yes">Some error message here</xsl:message>
XSLT20Converter parameters

XSL 2.0 transformationXSLT 2.0 compatible XSL transformation script to be executed.

4.3 - Destination Components

4.3.1 - FTPDestination

Uploads the data as a file to an FTP server.
FTPDestination parameters

HostHost name or IP address of the FTP server.
PortPort number of the FTP server.
UserUsername to log in with.
PasswordPassword for the User.
Beginning of the file nameFull path to the file and the filename itself (for example: "/var/test/destinationfile.txt").
Format of the date included in the file nameIf you wish to append the current date to the filename, the date format can be specified here according to Java SimpleDateFormat syntax (for example "yyyyMMdd"). This parameter may be left empty. (Optional)
File extensionFilename suffix (for example "txt"), without the leading dot. This parameter is intended to be used together with "Format of the date included in the file name" option and may be left empty. (Optional)
File typeChooses the FTP file transfer mode to be used, either Binary (recommended) or ASCII.
CharsetCharacter encoding of the file to send.

4.3.2 - HTTPDestination

Sends a request to an HTTP server. It can be used for example to simulate web form submission (GET and POST methods), to upload a file (PUT method) or to send a SOAP message. The component's functionality and parameters are identical to those of the HTTPConverter component.
HTTPDestination parameters

HostHost name or IP number of the HTTP server.
PortPort number of HTTP server (default: 80).
PathDirectory path for the file to be retrieved. With a leading slash ('/'). (Optional)
Query/FilenameName of the file to be retrieved. HTTP GET query parameters can appended to the filename.
UserUser name to be used for protected sites. (Optional)
PasswordPassword to be used for protected sites. (Optional)
Request methodRequest method to use. POST, GET, PUT and SOAP methods are available. SOAP method posts the component's input data to the server as Content-Type: text/xml.
Request protocolRequest protocol to use: either HTTP or HTTPS.
SOAPAction headerSOAPAction header to send with a SOAP request. (Optional)
Accept self-signed certificates (HTTPS)Check to allow connections to servers using a self-signed SSL certificate. By default self-signed certificates are not trusted and the connection is aborted. This setting is ignored if Request protocol is not set to HTTPS.
Content typeContent-Type value for POST and SOAP (=POST) type requests. If left empty, "text/xml" is used by default. Note: character encoding information ("; charset=Charset") is automatically appended to the value given here, so the charset info should not be written to this field.
Request parametersParameters to be used in the request. (Optional)
Disable response status code checkCheck to ignore error codes in the HTTP response and pass the response body normally to the next Pipe component.
Write server response to application logCheck to log server responses to requests in OpenSyncro's log file. (Optional)
CharsetCharacter encoding to send the HTTP request in. Only affects the SOAP Request method.
Choose charset to use in reading the responseCheck to activate the "Charset used to read the response" setting. If not activated, the HTTP(S) response is assumed to be in ISO-8859-1 charset.
Charset used to read the responseCharacter set to decode the HTTP(S) response with. Requires the checkbox "Choose charset to use in reading the response" to be selected - otherwise this setting is ignored.
Request parameters can be specified in two ways. When using GET or POST methods, input data from previous components must be name value pairs separated by "=" and "&". For example:
id=500&encoding=UTF-8
Parameters specified in the Request parameter field have to be name value pairs, where names and values are separated by "=" and pairs themselves are separated by a newline. For example:
lang=en
req=orders
Two supplied sets of parameters will be combined (in case GET method is used) in a request: http://host:port/directory/query?id=500&encoding=UTF-8&lang=en&req=orders.

If PUT method is used the Request parameter field must be left empty. Input data from previous components is sent as the body in the PUT request.

Using SOAP method allows you to send component's input data in the body of the request and the data does not need to be name=value pairs. To send SOAP messages, the component's input data has to be a complete SOAP XML message including the env:Envelope and env:Body elements (where xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"). The component simply HTTP POSTs the data as-is without performing XML validation, well-formedness or any other checks.

You can specify additional request parameters in the Request parameter field. The SOAPAction header field can be used to specify the SOAPAction header when sending SOAP requests.

Responses to requests can be logged to OpenSyncro's log file. For this the Write server response to application log checkbox should be checked. Both the response's HTTP headers and reponse body will be logged.

4.3.3 - JDBCDestination

Sends SQL Insert, Update and Delete statements read from input data to a database.
JDBCDestination parameters

JDBC URLFull JDBC URL (consult your JDBC driver's documentation), including the database's name and type. MySQL example: jdbc:mysql://localhost/testdatabase
UsernameName of the user to login with
PasswordPassword of the user
JDBC driver class nameJava class name of the JDBC driver to be used for connecting. For example for MySQL Connector/J try com.mysql.jdbc.Driver . The JDBC driver must be included in the Java classpath of OpenSyncro webapp.

4.3.4 - LocalFileDestination

Writes the data to a file in local file system.
LocalFileDestination parameters

DirectoryFull path to the directory the file will be created (or overwritten). No trailing slash ('/') character.
File nameName of the file (without path).
String to add at beginning of fileA String that will be added to the start of the file.
String to add at end of fileA String that will be added to the end of the file.
CharsetCharacter encoding to be used in the file.

4.3.5 - MultiFileDestination

Writes the data to multiple files in local file system. Each data block will be written to a different file, whose names consist of a prefix, auto-incrementing index number and a file extension.
MultiFileDestination parameters

DirectoryFull path to the directory containing the file - without trailing slash ('/') character.
File name prefixBeginning of the filename, before the automatically generated Date.
Index number start valueThe auto-incrementing counter between File name prefix and File extension starts with this (integer) value
File extensionFilename suffix (for example "txt") without the leading dot. This parameter may be left empty.
CharsetCharacter encoding of the file(s). This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.

4.3.6 - RemoteCustomerDestination

Imports XML customer data to Workspace through OpenInterface. Refer to Workspace OpenInterface API documentation for XML schema and data examples.
RemoteCustomerDestination parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Import modeChoose one of the following Workspace OpenInterface import methods:

Insert or update - Insert if the customer does not exist in the database or update if it does exist.

Only insert - Do not update any existing customers in the database, only insert new customers.

Only update - Update if the customer exists in the database, otherwise do nothing.

Insert as new - Does not try to match existing customers, inserts all customers as new records.

Replace all - Clears the entire customer database before starting to import (insert) customers. Note: This mode can not be currently used in iterating Pipes, as it will clear the database before importing every block of data, leaving only the last data block contents in the database.
Create customer groupsIf this checkbox is checked, all non-existent customer groups referenced by the imported data will be created.

4.3.7 - RemoteOrderDestination

Imports XML sales order data to Workspace through OpenInterface. Refer to Workspace OpenInterface API documentation for XML schema and data examples.
RemoteOrderDestination parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Import modeChoose one of the following Workspace OpenInterface import methods:

Insert or update - Insert if the order does not exist in the database or update if it does exist.

Only insert - Do not update any existing orders in the database, only insert new orders.

Only update - Update if the order exists in the database, otherwise do nothing.
Invoke 'Received' events for inserted ordersIf this checkbox is checked, each new order inserted to Workspace will launch actions associated with the 'Received' event.
Additive answer updateIf this checkbox is checked, the existing list of customer answers is not cleared when updating an order. New answers will be appended to the list.
Additive basket updateIf this checkbox is checked, the existing list of baskets (=order rows, products) is not cleared when updating an order. New baskets will be appended to the list.
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

4.3.8 - RemotePriceListDestination

Imports XML contract pricing data to Workspace through OpenInterface. Refer to Workspace OpenInterface API documentation for XML schema and data examples.
RemotePriceListDestination parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Import modeChoose one of the following Workspace OpenInterface import methods:

Insert or update - Insert if the pricelist entry does not exist in the database or update the entry if it does exist.

Only insert - Do not update any existing pricelist entries in the database, only insert new entries.

Only update - Update if the pricelist entry exists in the database, otherwise do nothing.

Replace all - Clears the entire pricelist before starting to import (insert) pricelist entries. Note: This mode can not be currently used in iterating Pipes, as it will clear the database before importing every block of data, leaving only the last data block contents in the database.
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

4.3.9 - RemoteProductDestination

Imports XML product data to Workspace through OpenInterface. Refer to Workspace OpenInterface API documentation for XML schema and data examples.
RemoteProductDestination parameters

Open Interface URLComplete URL path to the Workspace installation, e.g. http://localhost:8080 . No trailing slash ('/') character should be added. The component will append "/workspace.admin/openinterfaceaddress" to this OI URL in order to locate OpenInterface WebService.
DatabaseName of the Workspace shop's database.
User nameName of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
PasswordPassword of the Workspace user (see above).
Import modeChoose one of the following Workspace OpenInterface import methods:

Insert or update - Insert if the product does not exist in the database or update if it does exist.

Only insert - Do not update any existing products in the database, only insert new products.

Only update - Update if the product exists in the database, otherwise do nothing.

Replace all - Clears the entire product database before starting to import (insert) products. Note: This mode can not be currently used in iterating Pipes, as it will clear the database before importing every block of data, leaving only the last data block contents in the database.
Create product groupsIf this checkbox is checked, all non-existent product groups referenced by the imported data will be created.
Additive product group updateIf this checkbox is checked, an updated product will be only added to new product groups and not removed from any existing groups. If the checkbox is not checked (default), the product group(s) from the XML will replace the product's current group associations in database.
Additive product option updateIf this checkbox is checked, only new product options can be only added to an updated product and existing product options will not be removed. If the checkbox is not checked (default), product option list from the XML will replace the current options of a product in database.
Protected groupsA list of product groups (one full product group path per line) to protect from changes.
Note: if Database parameter is incorrect, OpenSyncro may write "Failed to get the O.I. Endpoint address" error to the Transfer log - even if the Open Interface URL would be correct.

4.3.10 - TimestampFileDestination

Writes data to a local file with timestamp in the filename. The timestamp pattern should conform to java.text.SimpleDateFormat.
TimestampFileDestination parameters

DirectoryFull path to the directory containing the file - without trailing slash ('/') character.
File name prefixBeginning of the filename, before the automatically generated Date.
Date formatDate format according to Java SimpleDateFormat syntax (for example "yyyyMMdd").
File extensionFilename suffix (for example "txt") without the leading dot. This parameter may be left empty.
CharsetCharacter encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.