Create a FireForm integration

Note:

The process below requires technical expertise related to the management of API configurations.

FireForm integrations are used to send submitted form entry data to an external endpoint (such as an API) when it is routed.

Before creating an integration, a connection with an external source must be established. The external source needs to have a publicly accessible endpoint from which the system can retrieve data. To set up an integrated data source, you will need the following information:

  • HTTP method (PUT, POST)
  • End point URL (REST API)
  • Authorization type (No Auth, API Key, Bearer Token, Basic Auth, OAuth 2.0)
  • Data format

To create the integration:

  1. In FireForm, from your form's "Form Detail" page, select Integration. A page will display that lists any previously created integrations for the form.
  2. Select Add Integration.
  3. Use the drop-down to select which state should trigger the integration and, if needed, the routing step to which the form should move after the integration has occurred.
  4. Select Save.
  5. Select Add Integration Rule.
  6. On the "Add Integration Rule" page, configure the fields as outlined below using the information about your external data source. To determine which method will be required, refer to the API documentation associated with your external data source.
    • Name, Rule Order, and Status:
      • Name: Enter a name that is brief but descriptive, so it can be easily selected from a list.
      • Rule Order: If multiple integrations are defined for the same state, the integrations will run according to the order of the rules.
      • Status: To apply the integration to the form, this must be set to active. (Inactive means the integration is created but not yet applied to the form (and is therefore not functioning).
    • Settings:
      • HTTP method:
        • PUT: The information will be sent to an external source and completely replace whatever currently exists at the target URL with something else.
        • POST: The information will be sent to an external web server.
        • GET: The information will be received from the external source.
      • End Point URL: Enter the external URL that will receive the information.
      • Use Custom HTTP Header: Enter a custom HTTP header, if desired. The format for the header is JSON syntax with single quotes:
        { 'Accept': 'application/json' }
      • Proceed on Failure: This allows subsequent integrations to run even if this integration fails; if defined, it will move the form to the "Move To" state.
    • Authorization Type: You can select only one option when configuring an integration. Each option will result in additional fields, requiring additional information. The options are:
      • No Auth
      • Api Key
      • Bearer Token
      • Basic Auth
      • OAuth 2.0
    • Data Format: You can select only one option when configuring an integration. Each option will result in additional fields, requiring additional information. The options are:
      • Send Key-Value Pairs: Use a source-to-target method to send data. The source is the element response (selected using the FireForm Element ID) or hard-coded text. The target is the location where the data should be put in the external system.
        Note:

        Ultimately, this is a helper to build a JSON object to send the data. The user matches the source and target, and FireForm builds a JSON object behind the scenes before sending the data.

        For example, where Element_1 on the form is the user's email address on the form and email is the name of the field in the external system where the information should post:

        'Send Key-Value Pairs' example

      • Send Raw Data: Allow users to write their own JSON objects using a key-value relationship to send data to the external source.
    • File Attachment Key-Value Pairs: This allows any attachments uploaded on the form to be sent to the external source. It is very similar to the key-value pairs above, but it can only be used to select a FireForm element with the File Attachment data type.
      • Send Arbitrary Binary Data: Will include {Element_X:FileExtension} and {Element_X:FileSize}.
      • Form PDF = {Element_0}: Will send a PDF of the form entry.
    • Response Key-Value Pairs: This is used when an external system sends information back to use in their response JSON. It allows us to update a form element with the response.

      For example, an integration runs to create a work order in the AiM system. The success message that AiM sends back also contains the newly created work order number. We parse the work order number out of their response and update the AiM work order number element that has previously been defined on the form. Element Status in FireForm must be integration for this to work.

  7. Select Save.

This is document bghk in the Knowledge Base.
Last modified on 2024-03-11 11:40:41.