XML-API Application Interface

Transcription

1 XML-API Application Interface Introduction SilentFax is designed to be a network fax delivery system. It can deliver received faxes to users either by or over the network, and users can send out a fax by printing from the SilentFax printer. SilentFax XML-API is designed to allow an application program ( the App ) to receive and/or to send faxes automatically without any direct human intervention. For example, your customers can place orders on your web site and your web application can use the SilentFax XML-API to send a confirmation fax. Although both inbound and outbound sides are implemented, XML-API is mostly about generating outgoing faxes in an automated manner. As explained later, there is no API for incoming faxes, although SilentFax can generate an XML information file in the context of archiving feature. Overview Roughly speaking, SilentFax XML-API works by placing a set of files in monitored and shared folders. The set includes one XML-API file and one or more document files. When SilentFax detects an XML-API file in the monitored folder, it handles the request to generate an outgoing fax. Generating a faxable TIFF/F file is an important step in the XML-API operation. Besides providing some basic information (recipient s name, fax number and so on), the XML-API file must also provide information about the given document files and other predefined files to be used. The conversion capabilities and required XML tags are described later in this document. The shared folder is another important area. In some cases, the shared folder (-i.e. Windows Networking-) may be the simplest way of moving the XML-API and document files to a folder in the SilentFax server. In some cases, however, using shared folder may not be SilentFax XML API Developer s Guide Preliminary Release Page 1

2 feasible because of permissions and security concerns. For such cases, SilentFax XML-API package offers different alternatives as described in the Transport Mechanism section. All XML-API requests are handled on behalf of a user mailbox. After the completion of the fax transmission, SilentFax will return a transmission report to this user. In many cases, this may not necessarily be the desired action. By using XML-API Administration HTML Application (HTA), you can specify what SilentFax should do for successfully transmitted or failed faxes. The XML-API Administration HTA is explained later in this document. Generating a Faxable TIFF/F File There are number of XML tags used in the XML-API to describe the input document files so that SilentFax can generate a TIFF/F file as desired. Currently SilentFax XML-API can generate a faxable TIFF/F file from three input file formats: Plain Text You may provide a simple text (ASCII) file and SilentFax can create a faxable file by placing the text onto a predefined overlay/logo page. XML Form In a form application, you may provide a file which contains the form information, and SilentFax can combine the information with a predefined form template and overlay the result on a blank overlay/logo page. TIFF/F You can provide a TIFF/F file in which case SilentFax XML-API just verifies the file. Therefore, the contents of the control file for outgoing AIX requests plays a very important role. This is the API that allows applications to control the SilentFax server. SilentFax XML API Developer s Guide Preliminary Release Page 2

3 XML-API Administration HTA XML-API Administration is implemented as an HTML application. It is located in the C:\SFServer\HTA folder. Since it referred often, you may want to create a shortcut on the desktop. Screenshots More explanation to be provided later. SilentFax XML API Developer s Guide Preliminary Release Page 3

4 SilentFax XML API Developer s Guide Preliminary Release Page 4

5 XML-API Tags XML Tag Prop Description <DOCUMENT> Must Description of one input document <DOC_TYPE> Must Document Type: PLAINTEXT, FORM_XML, TIFF <DOC_FILE> Must Name of the input document file <DELIVERY_TYPE> Must Must be FAX. The option to be implemented. <DELIVERY_DESC> Description. Used by the Inbox entry for your reference. <DELIVERY_ADDRESS> N / A Fax telephone number or address. Not implemented yet, use <TO_TELNO> tag. <TEMPLATE> Must Pre-defined form template to be used in XML form applications. Plaintext always uses PlaintextTemplate.xml <OVERLAY> <FROM_MBX> Predefined overlay/logo page User mailbox sending this fax, therefore the result of transmission will be sent to this mailbox. If exists, it overwrites the default mailbox specified in XML-API Administration. <COVERPAGE> N / A Coverpage option. Not implemented yet. <FROM_NAME> <FROM_COMPANY> <TO_NAME> <TO_COMPANY> Sender s name. This will appear in the coverpage. Sender s company name. This will appear in the coverpage. Recipient s name. This will appear in the coverpage. Recipient s company name. This will appear in the coverpage. <TO_TELNO> Must Fax telephone number. This must be supplied. <SUBJECT> Subject field. This will appear in the coverpage. SilentFax XML API Developer s Guide Preliminary Release Page 5

6 XML-API Example: Sending a text document The following example demonstrates an XML API request where The text file, wikipedia.txt will be formatted according to the origin X, origin Y, width, height and font information specified in PlaintextTemplate.xml. The formatted text will be placed over the overlay tiff file, VP_SmCenter.tif. No coverpage is specified. No user mailbox is specified, the default mailbox will be used. <SILENTFAX_AIX> // Description of the input text file <DOCUMENT> <DOC_TYPE>PLAINTEXT</DOC_TYPE> <DOC_FILE>Wikipedia.txt</DOC_FILE> </DOCUMENT> // To be delivered by fax <DELIVERY_TYPE>FAX</DELIVERY_TYPE> <DELIVERY_DESC>AIX-Outbound Fax</DELIVERY_DESC> // Predefined template filename to format the text <TEMPLATE>PlaintextTemplate.xml</TEMPLATE> // Predefined overlay/logo file <OVERLAY>VP_SmCenter.tif</OVERLAY> // User mailbox not specified <FROM_MBX> </FROM_MBX> // Fax telephone number must exists <TO_TELNO> </TO_TELNO> </SILENTFAX_AIX> SilentFax XML API Developer s Guide Preliminary Release Page 6

7 XML-API Example: XMLForm document The following example demonstrates an XMLForm application. <DOCUMENT_FILE> ( ZFormInfo.xml ) provides the values. The form fields will be populated by these values. <TEMPLATE> tag value ( ZTemplate.xml ) defines a predefined form. (Conceptually, this is similar to an HTML form). The form may include some static text such as field names and some dynamic fields. The dynamic fields specify tag names which are later searched in the document file. Example: Template <ITEM type='label' >Date/Time:</ITEM> Static label <ITEM type='field' >DATE</ITEM> Dynamic field tag name Document <DATE> June 12, :30 </DATE> Dynamic field value The formatted text will be placed over the overlay file, ZLogo.tiff. <SILENTFAX_AIX> // Document is an XML file which includes data values to be used // to fill in the form fields as specified by the template XML file. <DOCUMENT> <DOC_TYPE>FORM_XML</DOC_TYPE> <DOC_FILE>ZFormInfo.xml</DOC_FILE> </DOCUMENT> // To be delivered by fax <DELIVERY_TYPE>FAX</DELIVERY_TYPE> <DELIVERY_DESC>AIX-Outbound Fax</DELIVERY_DESC> // Template XML defines a blank form <TEMPLATE>ZTemplate.xml</TEMPLATE> // Predefined overlay/logo file <OVERLAY>ZLogo.tif</OVERLAY> // User mailbox the transmission result will be reported to this user <FROM_MBX>201</FROM_MBX> // Fax telephone number must exists <TO_TELNO> </TO_TELNO> </SILENTFAX_AIX> SilentFax XML API Developer s Guide Preliminary Release Page 7

8 Sample Files and Quick Testing TBD SilentFax XML API Developer s Guide Preliminary Release Page 8