formatta e-forms manager 8 e-forms ma… · processing of form submissions that will allow...

Formatta E-Forms Manager 8.x

XML Messaging Guide

December 2012

Access FSA, LLC PO Box 733

Sulphur Springs, TX 75483 (888) 448-1811

www.formatta.com www.accessefm.com

http://www.formatta.com/

http://www.accessefm.com/

E-Forms Manager 8.x XML Messaging Guide

Copyright © 2012 Access FSA, LLC. All rights reserved. Published December, 2012 Access FSA, LLC believes the information in this publication is accurate as of the date above. The information is subject to change without notice. THE INFORMATION IN THIS DOCUMENT IS PROVIDED “AS IS.” ACCESS FSA, LLC MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION CONTAINED HEREIN, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. ACCESS FSA, LLC ALSO DISCLAIMS ANY RESPONSIBILITY FOR DAMAGES OF ANY KIND, INCLUDING DIRECT OR INDIRECT DAMAGES OF ANY KIND THAT MAY STEM FROM THE USE OF THIS INFORMATION, INCLUDING CONSEQUENTIAL DAMAGES. Use, copying, and distribution of any Access Formatta software described in this document requires applicable software licenses. All other trademarks used herein are the property of their respective owners.


Table of Contents 1 Introduction ............................................................................................................ 4

1.1 Intended Audience ........................................................................................... 4 1.2 Related Resources and Documentation ........................................................... 4 1.3 Conventions Used in this Document ................................................................ 5

2 Standards Used for Submission Transport .......................................................... 7 2.1 Web Services ................................................................................................... 7 2.2 SOAP Messaging and SOAP with Attachments ............................................... 7

3 Solution Components ............................................................................................ 9 3.1 E-Forms Manager ............................................................................................ 9

3.1.1 E-Forms Manager Processing Status Service Location ................................ 9 3.2 Connector Services.......................................................................................... 9 3.3 Destination Application .................................................................................. 10 3.4 Component Interaction for Submission Processing ........................................ 10

4 Message Delivery Sequence ............................................................................... 12 5 E-Forms Manager Configuration for Message Delivery .................................... 14

5.1 Define HTTP Endpoint Connections .............................................................. 14 5.2 Associate a Document Type ID with the Form ............................................... 14 5.3 Enable and Configure SOAP Messaging for the Form ................................... 15 5.4 Enabling XML Messaging as Workflow-based ............................................... 17

6 Message Definitions and Descriptions ............................................................... 19 6.1 formSubmission – The submission package SOAP message ........................ 19

6.1.1 The SOAP Envelope Part .......................................................................... 20 6.1.2 The Form Field Data Attachment Part ........................................................ 23 6.1.3 The Submitted Form Document Attachment Part ....................................... 24

6.2 formSubmissionAck – Response Message for Acknowledgement of receipt of a Form Submission Message ......................................................................... 25

6.3 formSubmissionProcStatus – Asynchronous Message for Providing Processing Status to EFM .............................................................................. 26

6.4 formSubmissionProcStatusAck – Response Message from EFM for Acknowledgement of receipt of a formSubmissionProcStatus Message ........ 28


1 Introduction Since version 7.2, E-Forms Manager provides a simple SOAP-based service tied to the processing of form submissions that will allow submitted forms, form data, and submission metadata to be handed off to other applications over HTTP. Use of this feature involves the development and/or deployment of a receiving or “Connector Service” application that can receive SOAP messages from E-Forms Manager, process them in a custom manner, and respond to E-Forms Manager as desired with acknowledgements and with information regarding the external processing status of submissions. This feature has been developed on as a straightforward and useful approach to providing real-time application level integration between Formatta E-Forms Manager and other systems such as content management, CRM, BPM, and more. For environments in which these types of systems exist and can benefit from an e-forms data and document collection interface, E-Forms Manager will allow a simple yet powerful handoff of data and documents. The purpose of this document is to give an overview of the main software components involved in this integration on the E-Forms Manager side and how they are expected to interact with the connector services in order to implement such handoffs.

1.1 Intended Audience

This document is intended for developers, system integrators, and other people who have at least a cursory familiarity with the concepts around web services, enterprise integration, XML, and the SOAP protocol; who are familiar with Formatta E-Forms Manager and its form processing and automation features; and for those who are interested building applications and services that can connect E-Forms Manager’s e-forms capabilities with other systems.

1.2 Related Resources and Documentation

Many of the concepts and technologies referenced in this document consist of standard and commonly used frameworks and methodologies such as HTTP and SOAP with Attachments. Links to informational sites are provided in this document where they can add further explanation of the concepts included here, and links to supporting documentation can be found where referenced in the sections that follow. An online user’s guide for this version of E-Forms Manager is available from

http://www.formatta.com/help/v7/manager/manager.htm. The online help

is useful as a reference for E-Forms Manager users and administrators and provides overviews of functionality and step-by-step instructions for customizing, using, and maintaining the system. Acess Formatta partners may find additional resources about E-Forms Manager and other Formatta software by logging into Formatta PartnerNet at

http://www.formatta.com/partnernet/.

http://www.formatta.com/help/v7/manager/manager.htm

http://www.formatta.com/partnernet/


1.3 Conventions Used in this Document

Within this document you may find symbols that are meant to call special attention to noteworthy information, or text formatted in such a way as to indicate the type of information represented in the text. Special Notices Special notices are signified using the following conventions:

Note:

Used for information that is of special significance or importance in the context of the subject matter being described.

IMPORTANT

Information associated with this symbol should be understood as especially significant in relation to the proper operation of the software.

CAUTION

A Caution notice may provide information essential to avoiding data loss or corruption, or damage to the system.

STOP

This may be found in the context of step-by-step instructions and will describe a situation in which you should discontinue the steps and perform some other type of operation.


Fonts and Text Formatting The special typographical conventions described below are used within this document:

Bold: Indicates:

Specific applications, programs, utilities, or services

Text or other elements seen on user interfaces

Text to be typed, viewed, or clicked on by a user

Italic: Indicates:

Titles of documentation or other publications

Emphasis

Token or variable names

Courier: Indicates:

Log file or console output

File system paths

File names

URLs and hyperlinks

Text file contents or snippets detailing configuration settings

Examples of programming code or scripting

Courier Bold: Indicates:

Commands or other text provided as input by a user


2 Standards Used for Submission Transport This new submission messaging feature essentially centers around E-Forms Manager’s ability to encapsulate information about a form submission and send it off to a service or application outside of E-Forms Manager for processing. In many cases, for solutions to utilize this messaging, development of an application or service outside of E-Forms Manager will be necessary in order to consume and process these messages in a manner pertinent to the application at hand. With this in mind, Access’ goal in designing the messaging mechanism has been to provide interfaces and message structures that are simple, standards-based, and platform-neutral. The key standards employed are HTTP, SOA-type web services, and SOAP with Attachments. These are described in more detail below.

2.1 Web Services

In order to provide message transport between E-Forms Manager and connected applications, the HTTP protocol using SOA-style web services provides the underlying mechanism. Several popular styles of web service implementation include Remote Procedure Call (RPC), Representational State Transfer (REST), and Services Oriented Architecture (SOA). E-Forms Manager’s submission messaging utilizes the SOA type of service. Benefits of the use of SOA-type services include:

Simplicity: Unlike RPC and REST, SOA employs a message, rather than an operation, as the basic unit of communication. This fits well for the type of information being exchanged with E-Forms Manager, since the transaction consists fundamentally a simple handoff of a submitted form and related data. A SOA-based consumer does not need to define specific methods or operations and does not require a WSDL description of its services.

Flexibility: SOA-based consumers for the Formatta submission message can be developed in a variety of ways and can be considered “loosely coupled” in that the E-Forms Manager server needs to know very little about the system it is writing to and the consumer (or connector) needs very little information about E-Forms Manager other than how to connect to it and send a message. The bulk of the information related to the transaction exists within the messages themselves, as will be described below.

Platform Neutrality: There are no specific language or platform requirements for SOA-based services. So a connector for E-Forms Manager submissions can be implemented as Java applications (e.g., using Servlets or JSP pages), as a .NET application, or using many other technologies.

2.2 SOAP Messaging and SOAP with Attachments

As the means of moving data and documents representing form submissions and their contents to other applications, Access chose the SOAP standard, specifically SOAP with Attachments, as the transport mechanism. SOAP, or Simple Object Access Protocol, is a protocol specification for exchanging structured information via web services over a network. SOAP messages follow a standard XML structure in which the main components of the message are defined such as the Envelope, Header, and Body elements of the message. Within these individual parts, information specific to the


message at hand is provided in predefined structured XML format. Specifications and examples for the structure of these messages are provided below. The E-Forms Manager submission messaging feature produces and consumes messages conforming to the SOAP 1.1 specification and SOAP with Attachments note. The SOAP with Attachments standard defines a means of structuring SOAP messages consisting of a MIME multipart/related message format. Such messages are consistent with the SOAP standard, but allow information in different formats (for example, both text as XML and documents as binary) to be sent and received in a single transaction. Much like an email that contains file attachments, a SOAP with Attachments message can contain relay both metadata and document objects in the same message. Since the results of an E-Forms Manager e-form submission may include form data and submission-related metadata in XML format, as well as a form itself in a binary document format, this type of messaging is ideal for application integration with E-Forms Manager. It allows the representation of a form submission to be handed off in a single, quick transaction and processed in whatever way is appropriate by the application connector. For more information on SOAP with Attachments, see http://www.w3.org/TR/SOAP-attachments.

http://www.w3.org/TR/SOAP-attachments

http://www.w3.org/TR/SOAP-attachments


3 Solution Components A full solution that uses E-Forms Manager’s SOAP Messaging for Submissions in order to integrate with an outside application relies on functionality built into E-Forms Manager to produce and send messages and to receive processing status, as well as a separate application whose role is to consume and process messages from E-Forms Manager by transforming their contents as necessary and sending them into the application.

3.1 E-Forms Manager

A SOAP-based integration between E-Forms Manager and a Connector Service for application integration relies on two main interfaces within the E-Forms Manager system:

1. A Submission Messaging web service client that calls the Connector Service as forms are submitted into E-Forms Manager (either on every submission or based on E-Forms Manager Workflow processing rules), and

2. A Processing Status web service that allows the connector service to update E-

Forms Manager with status information about submissions it has received. This outbound messaging client and inbound service operate independently of each other, except insofar as the status update service requires the use of a reference ID initially provided by the client. Calls to the status update service are optional, and are meant to provide application-specific processing status information back to E-Forms Manager for viewing by E-Forms Manager administrators.

This communication structure allows e-form submission processing outside of E-Forms Manager to be performed asynchronously with regard to the actual handoff.

3.1.1 E-Forms Manager Processing Status Service Location

The E-Forms Manager processing status service listens on the standard E-Forms Manager root context and on the same port. So if your E-Forms Manager instance is listening as http://server1:8080/efm/, the processing status service will be found at http://server1:8080/efm/xmlm/status.

3.2 Connector Services

A Connector Service acts as a custom broker between E-Forms Manager and an enterprise application in order to feed information received from E-Forms Manager to that application. It understands the message structure from Formatta as well as the interface to the destination application so that it can properly communicate with both for a smooth data and document handoff. Connector Services for E-Forms Manager messaging can be custom-built for specific integrations, or may be provided by Access or third party software vendors for use with popular enterprise software applications. The role of a Connector Service is to:

Receive SOAP messages from the E-Forms Manager client described above, containing information related to e-form submissions.

Parse and transform the message contents in a manner appropriate for integration with another application.

http://server1:8080/efm/

http://server1:8080/efm/xmlm/status


Provide information related to the e-form submission, optionally including the submitted electronic document itself, to the application for storage or further processing.

Optionally call back to E-Forms Manager’s Processing Status web service (described above) to provide application-specific information with regard to the processing of the submission and its data.

In the above manner, a Connector Service can receive the submission and process it on its own schedule without requiring E-Forms Manager to wait for the results of processing. Once processing is complete (either successfully or through an error condition), the Connector Service can call E-Forms Manager’s status update service in order to provide notification as to the status of the submission’s processing.

3.3 Destination Application

The destination application can be any type of software system that can receive, process, or store electronic data or documents. Examples include databases, document management systems, CRM systems, and portal applications. As long as the application can accept such information through a services or other programmatic interface, or even through file processing, then a Connector Service can be built that allows Formatta form submissions to be passed along to it.

3.4 Component Interaction for Submission Processing

The diagram below provides an overview of how Formatta E-Forms Manager’s SOAP messaging capability can be used along with a Connector Service and enterprise application in order to send submission-related content into it.

The sequence of events illustrated here is as follows:

1. User submits a form to E-Forms Manager


2. E-Forms Manager processes the submission, and creates a SOAP message containing submission metadata, form data, and/or submission-related documents.

3. The E-Forms Manager Outbound Web Service Client calls a Connector Service, passing the SOAP message.

4. The Connector service receives the message and uses its built in logic and configurations to perform a handoff of the submitted documents and data to the destination system.

5. The Connector Service calls the EFM status update service, providing information with regard to the processing of the form submission.

6. E-Forms Manager updates its logs with external application’s processing status.


4 Message Delivery Sequence The diagram below provides a more detailed sequence events describing the individual transactions involved in the processing of a submitted form.

In the diagram, the individual transactions shown are numbered according to the order in which they occur. A description for each numbered transaction is below. A detailed description of each of the messages involved in these transactions is provided later on in this document.

1. User submits an electronic form to E-Forms Manager. 2. If the form’s settings require outbound messaging, E-Forms Manager’s form

processing queues an internal request to send a message. 3. E-Forms Manager’s messaging client constructs a SOAP message according to

the form’s settings. The message includes data about the submission, one or more form field values, and may contain a copy of the submitted form in its native (.pff) format. E-Forms Manager establishes a connection to the HTTP Endpoint designated in the form’s definition and sends the SOAP message via HTTP request. The message is received by the Connector Service.

4. The Connector Service provides a synchronous response containing a form submission acknowledgement SOAP message (detailed later in this document), or with a SOAP fault if the receipt of the original message failed.

5. E-Forms Manager updates its internal status using the results of the acknowledgement, to indicate either that the handoff was successful or that it failed.

6. The Connector Service parses and translates the submission message as necessary, then sends the document and/or data into the destination system.

7. The Connector Service creates a Form Submission Processing Status SOAP message (described later) indicating the status of the submission with regard to


the destination system. This message is delivered asynchronously with respect to the original submission package, and whether it is sent at all is optional. The message contains a unique transaction reference ID that was contained in the original submission package, which E-Forms Manager uses to find and update the status of its related submission.

8. E-Forms Manager’s inbound message service provides a synchronous acknowledgement which specifies (a) successful processing of the status message or (b) failed processing of the status message.

9. E-Forms Manager updates its internal submission log to contain the destination application’s processing status description. This status is now available for viewing by E-Forms Manager administrators.


5 E-Forms Manager Configuration for Message Delivery The process of configuring the construction and delivery of submission-related SOAP messages by E-Forms Manager is straightforward and can be performed all in the E-Forms Manager administrative web interface. Once you have a form uploaded into the E-Forms Manager catalog, you can follow the steps below to have its submissions sent out to an available Connector Service for outside processing.

5.1 Define HTTP Endpoint Connections

The first step in defining outbound SOAP message delivery from form submissions is to provide E-Forms Manager with a URL representing the location of the service, servlet, JSP, or other HTTP-based interface that can accept and process the message handoff. To do this:

1. Go to the Administration tab in E-Forms Manager, and choose the Messaging menu item. On this screen you will see a tab labeled Endpoints.

2. Click the New Endpoint link. This will open a window prompting you to enter the following values:

Endpoint Name: In this field, enter a unique name that accurately represents the purpose, location, or application associated with the Connector Service with which it will provide a connection.

URL: In this screen, enter a URL containing the protocol, host, port, and context of the service that will accept submission SOAP messages.

3. Optionally, enter a username and password if the endpoint requires authentication.

4. Click the Finish button to save your endpoint definition. The new endpoint name will now be available for selection in the form catalog where messaging for forms is defined.

5.2 Associate a Document Type ID with the Form

The E-Forms Manager catalog allows you to assign a document type ID to its forms. This value can be useful for systems that process forms and form data outside of E-


Forms Manager, since it can be used to identify the data set or business process with which a form is associated externally. Multiple forms may contain the same document type ID if they are meant to take part in the same external process, or may have different ones if they need to be processed differently. The document type ID assigned is contained as a data element in the submission SOAP message, so is available for use in any logic needed by the Connector Service to process the message. To assign a document type ID to a form:

1. Find the form in the E-Forms Manager catalog that you want to configure SOAP messaging.

2. From the Form Details screen, click the Edit Form Details link.

3. This opens a screen that contains a field labeled Document Type Id. Enter a

value up to twelve characters in length into this field, and click the Save button.

5.3 Enable and Configure SOAP Messaging for the Form

The next step involves defining the contents of the message that will be placed into a SOAP message at time of submission, and in specifying whether the form will be sent upon every submission or based on E-Form Manager’s rule-based workflow processing. To do this:


1. In the E-Forms Manager catalog, find the form version that you want to configure

for SOAP messaging. Click the Edit Version Details link from the form information screen.

2. On the General tab, make sure that submission is enabled for the form.

3. Go to the Autowrite tab, and select the XML Messaging sub-tab.

4. On this screen, use the available fields and controls to specify the following

settings:

Enable XMLM Messaging: Checking this box specifies that every submission of this form version will result in the construction and delivery of a submission SOAP message. If you want the messaging for this form version to be based on workflow processing instead (or if you want it to be disabled for now), leave this box unchecked.

Endpoint Name: Choose the endpoint defined in the section above. This provides the destination for the form’s message delivery.

Include Submitted Form: Check this box if you want to include the submitted form document in the outbound message. If you only want to send form data, you may leave this unchecked.

Include Data from Fields: Choose any fields that you want sent to the destination system from the list on the left and select them by moving to the Selected Fields list on the right. Values and field names for all of the selected fields will be contained in an XML portion of the SOAP message for processing by the Connector Service and destination application.


5. Once you have made all of the settings, click the Save Changes button at the

bottom.

5.4 Enabling XML Messaging as Workflow-based

If instead of sending every submission out in a message you want the delivery to be based on E-Forms Manager’s workflow processing rules, you can create a workflow rule and associated action that makes this delivery conditional based on the content or state of the form. E-Forms Manager contains a workflow action called Perform XML Messaging that calls for the construction and delivery of the submission SOAP message specifically when actions of this type are executed by workflow processing. To configure XML messaging as workflow based:

1. Go to the Workflow tab for the form version you want to configure. 2. Find or create a workflow rule with which you want message delivery to be

associated.

3. With workflow disabled, click on the rule to open up its properties window. On this window, click the New Action link. This will open up the Workflow Action design wizard.

4. On the first screen, provide information for the following fields:

Action Name: Give a brief name that accurately describes the nature of the action, e.g., “Send to Documentum.”

Action Type: Choose Perform XML Messaging. Note that you do not need to specify any settings with regard to the message or its destination. All of that information was provided in the Autowrite area in the previous steps. If you checked the Enable XML Messaging box in that area, you will receive a warning on the next screen indicating that every submission will send a message and not just execution of this workflow action.

Action Order: Specify the order in the sequence of actions in which you want the messaging operation to occur.

Enable Logging: Check this box if the action takes place in an E-Forms Manager Workflow business process for which you want to provide status


tracking. If you enable logging here, you will be prompted in the following screen to specify the contents of the status message shown from the form or in E-Forms Manager.

5. The final screen, shown below, will simply provide information related to your

messaging configuration. It will not require any input, but will show any applicable warnings if necessary. Click the Finish button to save and close your workflow action definition.


6 Message Definitions and Descriptions This section provides specific information on each of the messages that take part in the submission information handoff from E-Forms Manager to a Connector Service for processing, including the submission package as well as acknowledgements and status updates. A complete round trip that includes the submission delivery to the Connector Service and a processing status update to E-Forms Manager would involve the following messages:

formSubmission: The SOAP with Attachments message initially sent from E-Forms Manager to the Connector Service.

formSubmissionAck: The synchronous response to the formSubmission request, which provides a simple status code and message indicating the receipt status of the message (as opposed the destination application’s processing status, which is sent asynchronously in the next step).

formSubmissionProcStatus: The message sent from the Connector Service to E-Forms Manager containing a status code and optionally a message, which indicates the status of the submission with regard to its handoff to and/or processing by the destination application. This message is sent asynchronously with respect to the original formSubmission.

formSubmissionProcStatusAck: The synchronous response from E-Forms Manager to the Connector Service formSubmissionProcStatus call, that provides and acknowledgement of receipt and processing of the status update request.

Each of these messages, their contents and structure will be described in detail below.

6.1 formSubmission – The submission package SOAP message

This message is constructed by E-Forms Manager and sent to the Connector Service at time of form submission, or based on workflow processing rules in E-Forms Manager. This is the SOAP with attachments message that contains the payload of a form submission. The message is separated into different MIME parts, each of which represents a major part of the message, including the SOAP envelope, and one or two attachments containing form field information and the optionally the submitted form. The structure of this message is pictured below, with each of the MIME parts in blue.


6.1.1 The SOAP Envelope Part

The SOAP Envelope MIME part consists of an XML document that defines the overall package and its structure. It contains the header and body sections described below. Below is an example of the SOAP Envelope section of one of these messages:


6.1.1.1 SOAP Header Definition

The first part of the envelope is a SOAP Header element, with high-level information that includes an XML structure that conforms to Formatta’s messageHeader schema, which is available from: http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-messageHeader.xsd

Values available for use in this XML structure are:

Element Required? Description

transactionRefId Yes Created by EFM, this value is required by subsequent calls back to E-Forms Manager to associate status messages with form submission messages received earlier.

username No For authentication of the message if required by the Connector Service or destination application.

password No For authentication of the message if required by the Connector Service or destination application.

The diagram below depicts the structure of the messageHeader XML portion of the SOAP header.

6.1.1.2 SOAP Body Definition

The SOAP Body element includes an XML structure conforming to Formatta’s formSubmission XML schema, available from: http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmission.xsd


http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-messageHeader.xsd

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmission.xsd

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmission.xsd



submissionRefId Yes A submission reference ID, which is used to identify the submission within EFM.

submittedOn Yes Timestamp representing the server's recorded date and time of submission.

submittedByUserId No Login ID of the submitter, available only when submission requires authentication.

submittedByName No First and last name of the form submitter. Available only when submission requires authentication.

formTitle Yes The EFM title of the submitted form.

formDocTypeId Yes Assigned to a form when uploaded to EFM. Used to identify the form as a code outside of EFM. Pertains to all versions of a given form in EFM. This value can be useful in determining how to process the form outside of EFM.

formVersionNumber Yes Assigned to a form version in EFM. Can be used outside of EFM to identify a particular version of a form when combined with the FormDocTypeId

formData Yes A content-id reference to the XML attachment in the SOAP message containing form field data.

pff No A content-id reference to the binary attachment in the SOAP message containing the submitted form, if it exists. This element contains a filename attribute that gives the native (.pff) file name of the submitted form document.

The diagram below depicts the structure of the formSubmission XML portion of the SOAP body.


6.1.2 The Form Field Data Attachment Part

The Form Data Attachment MIME part consists of an XML document that contains field names and data specified for delivery within the package. The attachment part uses a MIME type of text/xml and is identified by a content-id of form_data. This MIME part is referenced within the formSubmission XML in the SOAP Body from the formData XML element. An example of this section from a form submission message is pictured below:


The form field names and data are provided in an XML structure that conforms to Formatta’s formData schema, which is available from: http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formData.xsd



fieldCode Yes The name of the form field, as specified by the form designer and displayed in EFM.

Value Yes The tag is always present. If no data was entered into the form field, then the element will be empty but not suppressed.

The diagram below depicts the structure of the formData XML for this attachment:

6.1.3 The Submitted Form Document Attachment Part

The Submitted Form Attachment MIME part consists of a binary attachment that contains the submitted document itself in its native (.pff) format. This attachment part uses a MIME type of application/pff and is identified by a content-id of submitted_form.

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formData.xsd

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formData.xsd


This MIME part is referenced within the formSubmission XML in the SOAP Body from the pff XML element. If inclusion of the form is not specified in E-Forms Manager, then the pff XML element will be non-existent in the formSubmission XML, and the binary attachment will not be included in the package. An example of this section from a form submission message is pictured below:

6.2 formSubmissionAck – Response Message for Acknowledgement of receipt of a Form Submission Message

When a Connector Service receives a Form Submission SOAP message, it must respond synchronously to the E-Forms Manager calling client with an acknowledgement indicating whether or not the message was received successfully. This should occur before the service attempts to process the message, and should simply provide an indicator as to whether the service has obtained a valid message and will attempt to process it. A sample of a formSubmissionAck message, indicating successful receipt of the message is pictured below:

If receipt of the message fails, the acknowledgement may return a SOAP fault or may return a status of FAILURE, along with a message indicating the nature of the error. For example, if the message cannot be parsed, the Connector Service should throw an


exception resulting and a SOAP Fault. If the message can be parsed but contains invalid credentials, then the Connector Service should return an acknowledgement with a FAILURE status and a message describing why the message cannot be processed. The SOAP Header portion of this message will contain a messageHeader element that has the necessary transactionRefId value. The structure for the acknowledgement portion of this message type conforms to Formatta’s formSubmissionAck schema, which is available from: http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionAck.xsd



ackCode Yes A value of SUCCESS or FAILURE

ackMessage Yes A message that can be provided either on success or failure, which would provide detailed information back to EFM.

The diagram below depicts the structure of the acknowledgement portion of this message:

6.3 formSubmissionProcStatus – Asynchronous Message for Providing Processing Status to EFM

Once the Connector Service has attempted, either successfully or unsuccessfully, to process the form submission message, it may make a call to E-Forms Manager’s processing status service to provide a status. This message must contain the transaction reference ID that was provided in the original submission message, and should contain information specific to the external processing of the message. A sample of a formSubmissionProcStatus message, indicating successful processing of the message is pictured below:

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionAck.xsd

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionAck.xsd


If processing of the message fails, the message may provide a status of FAILURE, along with a message indicating the nature of the error. The SOAP Header portion of this message will contain a messageHeader element that has the necessary transactionRefId value. The structure for the formSubmissionProcStatus portion of this message type conforms to Formatta’s formSubmissionProcStatus schema, which is available from: http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionProcStatus.xsd



statusCode Yes A value of SUCCESS or FAILURE

statusMessage Yes A message that can be provided either on success or failure, which would provide detailed information back to EFM.


http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionProcStatus.xsd

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionProcStatus.xsd


6.4 formSubmissionProcStatusAck – Response Message from EFM for Acknowledgement of receipt of a formSubmissionProcStatus Message

When a Connector Service sends a formSubmissionProcStatus message, it will receive a synchronous response with E-Forms Manager’s status with respect to processing of the form. A sample of a formSubmissionProcStatusAck message, indicating successful receipt of the processing status message is pictured below:

If receipt of the message fails, the EFM service will throw an exception, resulting in a SOAP fault. This will happen, for example, if the message cannot be parsed or if it contains invalid information. Otherwise, it will return a status of SUCCESS along with a message. The SOAP Header portion of this message will contain a messageHeader element that has the necessary transactionRefId value. The structure for the acknowledgement portion of this message type conforms to Formatta’s formSubmissionProcStatusAck schema, which is available from: http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-

formSubmissionProcStatusAck.xsd

Values available available in this XML structure are:


ackCode Yes A value of SUCCESS. (A SOAP Fault is thrown in the event of failure)

ackMessage Yes


http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionProcStatusAck.xsd

http://www2.formatta.com/schemas/efm/xmlm/1.0/XMLM-formSubmissionProcStatusAck.xsd

formatta e-forms manager 8 e-forms ma… · processing of form submissions that will allow...

Documents