Eloqua Application API Create an external activity endpoint – External Asset Types and External Activity Types No Longer Created and New Action Permission (Nov 2018)

Version 5

    Overview

     

    With the arrival of Eloqua release 18D (Nov 16 - 17, 2018), the Create an external activity Application API endpoint will no longer create External Asset Types or External Activity Types if they do not exist, and a new Action Permission, “Register External Activities”, will be required to use the Create an external activity Application API endpoint.

     

    What’s changing?

     

    Currently, when creating External Activities via the Application API, if External Asset Types or External Activity Types do not exist they are created, and there is no Action Permission corresponding to the Create an external activity Application API endpoint.

     

    A new Action Permission, “Register External Activities”, is being added in 18C, and with 18D, it will be enforced and required to create External Activities using the Application API.

     

    With 18D, the Create an external activity endpoint, POST /api/REST/2.0/data/activity, will no longer create External Asset Types or External Activity Types if they do not exist.

     

    Notes:

    • If the External Asset (assetName) does not exist, it will still be created
    • If the External Asset (assetName) included exists, but does not have the indicated External Asset Type (assetType) set as the externalAssetTypeId, a new External Asset will be created

     

    Example

     

    Prior to 18D, External Asset Types and External Activity Types that do not exist are created:

     

    POST /api/REST/2.0/data/activity

    {

      "name": "External Asset Name - Does Not Exist",

      "assetName": "External Asset Name - Does Not Exist",

      "assetType": "External Asset Type - Does Not Exist",

      "activityType": "External Activity Type - Does Not Exist",

      "activityDate": "1531780746",

      "campaignId": 47,

      "contactId": 1

    }

     

    Response: 201 Created

    {

      "type": "ExternalActivities",

      "id": "225660",

      "depth": "complete",

      "name": "External Asset Name - Does Not Exist",

      "activityDate": "1531780746",

      "activityType": "External Activity Type - Does Not Exist",

      "assetName": "External Asset Name - Does Not Exist",

      "assetType": "External Asset Type - Does Not Exist",

      "campaignId": 47,

      "contactId": 1

    }

     

     

    After 18D, External Asset Types or External Activity Types that do not exist will not be created, and will result in a validation error:

     

    POST /api/REST/2.0/data/activity

    {

      "name": "External Asset Name - Does Not Exist",

      "assetName": "External Asset Name - Does Not Exist",

      "assetType": "External Asset Type - Does Not Exist",

      "activityType": "External Activity Type - Does Not Exist",

      "activityDate": "1531780746",

      "campaignId": 47,

      "contactId": 1

    }

     

    Response: 400 ValidationError

    [

      {

        "type": "ObjectValidationError",

        "container": {

          "type": "ObjectKey",

          "objectType": "ExternalActivities"

        },

        "property": "assestTypeNotFound",

        "requirement": {

          "type": "ReferenceExistsRequirement"

        }

      },

      {

        "type": "ObjectValidationError",

        "container": {

          "type": "ObjectKey",

          "objectType": "ExternalActivities"

        },

        "property": "activityTypeNotFound",

        "requirement": {

          "type": "ReferenceExistsRequirement"

        }

      }

    ]

     

    Timeline

     

    With the arrival of Eloqua release 18C, a new Action Permission, “Register External Activities”, will be available. Release 18C is anticipated to arrive between Aug 17 - 18, 2018. Check the Eloqua Release Center for specific dates and times.

     

    With the arrival of Eloqua release 18D:

    • The new Action Permission, “Register External Activities”, will be enforced, and will be required to create External Activities using the Create an external activity Application API endpoint (POST /api/REST/2.0/data/activity).
    • The Create an external activity Application API endpoint (POST /api/REST/2.0/data/activity) will no longer create External Asset Types or External Activity Types if they do not exist.

     

    Release 18D is anticipated to arrive between Nov 16 - 17, 2018. Check the Eloqua Release Center for specific dates and times.

     

    Next Steps

     

    Make sure any Users that are creating External Activities using the Create an external activity Application API endpoint (POST /api/REST/2.0/data/activity) have the “Register External Activities” Action Permission prior to the 18D release, when it will be enforced.

     

    Action Permissions are set at the Security Group level, and Security Groups are assigned to Users. See Action permissions for instructions for viewing and setting Action Permissions. All Users in a Security Group can be viewed from the Security Group Overview screen, see Modifying security groups for instructions. To view current Security Groups for a specific User, and make changes, see Adding users to security groups.

     

    If relying on the Create an external activity Application API endpoint (POST /api/REST/2.0/data/activity) to create External Asset Types or External Activity Types if they do not exist, this will need to be updated to use the appropriate endpoint to create External Asset Types and External Activity Types before creating the External Activity:

     

    Confirm Users have the appropriate Action Permission to create External Assets and External Asset Types.

     

    Example

     

    1. Create External Asset Type with External Activity Type

     

    POST /api/REST/2.0/assets/external/type

    {

      "name": "External Asset Type - Exists",

      "activityTypes": [

        {

          "name": "External Activity Type - Exists"

        }

      ]

    }

     

    Response: 201 Created

    {

      "type": "ExternalAssetType",

      "id": "585",

      "createdAt": "1533076142",

      "createdBy": "71",

      "depth": "complete",

      "name": "External Asset Type - Exists",

      "updatedAt": "1533076142",

      "updatedBy": "71",

      "activityTypes":

    [

        {

          "type": "ExternalActivityType",

          "id": "656",

          "createdAt": "1533076143",

          "createdBy": "71",

          "depth": "complete",

          "name": "External Activity Type - Exists",

          "updatedAt": "1533076143",

          "updatedBy": "71"

        }

      ]

    }

     

    2. Create External Asset and link to External Asset Type created in Step 1

     

    Optional, as the External Asset will be created if it does not exist with Create an external activity Application API endpoint

     

    POST /api/REST/2.0/assets/external

    {

      "name": "External Asset Name - Exists",

      "externalAssetTypeId": "585"

    }

     

    Response: 201 Created

    {

      "type": "ExternalAsset",

      "id": "115",

      "createdAt": "1533076577",

      "createdBy": "71",

      "depth": "complete",

      "name": "External Asset Name - Exists",

      "updatedAt": "1533076577",

      "updatedBy": "71",

      "externalAssetTypeId": "585"

    }

     

    3. Create External Activity with existing External Asset, External Asset Type, and External Activity Type

     

    POST /api/REST/2.0/data/activity

    {

      "name": "External Asset Name - Exists",

      "assetName": "External Asset Name - Exists",

      "assetType": "External Asset Type - Exists",

      "activityType": "External Activity Type - Exists",

      "activityDate": "1531780746",

      "campaignId": 47,

      "contactId": 1

    }

     

    Response: 201 Created

    {

      "type": "ExternalActivities",

      "id": "650",

      "depth": "complete",

      "name": "External Asset Name - Exists",

      "activityDate": "1531780746",

      "activityType": "External Activity Type - Exists",

      "assetName": "External Asset Name - Exists",

      "assetType": "External Asset Type - Exists",

      "campaignId": 47,

      "contactId": 1

    }

     

    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 these changes?

    A: The Create an external activity Application API endpoint - POST /api/REST/2.0/data/activity

     

    Q: What is the difference between the three External Asset Action Permissions?

    A: “Define External Assets and Activities” allows a User to add and manage External Assets, External Asset Types, and External Activity Types. “Register External Activities”, with 18D, will allow a User to create External Activities using the Create an external activity Application API endpoint. “Upload External Assets” allows a User to upload External Activities.

     

    Q: How do I confirm a User has the “Register External Activities” Action Permission?

    A: Action Permissions are set at the Security Group level, and Security Groups are assigned to Users. See Action permissions for instructions for viewing and setting Action Permissions. To view current Security Groups for a specific User, and make changes, see Adding users to security groups.

     

    Q: Where can I find general information on External Assets and Activities?

    A: On this Help Center page: External assets and activities.