Authentication Token Settings in the Administration Menu
Within the Admin Settings of the portal, you can now access the admin interface for managing authentication tokens.
These tokens, once created, are used by adding the value to the Authorization header, with a value of Bearer [token]. It is going to look something like this when it’s been added:
Authorization: “Bearer 358e3977459b438caa9463bba0b6a804-a4f2219dcb31422c9318bfc9fe4bc2e3”
You can utilize this in an Excel Power Query to access the API utilizing Excel to build reports. Generally, you’ll use these tokens for any sort of integrations or automation that would target the platform cache. This will allow you to query the updated platform and Service Manager data using the ODATA REST API framework, giving you access to a lot of pre-built integrations (again back to Excel) as well as making it easy to build your own.
HTML Knowledge Analytics
Within the Cireson Service Manager Portal, we already have the HTML Knowledge Base. This is one of the core components of the portal, and also one of the few features where the Portal is the source of truth. This is also one of the most widely used features, so we wanted to add some new capabilities to it, and the synchronization is just the first of many.
What the synchronization does at this point, is look at all your existing KB articles and then make a cached copy of them within the Cireson Platform Cache. This creates the new end-point for querying the Knowledge Base data through the ODATA API. An overly simplistic query will look something like this:
https://your.host.com/platform/api/KnowledgeArticle?$top=10&$select=Title
This query would select the first 10 results from the synchronized Knowledge Articles and return only the value of the Title property. There is a lot more you can do with ODATA, but I’m not going to address all of that today.
Now that we understand the basics, let us utilize Excel to do the complicated query configuration and look at setting it up to access the new endpoints.
Example: Excel OData Connection
For our example we are going to create a new blank workbook:
Once the empty workbook is loaded, we can select the Data tab > Get Data > From Other Sources > From OData Feed:
When you are connecting an OData feed the first thing you have to do is point it to the OData API URL. In our case, this is going to be your Service Manager Portal URL with /platform/API appended to it.
Once you’ve selected the URL it will ask you for an authentication method with the OData integration. We will select anonymous here, which will give us a list of Platform endpoints, but we won’t be able to access the actual entity data just yet.
Once we have the list of endpoints we can search for the KnowledgeArticle endpoint and select it.
Then we see the below error message, but we are going to go ahead and ignore it. Click cancel in the message, and then click Load at the bottom of the Navigator popup.
This will load our data, then hover the mouse over the KnowledgeArticle query and select Edit on the left in the popup.
This will bring up a new window with the Power Query Editor. On the Home tab, click on the Advanced Editor button, to bring up the advanced editor.
When the advanced editor comes up, it will look very similar to the below. This is where we can add additional headers to the queries OData connection settings.
We are going to replace the [Implementation=”2.0"] with our header values and authentication token. When we are done it should look like the below image.
We’ve added a new array, with a Header value which includes an array of header properties. In the authentication property, we’ve included the bearer token information.
Click Done and the window will close, but we will still see the below error in the Power Query Editor. Click the Edit Credentials button.
This will again show us the authentication information, we don’t need to make any changes or updates to what we see here though, just go ahead and click Connect.
This time, it will connect successfully using the authentication token in the query, which all happens in the background now. You should see it pull the data from the KnowledgeArticle endpoint now, and display it in the query editor.
From here, you can manipulate the data in all sorts of ways, even merge data from multiple endpoints.
Next, click Close & Load to load the data into your Excel spreadsheet.
There you have it. Now you have a data source and table connected to your Platform OData endpoint, that can be refreshed on-demand.
