Skip navigation

In the post Cloud Components: Making marketers more productive, I introduced Cloud Components and how they are used in Eloqua landing pages. 

 

I also mentioned that "a new and exciting method of integration was also introduced".

 

We looked at the anatomy of a Cloud Component Provider from a high level in the series of posts:

 

The next step is actually building one!  For anyone interested in getting started with their first Cloud Component, I have great news.

 

There is now a fantastic tutorial that covers developing a Cloud Component Provider on Heroku, using NodeJS.

 

It is located HERE.

 

Even if you are not familiar with NodeJS or Heroku, this tutorial outlines all the required pieces to get you started.

 

Happy coding!!

Now that you've built your Cloud Component Provider, and exposed your Endpoints, it's time to create your Service Definition.

 

The Service Definition is a publicly exposed JSON document that describes your Provider. 

 

The following must be outlined in the Service Definition:

 

  • Provider Name
  • Version
  • Logo
  • A list of the Cloud Components that are a part of your Provider.  Each item in the component section must define:
    • Component Name
    • A 64x64 icon
    • A list of exposed Endpoints

 

Let's look at an example of what a JSON Service Definition could look like:

 

{

"name": "My CCP Provider",

"version": "2.0.0",

"logoUrl": "https://mycompany.com/ccpservice/images/ccpLogo.png",

"components": [{

    "name": "My First Component",

    "description": "This is my first Eloqua Cloud Component",

    "iconURL": "https://mycompany.com/ccpservice/images/components/icon.png",

    "componentImage": {

      "height": "200",

      "width": "200",

      "url": "https://mycompany.com/ccpservice/images/components/placeholder.png"

    },

    "createInstance": "https://mycompany.com/ccpservice/components/create/{Id}",

    "removeInstance": "https://mycompany.com/ccpservice/components/remove/{Id}",

    "configurationUrl": "https://mycompany.com/ccpservice/components/configure/myComponentConfig.aspx?{Id}",

    "renderInstance": "https://mycompany.com/ccpservice/components/render/{Id}?assetId={AssetId}&contactId={ContactId}&visitorId={VisitorId}",

    "instanceImage": "https://mycompany.com/ccpservice/components/preview/{Id}?assetId={AssetId}&contactId={ContactId}&visitorId={VisitorId}"

  }]

}

 

The first section of the JSON document describes you Provider. This section contains the following:

 

  • The name property is the name of your provider service.  This will be displayed in both the cloud component setup and landing page editor areas of Eloqua. 
  • The version property contains your provider version information.
  • The logoUrl property points to the location of your provider’s logo. Your logo will show in the cloud component setup area of Eloqua.


Next is an array of components, with each item in the array representing a single component.  In the example JSON above, the provider has only a single component.  Below are the properties for this section, and how they are used:

 

  • name - Represents the name of the component.
  • description - This is a description for your component.  This is displayed cloud components setup area of Eloqua application and should contain some usage information.
  • iconUrl - The location of your component's icon (64x64).  This icon will be displayed in both the cloud component setup and landing page editor areas of Eloqua, and should provide an easy way for users to identify your component.
  • componentImage - The location of the image that will be displayed when your component is dragged onto a landing page in Eloqua.  This will serve as a placeholder image for your component until it is rendered on the page.

 

Now that you have your Service Definition built, it will be used to register your Provider with Eloqua.

In the post Building Cloud Components: The Provider, we pointed you to a complete tutorial for creating a Cloud Component Provider for Eloqua.

 

In this series, we will break down the different parts of the Provider to get a higher-level understanding of how they function.

 

A Cloud Component Provider must expose a series of service Endpoints that the Eloqua Cloud Components framework calls out to. 

 

The following are the Endpoints that must be made available by a Provider:

 

 

 

 

 

 

Once the Endpoints have been built out and exposed, it's time to generate the Service Definition.

A Cloud Component Provider must expose a series of endpoints that the Eloqua Cloud Components framework calls out to.  One of these endpoints is called "instanceImage".

 

The instanceImage endpoint returns a preview image for the component from the external or "cloud" system.

 

Here is an example of what a instanceImage endpoint in the Provider could look like:

 

This endpoint will be called with a GET method.

 

https://mycompany.com/ccpservice/components/preview/{Id}?assetId={AssetId}&contactId={ContactId}&visitorId={VisitorId}

 

Now, Let's look at how this is used by the Cloud Component framework.

 

CCPframework-instanceImage.png

 

When a landing page is previewed, the instanceImage endpoint is called with a GET method.  When the endpoint is called:

  1. A GUID is passed though the parameter “{Id}” along with the call.  In addition to the {Id}, the framework can optionally pass the assetId (the Id of the landing page) through the parameter “{AssetId}”,  contactId (if one exists) through “{ContactId}”, and visitorId through "{VisitorId}".  The Provider can then accept these parameters, and use them to do things such as personalize the component, or use the Eloqua API to retrieve further contact information.
  2. The Provider returns a JSON response in the following format:

         

     { "url": "https://mycompany.com/ccpservice/components/image.png", "Height": 100, "Width": 100}


  1. The framework then merges the image into the landing page code.

 

OK, so we've previewed the component, now let's Render it on our page.

A Cloud Component Provider must expose a series of endpoints that the Eloqua Cloud Components framework calls out to.  One of these endpoints is called "removeInstance".

 

The removeInstance endpoint is what handles the deletion of the component in the external or "cloud" system, when it is removed from the Eloqua Landing Page that it resides on. 

 

Here is an example of what a removeInstance endpoint in the Provider could look like:

 

This endpoint will be called with a DELETE method.


https://mycompany.com/ccpservice/components/remove/{Id}

 

Now, Let's look at how this is used by the Cloud Component framework.

 

CCPframework-removeInstance.png

 

When a marketer removes a Cloud Component from a Landing Page, through the editor in Eloqua, the removeInstance endpoint is called with a DELETE method.  When the endpoint is called, a GUID is passed though the parameter “{Id}” along with the call.  The provider must be able to accept this parameter, and use it to remove/delete the component from their system.

 


A Cloud Component Provider must expose a series of endpoints that the Eloqua Cloud Components framework calls out to.  One of these endpoints is called "renderInstance".

 

The renderInstance endpoint generates and returns the HTML content for the component from the external or "cloud" system.

 

Here is an example of what a renderInstance endpoint in the Provider could look like:

 

This endpoint will be called with a GET method.

 

https://mycompany.com/ccpservice/components/render/{Id}?assetId={AssetId}&contactId={ContactId}&visitorId={VisitorId}

 

Now, Let's look at how this is used by the Cloud Component framework.

 

CCPframework-renderInstance.png

 

When a landing page is rendered the renderInstance endpoint is called with a GET method.  When the endpoint is called:

  1. A GUID is passed though the parameter “{Id}” along with the call.  In addition to the {Id}, the framework can optionally pass the assetId (the Id of the landing page) through the parameter “{AssetId}”,  contactId (if one exists) through “{ContactId}”, and visitorId through "{VisitorId}".  The Provider can then accept these parameters, and use them to do things such as personalize the component, or use the Eloqua API to retrieve further contact information.
  2. The Provider does it's magic, and returns a block of HTML to the Cloud Component framework.
  3. The framework then merges the returned HTML into the landing page code.

 

The marketer would like to remove the component from the landing page, it's time to Remove it from our Provider data store

A Cloud Component Provider must expose a series of endpoints that the Eloqua Cloud Components framework calls out to.  One of these endpoints is called "configurationUrl".

 

The configurationUrl endpoint points to the configuration page for the component from the external or "cloud" system.

 

(Note: Although referred to as an "Endpoint", the configurationUrl is simply a url in your provider's service definition, that points to the configuration page for the component.)

 

Here is an example of what a configurationUrl in the Provider could look like:

 

https://mycompany.com/ccpservice/components/configure/myComponentConfig.aspx?{Id}

 

Now, Let's look at how this is used by the Cloud Component framework.

 

CCPframework-configurationUrl.png

 

When a marketer double-clicks on a Cloud Component in the Eloqua Landing Page editor, the configurationUrl endpoint is called.  When the endpoint is called:

  1. A GUID is passed though the parameter “{Id}” along with the call.  The provider must be able to accept this GUID, and use it to render the configuration page for the given component.
  2. The framework then displays the page to the marketer for configuration.

 

The Configuration page is used to gather information required by your component.  This information could be credentials to external systems, dimensions and styling, or Eloqua API credentials if using personalization features.  This Configuration information is then stored in the Provider's data store.

 

Now the component has been configured, it's time to preview it.

A Cloud Component Provider must expose a series of endpoints that the Eloqua Cloud Components framework calls out to.  One of these endpoints is called "createInstance".

 

The createInstance endpoint is what handles the creation and registration of the component in the external or "cloud" system, and links it with the Eloqua Landing Page that it resides on. 

 

Here is an example of what a createInstance endpoint in the Provider could look like:

 

https://mycompany.com/ccpservice/components/create/{Id}

 

This endpoint will be called with a POST method.

 

Now, Let's look at how this is used by the Cloud Component framework.

 

CCPframework-createInstance (1).png

 

When a marketer drags a Cloud Component onto a Landing Page through the editor in Eloqua, the createInstance endpoint is called with a POST method.  When the endpoint is called, a GUID is passed though the parameter “{Id}” along with the call.  The provider must be able to accept this parameter, and use it to register the component in their system. This GUID will then be passed when calling other Provider endpoints, as a means of identifying the component to operate on.

 

The component has been created, now we need to configure it.

In past How-To articles, we've touched on the basics of querying through the SOAP API.

 

In Eloqua API How To: Query a Contact by Email Address, we looked at how to find a contact based on email address, and in Eloqua API How To: Query a Contact by Multiple Fields we looked at using multiple fields.  We even touched on using dates in Eloqua API How To: Retrieve Activity Data through the API to bring back activity data.

 

This post will look at a few more ways to query for contacts, using different fields and criteria.

 

For this example, we will assume that we are searching for Contacts, and that the code HERE is being used.

 

Let's start by creating a string to hold the search query.

 

string searchQuery = "";

 

We could query using any contact field, but let's first look at using the Modified Date field.

 

First, we can query for contacts that have been modified since January 1st, 2012:

 

searchQuery = "C_DateModified>2012-01-01";

 

We could also find contacts that have been modified between January 1st, 2011 and January 1st, 2012:

 

searchQuery = "C_DateModified>2011-01-01 and C_DateModified<2012-01-01";


We've already seen how to search for a single email address:


searchQuery = "C_EmailAddress='person1@acme.com'";

 

But how about looking for multiple email addresses in one call?  An example of this is demonstrated below:


searchQuery = "C_EmailAddress='person1@acme.com' and C_EmailAddress='person2@acme.com' and C_EmailAddress='person3@acme.com'";

 

In this case, if you are querying on the same field, and using a "=" operator,  the API will actually treat an "and" as an "or" and return all matching values.

 

Once you've constructed your searchQuery, define a container for the results.

 

DynamicEntityQueryResults queryResult;

 

Next, execute the Query function and pass in the searchQuery string.

 

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

 

When the Query is executed, the contacts meeting the criteria will be returned for use in your code.

 

These search patterns can be used with any contact field, so play around with them to come up with the best method to suit your needs.

As new ways of integrating with Eloqua become available, deciding which solution is right for your becomes more of a challenge.

 

You will likely ask yourself "do I build a Cloud Connector, or a Cloud Component?"

 

Well, why not build both?

 

Developing both a Cloud Connector AND a Cloud Component, gives you a type of circular integration.

 

As an example, let's take a look at the amiando Cloud App.  This integration consists of both a Cloud Component and a Cloud Connector (Feeder)

 

The Cloud Component allows a marketer to add an event registration or ticket shop widget to a landing page.  Visitors to the page can then use the widget to register and/or purchase tickets for an event.  The Cloud Component also allows the marketer to add other useful widgets to their page (a map to the event, a list of other signed up for the event etc.).  This helps the marketer promote their event, and drive visitors to register.

 

The Cloud Connector allows the marketer to pull leads into contact groups in Eloqua based on event registration and attendance.  So now the marketer can not only promote the event via the landing page, but the registration and attendance data for the event can be pulled back into Eloqua.

 

This integration could even be extended by building a step-based Cloud Connector to gather the registration and attendance data for contacts already existing in your Eloqua instance.

 

So, if you are researching the possibilities for building a custom integration with Eloqua, consider the idea of building not just a single application, but a combination of applications to cover all the bases.

Filter Blog

By date: By tag: