Administration > e.net Solutions > Document Flow Manager Setup

Document Flow Manager Setup

Document Flow Manager is a component of SYSPRO e.net Solutions that facilitates collaborative commerce by automating document flow (i.e. the processing of incoming and outgoing documents such as sales orders and purchase orders) between trading partners.

System Requirements

System requirements Description
Operating system One of the following operating system must be installed:
  • Windows 2003 Server/Small Business Server
  • Windows 2008 Server
  • Windows 7
NTFS file system Enables folder polling (it is not possible to set the folder permissions on FAT/FAT 32).

Although you can run demo versions without security, this is not recommended.
Microsoft Message Queue (MSMQ) Queues requests to the SYSPRO server. It must be installed before DFM is installed.
Microsoft Collaborative Data Objects library (CDO) Outgoing responses from the Document Flow Manager use CDO to send email via SMTP (Simple Mail Transfer Protocol). This must be installed on the SYSPRO application server.
Microsoft Message Queue polling service (SYSPROMSMQPollerService) together with the Folder polling service (SYSPROFolderPollerService) The services must be installed on the SYSPRO application server.

You run the service installation programs from the command line from the \Base folder of the SYSPRO application server.

The operator installing DFM must have permission to access the same SYSPRO folders as the DFM user who will be using the service.
Microsoft XML Parser 3.0 (MSXML3) or above This must be installed on the SYSPRO application server.
Simple Mail Transport Protocol (SMTP) The virtual SMTP server is used to send email (outgoing responses) from Document Flow Manager. If the SYSPRO application server cannot resolve the email address, the email could be forwarded to the company's email server (SMART HOST).
SYSPRO installation (version 6.0 or higher) Document Flow Manager must be installed on the SYSPRO application server, as it uses the library routines made available by SYSPRO.
Valid license A valid license to run SYSPRO with e.net System Manager and e.net Document Flow Manager.

Licensing

Document Flow Manager is typically licensed by the number of concurrent users of SYSPRO.

The license includes DFM access to any business object (e.g. if you are only going to use business objects from DFM, then you only need to license the e.net System Manager and Document Flow Manager).

It does not mean that you can merely license the e.net System Manager and Document Flow Manager and access all the business objects from your own custom development, or from the Web-based Applications. These would still need to be licensed in the normal way.

Installation

During the SYSPRO installation, a number of executable files are placed in the SYSPRO \Base folder. These executables are used, together with command line parameters, to install Document Flow Manager.

[Note]

For Windows 7 and later, ensure that the Command prompt is launched in elevated mode (i.e. as an administrator) in order to write entries to the registry.

Executable files

  • SYSPROMSMQPollerService

    This installs the main polling service which polls the Microsoft Message Queue for incoming documents. Once located, these documents are processed according to their matching contract.

  • SYSPROFolderPollerService

    This installs the folder polling service which polls one or more folders for incoming documents. Once located, these documents are placed in the Microsoft Message Queue, together with the relevant contract number.

Registry entries created

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\SYSPRO MSMQ Poller

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\SYSPRO Folder Poller Service

Command line parameters

-i Installs the service (see Install parameters for more detail).
-r Removes the service.
-v Interrogates the service.
-x Stops the service.
-s Starts the service.

  • The parameters cannot contain spaces and (with the exception of the first parameter) can appear in any sequence.

  • The format of the installation command is the same for all the services, only the program name changes (i.e. SYSPROMSMQPollerService and SYSPROFolderPollerService).

  • Only one copy of each of these services can be installed on any machine.

  • All of the supplied parameters must be valid for the installation to succeed. Once a service is installed, it attempts to start automatically.

Install parameters

-o Indicates the next characters delimited by space is the operator code (e.g. __DFM) which must be created for a service to run.
-c Indicates the next characters delimited by space is the company id. The company must have a valid license that includes both the e.net System Manager and the e.net Document Flow Manager.
-l Indicates the next characters delimited by space is the language code (e.g. 05 to indicate English). If no language code is supplied, it defaults to the language specified during the installation.
-u Indicates the next characters delimited by space is the user name (e.g. DOMAIN\user) that is allowed to log on as a service. The user must have permission to install services (i.e. administrative rights) as well as log on as a service permissions.
-p Indicates the next characters delimited by space is the DOMAIN password.
Sample usage

SYSPROMSMQPollerService -i -o __DFM -c 0 [-l] [05] -u DOMAIN\user -p password

SYSPROFolderPollerService -i -o __DFM -c 0 [-l] [05] -u DOMAIN\user -p password

Configuration

A Document Flow Manager wizard enables you to configure contracts indicating the file types that must be located and which business object must be called when they are found. The polling interval for each of these services is also configurable.

For documents that are not in the XML format required by the business object, the contract can specify that they are pre-processed using XSLT. The same applies to the outgoing XML if the application that provided the original XML document needs a reply in a specified format. Alternatively, if being viewed by a user, the outgoing XML can be rendered as HTML using XSLT.

Toolbar and menu

Field Description
Add Loads a wizard that guides you through the process of adding a new contract.
Change Maintains details of the currently highlighted contract.
Delete Deletes the currently highlighted contract.
Options  
Message Queue Setup Configures the SYSPRO settings required for the Document Flow Manager. This must be performed prior to installing DFM services.

Document Flow Manager Control Setup

This is displayed when you select the Message Queue Setup option from the options menu.

Field Description
Message queue setup  
Queue type Indicates the type of message queue to use. Document Flow Manager requires the Private message queue setting. The Public setting is not supported by SYSPRO.
Queue name The name of the queue to be created (defaults to SYSPRO).

The queue is created the first time one of the three DFM Services is started.

Queue label A meaningful description for the queue (e.g. Document Flow Manager).
Email polling server setup The e-mail polling service only starts once a valid contract has been defined.
Mail server name

The mail server name to be used for polling e-mails. It should contain the name of the Microsoft Exchange Server that is to be polled.

This applies if the DFM must either poll email accounts or send email responses.
Email response server setup DFM can email the results from the document being processed.

The emails are either sent from an SMTP server that is running on the IP address entered on this screen, or routed via a smart host on this server to another email server.
SMTP TCP-IP address The TCP-IP address of the server from which you want to forward outgoing email. This only applies if (against the contract) you selected to send response email.

This address is used if emails are being sent from an SMTP server. Alternatively, you can use this address to identify the smart host through which all outgoing messages for remote domains must be routed (instead of sending them directly to the domain).

This allows messages to be routed over a connection that may be more direct or less costly than other routes. Enclose the IP address in brackets [ ] to increase system performance.

The brackets identify the value as an IP address and because Microsoft SMTP service checks for a name before checking for an IP address, the DNS lookup is bypassed.

The smart host is similar to the route domain option for remote domains. The difference is that once a smart host is designated, all outgoing messages are routed to that server. With a route domain, only messages for the remote domain are routed to a specific server. If a smart host has been configured, then you can still designate a different route for a remote domain. The route domain setting overrides the smart host setting.

Default email address The default email address to which messages are sent if a contract stipulates that an email should be sent, but no email address is provided.

Add New Contract Wizard

This wizard is launched when you select to add a new contract. The wizard helps you create a new contract between a document type and Document Flow Manager.

Field Description
Contract ID This is used to identify the contract.
Business Object class Indicate the type of business object to use for this contract.
Query Adds a Business object that is used to perform queries.
Setup Adds a Business object that is used for creating, changing and deleting semi-static information.
Transaction Adds a Business object that is used to change transactions that occur against the items created using the Setup class.
Business Object to invoke Select the business object you want to invoke for this contract.
Business Object name Indicates the name of the Business Object you selected to invoke.
Method name Indicates the Business object class you selected.
Operator code Enter the code of the SYSPRO operator to use when the contract is run (preferably the same operator code as you use to run the DFM Services).

The operator code entered here is displayed against the transaction in the XML Document Query program.

For some transaction type Business Objects (e.g. SORTOI) the operator code used to create the transaction is stored against the transaction.
Inbox message required  
Operator to notify Enter the code of the SYSPRO operator you want to notify.
Program to call Optionally enter the program to run when the operator opens the message.
Inbox message Enter the message you want to send to the operator.
Disable contract Select this to prevent the contract form being used.
Send response email  
Failed Sends an email if the process fails.
Success Sends an email if the process succeeds.
Both Sends an email regardless of whether the process fails or succeeds.
Click to add messages Refer to Setup Success / Fail Email Message.
Success Select this to design the email that must be sent if the document is processed successfully.
Fail Select this to design the email that must be sent if the document processing fails.
XML history required You use the XML Document Control program to specify the location of history documents and the number of days for which they must be kept.
Incoming Keeps copies of incoming documents.
Outgoing Keeps copies of outgoing documents.
Both Keeps copies of incoming and outgoing documents.
Save document Indicate whether the results from the business object should be written out to a folder where it can be accessed by another application such as Microsoft's BizTalk Server.

The name allocated to the output file depends on whether you are retaining history.

If you are retaining history then the file name is built up of the company id followed by DO (i.e. Document Out) and then the next number to use. The suffix is .XML unless you are performing an XSLT transformation on the file.

If you are not retaining history, the output file name starts with _T followed by a unique number.
Outgoing folder Enter the folder to which the document must be saved.
XSLT translation required  
Incoming Select this to perform translation on the incoming document before it is processed by the business object.
Outgoing Select this to perform translation on the outgoing document (i.e. the result from the business object).
Both Select this to perform translation on both the incoming and outgoing documents.
Incoming XSL filename Indicate the XSL filename (including the full path) that must be used to translate the incoming document for this contract.
Outgoing XSL filename Indicate the XSL filename (including the full path) that must be used to translate the outgoing document for this contract.
Outgoing file extension Indicate the extension of the outgoing XSL file.
Folder to poll Indicate the folder that requires polling.

A valid folder/file must be entered before you can continue.

The folder can reside on the SYSPRO application server or a different server. The Document Flow Manager Folder Service must have permission to read and delete the file in the specified folder.
File type Indicate the type of file to be polled for this contract.
Mailbox name Indicate the mailbox name (as defined on your server) to use for folder polling.
Root folder Indicate the root folder in which the folder to poll resides.
Folder Indicate the folder within the root folder that requires polling for this contract.
Delete original Email message Deletes the email message from the email folder specified after it has been processed (sent to the business object).

Any email without an attachment is deleted immediately.

Otherwise emails without an attachment are marked as read and left in the folder and emails with attachments are marked as read and sent to the business object, but left in the folder.

This can be useful if you want to re-send the attachment to the business object (you can simply mark it as unread and let the services resend it to the business object). However, depending on the number of emails received, this folder can become large and take up a lot of disk space if it is not manually cleared regularly.

Setup Success / Fail Email Message

This screen is displayed if you selected to set up response Email messages and you select the Success of Fail option.

Field Description
Email priority Select the priority rating for the email message.
Address from Enter the email address of the sender.
Address to Enter the email address of the recipient. Multiple email addresses can be entered separated by a semi-colon (;) as a delimiter.

If you selected Fail, then the email you design will be sent if the document fails during processing.

If you selected Success, then the email you design will be sent if the document is successfully processed.
Subject Enter an appropriate subject line for the email message.
Body Enter an appropriate message for the email.

A document resulting from the business object will be attached to the email.

Email polling

Special folders

A number of folders within the Microsoft Exchange mailbox cannot contain email messages (e.g. Calendar, Contacts, Journal, Notes and Tasks).

The Document Flow Manager folder polling service will not poll these folders.

Multiple contracts polling the same email folder

Similar to the folder polling service, the email polling service prevents you from configuring two contracts to poll the same email folder. A message is displayed if you attempt to configure a subsequent contract to poll the same Mailbox name/Root folder/Folder combination.

HKEY_CLASSES_ROOT\MAPI.Session should be renamed (for example) to HKEY_CLASSES_ROOT\MAPI.SessionZ

The contract should be configured while this change is in effect. Note that the screen containing the mailbox details will appear with a message indicating that no validation will take place.

Once the contract has been configured, you should revert to the original registry settings on the client. Thereafter, you should start the email polling service on the SYSPRO application server. If this does not start, check the Event Viewer to see whether any messages have been written to the event log. Check the spelling of the mailbox name, root folder and folder.

A message is displayed if they have been incorrectly spelled, or are not valid. To correct any errors, you must shut down the service, change the registry, update the contract, reset the registry entry and restart the service. Remember to rename the registry key when you have finished.

Collaboration Data Objects

In order to use the email polling facility, the CDO (Collaboration Data Objects) library must be installed. CDO 1.21 was previously available for download in a re-distributable format. However this version is no longer available. CDO must be installed by another product, such as Microsoft Outlook or Microsoft Exchange.

By default, Outlook 2000 and Outlook 2002 installations exclude the CDO 1.2x component. When you view the options for Office or Outlook setup, CDO is listed under the options for Outlook.

The Document Flow Manager email service must have permissions to access the required email accounts. When an email folder receives a new document, the attachment is extracted and placed into the message queue. The service does not check the content of the attachment since it does not need to be in XML format.

You should not poll a personal email account, because the email service will process the message before the user has had a chance to read it. Configure email accounts specifically for B2B. The use of server-side rules can assist the functionality by perhaps checking the Subject line and moving the email to a given folder, which in turn is being polled by the Document Flow Manager. Validation of email accounts generally happens when the Document Flow Manager email service is running. Only at this point can it be established if an email account is valid and the folder to poll exists.

Windows Event Log

The Windows event log records all system activities and is a useful source of information when trying to diagnose why a document is not being processed, or the services won't start.

Polling a folder across a network

If the Document Flow Manager is required to poll a folder on another machine on the network (not a mapped drive environment) the DFM services user must have permission to access that folder (i.e. read and write).

Multiple companies

The company id specified at the time of creating the Document Flow Manager services is only used to check whether DFM is licensed. Document Flow Manager can process contracts for any company id, regardless of the company used to create the service. A contract created within one SYSPRO company is, however, specific to that company (i.e. all companies with active contracts must be licensed to use the DFM). If you have more than one SYSPRO company and are licensed to use Document Flow Manager, you must import the e.net license.xml file for each company.

Notes and warnings

Encoding considerations

Under MSXML 3.0, the default encoding message written out to a new XML file is UTF-16 even if the file is in UTF-8 format.

Although it does not appear possible to write out a UTF-8 encoding message, you can prevent an encoding message from being written out. This is achieved by changing the xsl:output section to include omit-xml-declaration="yes" in your XSLT file.

For example, if you already had the entry:

<xsl:output method="xml"
encoding="UTF-8" version="1.0" indent="yes" />

then you could resolve the problem by changing it to:

<xsl:output method="xml" omit-xml-declaration="yes"
encoding="UTF-8" version="1.0" indent="yes" />

Installing Document Flow Manager

  1. Install SYSPRO (including e.net Solutions and importing the license file)

  2. Install the Microsoft Message Queue (MSMQ)

  3. Define a new DFM user.

  4. Create a DFM folder structure.

  5. Enable folder access to the user of the DFM service.

  6. Enable email access to the user of the DFM service.

  7. Add a SYSPRO DFM operator that will be used by the services.

  8. Configure the Document Flow Manager (Program List > Administration > e.net Solutions > Document Flow Manager).

  9. Configure the XML Control Record (Program List > Business-to-Business Trading > XML Control Record).

    This enables you to configure how you want SYSPRO to process incoming, outgoing and failed XML documents.

Configuring SYSPRO for DFM

  1. Confirm that your SYSPRO installation is licensed to use the e.net System Manager and e.net Document Flow Manager.

    1. Open the Company Setup program (SYSOPRO Ribbon bar > Setup > Company Setup)

    2. Highlight the company you want to review.

    3. Select Change.

    4. Select the Registration tab.

    5. Locate the e.net System Manager and e.net Document Flow Manager options.

    6. Ensure that the Installed column for these options is enabled.

  2. Confirm that e.net Solutions licensing has been configured.

    1. Open the System Setup program (SYSPRO Ribbon bar > Setup > System Setup).

    2. Select Configure e.net License.

    3. Select the Configure e.net Licenses option.

    4. Select Next.

    5. Select Business Objects or Web-based Applications.

      If you are licensed to use e.net Solutions then a window is displayed enabling you to apportion licenses to the required operators. Otherwise you will be required to import the license.xml file.

  3. Confirm that licenses have been apportioned to operators for accessing the functional areas of e.net Solutions.

Installing the Microsoft Message Queue

  1. Navigate to the Microsoft Message Queue feature located within the Windows Control Panel.

    The location and wording will vary according to your version of Windows.

    For example: In Windows 2007 this is located in the Turn Windows features on or off section of the Programs and Features function. In earlier versions, this is located within the Add/Remove Windows Components section of the Add or Remove Programs function.

  2. Enable the Message Queuing option.

    If the server is part of a Domain or Active Directory, then a check is performed to establish whether MSMQ has been installed on the Domain Controller. If it has, then the installation will continue. If it does not exist on the Domain Controller, then it must be installed before continuing.

    If the setup wizard is unable to locate an MSMQ server automatically then a window is displayed (Active Directory Integration or Message Queuing Type) that allows you to configure it manually.

    Against the Message Queuing Type window ensure that you enable the Message Queue Server option and that you disable the Enable Routing option.

Creating a user on your local machine

We recommend that you run Document Flow Manager with its own operating system user. The reason for this is that the services do not function correctly if configured to run as the local system account. It is also easier to configure permissions against a defined user than compromise one that was originally created to serve a different purpose.

If the DFM Folder Poller service only needs to poll folders on the SYSPRO application server, then you only need to create a local user account. If it needs to poll folders on other machines (or the Email Folder Poller service is also being used) then you must create the user as a domain user.

  1. Open the Computer Management facility (Control Panel > Administrative Tools > View by: Large icons > Computer Management).

  2. Navigate to the Local Users and Groups folder.

  3. Right-click on the User folder and select New User from the menu.

  4. Enter the required user details.

    We recommend that you uncheck the option: User must change password at next logon and enable the option: Password never expires. Otherwise, when you need to change the password the DFM services will stop functioning and the password against the services will need to be changed manually.

  5. Exit the Computer Management facility.

Configuring a user to run as a service

  1. Open the Local Security Policy facility (Control Panel > View by : Large icons > Administrative Tools > Local Security Policy).

  2. Expand the Local Policies folder.

  3. Select the User Rights Assignment subfolder.

  4. Right-click on the Log on as a service policy.

  5. Select Properties from the menu.

  6. Locate the user you want to configure.

  7. Configure the user to run as a service.

    1. Select Add User or Group.

    2. Select Locations.

    3. Highlight your local machine name and select OK.

    4. Enter the name of the DFM user that you created on your local machine.

    5. Select Check Names to confirm that the user name entered is valid.

  8. Exit the Local Security Policy facility.

Creating a SYSPRO operator for DFM

You would typically follow this procedure to create a Document Flow Manager User within the SYSPRO environment. For maintenance reasons, we recommend that you create a separate SYSPRO operator for the Document Flow Manager Services.

  1. Log in to SYSPRO as an administrator.

  2. Navigate to the Operators program and select to add a new operator.

  3. Enter the operator name and network user name.

    We recommend prefixing your entry at the Network user name with two underscore characters (e.g. __DFM). This prevents the operator from logging into SYSPRO in the normal way, ensuring that the DFM operator code cannot be used to bypass security.

  4. Assign the operator to a group.

    Ensure that the group has administrator privileges, or has been granted access to the relevant e.net classes/business objects.

Checking whether a DFM service is installed

  1. Load a command prompt.

    You can also view the service using the Windows Control Panel(Start > Control Panel > Administrative Tools > Services)

  2. Navigate to the \Base folder of your SYSPRO installation on the server.

  3. Interrogate the service using the -v command line parameter.

    • Enter SYSPROMSMQPollerService -v to interrogate the main polling service.

    • Enter SYSPROFolderPollerService -v to interrogate the folder polling service.

    • Enter SYSPROEmailPollerService -v to interrogate the email polling service.

Installing a DFM service

  1. Load a command prompt.

    For Windows 7 and later, ensure that the Command prompt is loaded in elevated mode (i.e. as an administrator) in order to write entries to the registry.

  2. Navigate to the Base folder of your SYSPRO installation on the server.

  3. Install the service using the -i command line parameter.

    For example:

    SYSPROMSMQPollerService -i -o __DFM -c 0 [-l] [05] -u DOMAIN\user -p password

    where:

    • -i informs the service that it must install.

    • -o indicates the next characters delimited by space is the operator code.

    • __DFM the SYSPRO operator code that must be created for a service to run

    • -c indicates the next characters delimited by space is the company id.

    • 05 is the language code.

    • -u indicates the next characters delimited by space is the user name.

    • DOMAIN\user the user that is allowed to log on as a service (local policies).

    • -p indicates the next characters delimited by space is the DOMAIN password.

    • password is the password for the user.

Checking whether a DFM service is running

  1. Open the Services facility (Control Panel > View by : Large icons > Administrative Tools > Services).

  2. Locate the service you want to review.

  3. Review the entry in the Status column.

    A status of Started indicates the service is running.

Starting a DFM service manually

  • In a SQL Server environment, ensure that SQL Server is running before starting any of the services. This is because the service attempts to log in to SYSPRO to ensure that the company license information includes the e.net System Manager and e.net Document Flow Manager. This will not be possible if SQL Server is not running.

  1. Load a command prompt.

  2. Navigate to the \Base folder of your SYSPRO installation on the server.

  3. Launch the service using the -s command line parameter.

    • Enter SYSPROMSMQPollerService -s to start the main polling service.

    • Enter SYSPROFolderPollerService -s to start the folder polling service.

    • Enter SYSPROEmailPollerService -s to start the email polling service.

Stopping a DFM service

  1. Load a command prompt.

  2. Navigate to the \Base folder of your SYSPRO installation on the server.

  3. Stop the service using the -x command line parameter.

    • Enter SYSPROMSMQPollerService -x to stop the main polling service.

    • Enter SYSPROFolderPollerService -x to stop the folder polling service.

    • Enter SYSPROEmailPollerService -x to stop the email polling service.

Removing a DFM service

  1. Load a command prompt.

  2. Navigate to the \Base folder of your SYSPRO installation on the server.

  3. Remove the service using the -r command line parameter.

    • Enter SYSPROMSMQPollerService -r to remove the main polling service.

    • Enter SYSPROFolderPollerService -r to remove the folder polling service.

    • Enter SYSPROEmailPollerService -r to remove the email polling service.

Querying XML documents

You would typically use this procedure to view incoming, outgoing and failed documents processed by the Document Flow Manager and Electronic Data Interchange systems.

  1. Open the XML Document Query program (SYSPRO programs > Business-to-Business Trading > XML Document Control).

  2. Select the type of document for which you want to conduct a search.

  3. Select the operator(s) against whom you want to conduct the search.

  4. Select a range of dates within which you want to conduct the search.

  5. Select Start Processing to start the search process.

    Depending on your selections, a list of documents is displayed in the listview pane.

Configuring the DFM diagnostic utility

  1. Open the System Setup program (SYSPRO Ribbon bar > Setup > General Setup).

  2. Select enet02 at the Diagnostics field.

    The Document Flow Manager will output a log file (\Base\Settings\enetlog02.txt) of each business object that has been run.

Disabling MSMQ journals

You would typically use this procedure to prevent SYSPRO Document Flow Manager journals from being retained by the Microsoft Message Queuing application.

  1. Open the Computer Management facility (Control Panel > Administrative Tools > Computer Management).

  2. Expand the Services and Applications folder.

  3. Expand the Message Queuing folder.

  4. Expand the Private Queues folder.

  5. Right-click the syspro folder.

  6. Deselect the Enabled option from the Journal section.

    The Journals option is enabled by default. When a document enters the queue it resides under Queue messages. Once it has been processed, it appears under Journal messages.