Forms

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.

Make sure the AEM user (for example helix@adobe.com) that is configured for your project has edit permission on the sheet.

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.

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.

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.

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).