Hints and Tips - Using the Liberty Converse Report API

[JonathanRedsell]

29+ reports come bundled as part of Liberty Converse Contact Contact Centre, but that’s not the only reporting solution available to our customers. Liberty Converse comes with an API that allows customers to extract the report data into 3rd party applications, such as Microsoft Excel and PowerBI.

We pride ourselves in providing customers with all the data they need out of the box, but sometimes you may want to report on a metric that is not included or is a sum or parts we have not thought about. Firstly can I ask that if you ever find something missing, please add this to our Ideas Portal using the link at the top of this page (it’s under resources). However, this is where using 3rd party applications and the Report API come in handy. Let’s take a look at the steps required to configure the API Key, a Report, and connect to both Microsoft Excel and Power BI applications.

Step 1. Creating an API Key

You will need system administrator privileges to create an API Key

1. Within your Liberty Converse system, click on the Admin Cog and click Platform. Then, click API Keys within the Other section as highlighted.
   

   

2. Click Add to create a new API Key. (It may be you already have a reports API. If so, make a note of the Key in a notepad Document).
   

   

3. Configure your API key and click Save.
   a) Name: add a name for your API Key (in this example, I have called it Report API).
   b) Description: give your API a description (in this example, I have said it is for reporting on all groups).
   c) Status: Enable or Disable your API key. (You may want to retire API Keys instead of removing them or not enable them for immediate use. If so, you can set the API key to be disabled).
   d) Groups: You can select all Or individual Groups from the drop-down list, which will work with this API key.
   e) Features: Select the features of this API Key; in this example, I have selected Report & Saved Reports as that is what I want this API Key to do. It is vital for security you only enable the features you wish this API Key to be able to do.
   

   

4. Your API Key is created and displayed. Make a copy of this (by selecting the text in your browser and using its copy command) and paste it into a text editor like Notepad (to save for later).
   

   

Congratulations, you have created your API Key

Step 2. Creating your Reports API URL

At this point, I assume you know how to create, customise and save a report within Liberty Contact Centre, so I am skipping this step. I have created three reports that I want to use with my 3rd party applications - there is no limit to the data you can extract; this is down to your requirements.

• Agent Status Breakdown.
• Interactions Report.
• Audit Log Report.

1. Click the … menu next to the report you want to share, and then click More Info
   

   

2. Click Copy and paste this into a text editor (like Notepad). You can use the same one from when you created the API Key if required.
   

   

3. Using your text editor, replace the x’s at the end of the URL
   

   
   
   With your API Key
   
   
   
   This is the URL you will use for importing into your 3rd party application.

Do this for each of the reports you want to use with a 3rd party applications.

Congratulations, you have created your Report API URL

Step 3. Importing to a 3rd Party application

Microsoft Excel

1. Create a blank Excel worksheet. Go to Data and click on From Web within the Get Data section.
   

   

2. Paste your Report API URL into the URL box and click ok.
   

   

You may be asked to authenticate at this point; if so, use the anonymous option and click OK/Connect

3. To extract the data, click on List and then click Convert Into Table
   

   

4. Click on the icon (with the 2 Expander Arrows) on the Value Header column and click Expand to New Rows.
   

   

5. Click on the same icon again. This will now display all the columns within the report. You can choose which to import or leave all selected, then click OK.
   

   

6. You can now transpose your data (manipulate your data fields to suit). When you are ready to import into Excel, click the Close and Load icon in the top left.
   

   

Congratulations, you have imported your report data into Excel

Microsoft Power BI

1. Within Microsoft Power BI, click the Get Data and then click Web.
   

   

2. Paste your Report API URL into the URL box and click ok.
   

   

You may be asked to authenticate at this point; if so, use the anonymous option and click OK/Connect

1. You can now transpose your data (manipulate your data fields to suit). When you are ready, click Close and Apply.
   
   

Congratulations, you have imported your report data into Power BI

End

That is how you can create an API Key to import your reporting data into 3rd party applications; this also works for extracting data into your data stores.

A little reminder, Netcall cannot advise on how to use a particular 3rd party application, but if you do have questions, please let us know, and if you feel that there is a specific report or piece of missing data, then please add this to the Ideas Portal.

Thanks for reading, and I hope you found this helpful.

Jonathan Redsell.

[LPankova]

Hi,

I’m trying to set up the report api to be ported into PowerBI or excel, but it seems to come up with “We couldn’t authenticate with credentials provided” error when I am trying to connect to the source, whether the access is anonymous or it’s my associated windows account or it’s just a straight up converse account password set up.

Is there something extra that needs to be done to gain access?

[Jwoolley]

Hi LPankova,

I think there’s a slight mistake in Jonathan’s original post. The API Key permission that is required is Saved Report not Report.

Could you try giving your API Key that permission and see if that works?

[LPankova]

Thank you Joshua, that has worked.

What is the difference between Report and Saved Report ?

[Jwoolley]

Glad to hear that’s solved it for you!

The 2 permissions are used to access 2 different API endpoints in Converse and do 2 different things.

The Report permission is used to load ad-hoc data from the Interactions or Audit Log reports only, so you can call the URL for example: /api/liberty/1/partitions/{partitionId}/acd/groups/{groupId}/report?api-key=xxx&type=interactions&startdate=2024-04-27&enddate=2024-05-01

This will run the interactions report between the Start Date 27th of April and the End Date 1st of May and give you the interactions between those dates, it doesn’t require you in the reports area to create a new Saved Report. But you can’t filter the data or columns as part of it (But you can do this after you’ve got the data from the API using Power BI or Excel, etc). This is more useful if you want to get the interactions or audit log data between 2 known dates, which doesn’t require you to have to save a new report each time.

The SavedReport permission is used in the API when you have created a Saved Report in the report area that you want to run against the API. So you will be able to run it using any saved filters or columns you have already saved against it.

More information about the 2 API’s can be found on the Help documentation if you wish to see how they work and what the responses look like:

https://docs.netcall.com/docs/liberty-converse/5.11/developer-guide/contact-centre-apis/report
https://docs.netcall.com/docs/liberty-converse/5.11/developer-guide/contact-centre-apis/savedreport

[LPankova]

Looking further into reports, it seems that saved reports have 3 previous months limit - is there way to extract the reports with more flexible dates? For example from 2024-01-01 to Today() ?

[Jwoolley]

I’ve had a look, it seems there currently isn’t a way to put today in as the end date of either the Report or SavedReport API’s.

The only currently 2 options you can do, 1 is to use a Saved Report with a custom date range (This will allow more than 3 months, any period you would like) and select the 1st of January, you can do that by opening the Date picker and scrolling back to January to select the 1st of January:

Then select the end date as today’s date in the date picker. Which should then look like this:

This will require you to update the end date to the current date before you use the API in Excel, Power BI, etc. But no changes to them will be required other than updating the end date of the report and saving it before running your Excel/Power BI again.

The other option is using the Report API and setting the enddate parameter to today’s date for example: /api/liberty/1/partitions/{partitionId}/acd/groups/{groupId}/report?api-key=xxx&type=interactions&startdate=2024-01-01&enddate=2024-05-01 but this will require you to edit your Excel, Power BI, etc URL each time to change the end date which isn’t the best.

I would recommend for now to use a Saved Report as you currently have to select the 1st of January as the start date and then update the end date in the saved report as and when you need it.

I think a great feature would be to be able to put enddate=today in the Report API and for Converse to convert it to the current date, this could be a great suggestion for our idea portal as I could see other customers using it: https://ideas.netcall.com/

[LPankova]

Thanks for the suggestions, I will submit this to the ideas portal as well.

The idea is to eliminate any manual work like this - we can pull data from other databases/platforms we use e.g. data from Liberty Create is refreshed each morning automatically in our PowerBI reports.

[JonathanRedsell]

What I do is create a report with a year behind and 2 years ahead and that way it will always pull data between those dates.

Hope that helps.

Jonathan