The Basics of Creating and Mapping a Common Resource
Learn how to use Cloud Elements 2.0 to create and access common resources using a consistent RESTful API with a JSON payload.
Join the DZone community and get the full member experience.Join For Free
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.
For example, we will define the resource myContacts as email, first name, and last name. In the drop-down menus, there are different 'types' that are supported: string, boolean, number and date, and the resource can additionally support nested objects.
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.
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.
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:
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.
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 Element.
Example of a common resource added to the HubSpot Element API Docs:
Other Configurations and 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, first name and last name, 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 your application, and to see live examples of our customers' integrations, check out our self-service demo center. (No need to talk to sales!)
Published at DZone with permission of Ross Garrett, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.