Transact Integration Gateway Setup

   PlatformApplicable to all products in Temenos Journey Manager.  |   System Manager / DevOps |  v4.3 & Higher   This feature is related to v4.3 and higher.

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. For example, if you want to install TIG v18.11 (tig-version will be v18.11).
2. Identify the JDK version (jdk-version) that is required when installing the tig-version version of Journey Manager. For example, if you use Journey Manager 18.11, the JDK will be JDK 11 (jdk-version = JDK 11).
3. jdk-version is the JDK version required when installing the TIG version identified in the first step. In this example, we need JDK 11 installed on our system in order to install TIG v18.11

Transact Client SDK

If you're using TIG in your Temenos Journey Manager 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 Temenos Journey Manager 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.

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": "[email protected]" },
			{ "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.

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

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

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.