Skip navigation

In the post Eloqua API How To: Create a Contact Group we looked at creating a new Contact Group asset.  Since Eloqua does not allow more than one asset type with the same name (in the same instance), when creating a new asset, it is very useful to know the names of existing assets of the same type.

 

That's when DescribeAssetType comes in handy.

 

The DescribeAssetType operation is used to list all of the entities of a particular type available in an instance. 

 

The following snippet will return all of the ContactGroup type Assets for a given Eloqua instance:

Note: we will assume that the code from here is also being used.

 

          //Set up the Eloqua Service
          var service = new EloquaInstance("instance", "userid", "password");  

          // Execute the request
          DescribeAssetTypeResult result = service.ServiceProxy.DescribeAssetType("ContactGroup");

          //Extract the ID, Name and Type of each Asset Type
          foreach (AssetType AssetType in result.AssetTypes)
          {
                         Console.WriteLine(String.Format("ID: {0}", AssetType.ID));
                         Console.WriteLine(String.Format("Type: {0}", AssetType.Type));
                         Console.WriteLine(String.Format("Name: {0}", AssetType.Name));
          }

 

You can now loop through the returned data, and check to make sure that Contact Group you are trying to create does not already exist.

Previous posts have shown how to create a Contact or a Data Card, and even how to add a Contact to a Contact Group

 

But what if the group that you want to add a contact to does not already exist in Eloqua?

 

In this post we will look at how to create a new Contact Group in Eloqua.

Note: we will assume that the code from here is also being used.


On to the code...

 

class CreateContactGroup
    {
        static void Main()
        {
            try
            {               
                //Set up the Eloqua Service
                var service = new EloquaInstance("instance", "userid", "password");

                // Build a Contact Group Asset Type object
                var assetType = new AssetType {ID = 0, Name = "ContactGroupName", Type = "ContactGroup"};

                // Create a new Array of Dynamic Assets
                DynamicAsset[] dynamicAssets = new DynamicAsset[1];

                // Create a new Dynamic Asset
                dynamicAssets[0] = new DynamicAsset
                                       {
                                           AssetType = assetType,
                                           FieldValueCollection = new DynamicAssetFields()
                                       };

                // Create a Dynamic Asset's Field Value Collection
                // Add the Contact Group's Name field to the Field Collection
                dynamicAssets[0].FieldValueCollection.Add("name", "TJs API Contacts");

                // Add the Contact Group's Description field to the Field Collection
                dynamicAssets[0].FieldValueCollection.Add("description", "A contact group created through the SOAP API");

                // Execute the request
                CreateAssetResult[] result = service.ServiceProxy.CreateAsset(dynamicAssets);

                // Verify the status of each Contact Group Create request in the results
                for (int i = 0; i < result.Length; i++)
                {
                    // Successfull requests return a positive integer value for ID
                    if (result[i].ID != -1)
                    {
                        Console.WriteLine("Success");
                    }
                    // Failed requests return a -1 integer value for ID
                    else
                    {
                        Console.WriteLine("Failure");

                        // Extract the Error Message and Error Code for each failed Create request
                        foreach (Error createError in result[i].Errors)
                        {
                            Console.WriteLine(String.Format("Code: {0}", createError.ErrorCode));
                            Console.WriteLine(String.Format("Message: {0}", createError.Message));
                        }
                    }
                }
            }
            catch (System.ServiceModel.FaultException ex)
            {
                // Customize your own Error handling code.
                Console.WriteLine(String.Format("Reson: {0}", ex.Reason));
                Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType()));
                Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name));
            }
            catch (Exception ex)
            {
                // Customize your own Error handling code.
                Console.WriteLine(String.Format("Exception Message: {0}", ex.Message));
            }

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

 

When the code executes, as long as the group name does not already exist in the instance that you are using, the new group will be created in Eloqua.  See Eloqua API How To: Describe an Asset Type for details on how to determine if a group of the same name already exists in an Eloqua instance.

newContactGroup.png

 

Once the Group has been successfully created, you will have the ID of the group that you can use to add a Contact to it.

Previously, we've looked at how to use the Eloqua API to pull Contacts, Data Cards, and Activity data from an Eloqua instance.

 

But what about data related to Visitors?

 

In this post, we will see an example of how to query for Visitor Profile Data stored in an Eloqua instance.

 

Once again, we will assume that the code found here is being used to establish a connection to the Eloqua API, and we will be using the EloquaService API (see Eloqua API - Which one do I use?).

 

The code is the same as that used for Eloqua API How To: Query a Contact by Email Address, with the exception of entityType.Name being "Visitor" instead of "Contact", and the use of a different search term.

 

In this snippet, we will use the Visitor field called "V_FirstVisitDateAndTime".  We will use the search term V_FirstVisitDateAndTime>2012-03-01 to bring back all Visitor data since March 1st, 2012.  You may choose to query using other fields, in this case, please see Eloqua API How To: Describe an Entity and Eloqua API How To: Query a Contact by Multiple Fields for more information on how to do this. 

 

(Note: Eloqua Visitor profile data is read-only)

 

Now, to the code...

 

    class QueryVisitorData

    {

        static void Main()

        {

           const string searchQuery = "V_FirstVisitDateAndTime>2012-03-01";

 

            try

            {

               //Create the service instance using your credentials

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

 

                // Instantiate a Visitor Entity Type

                EntityType visitorEntityType = new EntityType

                               {

                                  ID = 0,

                                  Name = "Visitor",

                                  Type = "Base"

                               };

 

                // Create a new list containing the fields you want populated

                // We will leave this empty for now, which will cause the code to return all fields

                List<string> fieldList = new List<string>();

 

                // Define a container for the Query results

                DynamicEntityQueryResults queryResult;

 

                // Set the page number and size for the results

                const int currentPage = 1;

                const int pageSize = 20;

 

                // If the field list is empty - the request will return all Entity Fields

                if (fieldList.Count == 0)

                {

                    // Execute the request and return all of the Entity's fields

                    queryResult = service.ServiceProxy.Query(visitorEntityType, searchQuery, null, currentPage, pageSize);

                }

                else

                {

                    // Execute the request and return only the selected fields

                    queryResult = service.ServiceProxy.Query(visitorEntityType, searchQuery, fieldList.ToArray(), currentPage, pageSize);

                }

 

                if (queryResult.Entities.Length > 0)

                {

                    //Extract the total number of pages and records

                    Console.WriteLine(String.Format("Total number of pages: {0}", queryResult.TotalPages));

                    Console.WriteLine(String.Format("Total number of records: {0}", queryResult.TotalRecords));

 

                    // Extract each Dynamic Entity in the result

                    foreach (DynamicEntity dynamicEntity in queryResult.Entities)

                    {

                        // Extract the field name and value of each field in the collection

                        foreach (KeyValuePair<string, string> field in dynamicEntity.FieldValueCollection)

                        {

                            Console.WriteLine(String.Format("Field Name: {0}: {1}", field.Key, field.Value));

                        }

                    }

                }

            }

 

            // Customize your own error handling code

            catch (System.ServiceModel.FaultException ex)

            {

                // Catch Service Model Fault Exceptions

                Console.WriteLine(String.Format("Reason: {0}", ex.Reason));

                Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType()));

                  Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name));

            }

            catch (Exception ex)

            {

                // Catch System Exceptions

                Console.WriteLine(String.Format("Exception Message: {0}", ex.Message));

            }

 

            // Wait for user input before stepping out.

            Console.WriteLine("Press any key to continue.");

            Console.ReadKey();

        }

    }