Solutions

Instructions for the new WebAPI interface in Reporter, version 9.2.x and newer

Solutions ID:    KB3899
Version:    16.0
Status:    Published
Published date:    07/15/2010
Updated:    01/17/2014
 

Problem Description

Does Reporter need special requirements to use the WebAPI interface?

What is the Webapi interface?

How do I download Reports using the WebAPI?

Do I need to have a Role configured to use the WebAPI?

What is the difference between the normal User interface, and the WebAPI?

Can I manage my Reports that are triggered by the WebAPI, the the normal UI?

How do I formulate a URL to create a report?

How do I formulate a URL to download a Report?

How do I formulate a URL to cancel a report?

How do I find what the reportid for a WebAPI report?

Do the reports, generated by the WebAPI, ever disappear from the active Reports list?

Resolution

The Web API is intended for advanced users who wish to generate reports using scripts, not the graphical user interface, or who want to use or embed data from the Reporter server into their own custom applications or portals. By using the Web API, advanced users can create sophisticated scripts for running reports or even embed report data into custom applications by downloading the report data in CSV or PDF format. The Web API is intended strictly for report management, not for performing administrative operations on Reporter. For example, you cannot create users or even schedule reports via the Web API. For these operations you will still need to access the graphical user interface.

This article is intended to show you what each individual URL does.  Using this information, you can can manually "AIM" URLs to conduct these tasks, or embed them in a bash script, or any other HTTP compatible scripting engine.

List of functions available to the WebAPI:

  • Create a report.
  • Get a status of a running report.
  • download a Report.
  • Set a report to be sent by e-mail.
  • Cancel a Report. 
  • Procure a list of databases available.
  • Archive a Report.

Example URLS:

NOTE: For the below URLS, we have used these values. 

  • username= admin
  • password= pass
  • database name = NEW-DEMO-LOGS
  • role = _admin

1: To create a  report:

A PDF report:

https://127.0.0.1:8082/api/create?username=admin&password=pass&database=NEW-DEMO-LOGS&role=_admin&action=download&label=MyReport&format=pdf&graphType=Pie&graphColumns=hits&columns=hits|page_views|browse_time|total_bytes|sc_bytes|cs_bytes&summarizeBy=c_ip&rows=25&filter0=sc_filter_category|ISNOT|Adult/Mature%20Content|Alcohol|Tobacco&filter1=c_ip|ISNOT|10.11.11.11

The above URLS  also requests a report of these values:

  • Report name - MyReport
  • Format = pdf
  • Columns, hits, pages views, browse time, total byets, sc-bytes, cs bytes.
  • It's summerized by c_ip and rows.
  • The filters are set for  a category of tabacco, and to exclude the ip address of 10.11.11.11

 The response to this URL will be similiar to this, and displayed in the browser.  You will need to note the report id  to use in future requests.

reportId:851986
reportName:MyReport
status:Running
state:1
percent_done:0
=

A CSV Report:

For obvious reasons, a csv report will not work if we include the arguments that setup the graph types, so we remove these arguments- "&graphType=Pie&graphColumns=hits&".  We can then rerun it by replacing "format=pdf" with "format=csv"   Everything else can remain in the URL.

https://127.0.0.1:8082/api/create?username=test&password=test&database=My proxy SG&role=admin&action=download&label=MyReport&format=csv&columns=hits|page_views|browse_time|total_bytes|sc_bytes|cs_bytes&summarizeBy=c_ip&rows=25&dateRelativeUnit=day&dateStart=2&endDate=1

2: To obtain a status of a report:

Using the the reportId from the response to the create URL, above, we can formulate a URL like the one below.

 https://localhost:8082/api/status?username=admin&password=pass&reportId=851985

3: To download a Report:

Using the the reportId formulate a URL like the one below.  In this case, we have used a reportid of 851985.

https://127.0.0.1:8082/api/download?username=admin&password=pass&reportId=851985

4: To archive a Report:

https://localhost:8082/api/create?username=admin&password=pass&database=NEW-DEMO-LOGS&role=_admin&action=archive&label=report2&format=csv&columns=hits|page_views&summarizeBy=sc_filter_category
 

5: To send a report by E-mail:

https://localhost:8082/api/create?username=admin&password=pass&database=NEW-DEMO-LOGS&role=_admin=email&label=email&format=pdf&emailTo=goofy@Disney.com&emailSubject=Hello&debug=true&columns=hits|page_views&summarizeBy=sc_filter_category

 Here are creating, and e-mailing with these values.

  • E-mail = goofy@disney.com
  • Subject= hello
  • Columns=hits,page views
  • Sumarized by category.

6: To cancel a Report:

This command will can cancel the report with the id of 851985.

https://127.0.0.1:8082/api/cancel?username=admin&password=pass&reportId=851985

 7: To list the databases available:

https://localhost:8082/api/listDatabases?username=admin&password=pass&role=_admin

8: Performance issues:

To protect against rogue scripts requesting too many reports, at any one time, there is a hard limit, of ten,  to the number of active reports running at any one time. This can be configured by editing the preferences.cfg file. Here is the section to edit.

  } # explicit_proxy
  webapi = {
    enabled = "true"
    requireHttps = "true"
    requireAdmin = "false"
    maxConcurrentReports = "10"
  } # webapi

Each report, however, will disapear out of the active reports list ( be release from memory) after ten mins from the time it was last downloaded.  In other words, if you keep downloading the same report at intervals of less than ten minuites you will never see it disapear from this list. 

NOTE:  If, however, you just create a report via the WebAPI but wait for another hour before you download it for the first time, the report still will be available. For example, if you created the report at 10.00am and only download it at 11.00am, the report will still will be available to download. However, if you try and download the report after an hour- say 2 hours later at12.00pm, it will no longer be available.  The report, however, will still will be available on the Reporter server at this directory C:\Program Files\Blue Coat Reporter 9\system\user_admin.

You can view the list of active reports, by following these steps:

  • Login to Reporter with you admin account.
  • Navigate to the adminstration sectoin of the UI.
  • Click on the system overview tab
  • Click on Active users/Reports.
  • To cancel any active report, click on the drop down list of the selected report, and chose cancel.

9: Using user ids other than the default admin ID in the webapi:

Only the default, local admin shows the date correctly. If the user is a created one ,even if it has administrator rights,  the reports dates will show with numbers, and  not properly formated dates. The default admin user is created with a default configuration file under /settings/user_info/user_admin.cfg. This file contains inforamtion regarding the defdault "current_database" selected by the user, as well as the default 'language'  While generating the reports, we read the language from the above node and based on that language, we format the date string.  If a user is created, but never logged in no default settings are set for this id. Without any default settings we cannot write out a proper date and time to the report.  To workaround this issue, ensure you login to each user id you create, before using them to run reports in the Webapi.  With each login, you will need to load each database that you intend to use when you log this same user to the Webapi. 

NOTE1: No pre-formated report  ( reports you can see through the normal User interface)  can be called through the WebAPI.  This includes reports that include a verdicts in them, such as 'denied'.  This includes the feature of the User interface reportting, called  sub reports.   All reports, you trigger and/or create through the WebAPI have to have their origins through the WebAPI. 

NOTE2: Tips for using the example BASH script:

An example script is provided with every Bluecoat Reporter -version 9.2.x,- installation in the <root install folder>/utilities/samples folder.  Notes on using this Feature are included here:

NOTE3: As mentioned above, to use the WebAPI you need to convert reporter to useing HTTPS. To do this, follow these steps.

  • Login to the Reporter user interface with your admin account.
  • Navigate to the administration tab, and click on General settings.
  • Click on System Settings, and then server settings.

 


Rate this Page

Please take a moment to complete this form to help us better serve you.

Did this document help answer your question?
 
 
If you are finished providing feedback, please click the RATE CONTENT button. Otherwise, please add more detail in the following text box and then click RATE CONTENT.
 
 

Your response will be used to improve our document content.

Ask a Question