Skip navigation

In my post Eloqua API How To: Submit A Form, the code assumes that you already know the ID of the Form that you are trying to submit.


But what if you don't already know this ID, or which fields are required in order to successfully submit the form?


Well, that's where the DescribeEntityType and DescribeEntity calls come in.


The DescribeEntityType operation is used to list all of the entities available in the system.  The following snippet will return all of the Forms for an Eloqua install:





// Set up the Eloqua API Service

EloquaServiceClient service = new EloquaServiceClient();


service.ClientCredentials.UserName.UserName = "Company\\User";

service.ClientCredentials.UserName.Password = "Password";



   // Execute the request

    DescribeEntityTypeResult result = service.DescribeEntityType("Form");




   // Extract the ID and Name of all Form EntityTypes

    foreach (EntityType entityType in result.EntityTypes)


        Console.WriteLine(String.Format("ID: {0}", entityType.ID));

        Console.WriteLine(String.Format("Name: {0}", entityType.Name));


With the returned data, you can locate your Form, and it's corresponding ID, to use for the submit.


The DescribeEntity operation is used to list the properties and field metadata of a DynamicEntity.  With this call,  you can determine which fields are required in order to submit a form.


See Eloqua API How To: Retrieve Entity Metadata for an example of it's usage.  In that code, you would use Form as the EntityType instead of Contact.


Using these operations, you'll be able to gather the information needed to work successfully with entities.

In a previous post, I showed you how to Eloqua API How To: Create and Retrieve a Contact.  This time we will look at how to create and retrieve a Custom Data Object (or Data Card).


The code below will show you how to create a new Data Card, then retrieve that Data Card to confirm that it was in fact saved in Eloqua.


Once again, I will be assuming that the code found Connecting to the Eloqua API - Generic Setup is being used to establish a connection to the Eloqua API.  It is also assumed that there is an existing Data Card Set created in Eloqua, and that you know it's ID and Data Card fields.


As before, we will be using the EloquaService API. For more information on which API to use for specific functions, see Eloqua SOAP API - Which one do I use?.


Now, the code...


    class CreateRetrieveDataCard
        static void Main()
            bool success = false;
            int dataCardId = 0;
            var dataCardIDs = new int[1];

                #region Setup the Eloqua service


                var service = new EloquaInstance("instance", "userid", "password");




                #region Create a DataCard using a Dynamic Entity


                // Build a DataCardSet Entity Type object - (the ID is the ID of an existing DataCardSet in Eloqua)
                EntityType entityType = new EntityType {ID = 31, Name = "DataCardSet", Type = "DataCardSet"};


               // Create an Array of Dynamic Entities
                DynamicEntity[] dynamicEntities = new DynamicEntity[1];


               // Create a new Dynamic Entity and add it to the Array of Entities
                dynamicEntities[0] = new DynamicEntity();
                dynamicEntities[0].EntityType = entityType;


               // Create a Dynamic Entity's Field Value Collection
                dynamicEntities[0].FieldValueCollection = new DynamicEntityFields();


               // Add the DataCard's Email Address field to the Dynamic Entity’s field collection
                dynamicEntities[0].FieldValueCollection.Add("Email1", "");


               // Add the DataCard's Title field to the Dynamic Entity’s field collection
                dynamicEntities[0].FieldValueCollection.Add("Title1", "Cloud");


               // Execute the request
                var result = service.ServiceProxy.Create(dynamicEntities);


               // Verify the status of each DataCard Create request in the results
                foreach (CreateResult t in result)
                        // Successfull requests return a positive integer value for ID
                    if (t.ID != -1)
                        dataCardId = t.ID;
                        success = true;
                        // Failed requests return a -1 integer value for ID
                        // Extract the Error Message and Error Code for each failed Create request
                        foreach (Error createError in t.Errors)
                            Console.WriteLine(String.Format("Code: {0}", createError.ErrorCode));
                            Console.WriteLine(String.Format("Message: {0}", createError.Message));




                #region Retrieve the DataCard dynamically


                if (success)
                    // Set the ID of the DataCard Entity
                    dataCardIDs[0] = dataCardId;


                    // Create a new list containing the fields you want populated
                    List<string> fieldList = new List<string>();


                    // Add DataCard fields to the field list


                    // Build a Dynamic Entity array to store the results
                    DynamicEntity[] retrievedEntities;


                    // If the field list is empty - the request will return all Entity Fields
                    // Otherwise, only fields defined in the field list are returned
                    retrievedEntities = service.ServiceProxy.Retrieve(entityType, dataCardIDs, fieldList.Count == 0 ? null : fieldList.ToArray());


                    // If a result was found, extract the field values for each Dynamic Entity
                    if (retrievedEntities.Length > 0)
                        foreach (DynamicEntity dynamicEntity in retrievedEntities)
                            Console.WriteLine("New DataCard Created Successfully!");


                            // Extract the Field Name and Value for each element in the collection
                            foreach (KeyValuePair<string, string> keyValPair in dynamicEntity.FieldValueCollection)
                                Console.WriteLine(String.Format("Field Name: {0}", keyValPair.Key));
                                Console.WriteLine(String.Format("Field Value: {0}", keyValPair.Value));




            // Customize your own error handling
            catch (System.ServiceModel.FaultException ex)
                // Catch Service Model Fault Exceptions
                Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString()));
                Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString()));
                Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString()));
            catch (Exception ex)
                // Catch System Exceptions
                Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString()));


            // Wait for user input before stepping out.
            Console.WriteLine("Press any key to continue.");





When the program is run, a console window will pop up showing the results as seen below.





In the post Building Cloud Connectors:  Connector or Feeder?, we discussed the differences between a step-based Cloud Connector, and a Feeder.


Put simply, a Feeder is an externally hosted application, that runs on a scheduled basis, and uses the Eloqua API to create  or "feed" Contacts and/or Custom Data Objects (aka DataCards) into Eloqua


When speaking with developers looking to build a Feeder, I am often asked what the basic implementation would look like.


In order to develop a Feeder, here are some basic things that you will need to do.


Develop and host your own application, external to Eloqua, that does the following:


1.  Presents a configuration page to the user that...



Collects the user's:

    • Eloqua username and password (for an API enabled account).
    • Eloqua Company name.
    • External system credentials (i.e. your system)



Allows the user to:


    • Configure field mappings between the two systems.
    • Select a contact group/list to put the contacts into.
    • Choose the interval at which to run (eg. Daily, Weekly, Monthly)



2.  Runs at the chosen interval, and uses the Eloqua API to...






Filter Blog

By date: By tag: