Transact Integration Gateway Setup

   Journey PlatformPreviously known as the Transact Platform.  |   System Manager / DevOps |  v4.3 & Higher   This feature is related to v4.3 and higher.

Note

Although Transact Integration Gateway (TIG) continues to receive support, it is recommended that Journey Platform solution builders move away from using TIG and instead use Journey Manager REST APIs to build Journey Platform solutions. Continuing to use TIG may complicate an upgrade path when TIG is eventually deprecated in a future release.

Prerequisites

You need a JDK installed on the system where you are installing Transact Integration Gateway (TIG). The JDK version you need is dependent upon the version of TIG you are installing, and can be identified as follows.

  1. Identify the TIG version (tig-version) that you want to install.
  2. Next, identify the JDK version (jdk-version) that is required when installing the tig-version version of Journey Manager.
  3. So, jdk-version is the JDK version required when installing the TIG version identified in the first step.

An example will help to clarify these steps.

  1. Say you want to install TIG v18.11 (tig-version = v18.11).
  2. Identify the JDK version required when installing Journey Manager v18.11; in this case, it's JDK 11 (jdk-version = JDK 11).
  3. So, we need JDK 11 installed on our system in order to install TIG v18.11.
Note

TIG and Journey Manager have been designed so that any version of TIG can communicate with any Journey Manager version. That is, you do not need to install the same version of TIG and Journey Manager.

Transact Client SDK

If you're using TIG in your Journey Platform solution, you may also want to use Transact Client SDK when building that solution. While Transact Client SDK is no longer under active development, it is compatible with later Journey Platform versions, just like TIG. You can download the latest Transact Client SDK release which includes reference documentation that is also available online.

Installation

A TIG Setup Wizard application is provided to enable fast and easy installation.

On a Windows server with a JRE available, TIG can be installed and running as a Windows Service within a few minutes.

See the Transaction Integration Gateway Installation Guide for further details.

Configuration

TIG is configured through a series of JSON configuration files. These files are located in the configuration directory: C:\avoka\transact\tig\config\

Config File Description

delivery-config.json

Transaction delivery channel configurations

proxy-config.json

Service API Gateway proxy configurations

services-config.json

Groovy Services configurations

scheduler-config.json

Scheduled Grooovy script job configurations

storage-config.json

Submission data storage configuration

The Groovy scripts directory is also under the configuration directory: C:\avoka\transact\tig\config\groovy\

This directory contains a number of sample Groovy scripts which are referenced in the groovy-config.json file including:

  • delivery-email.groovy
  • delivery-example.groovy
  • google-search.groovy
  • job-example.groovy
  • template-example.groovy

Delivery Config

The delivery configuration file defines transaction delivery channels to retrieve completed form transactions using the Manager REST Delivery APIs.

The sample delivery-config.json installed with TIG is shown below.

{
	"pollingIntervalMins": 1,
	"deliveryChannels": [
		{
			"deliveryUrl": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/",
			"user": "administrator",
			"password": "password",
			"dataDir": "C:/tig/delivery/",
			"subDir": "${submissionId}",
			"processingStatus": "Thank you your application is being processed",
			"serviceName": "delivery-example"
		}
	]
}

This configuration specifies a 1 minute polling interval to call the Manager REST Delivery API to see whether any new transactions are available.

The next element is a collection of delivery channels. A single TIG service can perform deliveries against many Manager Delivery Channels. For more information on how to configure a delivery channel, see the Transact Services Guide > REST API > Delivery API.

The JSON delivery channel attributes include:

Name Description

deliveryUrl

Delivery channel URL as defined for the Manager organization delivery channel's REST Service URL

user

Manager user login name.

Users must have the REST Delivery role assigned to them, be assigned to Manager console access, and organization access.

password

Manager user password

It is recommended that you configure specific REST delivery users, with only the REST Delivery role and no other permissions.

dataDir

Base data directory where form transaction data will be written

subDir

A pattern sub directory under the base dataDir

This folder is used to separate different transactions. There are a large number of patterns which can be used to create sub directories for data delivery (see below).

processingStatus

A processing status message which is returned to the Manager server when delivery is confirmed and may be displayed to the end user who submitted the form.

This is typically use to provided a message informing them that their application is being processed. This message has a maximum length of 100 characters; longer values will be truncated.

deleteData

A flag informing the Manager server to delete the transaction data immediately when it receives the delivery confirmation message.

Use this option only if you have delivered data into a high available storage system, and you have very strict data retention policies.

completedMarker

A flag to specify whether to create a zero length completed.txt file in the data delivery directory once all the transaction data has been delivered.

This option is useful for folder watch deliver integration systems which will perform ELT operations when a marker signal file appears in a directory.

serviceName

The name of a Groovy script service to call when all the transaction data has been written into the delivery directory.

Only delivery type services can be used for delivery integration.

The subDir pattern options include:

Pattern Variable Description

clientCode

Form's organization client code identifier

formCode

Unique form code identifier

formVersion

Form version number

formStatus

Transaction form status: [ Completed | Abandoned ]

portal

Name of the portal or form space

submissionId

Transaction submission identifier

receiptNumber

Transaction receipt number

submitKey

Transaction submit key GUID

trackingCode

Transaction tracking code

transRefNumber

Transaction Trn Ref Number

yyyy

Year; for example, 2015

mm

Month of year; for example, 08

dd

Day of month; for example, 01

Note that TIG will monitor any changes to the delivery configuration file and make these available immediately. However if you change the polling internal configuration, you will need to restart the TIG service for this change to take effect.

Proxy Config

The proxy configuration file defines internal services which may be called via Gateway Proxy calls.

The sample proxy-config.json installed with TIG is shown below.

[
	{
		"route": "google-search",
		"serviceUrl": "https://ajax.googleapis.com/ajax/services/search/web",
		"connectionTimeout": 10000,
		"returnErrors": true,
		"parameters": [
			{ "name": "v", "value": "1.0" }
		]
	}
]

This configuration specifies a collection of proxy services routes. The proxy attributes include:

Name Description

route

Proxy service route URL path

serviceUrl

Internal service API URL to call

headers

HTTP headers to add to the internal Service API call

parameters

HTTP request parameters to add to the internal Service API call

basicAuth

The HTTP Basic authentication header required to execute the call when performing a Service API Gateway call. The basic auth header is a Base64 encode username:password value.

connectionTimeout

The connection and socket transfer timeout in milliseconds for the internal Service API call. The default timeout is 10 seconds.

returnErrors

Return Groovy script errors to the caller when performing a Service API Gateway call. Use this option when developing scripts, but not in production. Default value is true.

An example of the proxy routing configuration is shown below:

  1. URL request from Manager to TIG:

    GET https://service.mycorp.com/tig/proxy/google-search/?q=Avoka
  2. TIG extracts gateway route path:

    address-lookup
  3. TIG looks up proxy route and makes internal call using the serviceUrl, for example:

    GET https://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Avoka

Services Config

The services configuration file defines Groovy script services which may be invoked via Gateway Service calls, via Deliveries or via Scheduled Jobs.

The sample services-config.json installed with TIG is shown below.

[
	{
		"serviceName": "delivery-email",
		"serviceType": "delivery",
		"groovyScript": "$tig/config/groovy/delivery-email.groovy",
		"parameters": [
			{ "name": "emailUrl", "value": "https://outlook.office365.com/EWS/Exchange.asmx" },
			{ "name": "emailUser", "value": "username@server.com" },
			{ "name": "emailPassword", "value": "password" }
		]
	},
	{
		"serviceName": "delivery-example",
		"serviceType": "delivery",
		"groovyScript": "$tig/config/groovy/delivery-example.groovy"
	},
	{
		"serviceName": "job-example",
		"serviceType": "scheduled",
		"groovyScript": "$tig/config/groovy/job-example.groovy" 
	},
	{
		"serviceName": "google-search",
		"serviceType": "gateway",
		"groovyScript": "$tig/config/groovy/google-search.groovy",
		"groovyTypeChecked": false,
		"executionTimeout": 10000,
		"returnErrors": true,
		"parameters": [
			{ "name": "urlBase", "value": "http://ajax.googleapis.com/" }
		]
	},
	{
		"serviceName": "template-example",
		"serviceType": "gateway",
		"groovyScript": "$tig/config/groovy/template-example.groovy",
		"parameters": [
			{ "name": "Test Mode", "value": "false" }
		]
	}
]

This configuration specifies a collection of Groovy services. The service attributes include:

Name Description

serviceName

Groovy service name, should be unique

serviceType

The type of Groovy service: [ delivery | gateway | scheduled ]

  • delivery services can be used for performing transaction delivery
  • gateway services can be called via REST service API
  • scheduled services can be called by scheduled Quartz Jobs

groovyScript

A Groovy script file path

The $tig variable is the TIG relative path location.

groovyTypeChecked

Perform strict Java style Groovy type checking before executing the script. Default value is false.

executionTimeout

End execution of the Groovy script if it takes longer than the specified number of milliseconds. Default value is 0 meaning no timeout.

returnErrors

Return any Groovy script errors to the caller when performing a Service API Gateway call. Use this option when developing scripts, but not in production. Default value is true.

basicAuth

The HTTP Basic authentication header required to execute the call when performing a Service API Gateway call

The basic auth header is a Base64 encode username:password value.

parameters

Collection of parameters to pass to the Groovy script as a parameters map. This is useful for externalizing configuration values.

Note

TIG will monitor any changes to the Groovy configuration file and Groovy script files and make these available immediately.

Gateway Services Config

Groovy services with the type gateway can be called externally from Manager using the gateway service URL. The URL path is used to resolve the name of the service to execute.

An example of the gateway service configuration is illustrated below:

  1. URL request from Manager to TIG:

    GET https://service.mycorp.com/tig/service/google-search/?q=Avoka
  2. TIG extracts service name path:

    google-search
  3. TIG looks up service name called "google-search" and invokes the gateway service type.

Only services with the type gateway can be called externally. Attempting to call a delivery or scheduled type service will result in a HTTP 404 Not Found status code being returned.

Scheduler Config

The scheduler configuration file defines Quartz job schedules for invoking Groovy services. Only services with the scheduled service type can be called by Quartz scheduled jobs.

The sample scheduler-config.json installed with TIG is shown below.

[
	{
		"jobName": "Cron Job",
		"jobType": "cron",
		"cronExpression": "0 30 1 * * ?",
		"serviceName": "job-example"
	},
	{
		"jobName": "Simple Job",
		"jobType": "simple",
		"repeatIntervalMins": 10,
		"serviceName": "job-example"
	}
]

This configuration specifies a collection of Groovy service job schedules. The job schedule attributes include:

Name Description

jobName

Name of the job

jobType

Job type: [ cron | simple ]

cronExpression

A cron scheduling expression, for cron type jobs only. For details, see Quartz Tutorials, Lesson 6: CronTrigger.

repeatIntervalMins

Repeat interval in minutes, for simple type jobs only

serviceName

Name of the Groovy service to call when the job is triggered

Note

If you make changes to scheduler-config.json, you must restart the TIG server for these changes to take effect.

Storage Config

The storage configuration file defines customer transaction data storage options.

The sample storage-config.json installed with TIG is shown below.

{
	"user": "administrator",
	"password": "tuart!23",
	"dataDir": "C:/tig/storage/"      
}

The storage attributes include:

Name Description

user

The BASIC authentication login user

This value should match the Manager TIG Service Connection Username.

password

The BASIC authentication login password

This value should match the Manager TIG Service Connection Username.

dataDir

The customer transaction data storage area

Note

If you make changes to storage-config.json, you must restart the TIG server for these changes to take effect.

The image below shows the Manager configurations for a Transact Integration Gateway Service Connection.

The image below shows a Manager configuration for the Hybrid Cloud Submission Data Storage service using Transact Integration Gateway.

Next, learn about developing with Transact Integration Gateway.