The Document System

The Document System

The Document System is used to export Documents created by SHARK as for example:

• Transaction acknowledgement. A confirmation of a pick or store operation.
• Stock reports.
• Delivery Notes.
• Shipment Documents.

There is a Document Browser in Shark under the "Maintenance" menu, for viewing generated documents.

The SHARK Link Document Exporter supports printing of paper or electronic documents like delivery notes, reports, transport documents, etc. The source of the generated document is always an XML document in the table "Document" in the database.

The basic components in the Document System

Basic Configuration

Configuration of the Document Job

The Document Exporter must be configured as a Shark Scheduler job.

Registry: Scheduler -> Jobs -> DocumentExport

Entry	Value	Notes
ClassName	dk.logiware.SHARKlink.jobs.DocExporter	Use the DocExporter module as job.
Enabled	True	Enable job to run
Name	DocumentExport
TriggerType	RepeatSeconds	Specify the job to run at fixed intervals
TriggerValue	180	Normal setup is to run every 180 seconds. Internally the DocExporter will repeat requests every 5 seconds.

Leave other parameters at default.

Typical setup of the Document Exporter

Document Ports

A outbound port in Shark is a way to export various data to external systems. Shark generates the data as XML and send the data to the requested port. The port is responsible for formatting the data to the required format. For each port a receiver is also specified, the receiver handles the actually transport of the formatted data, this could be for example be as a file, FTP or email.

The following default ports are used, more can be assigned if needed:

• OrderAck: General port used for confirmation of orders picked and stored as well as stock adjustments.
• DeliveryNote: An XML structure keeping information for the creation of a delivery note.
• StockReport: Automatic, typical nightly generated stock report.
• ASN: Advanced Shipping Notification, shipment information from the consolidation process.
• ParcelList: Shipment information from the consolidation process.

'

Standard setup for the Port handling order acknowledge.

FileNameFormat

The field FileNameFormat defines the file name of a generated file. It has some place holders for variables:

Place holder name	Description
%DocNumber%	This is the DocumentID from the table "Document" in the database. The number is unique and incremented for each new document.
%Sender%	Name of the sender eg. Shark
%Receiver%	Name of the receiver if specified.
%DocType%	Type is the name of the document, can for example be "StockReport"
%Copy%	Number of times this document has been resend.
%Arg1%	Optional customizable argument from the Document table.
%Arg2%	Optional customizable argument from the Document table.
%Arg3%	Optional customizable argument from the Document table.
%Date%	Current date
%Time%	Current time of day.

The XML Port

Port that just forward the native XML, forward with an envelope and/or transform the XML using an XSLT transformation.

Registry: Scheduler.Jobs.DocumentExport.Parameters .Ports.\<name>

Entry	Value	Notes
Name	<name>	Name of the Port. Predefined: OrderAck (Order acknowledge)
Type	dk.logiware.documents.PortXML	The formatter used.
Receiver	<name of receiver>	Name of the receiver that should transport this document to the final destination. Default: Host
XSLT	XSLT name | <path to xslt file>	If a name is specified, the XSLT is defined in the Script table in the database.
RawMode	True|false	If false a document envelope will be added to the XML.
Encoding	<name of the encoding>	Default is UTF-8
LogFiolder	<path>|<empty>	A copy of the XML file will be stored in this folder if it is defined.

Jasper Report Port

The Jasper Report Port converts the standard XML document from Shark to a PDF print file. It requires a Jasper Report design file, that defines the layout of the generated document. This file with the extension .jasper is generated by JasperSoft Studie from a design file (.jrxml file).

JasperSoft Studio is a free tool and available from here. It allows design of advanced reports including logos etc. Usefull for generating picking lists, delivery notes, etc.

The overall concept of the JasperReport Port.

Registry: Scheduler à Jobs à DocumentExport à Parameters à Ports à \<name>

Entry	Value	Notes
Name	<name>	Name of the Port.
Type	dk.logiware.documents.PortJasperReport	The Jasper Report formatter.
Receiver	<name of receiver>	Name of the receiver that should transport this document to the final destination.
XPath	<xpath>	An XPATH to the element containing data to be printed
ReportDesignFile	<file path>	Specify a Jasper Report design file used for formatting the print. The file has the extension .jasper.
TmpFolder	<path to temp folder>	Folder used to hold the generated files temporarily, until it is delivered to the Receiver.

PDF Printer Port

Registry: Scheduler à Jobs à DocumentExport à Parameters à Ports à \<name>

Entry	Value	Notes
Name	<name>	Name of the Port.
Type	dk.logiware.documents.PortPDFPrinter	The FOP formatter is used.
Receiver	<name of receiver>	Name of the receiver that should transport this document to the final destination.
FoFileName	<file path>	FOP design file formatting the report.

Label Printer Port

Used for printer labels to label printers already with printer formattet content.

Entry	Value	Notes
Name	<name>	Name of the Port.
Type	dk.logiware.documents.PortLabelPrinter
Receiver	<name of receiver>	Name of the receiver that should transport this document to the final destination. Leave it blank to make the clients decide the printer (receiver)

Groovy Port

The Groovy script port can be used for various more specialized purposes. Is for example useful for integrating to REST or SOAP web services.

Entry	Value	Notes
Name	<name>	Name of the Port.
Type	dk.logiware.documents.PortGroovy
Receiver	<name of receiver>	Name of the receiver that should transport this document to the final destination. Leave it blank to make the clients decide the printer (receiver)
ScriptName	<name of script>	Groovy script to execute.

Example on creating a special designed ZPL label from a document using a Groovy Script

import dk.logiware.util.printing.PrinterZPLPreview
import dk.logiware.util.printing.ZPLFormatter
import dk.logiware.util.string.StrUtil

/* 
* Documentation: ZPL II Programming Guide Volume One
* 
* Create a ZPL label using the SHARK ZPLFormatter class.
* If running in development, the label will be previewed in a window and not
* actually printed.
*/

def xml = ""

// The development flag is set when running from the Script Editor

if (development) {
    xml = dk.logiware.shark.model.DocumentHandler.getDocument(331975).getXMLData();
    tmpFolder = "/users/sos/tmp"
} else {
    xml = document.getXMLData()
}
def outFile = new File(tmpFolder, "labelprint.prn")

// Delete the file, if it already exists
outFile.delete()

// Parse the XML document
def deliveryNote = new XmlParser().parseText(xml)

def labelLength = 0             
labelLength = 1100 + deliveryNote.OrderLine.size() * 60

// Create the label
ZPLFormatter label = new ZPLFormatter(200, 80, 200);
label.addCode("MNN")
label.setZero(0, 20);
label.addCode("LL" + labelLength.toString())
label.addBarcode(7,9, "2000" + deliveryNote.OrderNumber.text())
label.addSpace(1)

// Defining font type used for the label
// See "ZPL II Programming Guide Volume One", page 13 "^A" command   
label.setFontType("0")

// Font size (height, width in dots) for the header
label.setFontSize(80,40)

label.addTextLine(13, "DELIVERY NOTE")
label.addTextLine(18,deliveryNote.OrderNumber.text()) 
label.addSpace(2)
label.setTabs(0,8,33,44)
label.setTabLimits(20,20,20,20)

// Setting font size for following
label.setFontSize(33,16)

label.addTextLine("Date:", StrUtil.strFixedLength(deliveryNote.ExpDate.text(),10), "Cust.nr.: " + deliveryNote.CustomerNumber.text())
label.addTextLine("REf:", "  " + deliveryNote.Misc1.text(), "")
label.addSpace(5)
label.addTextLine("Invoice.adr","", "Del.Adr", "")
label.addTextMultiLine(deliveryNote.CustomerName.text(), "", deliveryNote.DeliveryAddress1.text())
label.addTextMultiLine(deliveryNote.CustomerStreet.text(), "", deliveryNote.DeliveryAddress2.text())
label.addTextMultiLine(deliveryNote.CustomerZipCode.text(), "", deliveryNote.DeliveryAddress4.text())
label.addTextMultiLine(deliveryNote.CustomerCity.text(), "", deliveryNote.DeliveryAddress3.text())
label.addSpace(5)

// Define the column positions
label.setTabs(0,4,33,43,50)

label.setTabLimits(5,25,6,6,6)
label.addTextLine("Qty", "Name", "Price", "Discount", "Price")
label.addCode("GB", "600", "0", "1")
deliveryNote.OrderLine.each {            
    label.addTextLine("")                           
    label.addTextMultiLine(
        it.DeliveredQty.text(), 
        StrUtil.strFixedLength(it.ItemName.text(),15), 
        it.Misc2.text(), 
        it.Misc1.text(), 
        it.Misc3.text())
    label.addTextLine("", it.ArticleNumber.text())
}
label.addSpace(10)

label.close();

try{
    outFile.write(label.toString())
}
catch (Exception e) {
    e.printStackTrace()
}

if (development){         
        println "Development mode" 
        println label.toString()        
        new PrinterZPLPreview(200,80,200, label.toString()).show() 
} else { 
        try {      
            if (receiver==null) println "Receiver is null"
            println "Send label to receiver: " + receiver.toString() + " in file " + outFile.toString()
            receiver.sendFile(outFile)  
        }
        catch (Exception e) {                  
          println "Error: " + e.getMessage()
        }
        finally { 
            outFile.delete()
        }
}

Document Receivers

The Receiver defines the transport of Documents to the final destination (the receiver).

The default receiver is a folder in the file system with the name “Host”.

Folder Receiver

This will send the document to a network folder.

Registry: Scheduler -> Jobs -> DocumentExport -> Parameters ->Receivers -> \<name>

** Entry**	Value	Notes
Name	\<name>	Name of the receiver
Type	Folder	Type of the receiver.
OutFolder	\<path to folder>	Folder where the generated file is placed.
MoveFilesAsTemp	false	true

FTP Receiver

The FTP receiver will send the file to an FTP server. 

Registry: Scheduler -> Jobs -> DocumentExport -> Parameters ->Receivers -> \<name>

Entry	Value	Notes
Name	<name>	Name of the receiver
Type	FTP	Type of the receiver.
FTP_Server	<server name>	Name or IP address of the FTP Server
FTP_Login	<login namer>
FTP_Password	<password>
FTP_Directory	<ftp type>:<directory path>	This is the directory on the FTP server where the file will be placed. It also defines the FTP protocol in use. Examples: ftp:/ sftp:/ ftps:/
FTP_TmpDirectory	<tmp path>	If specified the file will first be moved to this folder and then moved to the final folder. This will prevent the host from start reading the file before it is transferred.
FTP_Timeout_Sec	Integer	Default is "180". Time in seconds until connection timeout.
LogFolder	<path>	Local folder where a copy of the file will be stored.

Email Receiver

Send the document to an email address This can for example be used to send error reports to specific users. 

To make use of the Email Receiver, an SMTP Server is required. In general there are a lot of security issues with sending emails. If available, one possibility is to use an internal SMTP server, another alternative is to setup a GMAIL (Google Email) account that can be used. Please note that Google has some limitations to the number of emails that can be send each day.

Entry	Value	Notes
Name	<name>	Name of the receiver
Type	Email	Type of the receiver.
Protocol	BASIC|SSL|GMAIL|TSL	BASIC is the simple SMTP. SLL Uses a secure socket. TSL Uses TSL as protocol. GMAIL is for ... GMAIL
From	<from email address>
To	<To email address>	More email addresses can be separated by ";"
Subject	<subject text>
SendFileAsAttachment	true|false	If true the file will be attached as a separate file to the email. If false it will be embedded into the email, the file is the expected to contain HTML.
SMTP_Host	<host name>	Host for the SMTP Server used for sending the email.
SMTP_Password	<password>	SMTP Password
SMTP_User	<user>	SMTP user name, used for logging in to the SMTP server.
SMTP_Port	<port>	Port number used by the SMTP Host
BodyText		Some text in HTML or text, that will be at the top of the email.

Printer Receiver

Sends the document as formatted by the Port to a Windows printer. A typical example is printing of a PDF report generated by a JasperReport port.

Entry	Value	Notes
Name	<name>	Name of the receiver
Type	Printer	Type of the receiver.
PrinterNAME		Folder where the generated file is placed.
PrintCmd		Command used to print the pdf file, default is: FoxIt Printer.exe %Filename% %Printer% %Printer% is replaced by "PrinterNAME".

It is designed to use the pdf command line printing util from FoxIt, but any other command line utility can be used. The program foxit.exe must be in the "bin" folder of the SHARK installation.

Scripting Receiver

Scripting is supported using Groovy. Using scripting, it is possible to generate general ASCII and other files, but more complicated interfaces like web service clients and similar can be implemented as well.

The Groovy script will receive the XML document and must interpret the XML using the Groovy XML tools.

Variables defined to the script when started

Variabel	Type	Description
docFileName	String	Absolute path to a file containing the XML document.
slogger	Slogger	Object to the logger system.

Label Printer Receiver

This will print a formattet label directly to the specified label printer, using the standard SHARK label print system. The name of the receiver must be \<workstation>/\<printer name>