Here’s a step-by-step guide on what a Common Resource is and how to create and map transformations within Sugar Integrate.
What is a Common Resource?
A Common Resource is simply a way of normalizing data between disparate systems. So, for example, if I want to pass data between Sugar Sell and Quick Books, I need to ensure that each application recognizes the data from the other one. Both of these systems have multiple address fields - which should I use? I could make a common resource to map the billing address of Sugar to the shipping address of Quickbooks. Maybe I need to combine first name and last name fields into a single full name field. What if one system has a field that takes values like "Hot", "Warm", or "Cold" but the other one uses a letter grade system. This is another great case for making a Common Resource that tells Sugar Integrate how to translate those values between the systems.
Every common resource within Sugar Integrate is accessed using a consistent RESTful API with a JSON payload regardless of the protocol used at the endpoint. The Sugar Integrate pre-built Adapters 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 adapter instances.
Creating a Common Resource
You can find all your common resources under the resources tab 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 "Build 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’s different ‘types’ that are supported: string, boolean, number and date, and the resource can additionally support nested objects.
Build a Common Resource In Sugar Integrate
A great place to start with when creating a common resource 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 Sugar Sell 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 firstName field in the common resource and mapped it over to the last_name field in the Sugar Sell contact resource. You can also edit these as free text fields.
For the fields that may not show up 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 Sugar Sell. So the contact object that comes back from Sugar Sell is difficult to work with as it has a lot of nested properties. Critical fields, like email_address, are nested sometimes several objects deep 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 adapter. Note this setting is set to TRUE by default.
Now, when you return to our Adapters tab (top left), and open the Adapter Instances, you can view the new resource in the API docs for that Adapter.
Example of a Common Resource added to the Sugar Sell Adapter API Docs:
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.