Accessing Reportage

SCORM Cloud users can access the highest level summary report, or starting page, of Reportage by logging into the SCORM Cloud Console and clicking the Launch Reportage link on the left side menu under "Reporting". The rest of this section outlines how Reportage URLs are accessed in general, and the Embedding Reports and Widgets section also details information about access.

Reportage is built with the capability to use (pluggable) authentication and authorization code, which serves to protect users from one another's data. For the installation of Reportage attached to our SCORM Cloud, authentication happens at the SCORM Cloud Web Services level. Initial entry into Reportage for any "private" report URL must happen through a signed web service call to rustici.reporting.launchReport, using two paramters, a reporturl parameter that holds the requested, plain text Reportage URL, and an auth parameter that has a specially prepared authentication "token" for accessing Reportage. This token is retrieved from a call to rustici.reporting.getReportageAuth and takes parameters detailing what permissions you would like to associate with the token.

Here's an example. Let's say the URL you want to access is just the Reportage home page. We'll use this URL for simplicity sake, but you can create much more intricate report URLs by navigating within Reportage. In this case we take http://cloud.scorm.com/Reportage/reportage.php?appId=YJ7K3DSFJA and use that as our reporturl parameter to the web service call of the Reporting service, using something like... String reportageAuth = ScormCloud.ReportingService.GetReportageAuth("FREENAV", false);
String authenticatedUrl = ScormCloud.ReportingService.GetReportUrl(reportageAuth, "http://cloud.scorm.com/Reportage/reportage.php?appId=YJ7K3DSFJA"); The result from this call will be an authenticated URL which can either be embedded in an iframe HTML element or as a URL to which the browser can be redirected. The first parameter to the GetReportageAuth method is the required navpermission parameter, which limits what navigation elements are enabled in Reportage for the launching session. NONAV means that no navigation is enabled for the session, DOWNONLY only allows the user to drill down into subsections of the launched report, and FREENAV allows the user to navigate both into subsections and supersections of the report, and allows them to change any parameter of the report they wish. Note that a single reportage auth "token" can be used on multiple calls to GetReportUrl.

The rustici.reporting.getReportageAuth web service call also takes an optional admin parameter, which specifies if the launching user should be considered an admin by Reportage. (Only admins can create custom URLs that can be used later, whether they are public encrypted URLs or private (and plaintext) URLs. For more information, see Embedding Reports and Widgets.)

Copied below is full example showing how to access the Reportage home page and a Reportage page for a specific learner and course, using the PHP SCORM Cloud client library. You can download the code for this example here.

<?php
require_once('Configuration.php');
require_once('ServiceRequest.php');
require_once('ReportingService.php');

$appId = 'your-app-id-here';
$pwd = 'your-secret-key-here';
$conf = new Configuration('http://cloud.scorm.com/EngineWebServices', $appId, $pwd);
$srvc = new ReportingService($conf);

$learnerId = "a-specific-learner-id-here";
$courseId = "a-specific-course-id-here";

$homePage = "/Reportage/reportage.php?appId=$appId";
$learnerPage = $homePage . "&learnerId=$learnerId";
$coursePage = $homePage . "&courseId=$courseId";

//These parameters won't allow the user to drill down or freely navigate, just view
$reportageAuth = $srvc->GetReportageAuth('NONAV', false); 

//Now we use the authentication token retrieved above as authentication for these links
$securedHomePage = $srvc->GetReportUrl($reportageAuth, $homePage);
$securedLearnerPage = $srvc->GetReportUrl($reportageAuth, $learnerPage);
$securedCoursePage = $srvc->GetReportUrl($reportageAuth, $coursePage);
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Reportage link test</title>
</head>
<body>
	<ul>
		<li><a href="<?=$securedHomePage?>">Reportage Home</a></li>
		<li><a href="<?=$securedLearnerPage?>">Reportage report for learner with id <?=$learnerId?></a></li>
		<li><a href="<?=$securedCoursePage?>">Reportage report for course with id <?=$courseId?></a></li>
	</ul>
</body>
</html>
                

Embedding Reports and Widgets

Reportage admin users have the option to generate and share URLs pointing directly to a particular report, or even part of a report, called a report widget.

Widget and Report URLs can be used for anonymous or authenticated access

By default, the URLs found in the text boxes of the UI are both encrypted and public. By copying and pasting the HTML or URL for a widget or report, respectively, it can be accessed both anonymously and securely.

The widget or report URL in the text boxes on a given page will be represented through a single, encrypted enc parameter. The enc parameter will include all the criteria selection information of the report or widget, and will be a publicly accessible URL, with a default public navigation permission of NONAV, meaning anyone who follows this URL will not be able to drill down or use the selection dialogs available to change the report parameters. (For more information on navigation permissions, see Accessing Reportage. )

There are three special parameters that can be given (only by an admin) on the Reportage URL in the browser to change how those widget and report URLs will work when accessed. The first two allow you to change the navigation permission of the encrypted (public) request. If the admin user appends allowPublicDrillDown=true to the currently accessed URL, the widget and report urls in the text boxes of that page will allow public anonymous users to drill down in the report when it is accessed later (using links in the details widgets of the report, for more information see Drilling Down). If the admin user instead appends allowPublicFreeNav=true to the current URL in their browser, the URLs that can be copied out of the resulting UI will allow public anonymous users the ability to freely navigate anywhere they wish, including changing the selection criteria. This is generally not recommended, as it essentially gives anyone who accesses the URL access to any data you have available.

Finally, there is the showDev parameter. If an admin user appends showDev to the current URL, the widget and report URLs generated in the UI will be unencrypted. Only unencrypted URLs can be used with the web service call to rustici.reporting.launchReport. Additionally, these unencrypted URLs which are passed to the web services are in a form that should be relatively easy to read and modify. This would allow an application that is integrated with SCORM Cloud to change some part of the report request dynamically, based on things like appId, courseId, learnerId, and many other parameters. The dynamically generated URL is passed to rustici.reporting.launchReport, and is authenticated through the web services along with Reportage.

So, in order to create links or embed parts of Reportage in an external application without allowing the resources to be accessible anonymously, an admin must enter Reportage, go to the report most like the one they wish to embed or link to, and use the showDev parameter to obtain the unencrypted URLs for those resources. Then those unencrypted URLs should be used in code using something like... String reportageAuth = ScormCloud.ReportingService.GetReportageAuth("DOWNONLY", false);
String authenticatedURL = ScormCloud.ReportingService.GetReportUrl(reportageAuth, "http://localhost/Reportage/reportage.php?appId=YJ7K3DSFJA&courseId=29cceb4f-b6eb-4e8b-a209-e9024313a6b3"); Note in this particular example we set navigation permissions for the reportage authentication token to DOWNONLY, which will allow the accessing user to drill down using the detail widgets in the report.

Now let's say you wanted to embed a report that was dynamically based on the course currently selected in your system, and that you might retrieve the id for that course using the method GetCurrentlySelectedCourseId. Further, assume that the navigational permissions should depend on the current user in your system, which can be found using GetUserReportNavPermissions, you could then use the following code to create a dynamic URL... String courseId = GetCurrentlySelectedCourseId();
String navPermission = GetUserReportNavPermission();

String reportageAuth = ScormCloud.ReportingService.GetReportageAuth(navPermission, false);
String authenticatedURL = ScormCloud.ReportingService.GetReportUrl(reportageAuth, "http://localhost/Reportage/reportage.php?appId=YJ7K3DSFJA&courseId=" + courseId);

There are a number of parameters you can add to an unencrypted Reportage Widget Url (the one used as a parameter to the GetReportUrl method above) that allow you to change the display behavior of a resulting widget. Note these parameters are only for widgets. They are as follows:

  iframe Reportage widgets can be embedded in a hosting page using either iFrames or with an more integrated AJAX method that is availabled to advanced users (for more information see Advanced Widget Integration).
  vertical (Applicable only to the summary widget) Display charts below numbers, rather than to the side, allowing the widget to fit in an area that is much more narrow.
  fixedSize (Applicable only to the details widget) Limits the height of a details widget and applies a small scrollbar for scrolling through the results. Useful if you do not wish for the height of the widget to change (perhaps because it is in an iFrame).
  showTitle Show the title of the widget. In the case of the summary widget, this includes the text showing the count of learners, courses, and registrations involved in the summary. In the case of the details widgets, this shows the top bar which includes the title and the expanding/contracting functionality along with it.
  expand (Applicable only to the details widget) Load the widget in it's expanded state, showing the results.
  embedded This parameter affects the behavior of the widget and should be left to it's default, true, for embedded widgets (and typically also for embedded report links).
  standalone This parameter affects the behavior of the widget and should be left to it's default, true, for embedded widgets.
  scriptBased A parameter which instructs Reportage to load this widget using dynamically loaded javascript. This should only be set to true when using the advanced widget integration method of embedding, and should never be active at the same time as the iframe parameter. For more information, please refer to the Advanced Widget Integration section.
  divname A parameter used along with the scriptBased parameter above, which instructs the widget where it should be loaded on the page. For more information, please refer to the Advanced Widget Integration section.

Below is an example PHP page that shows how one might show two embedded widgets for all your top level data all available dates, using the PHP SCORM Cloud client library. One widget is the summary widget, the other is a learner details widget, which will show the list of learners and their score for the registrations selected. There are many different widgets that can be discovered through the Reportage interface. Note that the widgets in this case are iframe based, for information on dynamic javascript based widgets that don't use iframes, please refer to the Advanced Widget Integration section below. You can download the code for the following example here.

<?php

require_once('Configuration.php');
require_once('ServiceRequest.php');
require_once('ReportingService.php');

$appId = 'your-app-id-here';
$pwd = 'your-secret-key-here';
$conf = new Configuration('http://cloud.scorm.com/EngineWebServices', $appId, $pwd);
$srvc = new ReportingService($conf);

//This url came from reportage UI, when accessing as an admin after putting showDev=true in address bar
$summaryUrl = "/Reportage/scormreports/widgets/summary/SummaryWidget.php?appId=$appId&srt=allLearnersAllCourses&standalone=true&showTitle=true&embedded=true&iframe=true";
$learnerDetailsUrl = "/Reportage/scormreports/widgets/DetailsWidget.php?appId=$appId&drt=learnerRegistration&standalone=true&embedded=true&fixedSize=true&iframe=true&expand=true";

$reportageAuth = $srvc->GetReportageAuth("DOWNONLY", false);
$securedSummaryUrl = $srvc->GetReportUrl($reportageAuth, $summaryUrl);
$securedDetailsUrl = $srvc->GetReportUrl($reportageAuth, $learnerDetailsUrl);

?>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Insert title here</title>
</head>
<body>
	<p>Here's some text</p>
		<iframe src='<?=$securedSummaryUrl?>' frameborder='0' width='1100' height='480'></iframe>
	<p>Here's some more text</p>
		<iframe src='<?=$securedDetailsUrl?>' frameborder='0' width='540' height='290'></iframe> 
</body>
</html>
                	

<?php
require_once('Configuration.php');
require_once('ServiceRequest.php');
require_once('ReportingService.php');

$appId = 'your-app-id-here';
$pwd = 'your-secret-key-here';
$conf = new Configuration('http://cloud.scorm.com/EngineWebServices', $appId, $pwd);
$srvc = new ReportingService($conf);

//This url came from reportage UI, when accessing as an admin after putting showDev=true in address bar
$summaryUrl = "/Reportage/scormreports/widgets/summary/SummaryWidget.php?appId=$appId&srt=allLearnersAllCourses&standalone=true&showTitle=true&embedded=true";
$learnerDetailsUrl = "/Reportage/scormreports/widgets/DetailsWidget.php?appId=$appId&drt=learnerRegistration&standalone=true&embedded=true";
$viewAllLearnerDetailsUrl = "/Reportage/scormreports/widgets/ViewAllDetailsWidget.php?appId=$appId&viewall=learners&standalone=true&embedded=true";

//Add some parameters
$summaryUrl .= "&scriptBased=true&divname=summary1";
$learnerDetailsUrl .= "&scriptBased=true&expand=true&showTitle=false&divname=detail1";
$viewAllLearnerDetailsUrl .= "&scriptBased=true&expand=true&showTitle=true&divname=viewall1";


$reportageAuth = $srvc->GetReportageAuth('NONAV', false); 
$securedSummaryUrl = $srvc->GetReportUrl($reportageAuth, $summaryUrl);
$securedDetailsUrl = $srvc->GetReportUrl($reportageAuth, $learnerDetailsUrl);
$securedViewAllUrl = $srvc->GetReportUrl($reportageAuth, $viewAllLearnerDetailsUrl);
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Insert title here</title>

<script type="text/javascript" src="http://cloud.scorm.com/Reportage/scripts/reportage.combined.js"></script>
<link rel="stylesheet" type="text/css" href="http://cloud.scorm.com/Reportage/css/reportage.combined.css"></link>

<script type="text/javascript">
	$(document).ready( function() {	
		loadScript('<?=$securedSummaryUrl?>');
		loadScript('<?=$securedDetailsUrl?>');
		loadScript('<?=$securedViewAllUrl?>');
	});
</script>
</head>
<body>
	<p>Here is text</p>
	<div id="detail1">Loading...</div>
	<p>And more text</p>
	<div id="summary1">Loading...</div>
	<p>And more text</p>
	<div id="viewall1">Loading...</div>
</body>
</html>