More topics

Sending data to another system

Last updated on November 22, 2024

You can have form data submitted to a service application through an application programming interface (API) instead of receiving it by email.

On this page:

This is a server-side configuration

CMS Forms is set to support email transmission by default. If you want the data to be sent to another application via an API instead, we'll need to set up a custom configuration for your form on the server.

This configuration will tell Orbeon to follow a different process for your particular form. Without it, Orbeon will just follow its default processes.

Considerations

Integrating a form with another system requires some additional thought.

Below is some guidance for your consideration.

Process development

Your custom form configuration will include two parts:

  1. Instructions to replace the "Submit" (email) button with the "Send" (API) button
  2. What process to follow when "Send" is pressed

There are usually 2 configurations created so that:

  1. Submissions made in the QA environment go to a test API/application
  2. Submissions made in the PROD environment go to a production API/application

These configurations are typically identical except for the location (URI) of the API.

The process should be at least reviewed by, if not co-developed with, the developers. Although processes follow a similar pattern, each situation can be unique, so we'll want to make sure the process makes sense for the way the API and application are set up and function.

Data mapping

Data mapping refers to the process of matching an incoming value with a system or database value.

Developers do this all the time, but since systems (and forms) are frequently modified, the funtion of mapping "control-A" to "database-entity-C" can result in additional effort in design and maintenance.

EXAMPLE: Mapping a phone number

Your form collects a phone number which has to be transformed for the intended application's database. 

  1. You collect the phone number using a masked control called contactPhone
  2. You transform that phone number into a different control called cleanedPhone
  3. The data gets sent to an application through an API
  4. The application or API:
    • Ignores or discards the value of contactPhone
    • Accepts the value of cleanedPhone
    • Saves the value of cleanedPhone to the database's entry for client-phone-number

In this scenario, you may save development and maintenance effort by renaming cleanedPhone to client-phone-number.

For additional information, see:

Data transmission options

There are several options available for how the data is transmitted to the API, all dependent on how the API and application are set up.

EXAMPLE: Most-common transmission

{pre-send process steps}

then send(
                uri = "URL of API",
                method = "POST",
                nonrelevant = "keep"
                )

{post-send process steps}

For additional technical information, see:

Email notifications

With most forms, you'll set up emails for:

  • The citizen submitting the form
  • The program area receiving the form

With an API, you'll want to consider which system will send out notifications.

  • Is it Orbeon?
  • Is it the application?
  • Is it a combination?

Even if you want notifications to go out from the application, you will probably want to set up at least one in Orbeon as part of the recovery process.

Recovery process

It's normal for network connections, APIs or applications to occassionally go offline or lose capacity for a short time for things like maintenance. During these times, Orbeon will not be able to transmit data to the API. The recovery process tells Orbeon what to do when this occurs.

EXAMPLE: A recovery process (plain language)

recover (

send an email to the program area with the data

send an error message to the analytics application

If you're using Orbeon to send out the citizen notification, then the process will need to specify which email template to use, when.

API testing

As a form author, you probably won't have acces and visibility into the API or application. You'll need assistance in testing the form and configuration.

Consider something like a 3-way call where:

  • The client can complete and submit a form
  • The developer can confirm the data arrived and was mapped correctly
  • You have the form open ready for a quick edit-and-publish if a data adjustment is required

Keep in mind that there are usually 2 configurations to test. How and when to test both depends on your transition plan.

Transition plan

Since there are usually two configurations - one for QA and one for PROD - you'll want to consider the form's state in determining the timing and method of transitioning to the new API-enabled form.

  • If this is a completely new form, you can probably follow the regular Publish to Release procedures
  • If this is a revision of an existing form, you'll likely want to follow the major revision procedures

For additional information, see:

Requesting an API transmission

To request a custom configuration for your form to send the data to an API, create a service request.

Let us know:

  • The Application and Form Name
  • Who the developer contacts are
  • The expected release date for the form

If available, also include:

  • The URLs to be used for QA and PROD
  • The desired transmission options (code)
  • The desired recovery process (description)
  • The name of the email template(s) used

Readying these configuration may take 3 or 4 weeks before they're ready for you to test in CMS Lite. This is dependent on complexity, how much back-and-forth there is, change window schedules, etc. There may also be a charge for this. You'll be advised ahead of time if this is the case.

If you need to revise an existing configuration, you can use the same process.