In building any application against the Eloqua API, whether for a Cloud Connector, or for another application type, one of the most common things you’ll need to do is to map the fields which you’re going to store data in or read data from.  Whether for contact fields, prospect fields, company fields, or data card fields, you’ll find yourself performing this task frequently.

 

In this sample code snippet, which uses the same general setup for the API as we have used for many other code snippets, we’ll look at populating a dropdown list box with the fields on a contact record.

 

The first function that we’ll use is ListContactFields, which queries the API and retrieves a list of the fields defined for the Base type of “Contact” using the DescribeEntity call.  The field definition returns the following values:

 

DisplayName – the name presented to the Eloqua user (ie “First Name”)

InternalName – a system name, that is used for field querying or updating (ie “C_FirstName”)

IsRequired – a Boolean value for whether the field is required and a create or update will fail if it is left blank

IsWriteable – a Boolean value for whether the field can be written to, or is a system field

DataType – the type (Number, Date, String, etc) of the field

 

 

        public List<string[]> ListContactFields()

        {

 

            if (this.ContactFieldList.Count() > 0)

            {

                return this.ContactFieldList;

            }

            else

            {

                string[] tmpFields;

                List<string[]> FieldList = new List<string[]>();

                try

                {

                    // Execute the request

                    EloquaServiceNew.EntityType entityType = new EloquaServiceNew.EntityType();

 

                    entityType.ID = 0;

                    entityType.Name = "Contact";

                    entityType.Type = "Base";

 

                    // Execute the request

 

                    if (this.OkayForNextEloquaAPICall(APICallType.DescribeEntity))

                    {   //pauses thread until 1 second has elapsed

                    }

                    EloquaServiceNew.DescribeEntityResult result = serviceProxy.DescribeEntity(entityType);

 

                    // Extract the ID, Name and Type of each Asset Type

 

                    foreach (EloquaServiceNew.DynamicEntityFieldDefinition fieldDef in result.Fields)

                    {

                        tmpFields = new string[5];

                        tmpFields[0] = fieldDef.DisplayName;

                        tmpFields[1] = fieldDef.InternalName;

                        tmpFields[2] = Convert.ToString(fieldDef.IsRequired);

                        tmpFields[3] = Convert.ToString(fieldDef.IsWriteable);

                        tmpFields[4] = Convert.ToString(fieldDef.DataType);

 

                        FieldList.Add(tmpFields);

                    }

                    CPMFieldListComparer flc = new CPMFieldListComparer();

 

                    FieldList.Sort(18, FieldList.Count - 18, flc);

 

                }

                catch (Exception ex)

                {

                    Trace.TraceWarning(String.Format("Exception in EloquaInstance:ListContactFields {0} :: {1}", ex.Message, ex.InnerException), "Exception");

 

                }

                this.ContactFieldList = FieldList;

                return FieldList;

            }

        }

 

Two things to note about this.  First, the EloquaInstance object definition has a ContactFieldList property added so that the retrieved set of fields can be saved if multiple fields are being mapped in one interface.  This is a very common usage pattern, and you may want to consider this.

 

Second, the fields are sorted using a specific Compare function that allows them to be sorted only from the 18th value forward.  If you notice, the typical Eloqua Contact Field dropdown has standard fields like email address, first name, last name, and address at the top, and then an alphabetically sorted list of fields below that.  To do this, we use:

 

    CPMFieldListComparer flc = new CPMFieldListComparer();

 

    FieldList.Sort(18, FieldList.Count - 18, flc);

 

 

    public class CPMFieldListComparer : IComparer<string[]>

    {

        public int Compare(string[] xField, string[] yField)

        {

            return string.Compare(xField[0], yField[0]);

        }

    }

 

With this List of string[] values returned, we can then begin to populate the dropdown list for our application.   This follows a normal pattern, but looks carefully at whether the field is read only or not, whether the field will be used to read from or write to, and what data type the field is.  Eloqua fields will return the following as data types:

 

Text: up to 100 chars

LargeText: 4000 chars

Number: whole number

Numeric: number with a decimal place

Date: date and time value

 

Looking at these values, the dropdown list can be populated with contact field values and the selected value chosen, allowing the user to quickly select which fields they would like to read contact data from or write contact data to.  Note that this is not always a simple one-to-one map, as date values can be written into string fields, and numeric values can be read into string variables, but not vice versa.

 

        public void PopulateContactFieldDropdown(DropDownList ddlTarget, string strValue, string strFieldType, bool blnReadOnly)

        {

            string strEloquaDataType = "";

            if (ddlTarget != null)

            {

                List<string[]> tmpContactFields = this.ListContactFields();

                if (tmpContactFields == null || tmpContactFields.Count == 0)

                {

                    ddlTarget.Items.Clear();

 

                    ddlTarget.Items.Add(new ListItem("(input Eloqua credentials and save)", "-1"));

 

                }

                else

                {

                    ddlTarget.Items.Clear();

 

                    ddlTarget.Items.Add(new ListItem("(please select field)", "-1"));

                    foreach (string[] tmpField in tmpContactFields)

                    {

                        strEloquaDataType = tmpField[4];

                        if ((tmpField[3] == "True") || blnReadOnly) //is writeable or field is read only

                        {

                            if (blnReadOnly)

                            {

                                switch (strFieldType)

                                {

                                    case "string":

                                        ddlTarget.Items.Add(new ListItem(tmpField[0], tmpField[1]));

                                        break;

                                    case "int":

                                        if ((strEloquaDataType == "Number") || (strEloquaDataType == "Numeric"))

                                            ddlTarget.Items.Add(new ListItem(tmpField[0], tmpField[1]));

                                        break;

                                    case "date":

                                        if ((strEloquaDataType == "Date"))

                                            ddlTarget.Items.Add(new ListItem(tmpField[0], tmpField[1]));

                                        break;

                                }

                            }

                            else

                            {

                                switch (strFieldType)

                                {

                                    case "string":

                                        if ((strEloquaDataType == "Text") || (strEloquaDataType == "LargeText"))

                                            ddlTarget.Items.Add(new ListItem(tmpField[0], tmpField[1]));

                                        break;

                                    case "int":

                                        if ((strEloquaDataType == "Numeric") || (strEloquaDataType == "Number") || (strEloquaDataType == "Text"))

                                            ddlTarget.Items.Add(new ListItem(tmpField[0], tmpField[1]));

                                        break;

                                    case "date":

                                        if ((strEloquaDataType == "Date") || (strEloquaDataType == "Text"))

                                            ddlTarget.Items.Add(new ListItem(tmpField[0], tmpField[1]));

                                        break;

                                }

                            }

                        }

                    }

                   if (ddlTarget.Items.FindByValue(strValue) != null)

                        ddlTarget.Items.FindByValue(strValue).Selected = true;

                }

            }

        }