Tutorial: Using Namara Projects to View External Data on Your Salesforce Dashboard
A little more than a year ago, we published an update to let Namara users know that the Namara API supported OData Version 4.0.
At the time, each data set was offered as it’s own OData Service and could be queried by any OData-compliant platform.
Since then, we’ve revisited our integration with Salesforce to make it more customizable.
Today, we are pleased to announce that we have improved the way that users can view Namara data in real time on their compatible .NET, SAP or Salesforce-based services. We have utilized our own platform’s Project functionality to allow users to quickly load in more data sets without having to perform extra authorization steps.
As an example, we will walk through the Namara integration on Salesforce.
STEP 1: Retrieve your Namara API key
After logging into your Namara account, click on your user icon in the sidebar (bottom left of the window) and select Account Settings. Then select the API Key tab.
You will need to create an API key if you have not already done so.
Have an open document available and paste your API key in there. You will need to access it a few times as well as keep track of a few other values, so keep it on hand.
STEP 2: Create a new project or use an existing project
For this example, I’m going to create a fresh project and add some new data to it. Below, I have created a sample project that I will use for this walkthrough.
If you already have a project that you would like to view, feel free to use that instead.
STEP 3: Put some data in your project
For this example, I’m going to use the Heritage Properties data set published in the Hamilton, Ontario open data portal. I start by browsing open data in the Marketplace, and searching “Heritage Properties Ontario”. I can quickly add these to a project by expanding the data set preview and selecting my new project.
When viewing your project, your url should match a pattern like this:
https://app.namara.io/#/organizations/<organization_id>/projects/<project_id>/list?...
Extract the values for organization_id and project_id from the url and paste them into the document where you have pasted your API key. You will need these later.
Data set result page with project drop-down
STEP 4: Turn on OData for my data sets
To start out, I want to make sure that I know the current versions for both of my data sets. I can find this out by clicking on the data set card to get to the table view, then clicking on the API Info tab.
I will make note that my data sets are at versions “en-0” and “en-1” respectively. Because Salesforce requires a static set of properties to view OData sources, we must pin our OData adapter to a specific version of a data set. (refer to our API Docs for more information about data set versioning.)
Now we need to set up our OData meta attributes that Salesforce will use to build external objects. Navigate back to the Project view and click on the cogwheel icon for each data set to edit the Project Item settings.
Once this is set up, you can quickly check to make sure that your data is being registered by the Namara OData adapter. Using the IDs that I’ve saved from earlier, I can view in a browser:
http://api.namara.io/v0/organizations/<organization_id>/projects/<project_id>/OData.svc
At this point, I should be able to see an XML document detailing the data that I’ve activated for viewing.
We can see from the metadata manifest that it’s registering both Hamilton and Brampton houses as entities and is picking up their properties. It’s also included our activated Project Items as metadata for the Project OData service.
STEP 5: Adding Namara as an external data source
On your Salesforce Lightning dashboard, access “Setup” in the top toolbar.
After arriving at the settings page, either enter “External Data Source” in the Quickfind bar, or navigate to Data > External Data Sources under the “Administration” header.
Click “New External Data Source”, and complete the form for your project.
Here, I have called the data source “Namara Heritage Homes”. I have selected OData 4.0 as my connector type (note that OData 2.0 is not supported by Namara).
The url that I provide is the same as the metadata manifest URL that we built back in step 3. Adjust the other parameter settings to match what is shown here.
Since we are authenticating by API key, we set authentication by User level. The username that you choose does not matter but the password field must be your Namara API key.
Once you have completed this form, click “Save”. You will see the “Validate and “Sync” button on a successful save, but will be unable to complete this action at this time.
STEP 6: Authenticating user for external data source
Go to your personal settings and add a new Authentication for the external system.
In the sidebar, navigate My Personal Information > Authentication Settings for External Systems. Click on the “new” button and set up the authentication for the new Namara data source that you’ve created.
Search for the user and set up their credentials using the API key. Please note that this assumes that you are the user and you are using your own API key. This can be set up on behalf of another user who is a member of your Namara Project. It can even be set up using their Project API key. (To learn more about how Namara lets you collaborate on data projects, check out our Features Pages.)
Once you’ve finished authorizing this user, save the form. Navigate back to our External Data Source by clicking the link provided.
STEP 7: Creating external objects using the data set
On this page, select “Validate and Sync”. After a moment, Salesforce will have received and read the metadata document. We are now provided with Data Sets that we can view as Salesforce External Objects.
Now select the Data Sets that you would like to view and click “Sync”.
If I go to my external objects view I should see that these have been added.
STEP 8: View data on my dashboard
Go back to the first settings/setup panel that we were on. Search “tabs” in the quickfind bar or navigate to User Interface > Tabs.
Create two new custom objects tabs for our two house data sets.
Now when we go back to our dashboard, we can see two new tabs, “BramptonHomes” and “Hamilton Homes”. We will create a new view for our HamiltonHomes data set. In the settings for one of the tabs, under the settings cog, create a new list view.
We will call this view “All Houses”. Initially, it’s not going to be a very interesting view.
We are going to edit our list view to show data that we care about. Under the gear cog, select the “Select Fields To Display” option. This should give us a small window allowing us to view specific fields for this list. I would recommend selecting all except for Display URL, External ID and __row_id. For the sake of a nice table, we are just going to select a few fields.
Which gives us our final table view.
I can scroll to see more, add any filters and sorting options, and use any other Salesforce functionality.
Want to see more data?
If I were to add additional Heritage Home data sets to my project, I would only have to activate those for OData inside of the project, and then re-synchronize the data source to pick up the new external objects.
ThinkData Works proudly works with governments to help them release high-value data, and their data management platform Namara connects users to every open data portal in North America.
