Generating SPMP Analytics from the command line

Transcription

1 IBM Cúram Social Program Management Generating SPMP Analytics from the command line Anthony Farrell is a senior software engineer in the IBM Cúram platform group. Anthony has technical responsibility for Business Intelligence in the Cúram platform, has 10 years experience of Cúram product development, is a certified Java programmer with strong Java, Java Platform Enterprise Edition, and business intelligence experience. Anthony Farrell AnthonyFarrell@ie.ibm.com

2 Copyright International Business Machines Corporation US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Introduction CONTENTS 1 Introduction About this article Audience Prerequisites Downloads Installing the command line tools Installing the tool that accompanies this article Publishing SPMP analytic content Installing BIRT runtime tools Configuring the command line tools Testing your database connection Copying database drivers to report engine Configuring the report engine Creating directories for log files and report outputs Testing the installation Running a BIRT report from the command line Getting command line help Conclusion Acknowledgements Further Reading... 9 Copyright

4 Generating SPMP Analytics from the command line 1 Introduction This article is the final installment in a series of articles that explores Cúram Social Program Management Platform Analytics on the Cúram Social Program Management Platform and Cúram Business Intelligence and Analytics. Organizations want up-to-date analytics while minimizing the impact on Cúram users. The number and complexity of your analytic workloads should not affect the responsiveness of the Cúram application for its users. A key strategic requirement is to ensure maximum application throughput, and support analytic workloads. This developerworks article provides an approach allowing you to generate SPMP Analytics (BIRT reports) from the command line, so that you can generate analytics during off peak times. This article provides a tool that allows you to run SPMP Analytics from the command line, you can now run BIRT reports from the command line without having to change the report. 1.1 About this article This article is the final installment in a series of developerworks articles. The previous articles are: 1. New IBM Cúram Analytics accelerator for IBM Cúram Social Program Management Platform. This article shows how to develop and integrate BIRT analytics into Cúram application pages. 2. IBM Cúram SPMP Analytics application screen captures. This article provides screen captures of all the default BIRT analytics that are provided in IBM Cúram Social Program Management Platform, so that you can see them without installing the application. 3. Using DB2 BLU to enable IBM Cúram Business Intelligence and Analytics. This article introduces IBM DB2 BLU and shows that IBM Cúram Business Intelligence and Analytics (BIA) can work with DB2 BLU. 4. Reading multi-temperature data with SPMP Analytics. This developerworks article provides an approach allowing you to build BIRT analytics reading warm Cúram data. Analytical data, where data latency is acceptable or preferred, is referred to as warm data in this article. 5. Generating SPMP Analytics from the command line. This is the final article in the series, in this article you are shown how to generate analytics during off peak times. 1.2 Audience This article is intended for technical users who are tasked with developing solutions that use Cúram Social Program Management Platform Analytics on Cúram Social Program Management Platform. 1.3 Prerequisites An installed IBM Cúram application development environment. IBM Cúram Social Program Management Platform version or higher. The tools in this article were tested against Cúram version and DB2 version 10.5 FP5. Knowledge of SPMP Analytics. 2

5 Installing the command line tools 1.4 Downloads The sample tool is posted with this article on the Cúram on developerworks community. Table 1: Sample download Description Name Size Sample tool with this article Generating-SPMPAnalytics- FromTheCommandLine.zip 22.3 KB Table 2: Open source download Description Name Size BIRT Runtime birt-runtime-osgi-4_4_ zip 228 KB 2 Installing the command line tools Complete the following steps to install the software that is required to run reports from the command line. This includes the BIRT report engine, SPMP analytics, and the tool that accompanies this article. In the following paragraphs, you create a location which contains the software required to run BIRT reports and the report objects for execution. Once you have installed the command line tools and performed the configuration steps you can copy this directory to any machine for use. 2.1 Installing the tool that accompanies this article The supported data source s provided with SPMP Analytics work with three distinct ecosystems within the Cúram development environment. The supported data sources can connect to the database when the report is deployed to Tomcat, an application server, or within the Eclipse instance used for BIRT development. This article provides a tool that allows supported data source s to connect to the database when the BIRT report is run from the command line. A key requirement is to be able to run, the same BIRT analytics that are displayed in application pages, from the command line without having to change the report in any way. You can now run BIRT reports from the command line without having to change the report to set database connection properties. Complete the following steps to install the tool that accompanies this article: Download the tool and extract the contents to the extract location, for example, c:\commandlinebirt. There is one file curam-birt-offline.jar. This JAR file contains the implementation of the supported data sources that can work in a command line environment. 2.2 Publishing SPMP analytic content Complete the following steps to publish your SPMP analytic content. The published content is then copied to the extract location, c:\commandlinebirt. Publishing your SPMP analytic content ensures that all resources are gathered together in one place, this includes BIRT library files, localized properties files, jar files, and BIRT reports. You require all these resources to run SPMP analytics from the command line. 3

6 Generating SPMP Analytics from the command line From the %CURAM_DIR%\BIContent folder, run the following command. The following steps are all relative to the root of the Cúram installation, which is defined by the %CURAM_DIR% environment variable. By default, the environment variable is set to C:\IBM\Curam\Development. build client.birt Check the build command is successful. You should see the following output: [echo] [echo] START: cleaning content... [echo] START: Publishing Application BIRT reports... [copy] Copying 39 files to %CURAM_DIR%\BIApp\CuramBIRTViewer\WebContent\WEB- INF\bicontent [echo] Publishing Application BIRT library resources... [echo] Publishing Application BIRT properties files... [copy] Copying 29 files %CURAM_DIR%\BIApp\CuramBIRTViewer\WebContent\WEB- INF\bicontent\resources\properties [echo] Publishing Application BIRT javascript modules... [echo] Publishing Application BIRT CSS... [echo] Publishing Application jars... [echo] END: Publishing BIRT resources - application content ready [echo] [echo] Curam BIRT viewer ready for business - BI content ready BUILD SUCCESSFUL. From the %CURAM_DIR%\BIApp\CuramBIRTViewer\WebContent\WEB-INF\ folder, copy the folder bicontent folder (and all subfolders & files) to the extract location, C:\commandLineBIRT. From the extract location, c:\commandlinebirt, copy the file curam-birtoffline.jar to the folder C:\commandLineBIRT\bicontent\resources\scriptlib 2.3 Installing BIRT runtime tools Complete the following steps to install the BIRT run time, the run time contains the report engine that is used to generate reports from the command line. Download the BIRT run time from, ds/drops/r-r1-4_4_ /birt-runtime-osgi-4_4_ zip, extract the contents to the extract location c:\commandlinebirt. From the extract location, go to the folder birt-runtime-osgi-4_4_1, remove all files and directories, leave only the ReportEngine folder. 4

7 Configuring the command line tools 3 Configuring the command line tools Complete the following steps to configure your command line tooling. You will test your database configuration properties, copy drivers to the BIRT report engine, configure your class path and create separate directories for log files and report outputs. In line with your secure development processes, you must ensure that your Bootstrap.properties file is securely locked down. 3.1 Testing your database connection The Bootstrap.properties file contains the machine-specific configuration properties for initially getting a connection to the application database. To verify that these settings are correct complete the following steps: 1. From your Cúram EJBServer project properties folder, %CURAM_DIR%\EJBServer\project\properties, ensure your database connection properties are correct. Pay specific attention to the following elements; curam.environment.bindings.location, curam.db.username, curam.db.password, curam.db.type, curam.db.name, curam.db.servername, curam.db.serverport 2. From your Cúram EJBServer folder, %CURAM_DIR%\EJBServer, test your Bootstrap.properties file. Run the following command to verify that your database connection is valid: o build configtest To check the database connection is successful, you should see the following output: [configtest] -- DATABASE CONFIGURATION --. [configtest] curam.db.type : DB2. [configtest] -- DATABASE CONNECTIVITY --. [configtest] Database Connection established. In line with your secure development processes, you must ensure that your Bootstrap.properties file is securely locked down. 3.2 Copying database drivers to report engine Complete the following steps to copy JDBC database drivers to the BIRT report engine, this allows the report engine to connect to the database. From your CúramSDEJ drivers folder, %CURAM_DIR%\CuramSDEJ\drivers, copy all files to the report engine drivers folder, C:\commandLineBIRT\birt-runtime-osgi- 4_4_1\ReportEngine\plugins\org.eclipse.birt.report.data.oda.jdbc_ v \drivers. 3.3 Configuring the report engine Complete the following steps to configure your java class path, and to enable the tool that accompanies this article. From the extract location, c:\commandlinebirt, edit the file birt-runtimeosgi-4_4_1\reportengine\getreport.bat. Create a backup of this file before you complete the following steps. 5

8 Generating SPMP Analytics from the command line At the start of the file, set the environment variable BIRT_HOME. For example, directly after the statement ECHO off, add the line set BIRT_HOME=C:\commandLineBIRT\birt-runtime-osgi-4_4_1 You will now set the BIRT class path, to create a valid class path replace existing text in the batch file with two new lines. Search for the 2 lines: set BIRTCLASSPATH= for %%i in (%BIRT_HOME%\ReportEngine\lib\*.jar) do set BIRTCLASSPATH=%%i;!BIRTCLASSPATH! Replace with these two lines(note, ensure %CURAM_DIR% is set or replaced with the full path to the properties directory): set BIRTCLASSPATH= set BIRTCLASSPATH=C:\commandLineBIRT\bicontent\resources\scriptlib\cura m-birtoffline.jar;c:\commandlinebirt\bicontent\resources\scriptlib\curambirt.jar; %CURAM_DIR%\EJBServer\project\properties;%BIRT_HOME%\ReportEngine\l ib\* You now create a Java property, this property tells the tool that accompanies this article to read the database connection details from the class path. You set the property curam.birt.offline to a value of true. For example, search for the line in the batch file that starts with: %JAVACMD% -cp Change to read: %JAVACMD% -cp "%BIRTCLASSPATH% -D"curam.birt.offline=true" 3.4 Creating directories for log files and report outputs Complete the following steps to create directories to store your log files and report outputs. Separate from the extract location, create a new directory for log files, for example, c:\commandlinebirtlogs. This directory is used by the BIRT run time when writing log messages. Creating a separate log directory from the deployed code location is good practice, especially in production. This allows you to give administrators access to the logs directory, restricting access to the deployed code location. Separate from the extract location, create a new directory for report outputs, for example, c:\commandlinebirtoutputs. This directory is used by the BIRT run time to save report instances. Creating a separate output directory from the deployed code location is good practice, especially in production. This allows you to give administrators access to the report outputs, restricting access to the deployed code location. 6

9 Testing the installation 4 Testing the installation 4.1 Running a BIRT report from the command line Complete the following steps to run the SPMP analytics chart CaseWorkloadReport.rptdesign, saving the report output to a PDF file. Open a command prompt and change to the report engine directory, C:\commandLineBIRT\birt-runtime-osgi-4_4_1\ReportEngine Run the batch file genreport.bat with the following parameters: Parameter name --config --config --config --config --format --output --parameter The final parameter is the BIRT report design file to run. Parameter value(use quotations where specified) "resourcedir=c:\commandlinebirt\bicontent\resourc es" "tempdir=c:\commandlinebirt" "logdir=c:\commandlinebirtlogs" "loglevel=all" PDF C:\commandLineBIRTOutputs\CaseWorkloadReport.p df "username=ascewuser" For example, c:\commandlinebirt\bicontent\components\core\birt\ CaseloadSummary\CaseWorkloadReport.rptdesign For example, by using the parameters in the table above, the command is as follows: genreport.bat --config "resourcedir=c:\commandlinebirt\bicontent\resources" --config "tempdir=c:\commandlinebirt" --config "logdir=c:\ commandlinebirtlogs" --config "loglevel=all" --format PDF --output c:\commandlinebirtoutputs\caseworkloadreport.pdf --parameter "username=ascewuser" c:\commandlinebirt\bicontent\components\core\birt\caseloadsummary\c aseworkloadreport.rptdesign Review and confirm that the generated report is correct. For example, open the file C:\commandLineBIRTOutputs\CaseWorkloadReport.pdf with a PDF viewer and confirm that it is correct. 4.2 Getting command line help To view the command line parameter/options available, run the following command: genreport.bat --help runrender This command, for example, provides the following output: ReportRunner's RUNRENDER mode: --mode/-m runrender [options] <rptdesign file> where options could be: --format/-f [HTML PDF] --output/-o <target file> --htmltype/-t < HTML ReportletNoCSS > --encoding/-e <target encoding> --locale/-l <locale> default is english --parameter/-p <"parametername=parametervalue"> --config/-c <"configname=configvalue"> --renderoption/-r <"optionname=optionvalue"> 7

10 Generating SPMP Analytics from the command line --file/-f <file> 1. parameters/configs/renderoptions in command line will override those in file 2. parameter/config/renderoption name cannot include characters such as ' ', '=', ':' use "--help/-h confignames" for a list of configurables use "--help/-h renderoptions" for a list of render options use "--help/-h file" for options in <file> 5 Conclusion This article provides an approach allowing you to generate SPMP Analytics (BIRT reports) from the command line, so that you can generate analytics during off peak times. You can now run SPMP analytics from the command line without having to change the report. When running a report by using genreport.bat, you incur the cost of starting the BIRT report engine each time. If you have many hundreds or thousands of reports to run, then the time that is required to start the report engine for each report might prove too costly. In this case, instead of using genreport.bat, create your own Java application by using the report engine API s and amortize the engine startup cost by running many reports. 8

11 Acknowledgements 6 Acknowledgements The author would like to thank the following members of Cúram product development team for their input, support, testing and reviews: Phillip Purdue, Client Solutions Professional, IBM Watson Health, who performed a business review of this article. Eoin Fitzpatrick, Software Engineer, Cúram Product Development, Cúram and Smarter Care, IBM Watson Health, who tested the tools in this article and performed a technical review of this document. Paraic O'Raghallaigh, information architect, Content Strategy, Cúram and Smarter Care, IBM Watson Health. John Delaney, Senior Software Engineer, Cúram and Smarter Care, IBM Watson Health, who performed a technical review of the document. 7 Further Reading Cúram Social Program Management Cúram SPMP Analytics Accelerator 01.ibm.com/support/knowledgecenter/SS8S5A_6.1.0/com.ibm.curam.content.doc/SPMAnalytic s/spmoverview/c_spm_spmanalyticsoverview.html Installing a Cúram Development Environment 01.ibm.com/support/knowledgecenter/SS8S5A_6.1.0/com.ibm.curam.content.doc/install_Devel opmentenvironment/ctr_install_installingthedevelopmentenvironment.html?lang=en Cúram Business Intelligence and Analytics Cúram Business Intelligence and Analytics Knowledge Center 01.ibm.com/support/knowledgecenter/SS8S5A_6.1.1/com.ibm.curam.nav.doc/common/t_ctr_bi a.html Cúram SPMP Analytics Accelerator 01.ibm.com/support/knowledgecenter/SS8S5A_6.1.0/com.ibm.curam.content.doc/SPMAnalytic s/spmoverview/c_spm_spmanalyticsoverview.html 9

12 Copyright Copyright IBM Corporation 2015 IBM United States of America Produced in the United States of America US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PAPER AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes may be made periodically to the information herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this paper at any time without notice. Any references in this document to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation 4205 South Miami Boulevard Research Triangle Park, NC U.S.A. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. If you are viewing this information softcopy, the photographs and color illustrations may not appear. 10

13 Generating SPMP Analytics from the command line Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol ( or ), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the web at "Copyright and trademark information" at Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Other company, product, or service names may be trademarks or service marks of others. 11