Form Connector

Version 20.0.7396


Form Connector



Form Connectors expose a public endpoint where WebForm data can be submitted into an ArcESB flow, or where existing data can be finalized and approved.

Overview

The public web endpoint exposed by a Form Connector allows clients to fill out Form data and submit this data into an Arc Flow. Forms can also be pre-populated with data from within an Arc flow, allowing the client to edit, finalize, or sign-off on a Form.

Forms are created within the Form Connector configuration panel. Forms are divided into sections, and each section can have a variable number of Form fields. These fields can be created and named manually, or read in automatically from other connectors in the flow. More details can be found in the Creating Forms section.

When Form Connectors are used to submit new data, the Form Connector should typically be at the start of a connected Flow. Clients can connect to the web endpoint, view and fill out the form, and submit this data into the configured Arc Flow. More details can be found in the Submitting New Form Data section.

When Form Connectors are used to approve or update existing data, the Form Connector should typically be in the middle of a connected Flow. Files that reach the Input folder of the Form Connector are displayed in a table that clients can view after connecting to the endpoint. Clients can then edit and finalize the data before submitting the form, allowing the data to continue through the Flow. More details can be found in the Pre-Populated Forms section.

Connector Configuration

Settings Tab

Connector Settings

Settings related to the core operation of the connector.

  • Endpoint The public endpoint where clients can access the WebForm, fill out Form fields, and submit the data to Arc.

Form Designer

The Form designer supports building a set of Form fields organized by Sections and Subforms. When clients connect to the configured Endpoint and submit a Form, they will see the field layed out as configured in this panel. The client’s view of the Form can be viewed using the Preview button. For more information, please see the Creating Forms section.

Local Folders

Settings that determine the folder on disk that files will be read from, and the folder that they will be received/written to.

  • Input Folder (Send) The connector reads files placed in this folder, and the data in these files becomes available to clients as pre-populated Form data.
  • Output Folder (Receive) When a client submits Form data, the connector will write the Form data file to this folder. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
  • Processed Folder (Sent) After a client submits a Form using a file in the Input/Send Folder, that file will be moved to this folder.

Users Tab

This tab supports creating User credentials for accessing the Endpoint. If the client is not already logged in to the application administration console, they will be prompted to enter the User/Password combination when browsing to the Endpoint. Users can be granted permissions according to whether they are allowed to submit Form data, edit pre-populated Form data, or simply read/view pre-populated Form data.

Creating Forms

A Form can have Fields, Sections, and Subforms:

  • Field - An input box with a label to where users enter Form data
  • Section - A heading that groups Fields together
  • Subforms - Nested forms within the form; these Subforms can have their own Sections and Fields

Available Fields

Fields are the basic unit of input for the Form. The ‘Available Fields’ list on the right displays the Fields that can currently be added to the Form. new Fields can always be created by clicking on ‘New Field’ and specifying the Field name.

The Available Fields list may also be pre-populated with existing Fields. The connector detects these Fields from surrounding connectors in the Flow. For example, if the Form Connector is connected to an XML Map Connector, the Form connector will attempt to detect any Templates in the XML Map Connector that indicate what data the Form Connector should output. The names of the available Fields are taken from the element names in these XML templates.

Sections

Sections divide Fields in the Form by categorizing them under a heading. For example, the ‘Ship To’ section may contain fields like Address, City, and Zip.

Sections are not required to add Fields to the Form, but may help users understand the Form at a glance. Section headings are added to the darker region of the Form, which is also where Fields are added. After adding a Section, make sure to expand this darker input region via the + button to add space for the appropriate Fields.

Adding Fields to the Form

Fields are added to the Form by dragging the Field from the Available Fields list into the darker region of the Form editor. It may be necessary to expand the darker region with the + button to add space for new Fields. Each ‘row’ added with this button fits two Fields.

Fields (and Section headings) can be dragged around to customize the look of the Form.

Subforms

Subforms function as nested Forms within the Form. Subforms have their own set of Sections, Fields, and even further nested Subforms.

Subforms should be used when a group of Fields in the Form may be repeated an unknown number of times. For example, if a Form represents a Purchase Order, then the number of Line Items will vary order-to-order. Thus, the data inputs necessary for Line Items should be a Subform so that users can add as many Line Items as they need before submitting the Forms.

Once a Subform is added to the Form, it can be made the ‘active’ Subform by clicking the ‘Edit Subform’ button underneath it. This changes the Form editor to focus on the Subform, where Fields can be dragged in and Sections can be added. To return to the main Form, click on the Title of the Form at the top of the Editor (the titles of the Form and each Subform are displayed like a folder path to indicate their hierarchy).

Submitting New Form Data

After creating the Form in the Form Editor, users can access the Form Connector’s web endpoint and submit data via the Form. After accessing the endpoint, users should click the New button to open a new blank Form and fill in the data.

For Fields in the main Form, users simply enter the values that correspond to the labels on the Form (which are taken from the name of the Fields dragged into the Form Designer).

For Subforms, users should click the + button for each instance of the Subform they intend to fill out. The number of Subforms added to the Form are displayed as a simple table, where each row represents an instance of the Subform. Click on a row in the table to edit the values entered in that row.

For example, if a user was entering Purchase Order data in the Form, the Form may include a ‘Line Items’ Subform. Users would add a new row to the ‘Line Items’ table for each Line Item in their Purchase Order, then click on each row to edit the data for that particular Line Item.

Form Output

Once a user has submitted a Form, the data is pushed to the Output/Receive folder of the Form connector. This output is an XML file with the following structure:

<Items>
  <FormTitle>
    <FieldA>data</FieldA>
    <FieldB>more data</FieldB>
    <FieldC>yet more data</FieldC>
    <SubformTitle>
      <SubFieldA>123</SubFieldA>
      <SubFieldB>456</SubFieldB>
    </SubformTitle>
    <SubformTitle>
      <SubFieldA>135</SubFieldA>
      <SubFieldB>246</SubFieldB>
    </SubformTitle>
  </FormTitle>
</Items>

This output is well suited to being processed by an XML Map Connector so that it can be mapped into an XML format usable by another connector.

Pre-Populated Forms

In addition to submitting new Forms via the New button, users can view pre-populated Forms and edit or approve them.

The pre-populated data comes from files sitting in the Input/Send folder of the Form Connector. After connecting to the web endpoint, users will see the list of these files in a table (files that have already been submitted are also included in the table with the ‘Submitted’ status).

Clicking on one of the rows in the table will bring up the Form with the data from that file already entered into the Form. Users can then edit these values or submit the values as-is to indicate that they are approved.

Submitted Forms are passed along in the Flow just like new Forms; the output XML generated by submitting the Form is described in the previous section.

Why Use Pre-Populated Forms

Reading data from an input file to pre-populate the Form allows a client to finalize or sign-off on data.

For example, consider a situation where the data for a Purchase Order is generated or retrieved earlier in the flow, like from database output pulled by the Database Connector. However, this Purchase Order data requires approval before it can be processed and sent out to an external party.

The data pulled by the Database Connector can be passed to the Form Connector, where it sits in the Input/Send folder until the approving party accesses the Form Connector’s web endpoint. The approving party clicks on each files to approve, edits or signs-off on the data, and submits the Form. The Purchase Order data then continues through the Arc Flow as normal.

Input File Format

Files in the Input/Send Folder of the Form Connector should match the XML structure of the configured Form. This XML structure matches the structure presented in the Form Output section:

  • A root Items element
  • A FormTitle element that is a child of Items
  • Each Field that is not in a Subform is a child of the FormTitle element
  • A SubformTitle element for each instance of the Subform that should be created
  • Each Field that is within the Subform should be a child of the SubformTitle element

Note that FormTitle and SubformTitle are stand-ins for the actual titles configured in the Form Designer.

Usage With the XML Map Connector

A common use of the Form Connector is to view, finalize, and approve data from another source (e.g. a database, a CSV file, etc). In order to populate a Form with external data, that data must be formatted as XML that matches the Form structure.

Arc uses XML as its primary data format, so many connectors exist to convert arbitrary data formats into XML. For example, the CSV Connector can convert CSV files into XML, the X12 Connector and EDIFACT Connector can be used to convert EDI files into XML, etc.

Once data is in XML format, the XML Map Connector can be used to transform the XML into the structure appropriate for the Form Connector:

First, the Form should be configured in the Form Connector will all necessary fields. Then, connect XML Map Connector to the Form Connector in the flow (and save the Flow changes). The XML Map Connector will automatically detect the XML structure of the Form and expose it as a possible Destination File.

Select the Form XML as the Destination File, and set the Source File to any arbitrary XML structure that represents the initial data format. The XML Map Connector’s visual designer will populate with the Source and Destination structures, and the Source elements can be dragged-and-dropped onto the Destination elements to create a mapping relationship.

Once the mapping is complete, the XML Map Connector will automatically convert files that match the Source File structure into the structure required by the Form Connector.

Please see the XML Map Connector documentation for more details on mapping XML structures.