Discussions
Product Notice: Eloqua Application API Form endpoints – Classic Design Editor Sunset Impact (Feb 202
With the arrival of Eloqua release 20A (Feb 2020), the Create a form Application API Form endpoints will default to creating Responsive forms.
For more information on the sunsetting the classic form design editor, see the Sunset of Classic Design Editors: Forms product notice.
What’s changing?
The Sunset of Classic Design Editors: Forms will impact the following Application API Form endpoints in 20A:
- 1.0
- Create a form: POST /api/REST/1.0/assets/form
- Update a form: PUT /api/REST/1.0/assets/form/{id}
- 2.0
- Create a form: POST /api/REST/2.0/assets/form
- Update a form: PUT /api/REST/2.0/assets/form/{id}
Notes:
- 2.0:
- formJson property
- formJson is a property that is applicable only to forms of type responsive
- For legacy forms, this property is not expected to be present/set during updating
- formJson should always be set to "{\"type\":\"responsiveForm\",\"version\":\"1\"}" during creation
- It’s recommended to leave formJson out of the create or update request, and let it be set by default
- § If not included in the request, formJson will be set to "{\"type\":\"responsiveForm\",\"version\":\"1\"}" by default
- formJson is a property that is applicable only to forms of type responsive
- isResponsive property
- isResponsive is a read only property depicting the responsive type of a form
- § If a form is responsive then this property holds “true” otherwise it is “false” for legacy forms
- § Avoid sending this property during creation or updating as this is a computed property based on form type, and the value will be ignored
- formJson property
- 1.0:
- isResponsive and formJson are not returned with 1.0
- While there is not direct impact to 1.0, if retrieving forms with 2.0 that were created with 1.0 the same impact will be observed:
- isResponsive will be set to “true”
- formJson will be set to "{\"type\":\"responsiveForm\",\"version\":\"1\"}"
- After creating or updating a form, to properly set the form’s html, and formJson, it is mandatory to open the form in the UI and do a re-save, this is the same behavior as today for setting the html with legacy forms
Example
Prior to 20A, isResponsive is set to “false” and formJson is not returned by default:
Request:
POST /api/REST/2.0/assets/form
{
"name": "19D_Default_Create",
"elements": [
{
"type": "FormField",
"name": "Favorite color.",
"style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
"dataType": "text",
"displayType": "text",
"htmlName": "favCol"
}
],
"processingType": "externalEmail"
}
Response: 201 Created
{
"type": "Form",
"currentStatus": "Draft",
"id": "71",
"createdAt": "1578702142",
"createdBy": "11",
"depth": "complete",
"folderId": "7",
"name": "19D_Default_Create",
"permissions": [
"Retrieve",
"SetSecurity",
"Delete",
"Update"
],
"updatedAt": "1578702142",
"updatedBy": "11",
"elements": [
{
"type": "FormField",
"id": "385",
"name": "Favorite color.",
"style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
"dataType": "text",
"displayType": "text",
"htmlName": "favCol",
"useGlobalSubscriptionStatus": "False",
"validations": []
}
],
"isResponsive": "false",
"processingSteps": [],
"processingType": "externalEmail"
}
After 20A, isResponsive is set to “true” and formJson is returned by default:
Request:
POST /api/REST/2.0/assets/form
{
"name": "20A_Default",
"elements": [
{
"type": "FormField",
"name": "Favorite color.",
"style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
"dataType": "text",
"displayType": "text",
"htmlName": "favCol"
}
],
"processingType": "externalEmail"
}
Response: 201 Created
{
"type": "Form",
"currentStatus": "Draft",
"id": "25988",
"createdAt": "1579037707",
"createdBy": "4",
"depth": "complete",
"folderId": "7",
"name": "20A_Default",
"permissions": [
"Retrieve",
"SetSecurity",
"Delete",
"Update"
],
"updatedAt": "1579037707",
"updatedBy": "4",
"elements": [
{
"type": "FormField",
"id": "4590",
"name": "Favorite color.",
"style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
"dataType": "text",
"displayType": "text",
"htmlName": "favCol",
"useGlobalSubscriptionStatus": "False",
"validations": []
}
],
"formJson": "{\"type\":\"responsiveForm\",\"version\":\"1\"}",
"isResponsive": "true",
"processingSteps": [],
"processingType": "externalEmail"
}
Timeline
- With the arrival of Eloqua release 20A (Feb, 2020), the Create a form Application API Form endpoints will default to creating Responsive forms. Check the Eloqua Release Center for specific dates and times.
Next Steps
If creating Forms via the Application API:
- Avoid setting isResponsive, and prepare for it to be set to “true” by default
- Prepare for formJson to be returned, and it’s recommend to leave formJson out of the request, letting Eloqua set the default value
- To properly set the form’s html, and formJson, it is mandatory to open the form in the UI and do a re-save, this is the same behavior as today for setting the html with legacy forms
If updating Forms via the Application API:
- Avoid setting isResponsive and let Eloqua set the default value and refrain changing formJson as well
- If there is a new element added or an existing element is removed then you need to open the form in UI and re-save to properly update the formJson and html
If the form html will not be used, it’s not necessary to open the form in the UI and do a re-save. As an example, if just using the form for blind form submissions, the form html, and formJson, will not need to be updated.
Additional Resources
View changes for Eloqua's APIs including, new features, significant recent changes, and platform notices, on the Eloqua Developer Changelog.
If you have questions, post a discussion on Code It!
FAQ
Q: What endpoints are impacted by this change?
A: The following endpoints are impacted:
- 1.0
- Create a form: POST /api/REST/1.0/assets/form
- Update a form: PUT /api/REST/1.0/assets/form/{id}
- 2.0
- Create a form: POST /api/REST/2.0/assets/form
- Update a form: PUT /api/REST/2.0/assets/form/{id}
Q: Where can I learn more about the Sunset of Classic Design Editor?
A: For more information on the sunsetting the classic form design editor, see the Sunset of Classic Design Editors: Forms product notice.