When building a Cloud Connector, one of the core things that  every developer needs to do is to count the members (contacts,  companies, or prospects) in a program step.  If there are members in the  step, you can then query the step directly to find out the contact IDs  of each member of the step, but first, its best to see if any members  exist in the step.

 

As a marketing automation program can  be run in one of many modes, and members can be added to the program in  many ways, you won’t know that members exist in the step until you query  it to retrieve a count.

 

The following code snippet shows you how this can be accomplished.

 

First, you will need some general setup for API use.  Many of these code snippets use a similar setup, so the general API setup instructions can be shared.  You will need the SOAP endpoints for the calls defined.  In this  example, we will only use the External Action Service, but this code  snippet shows both that and the standard Eloqua SOAP API configured as  they will usually be used in tandem by most programs that leverage the  Eloqua API.

 

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; };

 

            //without prior knowledge, set the last API call 1s ago to allow new object instances to invoke call

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

 

        }

 

       }

 

 

With  that as a constructor, our Eloqua instance object is ready to count the  members in the program builder step.  Each count call takes in as  parameters the Program Builder Step ID (this is the number that you see  in the Program Step configuration window when you set it as a Cloud  Connector) and an ExternalActionStatus.  The ExternalActionStatus is one  of three values:

 

0 – Awaiting Action

1 – In Progress

2 - Completed

 

Note  that the contacts (or companies, or prospects) in the step will not  show up to the API until program builder has executed.  You may see them  in that step in the UI, but they will not be seen by the API until the  next cycle.

 

To count the members in the step, just call GetMemberCountInStepByStatus with the step ID and status you are interested in.

 

 

 

        public int CountMembersInStepByStatus(int intPBStepID, int intStepStatus)

        {

            int intMemberCount = 0;

            try

            {

                EloquaProgramService.ExternalActionStatus status;

                status = (EloquaProgramService.ExternalActionStatus)intStepStatus;

 

                try

                {

                    intMemberCount = programServiceProxy.GetMemberCountInStepByStatus(intPBStepID, status);

                }

                catch (Exception ex)

                {

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

                    throw;

                }

 

            }

            catch (Exception ex)

            {

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

                throw;

            }

            return intMemberCount;

        }

 

From  there, you will know how many members are in each step, at each  status.  If there are members in the Awaiting Action status, you can  then retrieve the members of the step and begin to execute your Cloud  Connector logic against them.