In the latest versions of the Cireson Service Management Portal for SCSM, we’ve included a fantastic new ODATA API for querying data that has been cached by the Cireson Platform. (Stay tuned for another blog post about the Cireson Platform and how incredibly extensible it is). Today we’ll focus on the new Authentication Tokens interface and take a brief look at updates coming soon to how you can access your Knowledge Base data through the Platform.
Bearer-ing the Responsibility of Authentication Tokens
Within the Admin Settings of the Portal, you can now access the admin interface for managing authentication tokens.
Once created, these authentication tokens 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”
We will show an example later (below) of how you can utilize this in an Excel Power Query to access the API utilizing Excel to build reports. Generally, you’ll use these authentication 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.
Let’s take a look at the new Knowledge Base synchronization built into the platform and then we will look at how we can make the two work together for building Excel reports.
HTML Knowledge Analytics
Within the Cireson Service Manager Portal, we 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. The Knowledge Base is also one of the most widely used features of the Portal, which is why we are focused on adding some new capabilities to it. This 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.
Excel OData Connection
For our example today 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 tokens method and this is where things get a little tricky 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 (but not really since we don’t have access yet). Next, 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 tokens in the query, which now happens in the background. You should see it pull the data from the KnowledgeArticle endpoint and display it in the query editor.
From here, we can manipulate the data in all sorts of ways, including merge data from multiple endpoints (but that is beyond the scope of this blog). 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.
I hope you find this new authentication tokens feature as useful as we think you will! Please play around with the Knowledge Base synchronization while it’s in preview. Your feedback is valuable to use, and we look forward to hearing from you in the community!
