What are you looking for?

    Didn't find what you were looking for?

    Extend your Search in Community

    Got any questions?

    We're always happy to help with questions you might have. Contact Us

    Didn't find what you were looking for?

    Extend your Search in Community

    Got any questions?

    We're always happy to help with questions you might have. Contact Us

Journey Platform Topics

Transact Integration Gateway

   Journey Manager (JM) Previously known as Transact Manager (TM). |   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.

Overview

Transact Integration Gateway (TIG) is a lightweight gateway for performing on premise business integration. Customers using a cloud environment often have integration requirements for:

  • Dynamic data lookups or data validations to internal systems.
  • Straight through processing, when customers submit applications.
  • Background transaction delivery integration in internal systems.
  • Uploading form prefill reference data to the cloud servers.

Using the Transact Integration Gateway, customers can implement integrations like these quickly without additional software licenses.

If you already have integration gateway capabilities with solutions such as IBM Power Gateway or Mulesoft API Gateway, you may choose to use these. However, if you don't need the complexity of these solutions, the simpler Transact Integration Gateway may be suitable, and is an excellent option for performing delivery integration.

The Journey SDK for Java provides a Java API for Manager services, so you can build applications that integrate directly with them. Journey SDK documentation is included in the Journey SDK download package (authentication required) available on the Community web site.

Note

TIG is largely unchanged since TIG v4.3, so it is compatible with current Transact and Journey platform releases.

Usage and Deployment Models

The deployment model for TIG is to install the application on premise inside a DMZ or a secure location. The application is designed to be very easy to install and configure. You can literally install the application and perform transaction data delivery within minutes.

For High Availability (HA) deployment models you would typically install the two TIG applications on separate servers in different availability zones. TIG uses a stateless architecture, with configuration maintained in local JSONJSON (JavaScript Object Notation) is a syntax for storing and exchanging data and is used in Maestro to store forms. If a Form Builder wants to transfer their form to another system, they can do so by using the Download JSON file button. configuration files. There is no requirement for a shared database to support HA usage.

Delivery Integration

A typical use of TIG is to perform transaction delivery integration. In this deployment model, TIG is used to pull down completed transactions from the Cloud Hosted Journey Manager servers, and deliver this data into internal systems.

This usage model is illustrated in the diagram below.

For straight delivery integration, there is no requirement for TIG to be externally accessible. All network calls are outgoing from TIG to Manager servers. To complete transaction delivery, TIG needs to be able to write transaction data files to a secure and high availability file store such as a SAN, or it should be able to call other internal systems to complete delivery.

When internal transaction delivery has been completed, TIG will send a positive delivery confirmation message to the Manager server. Once this has been done, the transaction data on the server can either be deleted immediately or made available for scheduled data purging.

Service API Gateway

TIG can be used as a Service API Gateway to enable Cloud Manager servers to make real-time (synchronous) API calls to internal business systems. These calls are typically to perform operations like:

  • perform a security check before the user opens a saved form
  • prefill a form with the customer's profile data
  • make a form dynamic data call to perform data verification, such as Identity Verification (IDV)
  • straight through processing, when a customer submits an application resulting in an account being opened and the details returned to the user

This usage model is illustrated in the diagram below.

Operating as a Service API Gateway, TIG supports two modes of operation:

By using TIG as a Service API Gateway, access to internal systems can be strictly controlled and no internal network information is exposed externally.

Gateway Security

To provide security access control policies to protect internal Service APIs, we recommend a combination of the following security controls:

  • Transport Layer Security (TLS) protection for all network calls
  • IP address white list with TIG only accepting calls from configured Manager servers (configured on switch and TIG)
  • BASIC authentication over TLS, with TIG only allowing authenticated requests
  • Virtual Private Network (VPN) between business data center and AWS Virtual Private Cloud (VPC)
  • Mutual SSL authentication between Manager calls and TIG

TIG utilizes Apache for TLS termination and uses ModSecurity as an Web Application Firewall (WAF) to provided additional protection to the Service API Gateway.

Reference Data Integration

Another use for TIG is to upload reference data from business systems into Cloud Hosted Manager servers where it can be used for form prefill or form dynamic data.

This usage model is illustrated in the diagram below.

For uploading reference data, there is no requirement for TIG to be externally accessible. All network calls outgoing from TIG are to Manager servers.

TIG provides a Quartz Job scheduler facility which is used for performing background jobs. The job scheduler supports sophisticated CRONCron is a time-based job scheduler in Unix-like computer operating systems. People who set up and maintain software environments use cron to schedule jobs (commands or shell scripts) to run periodically at fixed times, dates, or intervals. expressions and simple interval based scheduling to invoke GroovyGroovy is a powerful scripting language which runs on the Java Virtual Machine. Across theJourney platform, Groovy is used to create services in Manager. These services are primarily used to create plug-in style systems that interact with Manager. scripts to perform integration tasks.

Installation

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

On Windows servers 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.

Groovy Development

TIG provides the same integration libraries as Manager for performing Groovy script development. This provides a wide range of options for performing simple and sophisticated integrations.

For details on the Groovy language, see the Groovy Language Syntax Specification.

Security Restrictions

The TIG Groovy 2.4.5 runtime is the same one provided with Manager and includes a number of security restrictions to prevent scripts from terminating the application server.

Script Development

A good way of developing TIG Groovy scripts and making configuration changes is to use a code editor and point it at the TIG config directory. Any changes you make to your Groovy scripts will be loaded immediately by TIG, and your scripts will be interpreted dynamically. This enables you to quickly develop and test scripts without having to go through lengthy compile and deployment cycles. The development experience is much like writing JavaScript.

A good code editor to use for this is the free Microsoft Visual Studio Code. In Visual Studio Code, open a TIG configuration directory to edit your Groovy scripts and configurations.

Delivery Service Script

A delivery type service Groovy script example is shown below. This script details the Groovy script parameters and error handling.

/** Groovy Delivery Script
 
	This Groovy script should perform any transaction delivery.
 
	If the delivery integration fails, then the script can throw an exception and the
	delivery will not be completed in Transaction Manager and can be retried again at a later point.
 
	If the script does not throw an exception, the transaction will be considered
	to have been delivered, and TM will be notified that delivery has been completed.
 
	At this point Transaction data will be available for purging.

	Script parameters:
		serviceName : String
		parameters  : Map<String, String>
		transaction : com.avoka.transact.service.delivery.Transaction
		deliveryDir : String      
 */
import com.avoka.core.groovy.GroovyLogger as logger

def deliveryInfo = """
   serviceName: $serviceName
    parameters: $parameters
transaction.id: $transaction.id
   deliveryDir: $deliveryDir
"""

logger.info deliveryInfo

The Groovy delivery service example below performs an Email delivery to the Microsoft Exchange Email server and includes the form XML, PDF receipt and file uploads as attachments to the email. The example externalizes email service configurations to service parameters.

/** Groovy Delivery Script

	This Groovy script should perform any transaction delivery.
	
	If the delivery integration fails, then the script can throw an exception and the
	delivery will not be completed in Transaction Manager and can be retried again at a later point.
	
	If the script does not throw an exception, the transaction will be considered
	to have been delivered, and TM will be notified that delivery has been completed.
	
	At this point Transaction data will be available for purging.
	
	Script parameters:
		serviceName : String
		parameters  : Map<String, String>
		transaction : com.avoka.transact.service.delivery.Transaction
		deliveryDir : String
 */
import com.avoka.core.groovy.GroovyLogger as logger
import com.avoka.transact.service.delivery.Transaction
import com.avoka.transact.service.delivery.Transaction.Attachment
import microsoft.exchange.webservices.data.core.*
import microsoft.exchange.webservices.data.credential.*
import microsoft.exchange.webservices.data.core.service.item.EmailMessage
import microsoft.exchange.webservices.data.core.enumeration.misc.ExchangeVersion
import microsoft.exchange.webservices.data.property.complex.MessageBody

logger.debug """$serviceName parameters: $parameters"""

// Create Exchange WS client
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010_SP2)
service.setUrl(new URI(parameters.emailUrl))
service.setCredentials(new WebCredentials(parameters.emailUser, parameters.emailPassword))

// Create email subject line and message body
def subject = """$transaction.formCode Submission: $transaction.id"""

def body = """
<pre>
    Form Name: $transaction.formName
Tracking Code: $transaction.trackingCode
        Email: $transaction.contactEmailAddress
</pre>
"""

// Send email with attachments
EmailMessage msg = new EmailMessage(service)
msg.getToRecipients().add(parameters.emailUser)
msg.setSubject(subject)
msg.setBody(MessageBody.getMessageBodyFromText(body))
msg.getAttachments().addFileAttachment("form.xml", transaction.xmlData)
msg.getAttachments().addFileAttachment("receipt.pdf", transaction.receiptData)
for (Attachment attachment : transaction.attachments) {
	def name = "attachment-" + attachment.id + "-" + attachment.fileName
	msg.getAttachments().addFileAttachment(name, attachment.fileData)
}
msg.send()

// Log message
logger.info """$subject  email sent to: $parameters.emailUser"""

Gateway Service Script

A gateway type service Groovy script is shown below. This script details the Groovy script parameters and error handling.

/** Groovy Servlet Script

	This Groovy script should perform its business logic using request context information
	and return its textual results.
	
	To render the response directly the script can use the HttpServletResponse response object
	and then return null. The GroovyServlet will then consider the operation to be completed.
	
	When handling internal errors, an error code should be send on the response object
	and the script should return null.
	
	If the script throws an exception the GroovyServlet will write the error to the
	server log file and return a HTTP 500 Server Error to the caller.
	
	Script parameters:
		serviceName : String
		parameters  : Map<String, String>
		request     :  javax.servlet.http.HttpServletRequest
		response    : javax.servlet.http.HttpServletResponse

	Script return:
		textual string data
 */
import com.avoka.core.groovy.GroovyLogger as logger
import com.avoka.component.http.GetRequest

def url = parameters.urlBase + 'ajax/services/search/web?v=1.0&q=' + request.getParameter('q')

def httpResponse = new GetRequest(url).execute()

response.setContentType('application/json')

return httpResponse.getTextContent()

Scheduled Service Script

A scheduled type service Groovy script is shown below. This script details the Groovy script parameters and error handling.

/** Groovy Job Script

	This scheduled Groovy script should perform its business logic.
	
	Any exceptions thrown will be logged to the server log file.
	
	Script parameters:
		jobName     : String
		serviceName : String
		parameters  : Map<String, String>
 */
import com.avoka.core.groovy.GroovyLogger as logger

def jobInfo = """
	jobName:     $jobName
	serviceName: $serviceName
	parameters:  $parameters
"""

logger.info jobInfo

Adding JAR Libraries

To include additional Java libraries (JAR) for use by Groovy scripts, place these libraries in the placeholder JBoss modules folder:

C:\avoka\transact\tig\server\modules\com\avoka\custom\main

Next, edit the modules.xml file to reference your included JAR files:

C:\avoka\transact\tig\server\modules\com\avoka\custom\main\modules.xml

For example:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.avoka.custom">
	<resources>
		<!-- Include your JAR libraries  here. -->
		<resource-root path="custom.jar" />
	</resources>
	<dependencies>
		<!-- Included your library module dependencies here. -->
		<module name="system" />
	</dependencies>
</module>
Note

You must restart the TIG service for these libraries to become available.

If your JAR file has dependencies on third party libraries, you should also include these files in this modules directory.

If the server has troubles loading your JAR files, you will typically see these when the server starts up or when you call your Groovy script.

Logging

To monitor the activity of TIG, see the server log file:

C:\avoka\transact\tig\server\standalone\log\server.log

When developing Groovy scripts, you can use the GroovyLogger to log DEBUG, INFO, WARN and ERROR messages to the server log file

import com.avoka.core.groovy.GroovyLogger as logger

logger.debug 'Started service call'

// ...

logger.debug 'Completed service call'

To tune the server logging output, edit the standalone.xml configuration file in:

C:\avoka\transact\tig\server\standalone\configuration\standalone.xml

By default, the GroovyLogger will only log INFO and above level messages.

See the JBoss standalone XML elements below for the various configuration options:

<subsystem xmlns="urn:jboss:domain:logging:1.1">
	<console-handler name="CONSOLE" autoflush="true">
		<level name="INFO"/>
		<formatter>
			<pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
		</formatter>
	</console-handler>
	<periodic-rotating-file-handler name="FILE" autoflush="true">
		<level name="INFO"/>
		<formatter>
			<pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
		</formatter>
		<file relative-to="jboss.server.log.dir" path="server.log"/>
		<suffix value=".yyyy-MM-dd"/>
		<append value="true"/>
	</periodic-rotating-file-handler>
	<logger category="com.avoka.core.groovy.GroovyLogger">
		<level name="INFO"/>
	</logger>
	<root-logger>
		<level name="INFO"/>
		<handlers>
		<handler name="CONSOLE"/>
		<handler name="FILE"/>
		</handlers>
	</root-logger>
</subsystem>

Next, learn about the Temenos Journey Platform overview.

Feedback

Did this topic provide the information you need or leave you wanting to know more? Is there some way we can make this topic better? Let us know how we can improve this documentation.

Contact Us

Community

Our Community is a dynamic, user-driven source of information that provides a home for sharing Journey platform knowledge where you can ask questions and get answers quickly.

Explore Community

Support

Temenos is committed to supporting our customers with Journey platform solutions installed in the cloud or on premise. Learn more about our Customer Care Team, and its policies, procedures, and processes.

Learn More