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
Directory	Full path to the directory - without trailing slash ('/') character.
File name filter regular expression	Regular expression for selecting which files from the specified directory will be read. If left empty, all files are read. (Optional)
Charset	Character 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
Host	Host name or IP address of the FTP server.
Port	Port number of the FTP server.
User	Username to log in with.
Password	Password for the User.
Beginning of the file name	Full path to the file and the filename itself (for example "/var/test/sourcefile.txt").
Format of the date included in the file name	If 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 extension	Filename 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 type	Chooses the FTP file transfer mode to be used, either Binary (recommended) or ASCII.
Add/subtract days from the current date	Amount of days to add to the current date. Use e.g. -1 for yesterday and 1 for tomorrow.
Charset	Character 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
Host	Host name or IP number of the HTTP server.
Port	Port number of HTTP server (default: 80).
Directory	Directory path for the file to be retrieved. With a leading slash ('/'). (Optional)
Filename/Query	Name of the file to be retrieved. HTTP GET query parameters can appended to the filename.
User	User name to be used for protected sites. (Optional)
Password	Password to be used for protected sites. (Optional)
Request method	Request method to use. POST and GET methods are available.
Request protocol	Request protocol to use: either HTTP or HTTPS.
Request parameters	Request parameters to be used in the request. (Optional)
Choose charset to use in reading the response	Check 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 response	Character 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
Directory	Full path to the directory containing the file - without trailing slash ('/') character.
File name	Name of the file (without path).
Delimiter	The 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 character	If the quote character is defined, delimiters inside quoted regions are ignored. For example " . (Optional)
Escape character	If the escape character is defined, quote chars preceded by an (unescaped) escape char are ignored. For example \ . (Optional)
Block size	Block size tells how many pieces one iteration block contains (at most). Must be a positive integer, at least 1.
Charset	Character 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
Directory	Full 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 format	If 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 extension	File name suffix, which is appended to File name prefix and the optional timestamp. (Optional)
Block size	Block size tells how many XML elements to read at each iteration step. Must be a positive integer, at least 1.
Chop depth	Specifies 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.
Charset	Character 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 URL	Full JDBC URL (consult your JDBC driver's documentation), including the database's name and type. MySQL example: jdbc:mysql://localhost/testdatabase
User name	Name of the user to login with
Password	Password of the user
JDBC driver class name	Java 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.
Charset	Character encoding for result XML.
Number of results to return at one iteration step	Number 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 iteration	Should each result start with the XML declaration line or not.
SQL select query	A 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
Directory	Full path to the directory containing the file - without trailing slash ('/') character.
File name	Name of the file (without path).
Charset	Character 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Customer ID	Match customer with this customer ID number. (Optional)
Customer ID greater than	Match customers with ID number greater than the specified integer. (Optional)
Customer ID less than	Match customers with ID number smaller than the specified integer. (Optional)
Customer ID in	Retrieve customers with ID matching one of the integers in a comma separated list. (Optional)
Primary customer group	Match customers with primary customer group name equal to this string. (Optional)
Customer group	Match customers with customer group name equal to this string. (Optional)
Customer created after	Match customers created after the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Customer created before	Match customers created before the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Last visit after	Match customers with last visit after the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Last visit before	Match customers with last visit before the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Customer modified after	Match customers which have been modified after specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Customer modified before	Match customers which have been modified before specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Admin modified after	Match customers which have been modified by administrator after specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Admin modified before	Match customers which have been modified by administrator before specified time (format: dd.MM.yyyy HH:mm:ss). (Optional)
Operation between customer and admin modified range	Operation 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Order ID greater than	Match orders with ID number greater than the specified integer. (Optional)
Order ID less than	Match orders with ID number smaller than the specified integer. (Optional)
Order ID in	Retrieve orders with ID matching one of the integers in a comma separated list. (Optional)
Sum greater than	Match orders with total sum of items greater than the specified number. (Optional)
Sum less than	Match orders with total sum of items smaller than the specified number. (Optional)
Handling status in	Match orders with handling status matching one of the comma separated list of names. (Optional)
Payment status in	Match orders with payment status matching one of the comma separated list of names. (Optional)
New handling status	Change 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 in	Match orders with customer ID matching one of the comma separated list of integers. (Optional)
After	Match orders created after the specified date (format: dd.MM.yyyy HH:mm:ss). (Optional)
Before	Match 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 pipe	String (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
Directory	Full path to the directory containing the file - without trailing slash ('/') character.
File name prefix	Beginning of the filename, before the automatically generated Date.
Date format	Date format according to Java SimpleDateFormat syntax (for example "yyyyMMdd").
File extension	Filename suffix (for example "txt") without the leading dot. This parameter may be left empty.
Charset	Character 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
HQL Select query for Workspace database	A 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 iterator	Maximum 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 step	Number 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 iteration	Should each result start with the XML declaration line or not.
New order handling status	Order 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 status	Order 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 Order	Retrieves 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
HQL Select query for Workspace database	A 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 iterator	Maximum 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 step	Number 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 iteration	Should each result start with the XML declaration line or not.

Example HQL Select queries
from Order	Retrieves all orders.
from Product	Retrieves all products.
from Customer	Retrieves 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 null	Retrieves 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.alarmLimit	Retrieves 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 script	The script with XML element names and regular expressions.
XML root element name	Name of the XML element that will contain the actual result data.
XML header line	XML 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 character	Character 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 character	CSV 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 name	Name for the XML element which will contain all data from the CSV table.
XML record element name	Name for the XML element which will contain a single CSV table row. For example: record.
Prefix/basename for generating missing field names	In 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 names	A 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 names	If 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 row	If the checkbox is checked, CSVtoXMLConverter leaves out the first CSV table row contents from the output.
XML header line	XML declaration to start the output XML with. May also contain XML elements or data. (Optional)
XML footer line	Data 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
Host	Host name or IP number of the HTTP server.
Port	Port number of HTTP server (default: 80).
Path	Directory path for the file to be retrieved. With a leading slash ('/'). (Optional)
Query/Filename	Name of the file to be retrieved. HTTP GET query parameters can appended to the filename.
User	User name to be used for protected sites. (Optional)
Password	Password to be used for protected sites. (Optional)
Request method	Request 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 protocol	Request protocol to use: either HTTP or HTTPS.
SOAPAction header	SOAPAction 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 type	Content-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 parameters	Parameters to be used in the request. (Optional)
Disable response status code check	Check to ignore error codes in the HTTP response and pass the response body normally to the next Pipe component.
Write server response to application log	Check to log server responses to requests in OpenSyncro's log file. (Optional)
Charset	Character encoding to send the HTTP request in. Only affects the SOAP Request method.
Choose charset to use in reading the response	Check 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 response	Character 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
Host	Host name or IP address of the database server
Port	Number of the port database server accepts connections to
Username	Name of the user to login with
Password	Password of the user
Database name	Name of the database to login at the server
JDBC driver class name	Java 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 type	Type of the database, e.g. mysql .
Charset	Character 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 strings	String 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
Directory	Full path to the directory containing the file - without trailing slash ('/') character.
File name	Name of the file (without path).
Charset	Character encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.
Append to input data	If 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
Directory	Full path to the directory the file will be created (or overwritten). No trailing slash ('/') character.
File name	Name of the file (without path).
Charset	Character encoding to be used in the file.
File write type	Output 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Import mode	Choose 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 orders	If this checkbox is checked, each new order inserted to Workspace will launch actions associated with the 'Received' event.
Additive answer update	If 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 update	If 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 Expression	The input data will be splitted at each occurrence of a pattern matching this regular expression.
String to be inserted at the beginning of each part	Insert this string ("header") at the beginning of each splitted data part. (Optional)
String to be appended to the end of each part	Append this string ("footer") at the end of each splitted data part. (Optional)
Don't output empty parts	If 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 part	Check 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Timeout for the query iterator	Maximum 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 once	Number 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 values	XPath 1.0 query to extract values from input XML. The query's result set is filtered to contain unique values.
HQL object name to query	Workspace's HQL object name to query. For example Product or Order.
HQL object's property to match against the value list returned by XPath query	HQL 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 result	Name 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 element	Name of the XML element which will be output once with each Child element. Parent element will contain the Child element.
Grouping element	Name of the element that contains the Child elements in the input XML.
Child element	Name of the Child elements to be output with the Parent element.
Retain grouping elements	Check 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:

Parent element = parentElement
Grouping element = groupingElement
Child element = childElement
Retain grouping elements = true (checked)

4.2.12 - XSLTConverter

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

XSLTConverter parameters
XSL transformation	XSLT 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 transformation	XSLT 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
Host	Host name or IP address of the FTP server.
Port	Port number of the FTP server.
User	Username to log in with.
Password	Password for the User.
Beginning of the file name	Full path to the file and the filename itself (for example: "/var/test/destinationfile.txt").
Format of the date included in the file name	If 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 extension	Filename 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 type	Chooses the FTP file transfer mode to be used, either Binary (recommended) or ASCII.
Charset	Character 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
Host	Host name or IP number of the HTTP server.
Port	Port number of HTTP server (default: 80).
Path	Directory path for the file to be retrieved. With a leading slash ('/'). (Optional)
Query/Filename	Name of the file to be retrieved. HTTP GET query parameters can appended to the filename.
User	User name to be used for protected sites. (Optional)
Password	Password to be used for protected sites. (Optional)
Request method	Request 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 protocol	Request protocol to use: either HTTP or HTTPS.
SOAPAction header	SOAPAction 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 type	Content-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 parameters	Parameters to be used in the request. (Optional)
Disable response status code check	Check to ignore error codes in the HTTP response and pass the response body normally to the next Pipe component.
Write server response to application log	Check to log server responses to requests in OpenSyncro's log file. (Optional)
Charset	Character encoding to send the HTTP request in. Only affects the SOAP Request method.
Choose charset to use in reading the response	Check 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 response	Character 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

4.3.3 - JDBCDestination

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

JDBCDestination parameters
JDBC URL	Full JDBC URL (consult your JDBC driver's documentation), including the database's name and type. MySQL example: jdbc:mysql://localhost/testdatabase
Username	Name of the user to login with
Password	Password of the user
JDBC driver class name	Java 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
Directory	Full path to the directory the file will be created (or overwritten). No trailing slash ('/') character.
File name	Name of the file (without path).
String to add at beginning of file	A String that will be added to the start of the file.
String to add at end of file	A String that will be added to the end of the file.
Charset	Character 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
Directory	Full path to the directory containing the file - without trailing slash ('/') character.
File name prefix	Beginning of the filename, before the automatically generated Date.
Index number start value	The auto-incrementing counter between File name prefix and File extension starts with this (integer) value
File extension	Filename suffix (for example "txt") without the leading dot. This parameter may be left empty.
Charset	Character 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Import mode	Choose 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 groups	If 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Import mode	Choose 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 orders	If this checkbox is checked, each new order inserted to Workspace will launch actions associated with the 'Received' event.
Additive answer update	If 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 update	If 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Import mode	Choose 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 URL	Complete 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.
Database	Name of the Workspace shop's database.
User name	Name of the Workspace user as which OpenSyncro will log in to WS. Note: the WS user must have OpenInterface access enabled.
Password	Password of the Workspace user (see above).
Import mode	Choose 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 groups	If this checkbox is checked, all non-existent product groups referenced by the imported data will be created.
Additive product group update	If 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 update	If 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 groups	A 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
Directory	Full path to the directory containing the file - without trailing slash ('/') character.
File name prefix	Beginning of the filename, before the automatically generated Date.
Date format	Date format according to Java SimpleDateFormat syntax (for example "yyyyMMdd").
File extension	Filename suffix (for example "txt") without the leading dot. This parameter may be left empty.
Charset	Character encoding of the file. This information is required for conversion to OpenSyncro's internal 16-bit Unicode character set.