Section - 2 : Setting Up the XML Add-On

---

With the XML add-on, you can import and export XML files while using Documaker Workstation and you can send and receive XML messages. Setting up the new import and export capabilities is similar to setting up any import/export file format.

To import and export XML files in Documaker Workstation, you use these XML add-on functions:

Function	This function lets you...
WXMImportXML	Import data from an XML file into a form set.
WXMExportXML	Export data from a form set to an XML file.
WXMEntryHookExtXMLLoad	Send messages from the system to any type of message server.
WXMImportXMLArchive	Send messages from the system to any type of message server.

Note: The ability to work with XML files is included in Documaker Workstation, but must be purchased separately by PPS users. You must also have a Docupresentment license to use the messaging features in the WXMEntryHookExtXMLLoad and WXMImportXMLArchive functions because they call Docupresentment files.

To use the XML add-on, you must first set up the import, export, and messaging functions. If applicable, you then set up Docupresentment.

Setting Up Documaker Workstation

To use the import and export functions, you must also add this control group and options to your FSISYS.INI or FSIUSER.INI file:

Option	Description
Ext	(Optional) Enter the extension for the output files. The default is XML.)
File	(Optional) Enter a file name, such as XMLEXP. If you omit this option the system prompts the user to enter the file name.
Path	(Optional) Enter the path, such as \xmlfile. If you omit this option, the system defaults to the current directory.
SuppressDlg	(Optional) Enter Yes to suppress the File Selection window. The default is No.

Follow the instructions below to complete the import, export, and messaging setup.

Setting Up the XML Export Format

Follow these steps to set up the XML export format:

1. Open the FSISYS.INI file in the resource library for which you want to use export files. You can use any text editor to open this file.

2. Locate the ExportFormats control group. Most text editors have a find or search function you can use to quickly find this group heading. Then add the following line:

   For this export format	Enter...
   XML	09=;XM;XML Export;WXMW32->WXMExportXML

   This assumes 09 is not already being used. Here is an example:

   < ExportFormats >

   09=;XM;XML Export;WXMW32->WXMExportXML

Setting Up the XML Import Format

Follow these steps to set up the XML import format:

1. Open the FSISYS.INI file in the resource library for which you want to use export files. You can use any text editor to open this file.

2. Locate the ImportFormats control group. Most text editors have a find or search function you can use to quickly find this group heading. Then add the following line:

   For this import format	Enter...
   XML	09=;XM;XML Import;WXMW32->WXMImportXML

   This assumes 09 is not already being used. Here is an example:

   < ImportFormats >

   09=;XM;XML Import;WXMW32->WXMImportXML

Setting Up the XML Message Format

To send a message from Documaker Workstation to a message handling program such as Docupresentment or MQSeries, you must add an option to either the ImportFormats or AFEProcedures control groups.

One example of sending and receiving a message from Documaker Workstation to a message handling program is to retrieve an archived record from Documaker Workstation via Docupresentment. You can do this two ways:

• Set it up as an import hook by adding the WXMImportXMLArchive function to ImportFormats control group.

  < ImportFormats >

  07=;XR;XML Import from IDS;WXMW32->WXMImportXMLArchive

  (This assumes 07 is not already being used.)

• Set it up as an entry hook by specifying the WXMEntryHookExtXMLLoad function as the parameter for EntryFormset option in the AFEProcedures control group.

  < AFEProcedures >

  EntryFormset = WXMW32->WXMEntryHookExtXMLLoad

Setting Up Docupresentment

If you are using Docupresentment as the message server, you must also add the INI options shown below to let Documaker Workstation retrieve an archived record from Docupresentment and load data into a form set before any data is entered by a user.

The archived record is retrieved using the Key1, Key2 and KeyID entered on the New Form Set window. For this to happen, you must set up the following request type in the DOCSERV.INI file for Docupresentment:

You can use any name for the archive library, as long as the same MRL name is used in Documaker Workstation.

You can set up this feature as an entry or import hook:

If you set it up as an entry or import hook, you must also set up these INI options:

Option	Description
DSIUseNTUserID	(Optional) Set this option to Yes to use the NT user ID. The default is No. This gives you a way to pass the NT user ID in the queue instead of the normal DMWS ID.
DSIVARS	(Optional) Enter variable;value, where variable is the variable name and value is its value. This lets you identify a constant list of variables to be sent in the queue.
DSIIgnoreTimeoutError	(Optional) Enter Yes to continue processing if a timeout occurs. The default is No. This gives you a way to ignore a timeout when waiting on a return queue.
DSIAttachedVarFile	(Optional) The default is DOCC_XML. Set this option to the attachment name if it differs from DOCC_XML. This gives you a way to specify the variable name the XML file is attached to.
DSIImportLevel	(Optional) This option is typically used by programmers. Enter 2 if you want the hook to operate on the FAP_MSGOPEN level. Enter 3 if you want it to operate on the FAP_MSGRUN level. The default is 2.
DSITimeout	(Optional) Enter the number of milliseconds you want for the time-out. The default is 60000 milliseconds or 60 seconds.
DSIReqType	(Optional) Enter the name of the request type of the message placed in the queue. The default is GETXML.
DSIRecordDFD	(Optional) Enter the name of a DFD file. The system tries to match variable fields sent in the request to field values in this DFD file. It then attaches the DFD record to the end of the message.

If the request for an XML file comes back with an error, as opposed to a time-out, Docupresentment displays an error message.

Using the Parser

The system uses the Expat XML parser, which was originally developed for Netscape. It is a third-party library. You cannot plug in your own parser. Here are some links if you want more information on Expat:

http://expat.sourceforge.net/

http://sourceforge.net/projects/expat/

The Expat parser supports these encodings:

• UTF-8
• ISO-8859-1
• US-ASCII

You should be able to use any of these encodings to pass information to Docupresentment, DSI APIs, or Documaker. Docupresentment sends back UTF-8.

Byte order marks

Some XML editors and software add the Byte Order Mark (BOM) to the beginning of the XML file, starting at offset 1. For example, if your XML file has UTF-8 encoding, the first three bytes of your XML file would contain...

EE BB BF

If, however, you open this file in a browser, you will not see this information. Furthermore, not all text editors display these values file. One sure way to find out if your XML file includes the BOM is to view the file using the Type DOS command.

The GenData program can handle XML files which include the BOM, but you must allow for this offset went you define the SeachMask option. Here are some examples:

If the BOM is included for UTF-8, define the SearchMask option as shown here:

If the BOM is not included, define the SearchMask option as shown here:

If you define the SearchMask option incorrectly, the GenData program will not create transaction trigger records.

XML File Format

Here is an example of the format of the XML file the system creates:

Keep in mind...

• DAPOPTIONS should have a value of M for multi-page sections (FAP files). There are other section options, but only M is applicable in XML.

  Use DAPINSTANCE to provide a page number for multi-page sections. If the section does not span multiple pages, omit the DAPINSTANCE value.

• When you have multiple XML transactions within a single file, separate each transaction with a line feed. This is a requirement of Documaker software, not the XML parser.

• Although you do not have to include line feeds inside the XML for a transaction, we suggest you add a line feed after each element tag. This makes it easier to read the file and helps in debugging your XML. A message like

  Line 255, column 8, syntax is incorrect

  is easier to diagnose than

  Line 1, column 156780, syntax is incorrect.