The Basics of Creating and Mapping a Common Resource

By Hannah Shain in Developer Posted Sep 21, 2017

Our Customer Enablement Manager, Clayton Shaver, recently demoed a deep dive on creating common resources in our newly released Cloud Elements 2.0. Here’s a step-by-step guide on what a common resource is and how to create and map transformations within our platform.

What is a Common Resource?

Every common resource within Cloud Elements 2.0 is accessed using a consistent RESTful API with a JSON payload regardless of the protocol used at the endpoint. The Cloud Elements pre-built connectors do the work of mapping the normalized API call to each application’s API endpoints, as well as transforming SOAP, XML and other API protocols to REST/JSON. A common resource allows you to take advantage of our “one-to-many” integration approach by mapping a single resource to multiple Element instances.

Creating a Common Resource

You can find all your common resources under the resources tab here on the left side of the platform. You'll find any of your existing common resources on the bottom left, but can also create new ones using the create new common resource button.

Create a Common Resource - Cloud Elements

For example, we will definte the resource myContacts as email, first name and last name. In the drop down menus there’s different ‘types’ that are supported: string, boolean, number and date, and the resource can additionally support nested objects.


BUILD A COMMON RESOURCE IN CLOUD ELEMENTS 2.0


A great place to start with when creating a common resource and transformation, is to define the object and match it to your origin system. If you’re writing an integration to your application, and inside of your application you already have an existing concept of a contact, then that's how you would go about defining this contact when creating a new resource.

Common Resource Transformations | API Integrations

MAPPING TRANSFORMATIONS

The next part of any common resource is building a transformation. Take the field and the common resource you just defined for your application, and map it to the field and resource at an endpoint.

On the right you’ll be able to see the mapped transformations and the option to create new transformations for your common resource. In our example we’ve already created a transformation for HubSpot for myContact.

HubSpot API Transformation | Common Resource.png

In our transformations screen, the drop down menus populate all the fields that are available in that destination resource, pulled via discovery APIs. In the above example, we’ve taken the email field in the common resource and mapped it over to the HubSpot contact resource. You can also edit these as free text fields.

For the fields that may not show up here in the drop down menu, a good example of this might be custom fields for a specific record, you can still make the mapping, even if it doesn't show up in the discovery object. From this window you can press  Try It Out (play button) which will run and will show you how your object is getting transformed.

In the original tab, you can see the original payload as it's coming back from HubSpot. So the contact object that comes back from HubSpot isn't necessarily v easy to work with, it has a lot of nested properties. Anything that you might care about, a first name or a last name, is nested several objects deep here. Compare this to the transformation, where you receive a clean response of the fields you are requesting.

Comparison of original payload versus transformation:

Original Payload | Creating Common Resource.png Transformed Payload | Creating a Common Resource.png

how to add docs to your common resource

Under the advanced settings, you can toggle on 'Add to API Docs.' When this is set to true, it will take this common resource and add it to the API docs for this Element. 

API Docs Toggle On | Common Resources.png

When you return to our Elements tab (top left), and open the Element Instances, you can view the new resource in the API docs for that Elements.Element Instance API Docs | Common Resource.png

Example of a common resource added to the HubSpot Element API Docs:API Docs | Create Common Resource.png

 

OTHER CONFIGURATIONS FOR RESOURCES

The cog at the top right corner of your common resource will also give you access to remove unmapped fields. If you set this to false by turning this toggle off and then save it, then run your transformation one more time, you can re-gather the original payload object. Notice the new fields mapped, firstname and lastname, are being included where they were not included before.

So what's happening here? When you turn off the remove unmapped fields, the platform is going to return all the fields in your original object, even if they haven't been mapped. For any field that has been mapped, the keys are going to be changed to the keys in the common resource.

This is a great solution if you wanted to get some easy properties such as first name and last name, but you still want to keep a record of all the other data that comes with that contact resource.

For more information on how Cloud Elements can be embedded into you application, and to see live examples of our customers' integrations, check out our self-service demo center. (No need to talk to sales!)

WATCH A DEMO