Skip to content

Host Link Scripting Interface#

It is possible to interface to SHARK using Groovy Scripting. This allows SHARK to interface to most systems without customizing the program it self, but it requires some knowledge in programming.

Importing Order using the Script Importer#

Activate the scripting interface from System Configuration menu.

Order Acknowledge by Scripting#

To get full control of how the format of the generated acknowledge response is, a Groovy script can be used for the formatting. Since Groovy is a general script language, it can be used for file generation, web services, database access etc.

The internally SHARK always generates an XML data structure for acknowledgement/confirmation when a order has been fulfilled. The scripting interface allows a Groovy script to interpret the XML and do whatever is required.

The configuration can be done by using the standard menu for configuration

Information flow in SHARK:

flowchart
    sp(Stored Procedure: Document_MakeOrderState<br>Port: OrderAck ) -- XML_Document --> Table_Documents
    Table_Documents -- XML_Document --> ScriptController("OrderAck")
    ScriptController -- Call Groovy Script --> GroovyScript
    GroovyScript -- some_data --> out(Groovy script output)

Typical interfaces where scripting fits well:

  • Generation of other file formats than XML (an alternative here is also to use XSLT to make the conversion).
  • Interface to REST Web Services.
  • Interface to SOAP Web Services.
  • Integration to databases.

Example on configuration of the script exporter

When the script is called, the following variables are defined:

Name Java Type Description
document DocumentVO This is the basic document. Use document.getXMLData() to get the XML code as a String.
slogger SLogger Logger class used for logging info, errors, etc. to the SHARK system log.
development boolean True if the script is running from the editor in a debug environment.
tmpFolder String Temporary folder if the script needs a working area
receiver String Name of the receiver.

External classes:

  • dk.logiware.sharklink.models.DocumentVO
  • dk.logiware.sharklink.SLogger
Script Example 
import java.text.SimpleDateFormat 
import java.util.Date

// Folder where files are written
def exportFolder = new File('/Users/sos/tmp')

// Parse the XML document from SHARK Document System
def xmldoc = new XmlParser().parse(document.getXMLData())

// Format a datetime string for the filename
def dateString = new SimpleDateFormat("yyyyMMddHHmmss").format(new Date()) 

// Define the filename
def filename = xmldoc.OrderNumber.text() + dateString + ".csv"

// Get parameters for the file from the XML document
def ordernumber = xmldoc.OrderNumber.text()
def state = xmldoc.State.text()

// Write the file
new File(exportFolder, filename).write("$state,$ordernumber")

Calling a REST or SOAP Web Service

Libraries good for call web services:

  • groovy-wslite - https://github.com/jwagenleitner/groovy-wslite. Supports both REST and SOAP, but the library is only available as standard in newer SHARK version.
  • Groovy HTTPBuilder . See for example JavaWorld.

Using the SLogger#

The SLogger class is accessible through the instance slogger, available when the script is called. The log will go the general target for the logs, typical the database. Can be viewed in the System Log.

Code Examples

Example: 

slogger.logError(String message, int errorCode, Exception exception)
slogger.logError(String message, int errorCode, Exception exception)
slogger.logError(String message, int errorCode, Exception exception, String orderNumber, String detailed)

slogger.logInfo(String message)
slogger.logInfo(String message, int errorNumber)
slogger.logInfo(String message, int errorNumber)
slogger.logInfo(String message, String detailedMessage, String order, int errorNumber)

slogger.logDebug(String message)
slogger.logDebug(String message, String detailedMessage, String order, int errorNumber)

slogger.logWarning(String message, int errorCode)

The errorCode is an integer and there is a number of predefined error codes in the ErrorCode object. If you create your own codes, it is recommended to make them in the range 4000-4999.

Report Order State Changing by Groovy Scripting#

This is only partly supported and required manually configuration.

To get full control of how the format of the generated acknowledge response is, a Groovy script can be used for the formatting. Since Groovy is a general script language, it can be used for file generation, web services, database access etc.

Information flow in SHARK:

flowchart
    sp(Stored Procedure: Document_MakeOrderState<br>Port: OrderStateChanged ) -- XML_Document --> Table_Documents
    Table_Documents -- XML_Document --> ScriptController("OrderStateChanged")
    ScriptController -- Call Groovy Script --> GroovyScript
    GroovyScript -- some_data --> out(Groovy script output)

The configuration must be done in the SHARK Registry, there is no simple dialog for the configuration.

Define a port using the type: dk.logiware.documents.PortGroovy

Define a port name that matches the document to grab (Probably OrderStateChanged)

The script is defined either as file or as a script name, using the parameter: ScriptName

Example on configuration of the script exporter

When the script is called, the following variables are defined:

Name Java Type Description
document DocumentVO This is the basic document. Use document.getXMLData() to get the XML code as a String.
slogger SLogger Logger class used for logging info, errors, etc. to the SHARK system log.
development boolean True if the script is running from the editor in a debug environment.
tmpFolder String Temporary folder if the script needs a working area
receiver String Name of the receiver.

External classes:

  • dk.logiware.sharklink.models.DocumentVO
  • dk.logiware.sharklink.SLogger
Script Example - Create a file name 
import java.text.SimpleDateFormat 
import java.util.Date

// Folder where files are written
def exportFolder = new File('/Users/sos/tmp')

// Parse the XML document from SHARK Document System
def xmldoc = new XmlParser().parse(document.getXMLData())

// Format a datetime string for the filename
def dateString = new SimpleDateFormat("yyyyMMddHHmmss").format(new Date()) 

// Define the filename
def filename = xmldoc.OrderNumber.text() + dateString + ".csv"

// Get parameters for the file from the XML document
def ordernumber = xmldoc.OrderNumber.text()
def state = xmldoc.State.text()

// Write the file
new File(exportFolder, filename).write("$state,$ordernumber")