style
content

Forms

AEM offers a forms service that ingests submitted data into a Microsoft Excel or Google Sheet document.

Having data submitted through forms on your website flow directly into spreadsheets makes it easily accessible to business users. Such data can also interact with more complex automated workflows as both Google Sheets as well as Microsoft Excel and Sharepoint offer access to a vibrant ecosystem and robust APIs.

Preparing a Sheet for Data Ingestion

  1. Create an Excel workbook or Google sheet anywhere under your project directory. This document uses a sheet in OneDrive called email-form.xlsx in the root of an AEM project.
  2. Make sure the AEM user (for example helix@adobe.com) that is configured for your project has edit permission on the sheet.
  3. Open the workbook created and rename the default sheet to incoming.


    Note: AEM will not send any data to this workbook if the incoming sheet does not exist.
  4. Preview the sheet in the sidekick.
    Note: Even if a sheet has been previewed previously it must be previewed again after creating the incoming sheet for the first time.
  5. Set up the sheet with the headers that match the data being ingested. You can either do this manually or by sending a POST request to the form route in the AEM Admin service. The admin service will look at the data in the POST body and create the necessary headers/tables and sheets required to ingest data and get the most from the forms service.
    For details on the format of the POST request to set up your sheet, see the Admin API documentation as well as the following example:

    Request: 
    POST /form/{owner}/{repo}/{ref}/en/email-form.json HTTP/1.1
{"data":{"firstName":"test"}}


    Response: 
    HTTP/1.1 200 OK
{"rowCount":2,"columns":["firstName"]}


    You can use a tool like curl or Postman to make this POST request. For example: 
    curl -s -i -X POST 'https://admin.hlx.page/form/{owner}/{repo}/{ref}/en/email-form.json' \
--header 'Content-Type: application/json' \
--data '{"data":{"firstName":"test"}}'


    Through the above POST request, we are providing sample data i.e. the form fields and sample values which will be used by the Admin service for setting up the form.
    The Admin service is recommended to set up your sheet, but if you would like to create the headers manually, please see the document Manual Forms Sheet Setup.
  6. After sending the POST request to the admin service you will see the following changes to your workbook.
    1. A sheet named helix-default is created. The data in this sheet is what will be returned when a GET request is made to the sheet. This is a great place to use spreadsheet formulas to summarize the data from the incoming sheet for consumption elsewhere.

      Note: The helix-default sheet should never contain any personally identifiable information or other data you are not ok with being publicly accessible.
    2. A sheet named slack was created. Here you can set up automatic notifications to a Slack channel anytime data is ingested to your spreadsheet. Currently AEM only supports notifications to the AEM Engineering slack org as well as the Adobe Enterprise Support org.
      1. To setup Slack notifications enter the teamId of the Slack workspace and the channel name or ID. You can also ask the slack-bot (with the debug command) for the teamId and the channel ID. Using the channel ID instead of the name is preferable, as it survives channel renames.

        Note: Older forms didn’t have the teamId column. The teamId was included in the channel column, separated by a # or /.
      2. Enter any title you want and under fields enter the names of the fields you want to see in the Slack notification. Each heading should be separated by a comma (eg. name, email).


Sending Data to Your Sheet

The sheet is now ready for data ingestion and you can send POST requests directly to the sheet on hlx.page, hlx.live or your production domain.

POST https://ref–repo–owner.hlx.(page|live)/email-form
POST https://my-domain.com/email-form

Note: The URL should not include the .json extension. The sheet must be published for POST operations to work on .live or on the production domain.

There are a few different ways you can format the form data in the POST body.

That’s it! The forms service runs every minute so you will quickly see your data ingested into the sheet.

Author-Created Forms

In many cases it is desirable to have authors create forms and decide what form fields should be presented to the visitor of your website. It is common to use the helix-default sheet of the same spreadsheet that is used for the submission of the form as the place to let the author define their forms.

Usually, there is a forms block that takes a reference to the spreadsheet and renders the form and handles the user flow through submission.


A simple example of such a form block can be found here and the Adaptive Forms Block is available here.

When you need forms with features like reCAPTCHA, accessibility, file uploads, field validations, e-signing, performance monitoring, spreadsheet based rules, document of record (DoR) and more, use the Adaptive Forms Block. It supports a wide range of forms, from simple ones collecting basic info (like contact forms or service requests) to complex ones with multiple sections, rules, and integrations with Adobe Sign, Adobe Workfront, and external systems. You can even use it to send data to spreadsheets or connect with external systems for enterprise-level forms. For more details, check out AEM Forms Edge Delivery Services documentation.

See the following example of what the spreadsheet for the form definition could look like.

The supported form fields are extensible and the form should be viewed as an example that gives you a starting point.

As an example a fully-functional form was added to this page, using the previously-listed code base by simply adding the following block in the Google Doc:

https://main--helix-website--adobe.hlx.page/developer/example-form/example-form.json

Feel free to try it out and see the form data flow into the incoming sheet. It may take a minute to get from the form service to the spreadsheet.