Discussions

Eloqua Application API Form endpoints – New “isHidden” property (May 2019 & Early Preview 19A)

OMC Documentation-Oracle
OMC Documentation-Oracle Posts: 103 Employee
edited Apr 3, 2019 10:34PM in Developer Tools

Overview

With the arrival of the 19B Eloqua release (May 2019), a new property, isHidden, that stores the “Form Visibility” form setting, will be added to the Application API Form endpoints. This feature can be enabled for Early Preview as of the 19A Eloqua release (Feb 2019)

What’s changing?

With 19B, we are adding isHidden to the Application API Form endpoints, which will impact the following endpoints:

Notes:

  • isHidden
  • When creating a Form using the API, if isHidden is not included in the request, isHidden will be set to “false”
  • When updating a Form using the API, if isHidden is not included in the request, isHidden will be set to “false”
  • The Partially update a form endpoint
  • In Eloqua, these Form Visibility Form Settings correlate to the following isHidden values:
    • Internal (Only visible within Eloqua) > isHidden = “true”
    • External (Visible to anyone with the URL) > isHidden = “false”
  • When creating a Form in Eloqua, the default Form Visibility Form Setting is “External (Visible to anyone with the URL)”
  • If a Form has isHidden set to “true”, Form submissions will not be accepted, including via both the 1.0 and 2.0 Create form data for a single form API endpoints, resulting in a 404 Object Not Found response
  • Forms created prior to 19B, or any Forms created prior to enabling this feature, will have isHidden
  • This update applies to both 1.0 and 2.0; however, all examples are using the Form 2.0 endpoints, and it’s recommended to use 2.0, as some features are only available on 2.0

Examples

After 19B, isHidden is returned when retrieving Forms at partial or complete depth:

Request:

GET /api/REST/2.0/assets/form/4594?depth=partial

Response: 200 OK

{

    "type": "Form",

    "currentStatus": "Draft",

    "id": "4594",

    "createdAt": "1551334814",

    "createdBy": "71",

    "depth": "partial",

    "folderId": "7",

    "name": "isHidden_true",

    "permissions": [

        "Retrieve",

        "SetSecurity",

        "Delete",

        "Update"

    ],

    "updatedAt": "1552670971",

    "updatedBy": "71",

    "elements": [

        {

            "type": "FormField",

            "id": "27700",

            "name": "Email Address",

            "style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",

"createdFromContactFieldId": "100001",

            "dataType": "text",

            "displayType": "text",

            "htmlName": "emailAddress",

"useGlobalSubscriptionStatus": "False",

            "validations": []

        },

        {

            "type": "FormField",

            "id": "27701",

            "name": "Submit",

            "style": "{\"submitButtonStyleType\":\"standard\",\"submitButtonWidthStyle\":\"100px\",\"submitButtonHeightStyle\":\"24px\"}",

            "altText": "Submit",

            "dataType": "text",

            "displayType": "submit",

            "htmlName": "submit",

"useGlobalSubscriptionStatus": "False",

            "validations": []

        }

    ],

    "htmlName": " isHidden_true",

    "isHidden": "true",

    "isResponsive": "false"

}

If isHidden is not included in the request to create a new Form, isHidden will be set to “false”:

Request:

POST /api/REST/2.0/assets/form

{   

    "name":"New Form without isHidden",

    "elements":[

        {

"type":"FormField",

            "name":"Favorite color.",

"style":"{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",

"dataType":"text",

"displayType":"text",

"htmlName":"favCol"

        }

    ],

"processingType":"externalEmail"

}

Response:

{

    "type": "Form",

    "currentStatus": "Draft",

    "id": "4623",

    "createdAt": "1552693787",

    "createdBy": "71",

    "depth": "complete",

    "folderId": "7",

    "name": "New Form without isHidden",

    "permissions": [

        "Retrieve",

        "SetSecurity",

        "Delete",

        "Update"

    ],

    "updatedAt": "1552693787",

    "updatedBy": "71",

    "elements": [

        {

            "type": "FormField",

            "id": "27796",

            "name": "Favorite color.",

            "style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",

            "dataType": "text",

            "displayType": "text",

            "htmlName": "favCol",

            "useGlobalSubscriptionStatus": "False",

            "validations": []

        }

    ],

    "isHidden": "false",

    "isResponsive": "false",

    "processingSteps": [],

    "processingType": "externalEmail"

}

If isHidden is not included in request to update a Form, isHidden will be set to “false”:

To demonstrate, this request:

PUT /api/REST/2.0/assets/form/4626

{   

    "id": "4626",

    "name": "Form Update"

}

Is the same as submitting this request:

PUT /api/REST/2.0/assets/form/4626

{   

    "id": "4626",

    "name": "Form Update",

    "isHidden": "false"

}

If submitting a request to create form data to a Form that has isHidden set to “true” the response will be a 404:

Form Id 4626 has isHidden set to “true”

Request:

POST /api/REST/2.0/data/form/4626

{

    "fieldValues": [

        {

            "id": "27799",

            "value": "blue"

        }  

    ]

}

Response:

404 Object Not Found (id: 4626)

Timeline

With the arrival of the 19B Eloqua release (May 2019), a new property, isHidden, that stores the “Form Visibility” form setting will be added to the Application API Form endpoints. This feature can be enabled for Early Preview as of the 19A Eloqua release (Feb 2019). Check the Eloqua Release Center for specific dates and times.

Next Steps

If retrieving Forms via the Application API, prepare for the isHidden property to be returned at partial or complete depth.

If creating or updating Forms via the Application API, you’ll need to be aware that if not including isHidden within the request to create or update a Form, isHidden will be set to “false”. The Partially update a form endpoint can be used to only update fields included in the request, i.e. if isHidden is left out of the request, it will not be modified.

If submitting form data via the Application API, you’ll need to be aware that receiving a 404 Object Not Found response can indicate isHidden is set to “true”, i.e. the Form has been set to Internal.

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:

Q: If a Form has isHidden set to “true” and I submit an update API request without isHidden, will isHidden change to “false”?

A: Yes. The Partially update a form endpoint can be used to only update fields included in the request, i.e. if isHidden is left out of the request, it will not be modified.

Q: How can I enable the feature for Early Preview in 19A?

A: Submit an SR to request the feature to be enabled.