Eloqua Application API Form endpoints - “PreventXSSCondition” field validation (Nov 2018)

Version 3

    Overview

     

    With the arrival of Eloqua release 18D (Nov 16 - 17, 2018), the Application API 2.0 Form endpoints will receive a new field validation of “PreventXSSCondition.”

     

    The Application API 1.0 Form endpoints will not receive this new field validation of “PreventXSSCondition.”

     

    What’s changing?

     

    With 18D, a new field validation “PreventXSSCondition” is being added to prevent form data from being saved if HTML in present in a field. This will impact the following Application API Form endpoints:

    • 1.0
    • 2.0 (The 2.0 endpoints are fully supported, and will be documented soon)
      • Retrieve a list of forms: GET /api/REST/2.0/assets/forms
        • Default depth is minimal
      • Retrieve an form: GET /api/REST/2.0/assets/form/{id}
        • Default depth is complete
      • Create a form: POST /api/REST/2.0/assets/form
        • Default depth is complete
      • Update a form: PUT /api/REST/2.0/assets/form/{id}
        • Default depth is complete

     

    Notes:

    • The processingSteps are only returned at complete depth
    • When retrieving forms with Application API 2.0 Form endpoints:
      • There will be no change to any requests at the minimal level, as validations are not returned at the minimal level
      • validations are returned at depths of partial and complete
      • When “PreventXSSCondition” field validation is selected for a field, it is returned within the validations list as type “PreventXSSCondition”
      • If “PreventXSSCondition” field validation is not selected for a field, there is no item returned in validations list for that field
    • When retrieving forms using the Application API 1.0 Form endpoints:
      • There will be no change to any requests at the minimal level, as validations are not returned at the minimal level
      • When retrieving a form by id, if any field includes the “PreventXSSCondition” field validation, the form will not be retrievable, resulting in a 501 error message
      • When retrieving a list of forms at partial or complete depth, if any form has a field that includes the “PreventXSSCondition” field validation, that field and any fields after this field will not be included in response
    • When creating, or updating, a form in the UI (Forms Editor):
      • The “PreventXSSCondition” field validation is available as optional, and typically selected by default, for the data types of “text” and “largeText” on the following field display types:
        • text
        • textArea
      • The “PreventXSSCondition” field validation is mandatory for the data types of “text” and “largeText” on the following field display types:
        • singleSelect
        • multiSelect
        • radio
        • checkbox
        • hidden
    • When creating or updating a form using the Application API 1.0 Form endpoints (POST /api/REST/1.0/assets/form or PUT /api/REST/1.0/assets/form/{id} ):
      • The “PreventXSSCondition” field validation is not available, and if trying to include it in the request, it will result in a 400 error message
    • When creating or updating a form using the Application API 2.0 Form endpoints (POST /api/REST/2.0/assets/form or PUT /api/REST/2.0/assets/form/{id} ):
      • It’s recommended to include the “PreventXSSCondition” field validation on all fields it is available, unless the field specifically requires collecting HTML
    • When updating a form using the Application API 2.0 Form endpoint (PUT /api/REST/2.0/assets/form/{id}):
      • It’s recommended to include the “PreventXSSCondition” field validation on all fields it is available, unless the field specifically requires collecting HTML
      • Once created, if the “PreventXSSCondition” field validation is not included in the POST /api/REST/<version>/assets/form request, for the data types of “text” and “largeText” on the following field display types, it can only be added via API (PUT /api/REST/2.0/assets/form/{id}):
        • singleSelect
        • multiSelect
        • radio
        • checkbox
        • hidden
    • We have officially supported the 2.0 Form endpoints as of release 483

     

     

    Examples – Retrieving Forms

     

    Retrieving a form that includes the “PreventXSSCondition” field validation on at least one field with 2.0:

     

    GET /api/REST/2.0/assets/forms?search=AFTER_18D_PreventXSSCondition_Selected&depth=partial

     

    Response:

     

    {

      "elements": [

        {

          "type": "Form",

          "currentStatus": "Draft",

          "id": "4229",

          "createdAt": "1536607868",

          "createdBy": "71",

          "depth": "partial",

          "folderId": "7",

          "name": "AFTER_18D_PreventXSSCondition_Selected",

          "permissions": [

            "Retrieve",

            "SetSecurity",

            "Delete",

            "Update"

          ],

          "updatedAt": "1536614600",

          "updatedBy": "71",

          "elements": [

            {

              "type": "FormField",

              "id": "25925",

              "name": "Email Address",

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

              "createdFromContactFieldId": "100001",

              "dataType": "text",

              "displayType": "text",

              "fieldMergeId": "138",

              "htmlName": "emailAddress",

              "useGlobalSubscriptionStatus": "False",

              "validations": [

                {

                  "type": "FieldValidation",

                  "id": "62600",

                  "depth": "partial",

                  "description": "Form Field Validation Rule",

                  "name": "Form Field Validation Rule",

                  "condition": {

                    "type": "IsEmailAddressCondition"

                  },

                  "isEnabled": "true",

                  "message": "A valid email address is required"

                },

                {

                  "type": "FieldValidation",

                  "id": "62601",

                  "depth": "partial",

                  "description": "Form Field Validation Rule",

                  "name": "Form Field Validation Rule",

                  "condition": {

                    "type": "IsRequiredCondition"

                  },

                  "isEnabled": "true",

                  "message": "This field is required"

                }

              ]

            },

            {

              "type": "FormField",

              "id": "25926",

              "name": "First Name",

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

              "createdFromContactFieldId": "100002",

              "dataType": "text",

              "displayType": "text",

              "fieldMergeId": "140",

              "htmlName": "firstName",

              "useGlobalSubscriptionStatus": "False",

              "validations": [

                {

                  "type": "FieldValidation",

                  "id": "62602",

                  "depth": "partial",

                  "description": "Form Field Validation Rule",

                  "name": "Form Field Validation Rule",

                  "condition": {

                    "type": "PreventUrlCondition"

                  },

                  "isEnabled": "true",

                  "message": "Value must not contain any URL's"

                },

                {

                  "type": "FieldValidation",

                  "id": "62603",

                  "depth": "partial",

                  "description": "Form Field Validation Rule",

                  "name": "Form Field Validation Rule",

                  "condition": {

                    "type": "PreventXSSCondition"

                  },

                  "isEnabled": "true",

                  "message": "Value must not contain any HTML"

                },

                {

                  "type": "FieldValidation",

                  "id": "62604",

                  "depth": "partial",

                  "description": "Form Field Validation Rule",

                  "name": "Form Field Validation Rule",

                  "condition": {

                    "type": "TextLengthCondition",

                    "maximum": "35",

                    "minimum": "0"

                  },

                  "isEnabled": "true",

                  "message": "Invalid length for field value"

                }

              ]

            },

            {

              "type": "FormField",

              "id": "25927",

              "name": "Submit",

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

              "altText": "Submit",

              "dataType": "text",

              "displayType": "submit",

              "htmlName": "submit",

              "useGlobalSubscriptionStatus": "False",

              "validations": [         

              ]

            }

          ],

          "htmlName": "AFTER_18D_PreventXSSCondition_Selected"

        }

      ],

      "page": 1,

      "pageSize": 1000,

      "total": 1

    }

     

    Retrieving a form that includes the “PreventXSSCondition” field validation on at least one field, same form as above example, with 1.0:

     

    GET /api/REST/1.0/assets/forms?search=AFTER_18D_PreventXSSCondition_Selected&depth=partial

     

    Response:

     

    {

      "elements": [

        {

          "type": "Form",

          "currentStatus": "Draft",

          "id": "4229",

          "createdAt": "1536607868",

          "createdBy": "71",

          "depth": "partial",

          "folderId": "7",

          "name": "AFTER_18D_PreventXSSCondition_Selected",

          "permissions": "fullControl",

          "updatedAt": "1536614600",

          "updatedBy": "71",

          "elements": [

            {

              "type": "FormField",

              "id": "25925",

              "name": "Email Address",

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

              "createdFromContactFieldId": "100001",

              "dataType": "text",

              "displayType": "text",

              "fieldMergeId": "138",

              "htmlName": "emailAddress",

              "validations": [

                {

                  "type": "FieldValidation",

                  "id": "62600",

                  "depth": "partial",

                  "description": "Form Field Validation Rule",

                  "name": "Form Field Validation Rule",

                  "condition": {

                    "type": "IsEmailAddressCondition"

                  },

                  "isEnabled": "true",

                  "message": "A valid email address is required"

                },

                {

                  "type": "FieldValidation",

                  "id": "62601",

                  "depth": "partial",

                  "description": "Form Field Validation Rule",

                  "name": "Form Field Validation Rule",

                  "condition": {

                    "type": "IsRequiredCondition"

                  },

                  "isEnabled": "true",

                  "message": "This field is required"

                }

              ]

            }

          ],

          "htmlName": "AFTER_18D_PreventXSSCondition_Selected"

        }

      ],

      "page": 1,

      "pageSize": 1000,

      "total": 1

    }

     

     

    Examples – Creating and Updating Forms

     

    Example - Creating a form that includes the “PreventXSSCondition” field validation (2.0 only):

     

    It’s recommended to include the “PreventXSSCondition” field validation on all fields it is available, unless the field specifically requires collecting a HTML. It’s also recommended to include "TextLengthCondition" field validation set to a maximum of 35 on all fields it is available. Read more about 35 character maximum limit on form fields by default in the 487 release.

     

    POST /api/REST/2.0/assets/form

     

    Request Body:

     

    {

      "type": "Form",

      "name": "AFTER_18D_PreventXSSCondition_Selected_Create_API",

      "elements": [

        {

          "type": "FormField",

          "id": "-1",

          "name": "Email Address",

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

          "createdFromContactFieldId": "100001",

          "dataType": "text",

          "displayType": "text",

          "fieldMergeId": "1",

          "htmlName": "emailAddress",

          "validations": [

            {

              "type": "FieldValidation",

              "id": "-2",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "IsRequiredCondition"

              },

              "isEnabled": "true",

              "message": "This field is required"

            },

           {

              "type": "FieldValidation",

              "id": "-3",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "-4",

              "depth": "partial",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "-5",

          "name": "Paragraph Text",

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

          "dataType": "largeText",

          "displayType": "textArea",

          "htmlName": "paragraphText",

          "validations": [

            {

              "type": "FieldValidation",

              "id": "-6",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "-7",

              "depth": "partial",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "-4",

          "name": "Hidden Field",

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

          "dataType": "text",

          "displayType": "hidden",

          "htmlName": "hiddenField",

          "useGlobalSubscriptionStatus": "False",

          "validations": [

            {

              "type": "FieldValidation",

              "id": "-5",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "-6",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "-7",

          "name": "Hidden Field",

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

          "dataType": "text",

          "displayType": "hidden",

          "htmlName": "hiddenCampaignId2",

          "useGlobalSubscriptionStatus": "False",

          "validations": [

            {

              "type": "FieldValidation",

              "id": "-8",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "-9",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "-10",

          "name": "Submit",

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

          "altText": "Submit",

          "dataType": "text",

          "displayType": "submit",

          "htmlName": "submit",

          "validations": [

         

          ]

        }

      ],

      "htmlName": "AFTER_18D_PreventXSSCondition_Selected_Create_API"

    }

     

    Response:

     

    {

      "type": "Form",

      "currentStatus": "Draft",

      "id": "4235",

      "createdAt": "1536616802",

      "createdBy": "71",

      "depth": "complete",

      "folderId": "7",

      "name": "AFTER_18D_PreventXSSCondition_Selected_Create_API",

      "permissions": [

        "Retrieve",

        "SetSecurity",

        "Delete",

        "Update"

      ],

      "updatedAt": "1536616802",

      "updatedBy": "71",

      "elements": [

        {

          "type": "FormField",

          "id": "25954",

          "initialId": "-1",

          "name": "Email Address",

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

          "createdFromContactFieldId": "100001",

          "dataType": "text",

          "displayType": "text",

          "fieldMergeId": "1",

          "htmlName": "emailAddress",

          "useGlobalSubscriptionStatus": "False",

          "validations": [

            {

              "type": "FieldValidation",

              "id": "62626",

              "initialId": "-2",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "IsRequiredCondition"

              },

              "isEnabled": "true",

              "message": "This field is required"

            },

            {

              "type": "FieldValidation",

              "id": "62627",

              "initialId": "-3",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "62628",

              "initialId": "-4",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "25955",

          "initialId": "-5",

          "name": "Paragraph Text",

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

          "dataType": "largeText",

          "displayType": "textArea",

          "htmlName": "paragraphText",

          "useGlobalSubscriptionStatus": "False",

          "validations": [

            {

              "type": "FieldValidation",

              "id": "62629",

              "initialId": "-6",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "62630",

              "initialId": "-7",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "25956",

          "initialId": "-4",

          "name": "Hidden Field",

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

          "dataType": "text",

          "displayType": "hidden",

          "htmlName": "hiddenField",

          "useGlobalSubscriptionStatus": "False",

          "validations": [

           {

              "type": "FieldValidation",

              "id": "62631",

              "initialId": "-5",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "62632",

              "initialId": "-6",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "25957",

          "initialId": "-7",

          "name": "Hidden Field",

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

          "dataType": "text",

          "displayType": "hidden",

          "htmlName": "hiddenCampaignId2",

          "useGlobalSubscriptionStatus": "False",

          "validations": [

            {

              "type": "FieldValidation",

              "id": "62633",

              "initialId": "-8",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "PreventXSSCondition"

              },

              "isEnabled": "true",

              "message": "Value must not contain any HTML"

            },

            {

              "type": "FieldValidation",

              "id": "62634",

              "initialId": "-9",

              "depth": "complete",

              "description": "Form Field Validation Rule",

              "name": "Form Field Validation Rule",

              "condition": {

                "type": "TextLengthCondition",

                "maximum": "35",

                "minimum": "0"

              },

              "isEnabled": "true",

              "message": "Invalid length for field value"

            }

          ]

        },

        {

          "type": "FormField",

          "id": "25958",

          "initialId": "-10",

          "name": "Submit",

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

          "altText": "Submit",

          "dataType": "text",

          "displayType": "submit",

          "htmlName": "submit",

          "useGlobalSubscriptionStatus": "False",

          "validations": [

         

          ]

        }

      ],

      "htmlName": "AFTER_18D_PreventXSSCondition_Selected_Create_API",

      "processingSteps": [

     

      ],

      "processingType": "externalWebsite"

    }

     

     

    Timeline

     

    With the arrival of Eloqua release 18D, the Application API 2.0 Form endpoints will receive a new field validation of “PreventXSSCondition”. Release 18D is anticipated to arrive between Nov 16 - 17, 2018. Check the Eloqua Release Center for specific dates and times.

     

    Next Steps

     

    If retrieving forms using the Application API, it’s recommended to start using the 2.0 form endpoints and prepare for the “PreventXSSCondition” field validation to be returned within validations.

     

    If creating or updating forms using the Application API, it’s recommended to start using the 2.0 Form endpoints, and including the “PreventXSSCondition” field validation on all fields it is available, unless the field specifically requires collecting HTML.

     

    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: All Form Application API endpoints (1.0 and 2.0), except DELETE endpoints.

     

    Q: I do not see the Form Application 2.0 endpoints within published endpoints, are they officially supported?

    A: Yes, the Form Application 2.0 endpoints are officially supported, and we are currently working on adding these endpoints to our officially supported documentation.