Code formats and examples for data connections middleware

formVersionId

This property is automatically appended by OpenForms to indicate which form a data connection originates from. This is important as a single data connection can be reused on multiple forms.

sendFields

This is the field information from your form that is being sent to an external application via middleware. Each field is identified by the external ID you have assigned to it, and multiple fields can be sent by separating their external IDs with commas.
See Send and receive fields and syntax for more information.

receiveFields

This is the field information that you are requesting from an external application via middleware. Each field is identified by the external ID you have assigned to it in your form, and multiple fields can be sent by separating their external IDs with commas.

See Send and receive fields and syntax for more information.

personId

The respondent’s ID number, as entered into the form

first_name

The respondent’s first name, as held in the CRM

last_name

The respondent’s last name, as held in the CRM

email

The respondent’s email address, as held in the CRM

fields

This is a property that contains information requested from an external application via middleware. The information nested within should match the receiveFields property sent from OpenForms.

errors

These are any error messages that arise from requests made to your external application via middleware. General errors can be an array containing multiple error strings. Errors specific to a particular field comprise a single error string.

warnings

These are any warning messages that arise from requests made to your external application via middleware. General warnings can be an array containing multiple warning strings. Warnings specific to a particular field comprise a single warning string.

success

These are success messages that arise from requests made to your external application via middleware. These can only apply to individual fields (a general success message would be redundant), and each field can contain a single success string.

referenceId

This is a string of text that is used as an identifier for form submission. For example, this could be the ID of a submission in your CRM application.

status

This is a string of text that represents the status of this form submission. For example this can be "lodged" if a submission has been lodged in your CRM application ready for staff to work on.

formId

This property is automatically appended by OpenForms to indicate which form a data connection originates from. This identifier is unique to each form, but does not identify form versions.

formVersionId

This property is automatically appended by OpenForms to indicate which form version a data connection originates from. This identifier is unique to each version of a form.

formVersionNumber

This property is automatically appended by OpenForms to indicate which version of a form a data connection originates from.

This number is not unique across forms (multiple forms can have a formVersionNumber of “2” for example), but read together with the formId, can identify individual forms and versions.

externalRespondentId

This property is an identifier (such as a staff ID) that originates outside of OpenForms. 

This property can be populated in a variety of ways. It can be entered into a form field, requested from an external application, or appended to a URL or form link (see an example below of the URL method). 

responseReferenceId

This property is automatically appended by OpenForms, and is used to identify a particular response within OpenForms. Each time a respondent opens a form, a unique responseReferenceId is assigned.

dataConnectionId

This property is automatically appended by OpenForms, indicating which data connection is being used for a particular data transfer. Each data connection is given a unique ID.

sourceType

When the same data connection is used multiple times in a form, triggering across multiple fields or sections, sourceType and sourceElementId properties can be used together to determine which part of a form a particular data connection instance is triggering from.

sourceElementId

This property is automatically appended by OpenForms and identifies the specific element of a form that a data connection is triggered from (for example, the third field of a section, or the second section of a form).

Together with the sourceType property, this can be used to identify where individual instances of multiple-use data connections are triggered from.

externalId 

This property identifies a unique item in an external application (for example, a particular parking infringement or animal registration).

In data connections version 1, this object was named "referenceId."

externalStatus 

This property identifies the status of a particular item in an external application (for example, whether a fine is "paid" or "unpaid.") OpenForms can receive and update statuses (for example, changing a fine from "unpaid" to "paid" upon completion of a payment).
In data connections version 1, this object was named "status."

callCounter

This property is automatically appended by OpenForms each time a data connection is triggered from a particular location in a form.

This information can be used a number of ways - for example, to provide analytics data, to limit data connection requests, or to prevent duplication of data when the same data connection is triggered multiple times.

sendFields

This is the field information from your form that is being sent to an external application. Each field is identified by the external ID you have assigned to it, and multiple fields can be sent by separating their external IDs with commas.
See Send and receive fields and syntax for more information. 

receiveFields

This is the field information that you are requesting from an external application. Each field is identified by the external ID you have assigned to it in your form, and multiple fields can be sent by separating their external IDs with commas. 
See Send and receive fields and syntax for more information.

LicensePlate

The car’s license plate number, as entered into the form

CarModel

The car’s model, as held in the CRM

lastTyreReplacementDate

The date of the car’s last tyre change, as held in the CRM

lastOilChange

The date of the car’s last oil change, as held in the CRM

fields

This is a property that contains information requested from an external application via middleware. The information nested within should match the “ReceiveFields” objects sent from OpenForms.

errors

These are any error messages that arise from requests made to your external application via middleware. General errors can be an array containing multiple error strings. Errors specific to a particular field comprise a single error string.

warnings

These are any warning messages that arise from requests made to your external application via middleware. General warnings can be an array containing multiple warning strings. Warnings specific to a particular field comprise a single warning string.

success

These are success messages that arise from requests made to your external application via middleware. These can only apply to individual fields (a general success message would be redundant), and each field can contain a single success string.

externalId

This property identifies a unique item in an external application (for example, a particular parking infringement or animal registration).
In data connections version 1, this object was named "referenceId."

externalStatus

This is a string of text that represents the status of this form submission. For example this might be "lodged" if a submission has been lodged in your CRM application ready for staff to work on.
In data connections version 1, this property was named "status."

externalRespondentId

This property is used to identify a user within a system that is not OpenForms, such as a CRM or DMS.

<field answer value>

{
     value: <field answer value>
}

<field answer value>

{
     value: <field answer value>
}

<field answer value>

{
     selectedValue: <field answer value>
}  

{
     value: <field answer value>
}  

[
     <value of checked item>,
]

{
     selectedValues: [
          <value of checked item>,
     ]
}

{
     multiValues: [
          <value of checked item>,
     ]
}

<field answer value>

{
     selectedValue: <field answer value>
}

{
     value: <field answer value> 
}

<field answer value> 

{
     selectedDate: <field answer value>
}

{
    value: <field answer value> 
}

<field answer value>

{
     value: <field answer value>
} 

[
     {
          "label":  <rank label>,
          "rank":   <rank>
     },
]

{
     selectedValues:  [
          {
               label: <rank label>,
               value: <rank>
          },
     ]
}

{
     multiValues: [
          {
               label: <rank label>,
               value: <rank>
          },
     ]
}

[
     {
          id:   <file identifier>,
          name: <file name>
     },

{
     files: [
          {
               id:   <file identifier>,
               name: <file name>,
               isDeleted: <if the file was deleted>
           },
       ]
}

{ 
     files: [
          {
               fileId: <file identifier>,
               fileName: <file name>,
          },   
    ]
}

<field answer value>

{
    value: <field answer value>
}

{
     method: <signature type>,
     name:   <signature name>,
     file: {
          id:   <file identifier>,
          name: <file name>
          isDeleted: <if the file was deleted>
     }
}

{
     type: <signature type>,
     name: <signatory name>,
     file: {
          id:   <file identifier>,
          name: <file name>,
          isDeleted: <if the file was deleted>
     }
}

{
     type: <signature type>,
     signatoryName: <signatatory name>,
     file: {
          id: <file identifier>,
          name: <file name>,
     }
}

{
     method: <signature type>,
     name:   <signatory name>,
     file:   <null>
}

{
     type: <signature type>
     name: <signatory name>
     file: {
          id:        <null>
          name:      <null>
          isDeleted: <null>
     }
{

{
     type:           <signature method>
     signatoryName: <signatory name>
     file:           <null>
}

{ 
    address: <full address>,
    latLng:  {
         lat:  <latitude>,
         long: <longitude>,
    }
}

{
     locationAddressFull: <full address>
     locationLatLong: {
          lat: <latitude>
          lng: <longitude>
     }
}

{
     address: <full address>
     latLng:  <null>
}

{
     locationAddressFull: <full address>
     locationLatLong:     <null>
}

{
     paymentAmount: <payment amount>
}

{
     transactionID:          <transaction ID from payment gateway>
     paymentAmount:          <payment amount>
     paymentAmountSurcharge: <surcharge amount>
}

transactionID will be <null> for mid-form data connections. 

{
     paymentTransactionID:        <transaction ID from payment gateway>
     paymentGateway:              <payment gateway selected by respondent>
     paymentAmount:               <payment amount>
     paymentAmountSurcharge:      <surcharge amount>
     paymentAmountConvenienceFee: <convenience fee amount>
}

paymentTransactionID and paymentGateyway will be <null> for mid-form data connections. paymentAmountSurcharge and paymentAmountConvenienceFee will also be <null> for mid-form data connections when they are variable.

[
     {
          label: <option label>,
          value: <option value>
     },
]

{
     selectedValues: [
          {
               label: <option label>,
               value: <option value>
          },
     ]
}

{
     multiValues: [
          {
               label: <option label>,
               value: <option value>
          },
     ] 
}

[
     {
          label: <option label>,
          value: [
               <option value>, 
          ]
     },
]

{
     selectedValues: [
          {
               label:  <option label>,
               values: [
                    <option value>,
               ]
            },
     ]
}

{
     multiValues: [
          {
               label: <option label>,
               values: [
                    <option value>,
               ]
          },
     ]
}

<field answer value>

{
     content: <content>
}

{
     url:     <url to the image>,
     altText: <alternative text for the image>
}

<video embed code>

{
     content: <video embed code>
}

{
     videoHtml:       <video embed code>
     videoTranscript: <video transcript text>
} 

{
     answer:  <field answer value>,
     success: <optional, success string>,
     warning: <optional, warning string>,
     error:   <optional, error string>
}

• To return multiple values that will be presented in a list for the form user to choose from, separate the values with \uE04D

{
     answer:  <field answer value>,
     altText: <optional, image alt text>,
     success: <optional, success string>,
     warning: <optional, warning string>,
     error:   <optional, error string>
}

{
     answer: <field answer value>
     listItems: [
          {
               text:  <option text>,
               value: <option value>
          },
     ],
     success: <optional, success string>, 
     warning: <optional, warning string>, 
     error:   <optional, error string>
}

• To check multiple values, separate values in the answer with a comma (,)
  
• To rank multiple values, separate the values in the answer with a pipe (|)

"Postcode": {  "value": "3000"  }  

"Postcode": {  "answer": ""  }

"Postcode": {  "answer": "3001"  }