Transact Integration Gateway Development

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

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>

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, take a look at an overview of the Temenos Journey Manager.