Recently, we looked at counting the members of a program builder step in order to trigger the actions of a Cloud Connector step.  Once you’ve counted the members, the next step is to retrieve the details of who is in the step.

 

The following code snippet shows you how this can be accomplished.  We start of with a copy of the general API setup instructions, which, if you've followed already, are common between code snippets.

 

First, the following SOAP Endpoints are defined:

 

EloquaProgramService  as: https://secure.eloqua.com/api/1.2/ExternalActionService.svc?wsdl

 

and EloquaServiceNew as: https://secure.eloqua.com/API/1.2/Service.svc?wsdl

 

 

With that, let’s create an object to manage our communication with Eloqua.  In creating an instance of this class, we’ll pass in three variables – the Eloqua Instance  name, the User ID, and the Password.

 

The Eloqua Instance name is the company name that you use on your login page.  Your user id and password represent the user account for an account that has API access.  To have API access, two things must be true – the API must be enabled for your instance, and the account you are using must have the right to use the API.  To turn on the API for your install, just call the Eloqua support desk and ask them to enable it for you.  Your system administrator will be able to grant access to the API security rights under the Admin console.

 

With that set up, our constructor just creates a serviceProxy for each endpoint and applies the Client Credentials to it.  The Eloqua Instance Name and the User ID are concatenated into a string that looks like InstanceName\UserID.

 

    public class EloquaInstance

    {

 

        private EloquaServiceNew.EloquaServiceClient serviceProxy;

        private EloquaProgramService.ExternalActionServiceClient programServiceProxy;

 

        private DateTime dttLastEloquaAPICall;

 

 

        public EloquaInstance(string InstanceName, string UserID, string UserPassword)

        {

            strInstanceName = InstanceName;

            strUserID = UserID;

            strUserPassword = UserPassword;

 

            serviceProxy = new EloquaServiceNew.EloquaServiceClient();

            serviceProxy.ClientCredentials.UserName.UserName = strInstanceName + "\\" + strUserID;

            serviceProxy.ClientCredentials.UserName.Password = strUserPassword;

 

 

            programServiceProxy = new EloquaProgramService.ExternalActionServiceClient();

            programServiceProxy.ClientCredentials.UserName.UserName = strInstanceName + "\\" + strUserID;

            programServiceProxy.ClientCredentials.UserName.Password = strUserPassword;

 

            ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

 

            dttLastEloquaAPICall = DateTime.Now.ToUniversalTime().Subtract(TimeSpan.FromMilliseconds(1000));

 

        }

 

       }

 

 

With that as a constructor, our Eloqua instance object is ready to get the members in the program builder step.  This is done iteratively, getting up to 100 contacts, companies, or prospects with each call. You query for a specific ExternalActionStatus, and get all members in the step with that status.

 

The ExternalActionStatus is one of three values:

 

0 – Awaiting Action

1 – In Progress

2 - Completed

 

Calling ListMembersInStepByStatus retrieves, by page, the set of members in the step.  Often, for a Cloud Connector, you will be processing 100 at a time, and them marking them as complete, so you may want to just start from a page number of 0.  A batch size of 100 is typical.

 

        public List<EloquaContact> ListContactsInStep(int intPBStepID, int intStepStatus, int intBatchSize)

        {

            List<EloquaContact> tmpContactsInStep = new List<EloquaContact>();

            EloquaContact tmpContact;

            int intPageNumber = 0;

 

            try

            {

                EloquaProgramService.ExternalActionStatus status;

                status = (EloquaProgramService.ExternalActionStatus)intStepStatus;

 

                Member[] result = null;

                try

                {

                    result = programServiceProxy.ListMembersInStepByStatus(intPBStepID, status, intPageNumber, intBatchSize);

                }

                catch (Exception ex)

                {

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

                    throw;

                }

                if (result != null)

                {

                    foreach (var eam in result)

                    {

                        try

                        {

                            if (eam != null)

                            {

                                if ((int)eam.EntityType == 1)

                                {

                                    tmpContact = new EloquaContact();

                                    tmpContact.ContactID = eam.EntityId;

                                    tmpContact.ExternalActionID = eam.Id;

                                    tmpContactsInStep.Add(tmpContact);

                                }

                            }

                        }

                        catch (Exception ex)

                        {

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

                        }

                    }

                }

            }

            catch (Exception ex)

            {

                Trace.TraceWarning(String.Format("Exception in EloquaInstance:ListContactsInStep {0} :: {1} :: {2} :: {3}", ex.Message, ex.InnerException, strInstanceName, intPBStepID.ToString()), "Exception");

                throw;

            }

            return tmpContactsInStep;

        }

 

 

To manage the contacts that are being returned, I’ve defined a simple class called EloquaContact.  You could manage them as a DynamicEntity, but often it’s easier to manage them directly as Contacts.

 

 

    public class EloquaContact

    {

        public int ContactID { get; set; }

 

        public string EmailAddress { get; set; }

        public int ExternalActionID { get; set; }

 

        public EloquaContact()

        {

            ContactID = 0;

            EmailAddress = "";

            ExternalActionID = 0;

        }

   }

 

 

The program step members that are returned by the query will have an EntityType of 1 (Contact).  The will also have an EntityID (ContactID) and and ExternalActionID that reflects their status in this particular step.  You’ll need this value later as we work with step members, so keep it handy.  I’ve added that as a property of my EloquaContact object.

 

The next thing we need to do, if we are going to begin working with these contacts is to set their status to InProgress to make sure that other instances of the same Cloud Connector, or other threads that are operating at the same time, do not retrieve the same members more than once.

 

To do this, we pass in to the SetMemberStatus call, an array of the members we would like to update.  These members are identified by their EntityType (1 for Contacts), old status, EntityID (Contact ID) and ExternalActionID.  If a contact has been previously moved to a new status, the results returned will not include this contact’s ID.

 

 

      public List<EloquaContact> SetStatusOfContactsInStep(int intProgramStepID, int intOldStepStatus, int intNewStepStatus, List<EloquaContact> tmpContactsInStep)

        {

 

            List<EloquaContact> tmpUpdatedContacts = new List<EloquaContact>();

            EloquaContact tmpContact;

            EloquaProgramService.ExternalActionStatus OldStatus;

            EloquaProgramService.ExternalActionStatus NewStatus;

            EloquaProgramService.Member[] stepMembers;

            OldStatus = (EloquaProgramService.ExternalActionStatus)intOldStepStatus;

            NewStatus = (EloquaProgramService.ExternalActionStatus)intNewStepStatus;

            EloquaProgramService.Member tmpMember;

 

            stepMembers = new EloquaProgramService.Member[tmpContactsInStep.Count()];

 

            try

            {

                for (int index = 0; index < tmpContactsInStep.Count(); index++)

                {

                    tmpMember = new EloquaProgramService.Member();

 

                    tmpMember.EntityId = tmpContactsInStep.ElementAt(index).ContactID;

                    tmpMember.EntityType = (EloquaProgramService.EntityType)1;

                    tmpMember.StepId = intProgramStepID;

                    tmpMember.Status = OldStatus;

                    tmpMember.Id = tmpContactsInStep.ElementAt(index).ExternalActionID;

                    stepMembers[index] = tmpMember;

                }

 

                var results = programServiceProxy.SetMemberStatus(stepMembers, NewStatus);

 

                foreach (Member tmpUpdatedMember in results)

                {

                    tmpContact = new EloquaContact();

                    tmpContact.ContactID = tmpUpdatedMember.EntityId;

                    tmpContact.ExternalActionID = tmpUpdatedMember.Id;

                    tmpUpdatedContacts.Add(tmpContact);

                }

            }

            catch (Exception ex)

            {

                Trace.TraceWarning(String.Format("Exception in EloquaInstance:SetStatusOfContactsInStep {0} :: {1} :: Step {2}", ex.Message, ex.InnerException, intProgramStepID.ToString()), "Exception");

 

                throw;

            }

            return tmpUpdatedContacts;

 

        }

 

Now we have a set of Contact IDs (follow an identical process for Prospects or Companies), and have set their status to In Progress so we can begin our work on these contacts according to the logic of the Cloud Connector we are building.