Version 25.2.9314

• Connector Configuration
  • Form Designer Tab
  • Settings Tab
    • Connector Settings
    • Advanced Settings
    • Logging
    • Miscellaneous
  • Form Users Tab
    • Adding Users
    • Editing Users
    • Deleting Individual Users
    • Deleting Multiple Users
  • Server Tab
    • Trusted IP Addresses
  • Transactions Tab
• Configuring the IIS Server
• Creating Forms
  • Adding Sections
  • Adding Detail Tables
  • Adding Fields
  • Form Field Types
    • Text Field Options
    • Dropdown Field Options
    • Radio Button Field Options
    • Checkbox Field Options
    • File Upload Field Options
  • Accessing Your Form
• Submitting Form Data
• Macros
  • Examples

Form connectors expose a public web endpoint where clients fill out a form and submit that data into a CData Arc flow.

Forms are created on the connector Form Designer tab. A form is divided into sections and detail tables, each of which can have a variable number of fields. For details, see Creating Forms.

When you use a Form connector to submit new data, you should place the connector 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. For more information, see Submitting Form Data.

The following sections explain how to configure the connector, create forms, and submit new form data.

Connector Configuration

This section contains all of the configurable connector properties.

Form Designer Tab

Settings related to building a set of form fields that are organized into sections and detail tables.

When clients connect to the configured endpoint and submit a form, they see fields that are laid out exactly as they are configured in the panel above.

The designer includes the following settings (see Creating Forms for more details).

• Form URL A link to the published form.
• Form Title of the form (for example, your company name).
• Add Dropdown to add a section or a detail table. Add Section lets you add specific sections to a form, and Add Detail lets you add a detail table to the form. Detail tables act like a pre-configured table where the form user can add as many records as they need for the dataset.
• Form Fields Drag and drop fields into detail table and section areas of the form. Repeat this as many times as necessary. The field types are:
  • Text Field An input text box with a name and description.
  • Dropdown A dropdown list with name and dropdown options.
  • Radio Buttons A set of radio buttons with name and radio button options.
  • Checkboxes A set of checkboxes with name and checkbox options.
  • File Upload Allows form users to upload specific file types directly to the form.
• Logo Upload your company logo, which appears at the top of the form. By default it uses the CData Arc logo. You can also change the color of the banner.
• Success Message The confirmation message users see after they submit form data successfully. You can change the default message or add additional text.

Settings Tab

Connector Settings

Settings related to the core configuration of the connector.

• Connector Id The static, unique identifier for the connector.
• Connector Type Displays the connector name and a description of what it does.
• Connector Description An optional field to provide a free-form description of the connector and its role in the flow.

Advanced Settings

• Local File Scheme A scheme for assigning filenames to messages that are output by the connector. You can use macros in your filenames dynamically to include information such as identifiers and timestamps. For more information, see Macros.

Logging

• Log Level The verbosity of logs generated by the connector. When you request support, set this to Debug.
• Log Subfolder Scheme Instructs the connector to group files in the Logs folder according to the selected interval. For example, the Weekly option instructs the connector to create a new subfolder each week and store all logs for the week in that folder. The blank setting tells the connector to save all logs directly in the Logs folder. For connectors that process many transactions, using subfolders helps keep logs organized and improves performance.
• Log Messages Check this to have the log entry for a processed file include a copy of the file itself. If you disable this, you might not be able to download a copy of the file from the Transactions tab.

Miscellaneous

Miscellaneous settings are for specific use cases.

• Other Settings Enables you to configure hidden connector settings in a semicolon-separated list (for example, setting1=value1;setting2=value2). Normal connector use cases and functionality should not require the use of these settings.

Form Users Tab

The Form Users tab lets you create user credentials for clients so that they can access the public endpoint. If a client is not logged into the application administration console already, that client is prompted to enter the User and Password combination when they browse to the endpoint.

You can add, edit, and delete credentials on this tab.

Adding Users

To add user credentials:

1. Click Add User to open the Add Form User dialog box.

2. Enter a username and password. (Click the eye icon to see the contents of the password field.)

3. Click Save Changes and the new user is added to the list of form users.

Editing Users

To edit users:

1. Click the ellipses next to the user that you want to edit, then click Edit.

2. Edit the credentials and click Save. If you decide not to make changes, click Cancel.

Deleting Individual Users

To delete individual users:

1. Click the ellipses next to the user that you want to edit, then click Remove.

2. Click Remove to delete the user or Cancel to cancel the deletion request.

Deleting Multiple Users

To remove multiple users, select the checkboxes for the users you want to delete, then click Remove. Confirm the deletion, or cancel the request.

Server Tab

Trusted IP Addresses

The following functions are available in the Trusted IP Addresses section:  

• Add Enter a new IP address range.
• Edit Modify the selected IP address range.
• Delete Deletes the selected IP address range from the list.

The following restrictions apply to this feature:

• localhost cannot be modified or removed from the list.
• Any IP addresses outside of the defined ranges are rejected.
• Ranges are supported. For example, the entry 100.10.100.1-15 indicates that IP addresses between 100.10.100.1 and 100.10.100.15 are allowed.
• Classless inter-domain routing (CIDR) notation is supported. For example, the entry 100.10.100.0/24 indicates that IP addresses between 100.10.100.0 and 100.10.100.255 are allowed.
• Wildcard patterns are supported. For example, the entry 100.10.100.* indicates that IP addresses beginning with 100.10.100 are allowed.

Note: In order for clients to reach the server, a clear network path is required. In cloud environments you might need to make changes in three places:

• The networking rules in the cloud console.
• The firewall rules on the machine hosting the application. For example, when using an Amazon AMI, you might use an Uncomplicated Firewall (UFW) to allow traffic on the desired port. A common strategy in Linux environments is to forward traffic from ports lower than 1024 to a non-standard port higher than 1024, while configuring the application to use the non-standard port. This avoids permission issues associated with non-root users binding to ports lower than 1024.
• The Trusted IP Addresses portion of the Settings page.

Transactions Tab

This tab lists all messages associated with the connector. Use the search bar to find specific messages, or click the funnel icon to apply a filter. You can filter by time, message direction, and/or status.

Incoming form responses appear on this tab.

Configuring the IIS Server

If your Arc instance is hosted on an IIS server and you use Microsoft Windows authentication to login to the application, you must disable Windows authentication for your users. Otherwise, the Form connector cannot properly authenticate users, and the connector will not work properly.

To disable Windows authentication:

1. In your IIS manager, create a new folder named connector in the base application path.

2. Select Authentication under IIS (in the right pane) for the connector folder.

   

3. Set Windows Authentication to Disabled for this folder.

   

Creating Forms

Forms have fields, sections, and details:

• Section: A heading that groups fields together
• Detail: An object that acts like a pre-configured table where the form user can add as many records as they need for the dataset
• Field: An input box with a label where users enter form data

To get started, click the Add button next to the form title, and choose whether to Add Section or Add Detail.

Adding Sections

Sections divide fields in the form by categorizing them under a heading. For example, the Ship To section might contain fields like Address, City, and Zip.

Sections are not required in order to add fields to the form. However, sections provide logical groupings of items that help users quickly understand the form.

To add a section:

1. Choose Add Section from the dropdown. Enter a section name.

2. Now you can start Adding Fields to the section.

   

Adding Detail Tables

Detail tables allow form creators to embed a table in the web form to enable structured, row-based data entry. They include a configurable number of columns which you define during the form creation. They are ideal for capturing repeatable datasets in a single form submission. End users can then dynamically add as many rows as needed and enter values for each column in those rows. See Accessing Your Form for an example.

To add a detail table to your form:

1. Click Add Detail from the dropdown. Enter a name.

2. Now you are ready to add columns to the table. Select any of the form field types.

   

Adding Fields

Fields are the basic unit of input for the form.

To add a field:

1. Drag an object from the Form Fields section into your section or detail table.

2. Enter a Display Name (for example, Line Item Id). By default, XML Name is populated, but you can use the Override checkbox to supply a different name.

3. Use the Is required checkbox to specify whether the field is mandatory.

4. The other options vary based on the form field type. The following example shows a text field being defined. When you are finished defining the field, click Add.

   

Tips:

• To edit a field, click the link to its name, or the ellipses to the right of the name.
• To remove a field, click the ellipses and choose Remove Instance.
• Drag and drop fields in a section or detail table to reorder their position in the form.

Form Field Types

Text Field Options

• Display Name: Name of the field in the form.
• XML Name: Sanitized version of the Display Name. It must be a valid XML element name.
• Override: Checkbox which allows you to change the default XML Name.
• Is required: Checkbox indicating whether the field is mandatory.
• Default Value: Populates the form with the text supplied here.
• Description: Helper text describing what the field is for.

Dropdown Field Options

• Display Name: Name of the field in the form.
• XML Name: Sanitized version of the Display Name. It must be a valid XML element name.
• Override: Checkbox which allows you to change the default XML Name.
• Dropdown Options: The list of options that appear in the form dropdown field. Click Add Option to add the options you need.
• Is required: Checkbox indicating whether the field is mandatory.
• Default Value: Populates the form with the text supplied here.
• Description: Helper text describing what the field is for.

Radio Button Field Options

• Display Name: Name of the field in the form.
• XML Name: Sanitized version of the Display Name. It must be a valid XML element name.
• Override: Checkbox which allows you to change the default XML Name.
• Radio Button Options: The list of options that appear in the form radio button field. Click Add Option to add the options you need.
• Is required: Checkbox indicating whether the field is mandatory.
• Default Value: Populates the form with the text supplied here.
• Description: Helper text describing what the field is for.

Checkbox Field Options

• Display Name: Name of the field in the form.
• XML Name: Sanitized version of the Display Name. It must be a valid XML element name.
• Override: Checkbox which allows you to change the default XML Name.
• Checkbox Options: The list of options that appear in the form checkbox field. Click Add Option to add the options you need.
• Is required: Checkbox indicating whether the field is mandatory.
• Default Value: Populates the form with the text supplied here.
• Description: Helper text describing what the field is for.

File Upload Field Options

• Display Name: Name of the field in the form.
• XML Name: Sanitized version of the Display Name. It must be a valid XML element name.
• Override: Checkbox which allows you to change the default XML Name.
• Accepted File Type Extensions: The allowed list of upload file types. For example, .xml only accepts XML files. To allow all file types, use *. Click Add Option to add the options you need.
• Is required: Checkbox indicating whether the field is mandatory.
• Default Value: Populates the form with the text supplied here.
• Description: Helper text describing what the field is for.

Accessing Your Form

When you finish designing your form, access it by clicking the Form URL link at the top of the designer. The following form is a simple example:

Submitting Form Data

After you create a form, users access the Form connector’s web endpoint and submit data using the form.

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 that you created).

Users can add rows to the detail table by clicking Add Row. Once a user enters all their data, they click Submit to submit their data. If the submission is successful, a message similar to the following appears.

When a user submits a form, the form data is pushed to the Transactions tab. The output is an XML file that contains the following structure:

<Items>
  <FormTitle>
    <FieldA>data</FieldA>
    <FieldB>more data</FieldB>
    <FieldC>even more data</FieldC>
    <DetailTitle>
      <SubFieldA>123</SubFieldA>
      <SubFieldB>456</SubFieldB>
    </DetailTitle>
    <DetailTitle>
      <SubFieldA>135</SubFieldA>
      <SubFieldB>246</SubFieldB>
    </DetailTitle>
  </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 that is usable by another connector.

Macros

Using macros in file naming strategies can enhance organizational efficiency and contextual understanding of data. By incorporating macros into filenames, you can dynamically include relevant information such as identifiers, timestamps, and header information, providing valuable context to each file. This helps ensure that filenames reflect details important to your organization.

CData Arc supports these macros, which all use the following syntax: %Macro%.

Examples

Some macros, such as %Ext% and %ShortDate%, do not require an argument, but others do. All macros that take an argument use the following syntax: %Macro:argument%

Here are some examples of the macros that take an argument:

• %Header:headername%: Where headername is the name of a header on a message.
• %Header:mycustomheader% resolves to the value of the mycustomheader header set on the input message.
• %Header:ponum% resolves to the value of the ponum header set on the input message.
• %RegexFilename:pattern%: Where pattern is a regex pattern. For example, %RegexFilename:^([\w][A-Za-z]+)% matches and resolves to the first word in the filename and is case insensitive (test_file.xml resolves to test).
• %Vault:vaultitem%: Where vaultitem is the name of an item in the vault. For example, %Vault:companyname% resolves to the value of the companyname item stored in the vault.
• %DateFormat:format%: Where format is an accepted date format (see Sample Date Formats for details). For example, %DateFormat:yyyy-MM-dd-HH-mm-ss-fff% resolves to the date and timestamp on the file.

You can also create more sophisticated macros, as shown in the following examples:

• Combining multiple macros in one filename: %DateFormat:yyyy-MM-dd-HH-mm-ss-fff%%EXT%
• Including text outside of the macro: MyFile_%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%
• Including text within the macro: %DateFormat:'DateProcessed-'yyyy-MM-dd_'TimeProcessed-'HH-mm-ss%