SXI Forum

With v2.3 of the SXI Web services you get some additional functionality.  SXIWebservices are distributed as a war file which can be downloaded from the SXI web server.

Below are some of the new features:

1. Each web service has the ability of writing their transaction to a database

2. The tables will be created should they not exist

3. SXIWebServices makes use of Tomcat connection pooling

4. Any database that is supported by Tomcat can be used for SXIWebServices

5. SXI Rest Importer and SXI SOAP Importer can also now be called synchronously

Some of the notable changes:

1. The config names have been changed to remove the word Async (e.g REST Importer used to be called SXIRESTAsyncImporter.properties however it is now called SXIRESTImporter.properties

2. The REST importer and the SOAP importer each have their own log for both the Async and Sync endpoints - this can be changed if need be.

3. A common return object returned by all SXIWebServices

4. Several bug fixes and code cleanups

Asynchronous Operation

When a calling system calls the asynchronous endpoints the web services will immediately respond with a Transaction Response.  This response will include the results of SAVING that transaction ONLY.  The transaction IDs that are returned are only the unique internal integration reference numbers that have been generated for each transaction and are not an indication of a full / complete transaction.  Asynchronous operations are typically called when integrating with systems like Service Desks.

Synchronous Operation

A synchronous operation relies on writing to a database.  The session will keep checking for a response that will be found in the "tranResult" field of specific transaction record that was inserted earlier.  The session will wait for the number of seconds found in the DBSyncTimeout configuration properties. 

• If a response is found before the time out has expired the data inside the "tranResult" field is sent back to the calling system, as well as a SUCCESS transaction status.

• If the Timeout value expires before the tranResult is found a FAILED status is returned to the calling system.

Installation:

Prerequisites:

1. Java               - v1.8_192 or above

2. Tomcat           - v9.0.13 or above

3. MS SQLExpress - v2017 or above installed on your local server

Basic Steps

1. Download the SXIWebServices-2.3.war file from the SXI FTP server

2. Rename SXIWebServices-2.3.war to SXIWebServices.war

3. Place the war file in the tomcat/webapps directory. Tomcat will extract it for you.

4. Configure the relevant properties files

5. Each SXIWebService endpoint has 3 potential outputs:

   1. XML file on the file system

   2. Database

   3. Elastic Search (Big Data - typically for reporting)

6. Configure the endpoints (discussed below)

7. Ensure the configuration that you are pointing to exists and can be accessed.

8. Restart Tomcat to activate the new configuration.

Configuration

1. Configure transactions to be written to an XML File:
   To configure the SXIWebService endpoint to create an XML file on the file system, edit the .properties file corresponding to the endpoint you wish to use.  These property files can be found in [tomcat_dir]/webapps/SXIWebServices/WEB-INF/classes directory.

   1. This functionality can be turned on by changing the CreateXML property from No to Yes.

   2. By default the Windows version of the XMLOutputPath is active.  Typically this is configured to point to the XPress XmlIn1, XmlIn2 or typically XmlOut directory.  If SXIWebServices is installed on a *nix machine then simply comment out the Windows XMLOutputPath property and un-comment the *Nix version and point the XMLOutputPath to the directory you wish to have the transaction files written into.

   3. Set the XMLEncoding to either ISO-8859-1 / UTF-8.  This determines what characterset is allowed to be placed into the XML output file.

   4. DefaultDestination must contain the IP address or hostname of the server where XPressStation is listening for transactions to be processed.  This can be left to 127.0.0.1 if you have configured XMLOutputPath to XmlOut - For more details about using the XLayer Transport Module XPress please speak to your SXI representative.

   NOTE: You MUST have write  permissions to access the directory configured in XMLOutputPath and the machine must have enough disk space to write those files.

   If you have enabled Creating XML files your config should include a section that look as follows:

   #==============================================================================#
   #Do you want the trigger to be created as an XML file: Yes/No
   CreateXML=Yes
   # Windows paths must use forward slashes.
   XMLOutputPath = C:/SXI/XPress/XmlOut
   #Unix
   #XMLOutputPath = /opt/SXI/docstore/process
   #This can be used to change the XML declaration (ISO-8859-1 / UTF-8)
   XMLEncoding=ISO-8859-1
   DefaultDestination = 127.0.0.1

2. Configure transactions to be written to a Database:
   There are 2 parts to this configuration:

   • The properties file - Note: not all the properties are needed any longer as we have moved to connection pooling and the redundant properties will be removed in due course.

   • The Context.xml file used to configure Tomcat's Connection Pooling.

   To turn on the functionality of writing the transactions to a database you need to change the CreateDBRecord property from No to Yes.

   1. The Properties File:

      1. This functionality can be turned on by changing the CreateDBRecord property from No to Yes.  This will always be here

      2. DBType refers to the type of database you are going to write the transactions into.  In THIS example we will write transactions to a MSSQLExpress server that has been installed locally. 

         • Note: you will need to download the jtds-1.3.1.jar file and copy it to the [tomcat_dir]/lib directory.  This jar file can be downloaded from the SXI FTP Server.

         • If you are wanting to write to a different database you will need to download the database driver jar file that is needed to communicate with that specific database type and copy it into the [tomcat_dir]/lib directory.  There will also be further configuration to change in the Context.xml part.

      3. The DBServer property refers to the IP address or hostname of the server where the database is installed.

      4. The DBPort property refers to the port the database is listening on. 

         • Note: SQLExpress will NOT work unless you ensure that TCP is enabled and that the firewall is not blocking traffic on port 1433. 

         • Here is a web page explaining how to do this.

      5. DBUser is a user that has suitable permissions to create a table and insert records into the DBName in the DBTriggerTable 

      6. DBPass is the password in clear text for the DBUser.

      7. DBName is the name of the database where the Web Service Transactions will be written to.

         • NOTE: This database MUST already exist before you can connect with the SXIWebServices.

      8. DBTriggerTable this is the name of the table where the transactions will actually be written to.  Note:  This table will be created if it does not already exist.

      9. DBSyncTimeout is a value in seconds indicating how long the Synchronous endpoints will wait for a response before returning to the calling system.  Please see more about the Synchronous operation lower down in this document.

      If you have enabled writing transactions to a database your config should include a section that look as follows:

      #==============================================================================#
      #Do you want the trigger to be inserted into a Database Table: Yes/No
      CreateDBRecord=Yes
      DBType=MSSQL
      DBServer=127.0.0.1
      DBPort=1433
      DBUser=sa
      DBPass=qwerty
      DBName=SXI_WS_Transactions
      DBTriggerTable=SXIWSTriggers
      DBSyncTimeout=15

   2. The context.xml File:
      The content.xml file can be found in the [tomcat_dir]/webapps/SXIWebServices/META-INF directory.
      Do NOT change the configuration option name="jdbc/sxiwsDB". It will break the connection pooling.  This will be address by configuration in a later version.
      You will not need to change everything in the Context.xml file and most of the fields are best left unchanged.  However the following will have to be changed:

      1. username is a user that has suitable permissions to create a table and insert records into the url database

      2. password is the password in clear text for the DBUser.

      3. url must include the SQL server (IP or name):port/<dbname>.

         • Note: there is no need to change the jdbc:jtds:sqlserver:// part of this url when we are using MSSQLExpress

         • If you are wanting to write to a different database you will need to download the database driver jar file that is needed to communicate with that specific database type you are wanting to write to and then copy it into the [tomcat_dir]/lib directory.  You will also need to change the driverClassName, typeand url (jdbc:jtds:sqlserver) lines in the Context.xml file.

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE xml>
      <Context path="/SXIWebServices">
        <Resource 
      	auth="Container" 
      	driverClassName="net.sourceforge.jtds.jdbc.Driver" 
      	maxActive="1000" 
      	maxIdle="30" 
      	maxWait="10000" 
      	name="jdbc/sxiwsDB" 
      	password="qwerty" 
      	removeAbandoned="true" 
      	removeAbandonedTimeout="30" 
      	type="javax.sql.DataSource" 
      	url="jdbc:jtds:sqlserver://localhost:1433/SXI_WS_Transactions" 
      	username="sa" 
      	validationQuery="select 1"/>
      </Context>

3. Configure transactions to be written to Elastic Search:
   This can be turned on by changing the CreateXDataRecord from No to Yes.

   You will also need to configure the IP address and port of the Elastic Search index server.

   If you have enabled writing XData records to be processed your config should include a section that look as follows:

   #==============================================================================#
   #Do you want the trigger to be inserted into the X-Data Index: Yes/No
   CreateXDataRecord=Yes
   XDataIndexServer=127.0.0.1
   XDataIndexPort=9200

You will need to edit the conf/server.xml file in the tomcat directory.

Look for the section as seen below:

<!--<Connector port="8443" 
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" /> -->

Uncomment that section (or copy it) and change the port to the port you wish Tomcat to listen for https traffic on.  Normally this is 443

You will need to apply a keystore.  In the following example the jks file is found in the conf directory and is called sxi_cert.jks.  The password is "password"

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" 
keystoreFile="conf/sxi_cert.jks" keystorePass="password" />

Restart Tomcat and you should be able to connect to your server using https://servername/

XLayer allows the user to configure different procedures based on various conditions during the integration process. This is done by conditionally executing alternate mappings within the Action Node.

Often it appears if the conditional statements are not working properly - here is why:

When using either the MATCHES or DOESNOTMATCH operator the value attribute is a Regular Expression so one needs to be mindful that any REGEX metacharacters must be escaped for the operation to work as intended
   
Following on from the MATCHES or DOESNOTMATCH discussion above one needs to be careful when setting the value attribute in the condition to extract its contents from another field in memory using the ~#~ notation for example ~#~MyField~#~. This field may contain a REGEX metacharacters in which the case the operation would not behave as intended. To get around this issue you would need to apply the MD5Hash rule to both fields that are used as the operands in the condition

The eq, lt, gt and ne operations ONLY work on NUMBERS