mgeise

A tutorial on adding a measure to a Jasper Report crosstab that was created using the wizard

A tutorial on creating a Jasper Report using iReport 4.1.2 based on an XML datasource of contacts

Create a Jasper iReport with a MySQL datasource

For more than three years, Jaspersoft has envisioned the capabilities we’ve just announced in our v5 platform. Because we’ve always intentionally constrained ourselves by exclusively delivering client (end-user) reporting and analysis functionality inside the web browser, our quest for v5 took longer than we would have wanted. But, we believe that the strengths and advantages of maintaining our simple, pure, web-server-based approach to advanced business intelligence is superior to relying on desktop-specific code or even browser plug-ins, which must be installed and maintained on every computer, preventing the scale and cost advantages Jaspersoft can offer. So the interface techniques and features we deliver are constrained based on key web client technologies, especially HTML. The trade-offs we’ve lived with in the past, though, are now essentially eliminated, as a new generation of HTML5 ushers in the consistent, advanced visualization and interaction we’ve long-wanted, while allowing us to maintain our pure web-based client delivery model. Satisfaction. Jaspersoft 5 is more than a new pretty face. We have delivered a completely new HTML5 visualization engine that allows a new-level of rich graphics and interaction, but we’re also providing a host of new and more advanced back-end services that make Jaspersoft 5 more surely the intelligence inside apps and business processes. In total, Jaspersoft 5 includes six major new features. 1. Data Exploration To enable everyone to become a more capable analyst, the Jaspersoft 5 platform includes stunning HTML5 charts, a new dimensional zoom tool (for exploring data at more or less levels of detail), and the ability to simply change or customize charts and tables to suit a particular type of thought or analysis. http://2.bp.blogspot.com/-nPJpUl1tpeQ/UKKKB5ByXsI/AAAAAAAAAG0/caSU0a3RK4Y/s400/jaspersoft5.png 2. Data Virtualization Some reporting and analysis applications are best delivered without moving or aggregating data. Instead, the query engine should virtualize those data views and enable reports, dashboards and analytic views to include data from all necessary sources. Jaspersoft 5 includes an advanced data virtualization engine so that building advanced analysis using practically any data source is straightforward, including Big Data sources. 3. Columnar In-Memory Engine The JasperReports server has supported in-memory operations for several years. Jaspersoft 5 takes this to a new level with improved performance, features, and now with support for up to a full Terabyte of in-memory data. This means that billions of rows of data can be explored at memory speeds with our new Server. 4. Enhanced Analytics To give the power user analyst another reason to use Jaspersoft, we’re now including greater analytic performance, new analytic features (e.g., conditional formatting, relative date filtering, and cross-tab sorting), consistently rich visualization (see #1 above) and broadened access to multi-dimensional data sources. By supporting the latest XML/A standard, we gain certified access to Microsoft SQL Analysis Services (MSAS) data sources in addition to the traditional Mondrian. More power and greater choice equals greater usage. 5. Improved Administration and Monitoring To make the lives easier of those who administer and manage a JasperReports Server, we’re now using our own tool to make our Server smarter and simpler. We’ve designed a set of best-practice, interactive reports that display system health and report on the most important elements of usage. Then, we streamlined the installation and upgrade process, so that getting started and staying up-to-date has never been easier. Together, these improvements are good for our customers and our technical team who supports them. 6. PHP Support Scripting tools are now the most popular for web application development. The PHP community needs more advanced reporting and analysis tools to make their applications more data-driven. By extending the JasperReports Server API to now include PHP support (via RESTful web service wrappers), we’ve taken an important first step toward supporting this fast-growing world beyond Java. Welcome to Jaspersoft. Jaspersoft 5 is poised to deliver self-service BI to help many more users answer their own questions, not just because of the beautiful new HTML5 graphing and interaction engine, but because it is designed to be highly embeddable (into apps and business processes) and, maybe most importantly, because it scales so powerfully and affordably. Putting reporting and analytics into the hands of far more users requires this fundamental reset of the BI formula. This is Jaspersoft 5. I invite you to learn more about Jaspersoft 5 here. And, I look forward to your comments and questions. Brian Gentile Chief Executive Officer Jaspersoft

For more than three years, Jaspersoft has envisioned the capabilities we’ve just announced in our v5 platform. Because we’ve always intentionally constrained ourselves by exclusively delivering client (end-user) reporting and analysis functionality inside the web browser, our quest for v5 took longer than we would have wanted. But, we believe that the strengths and advantages of maintaining our simple, pure, web-server-based approach to advanced business intelligence is superior to relying on desktop-specific code or even browser plug-ins, which must be installed and maintained on every computer, preventing the scale and cost advantages Jaspersoft can offer. So the interface techniques and features we deliver are constrained based on key web client technologies, especially HTML. The trade-offs we’ve lived with in the past, though, are now essentially eliminated, as a new generation of HTML5 ushers in the consistent, advanced visualization and interaction we’ve long-wanted, while allowing us to maintain our pure web-based client delivery model. Satisfaction. Jaspersoft 5 is more than a new pretty face. We have delivered a completely new HTML5 visualization engine that allows a new-level of rich graphics and interaction, but we’re also providing a host of new and more advanced back-end services that make Jaspersoft 5 more surely the intelligence inside apps and business processes. In total, Jaspersoft 5 includes six major new features. 1. Data Exploration To enable everyone to become a more capable analyst, the Jaspersoft 5 platform includes stunning HTML5 charts, a new dimensional zoom tool (for exploring data at more or less levels of detail), and the ability to simply change or customize charts and tables to suit a particular type of thought or analysis. http://2.bp.blogspot.com/-nPJpUl1tpeQ/UKKKB5ByXsI/AAAAAAAAAG0/caSU0a3RK4Y/s400/jaspersoft5.png 2. Data Virtualization Some reporting and analysis applications are best delivered without moving or aggregating data. Instead, the query engine should virtualize those data views and enable reports, dashboards and analytic views to include data from all necessary sources. Jaspersoft 5 includes an advanced data virtualization engine so that building advanced analysis using practically any data source is straightforward, including Big Data sources. 3. Columnar In-Memory Engine The JasperReports server has supported in-memory operations for several years. Jaspersoft 5 takes this to a new level with improved performance, features, and now with support for up to a full Terabyte of in-memory data. This means that billions of rows of data can be explored at memory speeds with our new Server. 4. Enhanced Analytics To give the power user analyst another reason to use Jaspersoft, we’re now including greater analytic performance, new analytic features (e.g., conditional formatting, relative date filtering, and cross-tab sorting), consistently rich visualization (see #1 above) and broadened access to multi-dimensional data sources. By supporting the latest XML/A standard, we gain certified access to Microsoft SQL Analysis Services (MSAS) data sources in addition to the traditional Mondrian. More power and greater choice equals greater usage. 5. Improved Administration and Monitoring To make the lives easier of those who administer and manage a JasperReports Server, we’re now using our own tool to make our Server smarter and simpler. We’ve designed a set of best-practice, interactive reports that display system health and report on the most important elements of usage. Then, we streamlined the installation and upgrade process, so that getting started and staying up-to-date has never been easier. Together, these improvements are good for our customers and our technical team who supports them. 6. PHP Support Scripting tools are now the most popular for web application development. The PHP community needs more advanced reporting and analysis tools to make their applications more data-driven. By extending the JasperReports Server API to now include PHP support (via RESTful web service wrappers), we’ve taken an important first step toward supporting this fast-growing world beyond Java. Welcome to Jaspersoft. Jaspersoft 5 is poised to deliver self-service BI to help many more users answer their own questions, not just because of the beautiful new HTML5 graphing and interaction engine, but because it is designed to be highly embeddable (into apps and business processes) and, maybe most importantly, because it scales so powerfully and affordably. Putting reporting and analytics into the hands of far more users requires this fundamental reset of the BI formula. This is Jaspersoft 5. I invite you to learn more about Jaspersoft 5 here. And, I look forward to your comments and questions. Brian Gentile Chief Executive Officer Jaspersoft

1. RequirementsTo use this client you need: * JasperReports Server (version >= 5.2) * PHP (version >= 5.3, with the php-curl extention) * Composer dependency manager (recommended, but not required) 2. DownloadingThe PHP Client can be obtained multiple ways 1) Download from Releases tab of the PHP Client extension listing. 2) Install using Composer. 3. Installation1) Add the following to the composer.json file for your project:{ "require": { "jaspersoft/rest-client": "*" }} 2) Regenerate your vender/autoload.php using composer.Alternatively, you can use the provided autoload.dist.php to load the classes from this client. 3. ResourcesPHP Client - Sample CodePHP Client - WordPress ExampleSee Also:Jaspersoft Tech Talk Episode 6: Embedding Jaspersoft into your PHP Application

IntroductionThis document demonstrates how to use the PHP Client to connect JasperReports Server data with the Wordpress CMS. Wordpress is a very popular PHP application that allows plugins and extensions, so that you can write your own code for the content on a page. Using the PHP wrapper, WordPress can interface with the API to exchange information between a JasperReports Server and a blog post. The example in this document only covers the runReport feature, although the wrapper has much more functionality, covering all endpoints of the API. Note: There is now a Wordpress plugin available which allows seamlessly embedding highly interactive reports and data visualizations inside your pages and blog posts using the TIBCO JasperReports® IO microservice engine. Requirements:A webserverPHP >=5.3 PEAR packages required by the PHP Client (see README)WordPress blog (see WordPress Installation)PHP ScriptIn order to receive data using the PHP wrapper, you must create and host a .php file that you can make requests with. In this example, jQuery is used to request data from a PHP script, and that data populates a drop down menu, as well as execute reports and return their data. Let's begin with the PHP script used to generate data from the server, name it runreport.php: <!--?phprequire_once('jasperclient/JasperClient.php');class WPReport { public $client; private $mime_types = array( 'html' =--> 'text/html', 'pdf' => 'application/pdf', 'xls' => 'application/vnd.ms-excel', 'csv' => 'text/csv', 'docx' => 'application/vnd.openxmlformats- officedocument.wordprocessingml.document', 'rtf' => 'text/rtf', 'odt' => 'application/vnd.oasis.opendocument.text', 'ods' => 'application/vnd.oasis.opendocument.spreadsheet', 'xlsx' => 'application/vnd.ms-excel' ); public function __construct() { $this->client = new JasperJasperClient('localhost', 8080, 'jasperadmin', 'jasperadmin', '/jasperserver-pro', 'organization_1'); } /** * run() is to be called via a GET parameter. Using run() will run a report specified by URI and FORMAT get calls. * Example: thisfile.php?func=run&uri=/reports/samples/AllAccounts&format=pdf * Calling the file in this manner will return the binary of the specified report, in PDF format */ public function run() { if(isset($_GET['uri']) && isset($_GET['format'])) { $report_data = $this->client->runReport($_GET['uri'], $_GET['format']); if ($_GET['format'] !== 'html') { echo $this->prepareForDownload($report_data, $_GET['format']); } else { echo $report_data; } } } /** * This function prepares a page with the proper headers to initiate a download dialog in modern browsers * by using this function we can supply the report binary and users can download the file */ private function prepareForDownload($data, $format) { header('Cache-Control: must-revalidate'); header('Pragma: public'); header('Content-Description: File Transfer'); header('Content-Disposition: attachment; filename=report.'.$format); header('Content-Transfer-Encoding: binary'); header('Content-Length: ' . strlen($data)); if(isset($this->mime_types[$format])) { header('Content-Type: ' . $this->mime_types[$format]); } else { header('Content-Type: application/octet-stream'); } echo $data; } /** * This function returns the reports vailable at the position 'uri' * the data is echoed in JSON format so it can be used by a jQuery function * to populate a dropdown select HTML element * example: thisfile.php?func=getReports&uri=/reports/samples */ public function getReports() { if(isset($_GET['uri'])) { $result = array(); $repo = $this->client->getRepository($_GET['uri']); foreach($repo as $r) { $result[] = array('name' => $r->getName(), 'uri' => $r->getUriString()); } echo json_encode($result); } } /** * This function simply json-ifys the array above to populate a drop-down menu * select HTML element. This way it is easy to change the formats available */ public function getTypes() { $result = array(); foreach($this->mime_types as $key => $val) { $result[] = array('name' => $key, 'value' => $val); } echo json_encode($result); }} // WPReport/* If the function exists in our class, and it is requested, then run it */if(isset($_GET['func']) && method_exists('WPReport', $_GET['func'])) { $r = new WPReport(); $r->$_GET['func']();}?>[/code]Breaking down the PHP ScriptFirst, the beginning of the file defines variables that are needed by a class. $client will hold the client object through which commands to the Jaspersoft Reports Server can be made. The $mime_types array is used to map file extensions to their respective MIME types. This is used when serving files for download. The Run Functionpublic function run() { if(isset($_GET['uri']) && isset($_GET['format'])) { $report_data = $this->client->runReport($_GET['uri'], $_GET['format']); if ($_GET['format'] !== 'html') { echo $this->prepareForDownload($report_data, $_GET['format']); } else { echo $report_data; } } }[/code]This function is runs a report on the server, and serves the data returned. When a URI and format are supplied in the URL as GET parameters, this function uses the client object to request a report from the server. If the report is requested in HTML, it is echoed. If it is any other format but HTML, it is passed to a different function that sends the proper headers along with the binary data so the file can be accepted for download by a browser. The prepareForDownload FunctionThe prepareForDownload function is only used to prepare the headers to be sent and echos the data from the server. This way when the file is retrieved, the browser knows how large it is, what to do with it, what to name it, and other data that signify a download dialog box. The report is displayed. This data is retrieved from the run function. getReports / getTypes functionpublic function getReports() { if(isset($_GET['uri'])) { $result = array(); $repo = $this->client->getRepository($_GET['uri']); foreach($repo as $r) { $result[] = array('name' => $r->getName(), 'uri' => $r->getUriString()); } echo json_encode($result); } } public function getTypes() { $result = array(); foreach($this->mime_types as $key => $val) { $result[] = array('name' => $key, 'value' => $val); } echo json_encode($result); }[/code]These two functions are used to prepare data for the jQuery script to populate the drop-down menus. The first function (getReports) uses getRepository to request all the reports' resourceDescriptors as 'uri' (defined by a GET variable). Then it takes this data, maps the name and URI to each other, and encodes it in a JSON format that can be easily consumed by JavaScript. The getTypes function does the same, except it only uses the data in the $mime_types array to supply the second drop-down menu item with the types that can be taken. This data could easily be hard-coded into the HTML, but for simplicity this function is used. Outside the WPReport classif(isset($_GET['func']) && method_exists('WPReport', $_GET['func'])) { $r = new WPReport(); $r->$_GET['func']();}[/code]These final lines of code interpret the GET data when the page is requested. It executes the function determined by the GET parameter func and runs the corresponding function. This way we don't have to maintain separate files for each task. JavaScript CodeThis specific example uses JavaScript to improve the user experience when using the report generator. It also prevents the page from reloading when requesting different reports. Coupling the JavaScript with an iframe we can serve the data generated by the prepareForDownload function without reloading the page. jQuery(function(){ // Manage AJAX loading image jQuery('#loading').hide(); jQuery('#loading').bind( "ajaxStart", function(){ jQuery(this).show(); }) .bind( "ajaxStop" , function(){ jQuery(this).hide(); }); // populate the dropdown box for the names of the reports jQuery.getJSON("http://localhost/runreport.php?func=getReports&uri=/reports/samples" ,function(data){ var sel = jQuery("#reportList").empty(); jQuery.each(data ,function(){ sel.append(jQuery("<option>") .val(this.uri).text(this.name)); }); }); // populate the dropdown for types of export jQuery.getJSON("http://localhost/runreport.php?func=getTypes" ,function(data){ var sel = jQuery("#exportList").empty(); jQuery.each(data ,function(){ sel.append(jQuery("</option><option>") .val(this.name) .text(this.name)); }); }); // on 'submit' get the report. display html in div, other formats activate hidden // iframe to trigger download jQuery('#repsub').on('click', function(event) { if (jQuery('#exportList').val() !== 'html') { document.getElementById("hFrame").src = 'http://localhost/ runreport.php?func=run&uri=' +jQuery('#reportList').val() +' &format=' +jQuery('#exportList').val(); } else { jQuery('#displayReport').load('/wordpress/wp-content/plugins/jasper/runreport.php?func=run&uri=' +jQuery('#reportList').val()+ '&format='+jQuery('#exportList').val()); } });});[/code]AjaxA loading indicator is created and bound to ajaxStart, so it is displayed whenever Ajax requests are being made. It is also set to hide when Ajax requests stop being made. The first getJSON function is used to populate the list of reports. It requests the data in JSON format from our PHP script. As you can see in the URL, it defines the function that is called, as well as the URI we wish to request reports from. An example of the data this returns is: [{"name":"AllAccounts","uri":"/reports/samples/AllAccounts"},{"name":"Cascading_multi_select_report","uri":"/reports/samples/Cascading_multi_select_report"},{"name":"Department","uri":"/reports/samples/Department"},{"name":"EmployeeAccounts","uri":"/reports/samples/EmployeeAccounts"},{"name":"Employees","uri":"/reports/samples/Employees"},{"name":"FlashChartReport","uri":"/reports/samples/FlashChartReport"},{"name":"FlashMapReport","uri":"/reports/samples/FlashMapReport"},{"name":"FlashWidgetReport","uri":"/reports/samples/FlashWidgetReport"},{"name":"Freight","uri":"/reports/samples/Freight"},{"name":"OpenFlashChartsReport","uri":"/reports/samples/OpenFlashChartsReport"},{"name":"PermissionsOfUsersWithARoleSharedByLoggedIn","uri":"/reports/samples/PermissionsOfUsersWithARoleSharedByLoggedIn"},{"name":"SalesByMonth","uri":"/reports/samples/SalesByMonth"},{"name":"StandardChartsAegeanReport","uri":"/reports/samples/StandardChartsAegeanReport"},{"name":"StandardChartsEyeCandyReport","uri":"/reports/samples/StandardChartsEyeCandyReport"},{"name":"StandardChartsReport","uri":"/reports/samples/StandardChartsReport"}] [/code]Luckily, this data makes more sense to JavaScript/jQuery than it does to a person. This data is basically a listing of report names and their URIs that can be used to set the name and value attributes of the element. Data is transferred from the PHP script to the second drop down menu in the same way as shown in the next getJSON function. jQuery('#repsub').on('click', function(event) { if (jQuery('#exportList').val() !== 'html') { document.getElementById("hFrame").src = 'http://localhost /runreport.php?func=run&uri='+jQuery('#reportList').val()+'&format= '+jQuery('#exportList').val(); } else { jQuery('#displayReport').load('http://localhost/runreport.php ?func=run&uri='+jQuery('#reportList').val()+'&format' +jQuery('#exportList').val()); }});[/code]This final function is bound to the Submit button. When it is clicked, two things can occur. The values chosen in the drop-down menus are taken using the .val() function and are used to fill in the GET arguments for the PHP script's URI and format options. Thus, if the report type is HTML, when the button is pressed, a DIV element is filled with the HTML produced by the script. Otherwise, we set the SRC attribute of a hidden iframe (id = hFrame) to the script. This is necessary because the headers must be the first thing served if a download dialog box is displayed. So by loading it through an iframe we are not bogged down by previously-loaded blog data. Sample Blog PostWe now need a user-facing form in HTML that incorporates the previous two scripts. To do this, add a new post with some HTML. If you are having trouble writing HTML in your posts, you might want to disable WordPress's visual text editor (Admin Panel > Users > Your Profile > Disable visual editor). Use the following code in your post: <div id="reportBox"> <h3 class="widget-title">View My Reports</h3> <label for="reportList"> Report name: </label> <select id="reportList" style="width:150px;"> <!-- populated by jquery --> </select> <label for="exportList"> Download as: </label> <br> <select id="exportList"> <!-- populated by jquery --> </select> <input name="submit" id="repsub" type="submit" value="submit" /> <label for="repsub" id="loading" > <img src="http://localhost/ajax-loader.gif" /> </label> <div id="displayReport"></div> <iframe style="display:none" id="hFrame"></iframe></div><!-- Scripts Below --><script type="application/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.js" /><script src="http://localhost/script.js" type="application/javascript" />[/code]Loading the JavaScript, the menus are populated, and the Submit button becomes active. HostingThe JavaScript file can be hosted anywhere accessible to the browser attempting to use it. The PHP script must be accessible to the browser using the site, as well as the server hosting the WordPress blog. In this example we use full paths to define the location of these scripts. However, it's fine to use relative paths in the correct context. The PHP client must be accessible to the PHP script so it can be included properly. To make that happen, you might need to adjust the require_once() function to match your environment.

About the ClassThe JasperReports Server PHP Client is a wrapper for the JasperReports Server REST API. This client abstracts the details behind the communications with the server into simple-to-use functions representative of their functionality on the server. Developers do not have to deal with parsing and creating JSON data, but rather deal with objects that represent resources within the server. By using JasperReports Server PHP Client, developers can focus on their logic and implementation rather than detailed communications with JasperReports Server. Getting StartedInvoking the ClientIn your project, you must include the autoloader so that classes can be loaded as needed. If you have not generated the autoloader file, please follow the instructions in the README for installation. Then you must initialize a client with your login credentials. require_once __DIR__ . "/vendor/autoload.php";use JaspersoftClientClient;$c = new Client( "http://localhost:8080/jasperserver-pro", "jasperadmin", "jasperadmin", "organization_1" ); Usage PatternsThere are several way to invoke the functions of the client: // Store service for several calls$js = $c->jobService();$js->getJobs("/reports/samples/AllAccounts");// Or access service methods directly$c->jobService()->getJobs("/reports/samples/AllAccounts"); Note that all examples on this page assume you are importing objects using the PHP 'use' keyword. If you are not, you must refer to the objects using the full qualified namespace. Altering the Request TimeoutIf you are having issues with requests timing out, you can alter the amount of time the client waits for a response before timing out. The default timeout is 30 seconds. // Let the client wait one whole minute before timing out$c->setRequestTimeout(60); Server InformationThe client class can also return data about the sever it is connecting to. This data includes date formats, license information and other info about the server's configruation. It is returned in an associative array format. $info = $c->serverInfo();print_r($info); Repository and Resource ServicesrepositoryService()Searching the RepositoryYou can search the repository by using a RepositorySearchCriteriaobject to define your search parameters. If no criteria is provided, the entire repository will be returned. Results are returned as a SearchResourcesResultobject. Each result is contained in the items element of the result object. // Returns entire repository$repo = $c->repositoryService()->searchResources();// Search for specific items in repository$criteria = new RepositorySearchCriteria();$criteria->q = "logo";$results = $c->repositoryService()->searchResources($criteria);foreach ($results->items as $res) { echo $res->label . "<br>";} Creating a ResourceMany types of resources can be created. See the namespace JaspersoftDtoResourceto see the types you may work with. Note: CompositeResourceand Resourceare abstract classes and are not expected to be insantisted or used with any 'CRUD' operations. $folder = new Folder;$folder->label = "ImageFolder";$folder->description = "A folder for storing images";$c->repositoryService()->createResource($folder, "/"); Working with Composite ResourcesSome resources can reference or define subresources, these resources are known as composite resources. When dealing with such resources while using the PHP Client, you can decide to provide a reference to an existing resource, or define the resource locally. For example, when you create a ReportUnit object, you can set the datasourcefield to either of the following: A string representing the path to a data source in the repository. This will create a reference to the designated resource.A concrete DataSourceobject with all the required fields. This will create a local definition of the data source.The following example defines a ReportUnit that references a data source and a query in the repository. The array of input controls includes both referenced resources and a locally defined InputControlstructure. $report_shop = new JaspersoftDTOResourceReportUnit();$city_control = new JaspersoftDTOResourceInputControl();$city_control->query = "/queries/cityQuery";$city_control->label = "city";$city_control->type = 7;$city_control->visible = true;$city_control->visibleColumns = ["city", "country", "zipcode"];$city_control->valueColumn = "city";$report_shop->label = "All Accounts Report of Shops";$report_shop->description = "AllAccounts style report derived from the shops JDBC datasource";$report_shop->uri = "/my_reports/allaccount_shop";$report_shop->dataSource = "/datasources/shopJDBC";$report_shop->inputControls = array( "/inputcontrols/age", "/inputcontrols/state", $city_control);$report_shop->query = "/queries/shop_accounts";$report_shop->jrxml = "/jrxml/allaccounts"; Creating Binary ResourcesThe repository service is capable of uploading binary files as well. These must be handled differently than other types of resources. The following example shows how to upload an image to the JasperReports Server repository. $file = new File;$file->description = "JPG of company logo";$file->label = "logo";$c->repositoryService()->createFileResource( $file, file_get_contents("/home/user/logo.jpg"), "/ImageFolder", ); Note: If your instance of JRS employs custom file types, you must define the mapping of the server type to the proper MIME type in the JaspersoftToolMimeMapper object which contains an associative array of JRS file types mapped to their relevant MIME type. Requesting Binary ContentThe following example shows how to request an image and display it in inline HTML using base64 encoding. $image = $c->repositoryService()->getResource("/ImageFolder/logo");$image_data = $c->repositoryService()->getBinaryFileData($image);echo "<img src="data:image/jpeg;base64,".base64_encode($image_data).""><br><h1> Example Corporation </h1>"; Deleting a ResourceThe deleteResourcesfunction removes resources from the repository, either one at a time or several at a time. When deleting a folder, all folder contents are deleted, including recursive subfolders and their contents, provided the user credentials have delete permission on all folders and resources. $c->repositoryService()->deleteResources("/ImageFolder/logo");$c->repositoryService()->deleteResources("/ImageFolder/logo2");// or$c->repositoryService()->deleteResources(array("/ImageFolder/logo", "/ImageFolder/logo2")); Moving a ResourceResources can be moved from one location to another within the Repository. Note that the moveResourcefunction does not rename the resource, only changes its parent. The following example moves the folder "/ImageFolder" to "/MyReports/ImageFolder": $c->repositoryService()->moveResource("/ImageFolder", "/MyReports"); Copying a ResourceResources can be copied from one location to another within the Repository. The following example copies the folder "/MyReports/ImageFolder" to "/SharedReports/ImageFolder". By setting the last argument to true, folders that do not exist in the new parent's path will be created. $c->repositoryService()->copyResource("/MyReports/ImageFolder", "/SharedReports", true); permissionService()Searching PermissionsYou can search for user permissions to a give resource in the repository by using the searchRepositoryPermissionsfunction. Provide the URI for the resource as the first argument. Other arguments are available to filter the results as needed. The following example lists all the set permission recipients for "/reports/samples/AllAccounts": $permissions = $c->permissionService()->searchRepositoryPermissions("/reports/samples/AllAccounts");foreach($permissions as $p) echo $p->recipient . "<br>"; Updating PermissionsTo update permissions, you must retrieve existing permissions, modify them, and then pass them to the updateRepositoryPermissionsfunction. The following example retrieves permissions for a report, alters the first one to have no access, and updates it on the server. $perms = $c->permissionService()->searchRepositoryPermissions("/reports/samples/AllAccounts");$perms[0]->mask = 0;$c->permissionService()->updateRepositoryPermissions("/reports/samples/AllAccounts", $perms); Updating a Single PermissionYou can update one permission at a time as shown in the following code example. It is also possible to create a new permission object from scratch and use it to update a single permission if desired. $perms = $c->permissionService()->searchRepositoryPermissions("/reports/samples/AllAccounts");$perms[0]->mask = 0;$c->permissionService()->updateRepositoryPermission($perms[0]); Creating PermissionsPermissions can be created by first describing the permissions in Permission objects, then passing them to the server. The following example creates a new permisison for joeuser in organization_1 to administer the AllAccounts report. $p = new RepositoryPermission("/reports/samples/AllAccounts", "user:/organization_1/joeuser", 1);$p2 = new RepositoryPermission("/reports/samples/AllAccounts", "user:/organization_1/janeuser", 32);$c->permissionService()->createRepositoryPermissions(array($p, $p2));// Likewise, you can create a single permission using the non-plural version$c->permissionService()->createRepositoryPermission($p); Deleting PermissionsRemoving permissions is possible by passing the permission to the deleteRepositoryPermissions function. The example below will delete the permission created in the previous example. $p = $c->permissionService()->searchRepositoryPermissions("/reports/samples/AllACcounts", null, null, "user:/organization_1/joeuser");$c->permissionService()->deleteRepositoryPermission($p[0]); importExportService()Exporting ResourcesUsing this service, you can export data from the server to store or import to another server. You must set the user credentials to a system admin (superuserby default) when calling this service. Data is compressed as a zip archive and sent as binary data. First construct an ExportTaskobject that defines what data is to be extracted, then pass it to the startExportTaskfunction. Data can then be stored using PHP file I/O functions, or streamed to a browser by preparing the proper headers and echoing the binary data. The following example requests an export, then refreshes the status of the export every 10 seconds. When it is finished, it downloads the data as a zip file, stores it in a file (export.zip), and offers a link to download the file. header('Content-Type: text/html; charset=utf-8');// The export service can take longer than 60 seconds to execute, so it is necessary to change the server execution time limitset_time_limit(0);$request->users[] = "jasperadmin";$metadata = $c->importExportService()->startExportTask($request);$decline = true;while ($decline) { $state = $c->importExportService()->getExportState($metadata->id); if ($state->phase == "finished") { $decline = false; echo "<br>Export task complete, downloading...."; } else { echo "Export in progress...<br>"; @flush(); @ob_flush(); sleep(10); }}$f = fopen('export.zip', 'w');$data = $c->importExportService()->fetchExport($metadata->id);fwrite($f, $data);fclose($f);echo "<br><br>Export catalog available for download <a href='export.zip'>here</a>."; Importing ResourcesThe import service allows you to import data that was previously exported. There are various flags that can be set to alter what data is imported; see the REST API documentation for specific examples of such flags. The following example submits an import from the file "import_data.zip" assumed to be stored in the same folder as the PHP file. It displays "Import in progress..." and checks the status every 10 seconds until it is complete. Then it announces that the import has completed. $request = new ImportTask;$request->update = true;$metadata = $c->importExportService()->startImportTask($request, file_get_contents('import_data.zip'));$continue = true;while($continue) { $state = $c->importExportService()->getImportState($metadata->id); if ($state->phase == 'finished') { $continue = false; echo "<br><br>Import complete!"; } else { echo "Import in progress...<br>"; @ob_flush(); @flush(); sleep(10); }} Reporting ServicesreportService()Running a ReportThe following code example requests the AllAccounts report in HTML format. Since the data is HTML, we can simply echo it, and the report will be presented in the web page. You can do many things with the binary data, including offering the file to be downloaded or storing it to a file. $report = $c->reportService()->runReport('/reports/samples/AllAccounts', 'html');echo $report; Downloading a Report in a Binary ReportBy setting the proper headers before calling the runReportfunction, you can serve binary data to a browser as a download. $report = $c->reportService()->runReport('/reports/samples/AllAccounts', 'pdf');header('Cache-Control: must-revalidate');header('Pragma: public');header('Content-Description: File Transfer');header('Content-Disposition: attachment; filename=report.pdf');header('Content-Transfer-Encoding: binary');header('Content-Length: ' . strlen($report));header('Content-Type: application/pdf');echo $report; Running a Report with Input ControlsThe following example shows how to run a report with various input controls. $controls = array( 'Country_multi_select' => array('USA', 'Mexico'), 'Cascading_state_multi_select' => array('CA', 'OR') );$report = $c->reportService()->runReport('/reports/samples/Cascading_multi_select_report', 'html', null, null, $controls);echo $report; Retrieving Input Control ValuesYou can retrieve the input controls defined for a report, their possible values, and other metadata about controls. The following example lists each control and its corresponding values. $input_controls = $c->reportService()->getReportInputControls('/reports/samples/Cascading_multi_select_report');foreach($input_controls as $ic) { printf('Key: %s <br />', $ic->id); foreach ($ic->options as $ico) { printf(' -- Value: %s <br />', $ico['label']); }} optionsService()Listing Report OptionsA report option is a set of saved input control values for a given report. You can view the different stored options for your reports using the getReportOptionsfunction. It takes the URI of a report that has options, and returns an array of objects representing each report option. The following example shows how to request all the ReportOptionsobjects, iterate through them and print the labels of each one. $report_options = $c->optionsService()->getReportOptions('/reports/samples/Cascading_multi_select_report');foreach($report_options as $ro) { echo $ro->label . "<br />";} Creating and Updating Report OptionsThe updateReportOptionsfunction can be used both to create new report options or to update existing ones. The following example shows how to create a new report option that makes selections for existing input controls. $success = $c->optionsService()->updateReportOptions( '/reports/samples/Cascading_multi_select_report', array('Country_multi_select' => array('Canada', 'USA'), 'Cascading_state_multi_select' => array('OR', 'WA', 'BC')), 'CanadaUSA', 'true');if ($success) { echo "Created new report option successfully";} Deleting Report OptionsTo delete a report option, specify the URI of the report, and provide the label of the report option. If your report options has whitespace in the label, the current version of this function may not handle it well. Instead, use the deleteResourcesfunction to delete the report option. try { $c->optionsService()->deleteReportOptions('/reports/samples/Cascading_multi_select_report', 'CanadaUSA');} catch (Exception $e) { printf("An exception was thrown: ", $e->getMessage());} jobService()Searching for JobsThe searchJobsfunction has various options that can be set to filter your results. With no options set, it returns all existing jobs on the server. All results are JobSummaryobjects that contain the ID of the job. The following example searches for all jobs scheduled for a given report. $allAccountsJobs = $c->jobService()->searchJobs("/reports/samples/AllAccounts");print_r($allAccountsJobs); Getting Job DetailsOnce you know the ID of a job, you can request the specific details of that job. The getJobfunction returns a Jobobject describing the job. $allAccountsJobs = $c->jobService()->searchJobs("/reports/samples/AllAccounts");$first_job_details = $c->jobService()->getJob($allAccountsJobs[0]->id); Creating a JobTo create a job, first create a well-defined Jobobject. The Jobobject contains subclasses that define the behaviour of the scheduled job. The response to a successful job creation contains the ID of the new job. // SimpleTrigger$trigger = new SimpleTrigger();$trigger->timezone = "America/Los_Angeles";$trigger->startType = 2;$trigger->startDate = "2025-10-26 10:00";$trigger->occurrenceCount = 1;// Source$source = new Source();$source->reportUnitURI = "/adhoc/topics/Cascading_multi_select_topic";$source->parameters = array("Country_multi_select" => array("Mexico"), "Country_name_single_select" => array("Chin-Lovell Engineering Associates"), "Country_state_multi_select" => array("DF", "Jalisco", "Mexico"));// Repository Destination$repoDest = new RepositoryDestination();$repoDest->folderURI = $f->uri;$job = new Job("Sample Job Name", $trigger, $source, "Cascading_multi_select_test", array("PDF", "XLS"), $repoDest);$job->description = "Sample Description";try { $c->jobService()->createJob($job);} catch (Exception e) { printf('Caught Exception: %s', $e->getMessage());} Updating a JobTo update a scheduled job, request its Jobobject from the server, modify it, and then call the updateJobfunction. The Jobclass uses properties and arrays to manage its data; this is different from the other objects that use only properties. This means you do not use get/set methods to alter the data in a Job object, but rather set the properties as if they were variables. If a property refers to a nested element of the Jobclass, use array functions to manipulate the arrays. $allAccountsJobs = $c->jobService()->searchJobs("/reports/samples/AllAccounts");$job = $c->jobService()->getJob($allAccountsJobs[0]->id);$job->label = "New label";$c->jobService()->updateJob($job); Pausing a JobWhen a job is paused, it does not run any reports. The only argument to the pauseJobfunction is either a single job ID as an integer or an array of job IDs. If no argument is provided, this function pauses all jobs to which the user has access. $c->jobService()->pauseJob(); Resuming a JobTo resume a job, pass the job ID to the resumeJobfunction. For convenience, you may also pass an array of job IDs. As with the pauseJobfunction, this function resumes all jobs if no argument is provided. $c->jobService()->resumeJob(); Deleting JobTo delete a job, search for the job by name or URI, then pass its ID to the deleteJobfunction. $c->jobService()->deleteJob('90210'); queryService()Executing a QueryThis service allows you to execute a query on a data source or Domain. Pass the URI of the data source or Domain and a properly written query string as parameters. The executeQueryfunction returns an associative array representing the names and values in the query results. $query = <<<EOF<query> <queryFields> <queryField id="public_opportunities.amount"/> <queryField id="public_opportunities.name"/> </queryFields></query>EOF;$result = $c->queryService()->executeQuery('/Domains/Simple_Domain', $query);print_r($result); Administration ServicesorganizationService()Searching for OrganizationsUse the searchOrganizationfunction to search for organizations by ID. $found = $c->organizationService()->searchOrganization('org');foreach ($found as $result) printf('<br>Organization Found: %s', $result->id); Getting Organization DetailsOnce you know the full ID of a specific organization, use the getOrganizationfunction to request its detailed information. This function returns an Organizationobject. $org_one = $c->organizationService()->getOrganization("organization_1");// Print the details of the $org_one Organization objectvar_dump($org_one); Creating an OrganizationTo create a new organization, define a new Organizationobject and pass it to the createOrganizationfunction. $new_organization = new Organization( 'test_organization', // alias 'test_organization', // id 'organization_1', // parent organization 'Test Organization'); // organization nametry { $c->organizationService()->createOrganization($new_organization);} catch (Exception $e) { printf('Creating organization failed: %s', $e->getMessage());} Updating an OrganizationTo modify an organization, obtain its Organizationobject with the searchOrganizationor getOrganizationfunctions. Then modify the fields you wish to update and pass it to the updateOrganizationfunction. $search = $c->organizationService()->searchOrganization('test_organization');$organization = $search[0];$organization->tenantDesc = "My test organization";try { $c->organizationService()->updateOrganization($organization);} catch (Exception $e) { printf('Unable to modify organization: %s', $e->getMessage());} Deleting OrganizationsTo delete an organization, obtain its Organizationobject with the searchOrganizationor getOrganizationfunctions, and pass it to the deleteOrganizationfunction. $search = $c->organizationService()->searchOrganizations('test_organization');$organization = $search[0];try { $c->organizationService->deleteOrganization($organization);} catch (Exception $e) { printf('Organization deletion failure: %s', $e->getMessage());} roleService()Searching for RolesUse the the searchRolesfunction to request all the roles of an organization, or all roles on the server. Optionally, you can search based on specific criteria for roles. The following example returns all roles on the server. $server_roles = $c->roleService()->searchRoles(); Getting a Specific RoleIf you know the name of the role, you can request it specifically using the getRolefunction. This function returns a Roleobject. $user_role = $c->roleService()->getRole("ROLE_USER"); Creating a RoleTo create a role, describe it in a Roleobject, then pass it to the createRolefunction. The following example creates a new role in organization_1. $robot_role = new Role("ROLE_ROBOT", "organization_1");$c->roleService()->createRole($robot_role); Updating a RoleTo upate a role, pass an updated Roleobject to the updateRolefunction. If you change the name of the role, you must pass the old name of the role as the second argument. $robot_role = $c->roleService()->getRole("ROLE_ROBOT", "organization_1");$old_name = $robot_role->roleName;$robot_role->roleName = "ROLE_HUMAN";$c->roleService()->updateRole($robot_role, $old_name); Deleting a RoleTo delete a role, first retrieve the Roleobject representing the role you wish to remove, then pass it to the deleteRolefunction. $role_human = $c->roleService()->getRole("ROLE_HUMAN", "organization_1");$c->roleService()->deleteRole($role_human); userService()Searching for UsersUsing the searchUsersfunction you can search for several users based on various critera. This function returns an array of UserLookupobjects that can be used with the getUserByLookupfunction to retrieve their fully described Userobjects. The example below finds all users of organization_1 containing 'j' in their username, and prints out the roles assigned to each user. $results = $c->userService()->searchUsers('j', 'organization_1');foreach ($results as $userLookup) { $user = $c->userService()->getUserByLookup($userLookup); printf('<br>Found user: %s', $user->fullName); foreach ($user->roles as $role) printf('<br> %10s User has role: %s', ' ', $role->roleName);} Creating a UserTo create a user, define a Userobject that fully describes the user, and pass it to the addOrUpdateUserfunction. $newUser = new User( 'BI_User', 'superSTRENGTHpassw0rd', 'clever@email.com', 'Business Intelligence User', 'organization_1', 'true'); $role = new Role('ROLE_USER', null, 'false');$newUser->addRole($role);try { $c->userService()->addOrUpdateUser($newUser);} catch (Exception $e) { printf('Could not add new user: %s', $e->getMessage());} Updating a UserTo update a user, pass an updated Userobject to the addOrUpdateUserfunction. $search = $c->userService()->searchUsers('californiaUser', 'organization_1');$californiaUser = $c->userService()->getUserByLookup($search[0]);$californiaUser->emailAddress('sanfrancisco-oakland@example.com');$californiaUser->password('SUPERstrongPASSWORD###!!!');try { $c->userService()->addOrUpdateUser($californiaUser);} catch (Exception $e) { printf('Attempt to modify the user failed with error: %s', $e->getMessage());} Delete UserTo delete a user, first retrieve the Userobject representing the user you wish to remove, then pass it to the deleteUserfunction. $user = $c->userService()->getUserByLookup( $c->userService()->searchUsers('jane', 'organization_1')[0]);$c->userService()->deleteUser($user); Reading AttributesUser attributes are name-value pairs that administrators can assign to any user. To read the attributes on a given user, pass a Userobject to the getAttributesfunction. You can also specifiy specific attributes that you wish to read, otherwise all attributes for the user will be returned. $californiaUser = $c->userService()->getUser("CaliforniaUser", "organization_1");$attributes = $c->userService()->getAttributes($californiaUser); Adding or Updating AttributesUse addOrUpdateAttributefunction to create or update an attribute for a user. Specify the name and value in an Attributeobject. If the attribute name matches an existing attribute, its value is updated. If the attribute name does not exist for the given user, the attribute is added to the user. $CAuser = $c->userService()->getUser("CaliforniaUser", "organization_1");$animal_attr = new Attribute("Favorite Animal", "Bear");$c->userService()->addOrUpdateAttribute($CAuser, $animal_attr); Deleting AttributesTo remove attributes from a user, pass a Userobject and an array of attribute names (not Attributeobjects) to the deleteAttributesfunction. If no attribute names are given, all attributes are removed. $joeUser = $c->userService()->getUser("joeuser", "organization_1");$c->userService()->deleteAttributes($joeUser);