JasperServer Web Services Guide Version 3.

http://www.jaspersoft.com/ 2008 JasperSoft Corporation. All rights reserved. Printed in the U.S.A. JasperSoft, the JasperSoft logo, JasperAnalysis, JasperServer, JasperETL, JasperReports, JasperStudio, iReport, and Jasper4 products are trademarks and/or registered trademarks of JasperSoft Corporation in the United States and in jurisdictions throughout the world. All other company and product names are or may be trade names or trademarks of their respective owners.

JasperServer Web Services Guide

Table of Contents
1 Introduction........................................................................................................................................................3 2 Repository Web Service....................................................................................................................................3 2.1 ResourceDescriptor.....................................................................................................................................3 2.2 Request and Operation Result.....................................................................................................................7 2.3 Operations in the Repository Service.........................................................................................................10 2.3.1 List.....................................................................................................................................................10 2.3.2 Get.....................................................................................................................................................12 2.3.3 Put.....................................................................................................................................................18 2.3.4 Delete................................................................................................................................................20 2.3.5 Move..................................................................................................................................................20 2.3.6 Copy..................................................................................................................................................20 2.3.7 runReport...........................................................................................................................................21 2.3.7.1 Report Output............................................................................................................................21 2.3.7.2 Report Locales...........................................................................................................................22 2.4 Errors and Implementation Suggestions....................................................................................................22 2.4.1 Errors.................................................................................................................................................22 2.4.2 Implementation Suggestions..............................................................................................................24 3 Report Scheduling Web Service.....................................................................................................................25 3.1 Types Defined in the WSDL.......................................................................................................................26 3.2 Operations in the Scheduling Service........................................................................................................27 3.2.1 Operation Descriptions......................................................................................................................27 3.2.2 Example Request and Operation Result............................................................................................27 3.2.3 Java Client Classes...........................................................................................................................29 Appendix A Repository Service API Constants.....................................................................................................30

1007-JSP21-4

JasperServer Web Services Guide

1 Introduction
This document describes the JasperSoft BI suites SOAP (Simple Object Access Protocol) web services Application Programming Interface (API). It describes the functionality provided in both Open Source and Professional editions. JasperServer offers these web services:

The repository web service lets you explore the repository, modify report units and several other resource types, and run reports with or without input parameters. The scheduling web service lets you schedule reports, retrieve information about jobs, and to delete them.

The web services take as input an XML document (the request), and return another XML document as the result (the operation result). Because they use XML, the web services provide easy, natural integration with the most common programming languages and environments. JasperSoft provides two complete sample applications that demonstrate the API: a simple J2EE (Java 2 Enterprise Edition) web application and the same application written in PHP (PHP Hypertext Preprocessor). By default, the web services are available at the following URL: Edition JasperSoft Open Source Web Service Repository Scheduling JasperSoft Professional Repository Scheduling URL http://localhost:8080/jasperserver/services/repository http://localhost:8080/jasperserver/services/ReportScheduler http://localhost:8080/jasperserver-pro/services/repository http://localhost:8080/jasperserver-pro/services/ReportScheduler

where localhost is the name of the computer hosting JasperSoft and 8080 is the port you specified during installation. Note: The context name (jasperserver or jasperserver-pro) may also depend on the specific installation of JasperServer. You must supply a valid account to access the web services. The web services accept the same accounts and credentials as the JasperSoft web interface. To simplify life for Java developers, JasperSoft provides a set of helper classes, including a ready-to-use client that can make it easier to integrate an external application with JasperServer, be it web- or desktop-based. These classes include an object model that represents resources and creates requests and operation results, along with a Marshaller and an Unmarshaller class to quickly move between XML and the Java object model. The presentation of each service includes code samples that show how to use these classes.

2 Repository Web Service

The repository web service is comprised of seven methods: list, get, put, delete, move, copy, and runReport. You can retriece the WSDL document that describes the repository service by invoking the URL of the service and appending the string ?wsdl to it. For example: http://localhost:8080/jasperserver/services/repository?wsdl The complete WSDL is detailed in Appendix A Error: Reference source not found on page Error: Reference source not found.

2.1 ResourceDescriptor
Resources (such as reports, images, and queries) are stored in a repository, which is organized like a file system, with a root and a hierarchical set of folders. Each object in the repository is considered a resource: a folder is a resource of type folder, a JRXML resource is a resource of type file, just as images and JAR files are of type file. Some resources are more abstract, such as connection definitions and an input controls. The repository web service operates on all resources. A resource is identified by: 3

A name. A label. A unique Uniform Resource Identifier (URI) that defines the location of the resource in the repository. An URI is similar to a Unix path (for example, /samples/reports/AllAccounts).

A resourceDescriptor tag is defined by the following DTD (Document Type Definition):

<!ELEMENT resourceDescriptor (label, description?, resourceProperty*, resourceDescriptor*, parameter*)> <!ATTLIST resourceDescriptor name CDATA #REQUIRED wsType CDATA #REQUIRED uriString CDATA #REQUIRED isNew ( true | false ) false >

<!ELEMENT resourceProperty (value?, resourceProperty*)> <!ATTLIST resourceProperty name CDATA #REQUIRED >

<!ELEMENT value (#PCDATA)>

<!ELEMENT parameter (#PCDATA)> <!ATTLIST parameter name CDATA #REQUIRED isListItem ( true | false ) false >

The wsType attribute defines the nature of the resource. Currently, the possible values for this attribute are: Value
bean contentResource datasource dataType folder font img inputControl jar jdbc jndi

Description
Spring bean data source The output of a report. Generic data source. This type is normally used for a data source ReportUnit child resource when the is not defined locally to the ReportUnit. Datatype (used with the input controls) Folder Font file (normally a True Type font) Image file Input control JAR file Data source of type JDBC Data source of type JNDI

JasperServer Web Services Guide Value

jrxml lov olapMondrianCon olapMondrianSchema olapXmlaCon prop query reference reportUnit xmlaConnection

Description
JRXML source file List of values (used with the input controls) OLAP Mondrian connection a direct connection to an OKAP source. OLAP Mondrian Schema OLAP XMLA connection a remote connection to an OLAP source. Resource bundle file (normally ending with .properties) for specific reports Query used to retrieve data from a data source Reference to another resource. References are present only into report units A complete report that can be run in JasperServer XMLA Connection

For all the other resource types found in the repository, the repository web service sets the attribute wsType to unknown. The isNew attribute is used with the put operation to indicate whether the resource being uploaded is new or replaces an existing resource in the repository. A resource can have a set of properties depending on its type and a set of children resources. Finally, a resource descriptor can contain one or more parameters: their use is not intended to describe the resource; they store the values users select when the runReport service is invoked. A resourceProperty is normally a simple pair of a name and a value. The Java class
com.jaspersoft.jasperserver.api.metadata.xml.domain.impl.ResourceDescriptor contains

constants for each property name. JasperSoft may add further constants in future releases. The following resourceDescriptor sample contains a set of simple properties; it describes a JDBC connection resource:

<resourceDescriptor name="JServerJdbcDS" wsType="jdbc" uriString="/datasources/JServerJdbcDS" isNew="false"> <resourceProperty name="PROP_DATASOURCE_DRIVER_CLASS"> <value>com.mysql.jdbc.Driver</value> </resourceProperty> <label>JServer Jdbc data source</label> <description>JServer Jdbc data source</description> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/datasources</value> </resourceProperty> <resourceProperty name="PROP_VERSION"> <value>0</value> </resourceProperty> <resourceProperty name="PROP_DATASOURCE_PASSWORD"> <value>password</value> </resourceProperty> <resourceProperty name="PROP_DATASOURCE_USERNAME"> <value>username</value> </resourceProperty> <resourceProperty name="PROP_DATASOURCE_USERNAME"> <value>username</value> </resourceProperty> <resourceProperty name="PROP_DATASOURCE_CONNECTION_URL"> <value>jdbc:mysql://localhost/test?autoReconnect=true</value> </resourceProperty> </resourceDescriptor> Some properties cannot be represented by a simple value. To accommodate more complicated properties, a resourceProperty can recursively contain other resourceProperties. This is the case for a List of Values resource: the values are contained in the resourceProperty named PROP_LOV and are represented by sub-resourceProperties. For example:
<resourceDescriptor name="SampleLOV" wsType="lov" uriString="/datatypes/SampleLOV" isNew="false"> <label>Sample List of Values</label> <resourceProperty name="PROP_RESOURCE_TYPE"> <value>com.jaspersoft.jasperserver.api.metadata.common.domain.ListOfValues</value> </resourceProperty> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/datatypes</value> </resourceProperty> <resourceProperty name="PROP_VERSION"> <value>-1</value> </resourceProperty> <resourceProperty name="PROP_HAS_DATA"> <value>false</value>

JasperServer Web Services Guide

</resourceProperty> <resourceProperty name="PROP_IS_REFERENCE"> <value>false</value> </resourceProperty> <resourceProperty name="PROP_LOV"> <resourceProperty name="US"> <value>United States</value> </resourceProperty> <resourceProperty name="CA"> <value>Canada</value> </resourceProperty> <resourceProperty name="IN"> <value>India</value> </resourceProperty> <resourceProperty name="IT"> <value>Italy</value> </resourceProperty> <resourceProperty name="DE"> <value>Germany</value> </resourceProperty> <resourceProperty name="RO"> <value>Romania</value> </resourceProperty> </resourceProperty> </resourceDescriptor>

Notice that, for each list item, the resourceProperty name represents the item value, and the resourceProperty value contains the item label. When a resourceDescriptor is used as an input parameter in a request document (for example, to specify a folder to list or a file to download), the description includes only a small portion of the entire resource descriptor definition: the part that describes the specific details of the resource in question can be ommitted. In many cases, the only information required to identify a resource in the repository is the wsType, the name, and the URI. The resource descriptor is a complex structure that transfers data regarding a specific resource between the server and the client. A request can include only one resource descriptor. Often, the request only includes a small portion of the entire resource descriptor definition: the part that describes the specific details of the resource in question. The resource descriptors that the server sends are completely populated with all the data about the resources being described.

2.2 Request and Operation Result

The repository web services operation takes a single input parameter of type string. This XML document represents the request. The following shows its DTD:
<!ELEMENT request (argument*, resourceDescriptor?)>

<!ATTLIST request operationName (get | list | put | runReport ) "list" locale #IMPLIED >

<!ELEMENT argument (#PCDATA)> <!ATTLIST argument name CDATA #REQUIRED >

A request is a very simple document that contains:

The operation to execute (list, get, put, delete, move, copy, or runReport). A set of optional arguments. Each argument is a pair of a key and a value that is used to achieve very particular results; arguments are only used rarely. A resource descriptor.

The operation name is redundant, since the operation to execute is intrinsic in the invoked service. Howeever, including the name can clarify the request document. The services act on a single resource at time. The resource that is the subject of the request is described by a resourceDescriptor. To get error messages in a particular locale supported by the server, specify the locale code with the locale attribute. Locale codes are in the form <language code>[_<country>[_<variant>]. Valid examples include en, en_US, it_IT, and ro. For a list of Java-compliant locales, please refer to Suns Java web site. The following sample request lists the repository root:
<?xml version="1.0" encoding="UTF-8"?> <request operationName="list" locale="en"> <resourceDescriptor name="" wsType="folder" uriString="/"> <label>null</label> </resourceDescriptor> </request>

Executing a service produces the operationResult in the form of a new XML document. The DTD is very simple:
<!ELEMENT operationResult (code, message?, resourceDescriptor*)> <!ATTLIST operationResult version NMTOKEN #REQUIRED >

<!ELEMENT code (#PCDATA)> <!ELEMENT message (#PCDATA)>

The operation result contains a return code, an optional return message and zero or more resource descriptors. A return code other than 0 indicates an error, which is normally described in the message tag.
8

JasperServer Web Services Guide The operation result always includes the version attribute: it can be used to detect the server version. For example, you can list the repository root and read the version set by the server in the response. In this case, we arent interested in the root folders content: we just want the version information from the response object itself. The operation result of such a request is:
<operationResult version="1.2.0"> <returnCode>0</returnCode> .... several resource descriptors.... .... </operationResult>

2.3 Operations in the Repository Service

2.3.1 List This service lists the contents of the specified folder or report unit. The following sample request lists the contents of the /ContentFiles folder in the repository:
<request operationName="list" locale="en"> <resourceDescriptor name="" wsType="folder" uriString="/ContentFiles" isNew="false"> <label>null</label> </resourceDescriptor> </request>

Sample response:
<operationResult version="1.2.0"> <returnCode>0</returnCode> <resourceDescriptor name="html" wsType="folder" uriString="/ContentFiles/html" isNew="false"> <label>html</label> <resourceProperty name="PROP_RESOURCE_TYPE"> <value>com.jaspersoft.jasperserver.api.metadata.common.domain.Folder</value> </resourceProperty> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/ContentFiles</value> </resourceProperty> <resourceProperty name="PROP_VERSION"> <value>0</value> </resourceProperty> </resourceDescriptor> <resourceDescriptor name="pdf" wsType="folder" uriString="/ContentFiles/pdf" isNew="false"> <label>pdf</label> <resourceProperty name="PROP_RESOURCE_TYPE"> <value>com.jaspersoft.jasperserver.api.metadata.common.domain.Folder</value> </resourceProperty> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/ContentFiles</value> </resourceProperty> <resourceProperty name="PROP_VERSION"> <value>0</value> </resourceProperty> </resourceDescriptor> <resourceDescriptor name="xls" wsType="folder" uriString="/ContentFiles/xls" isNew="false"> <label>xls</label>

10

JasperServer Web Services Guide

<resourceProperty name="PROP_RESOURCE_TYPE"> <value>com.jaspersoft.jasperserver.api.metadata.common.domain.Folder</value> </resourceProperty> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/ContentFiles</value> </resourceProperty> <resourceProperty name="PROP_VERSION"> <value>0</value> </resourceProperty> </resourceDescriptor> </operationResult>

When it lists a folder, the repository web service returns a set of resource descriptors: one for each resource that resides in the specified folder. Use / as the URI to identify the root folder. Similarly, when it lists a report unit, the repository web service returns a set of resource descriptors that contain (at a minimum) the main JRXML source file. Since a resource in a report unit can be either a local resource or a reference to another repository resource, you should keep a few details in mind:

If a report unit data source is not defined locally, its wsType is set to datasource, which does not indicate the exact nature of the resource. Its type should simply be reference, but since the data source used by the report unit is a special child resource, its easy to recognize. The URI of the referenced resource is available in the PROP_REFERENCE_URI property. The main JRXML resources wsType is always set to jrxml, even if its a reference to an external JRXML resource. By looking at the PROP_IS_REFERENCE and PROP_REFERENCE_URI properties, you can determine where the resource is actually stored. The PROP_RU_IS_MAIN_REPORT property identifies the main JRXML source file of the report unit, even if the order of its children is altered. The purpose of listing a report unit is to get the list of the resources contained in the report unit. To retrieve the entire report unit (report unit resource as well as its children) at the same time, use the get service.

The list operation also provides request arguments to get the list of all resources of a given type in the repository, for example all the report units. This use of the list operation has the following syntax:
<request operationName="list"> <argument name="LIST_RESOURCES"/> <argument name="RESOURCE_TYPE">reportUnit</argument> <argument name="PARENT_DIRECTORY">/reports</argument> </request> or <request operationName="list"> <argument name="LIST_RESOURCES"/> <argument name="RESOURCE_TYPE">reportUnit</argument> <argument name="START_FROM_DIRECTORY">/reports</argument> </request>

No value is needed for the LIST_RESOURCES argument. The value of the RESOURCE_TYPE argument can be any value of wsType except folder. The PARENT_DIRECTORY argument is the URI of the folder in which you want to look for resources. If you want to look for the resources in a branch of the repository, use the START_FROM_DIRECTORY argument. 11

Several Java methods in com.jaspersoft.jasperserver.irplugin.wsclient.WSClient use LIST_RESOURCES: list(String xmlRequest) - Sends any custom request, including one using LIST_RESOURCES as shown above. listResources(String type) - Lists all resources of the given type in the repository visible to the logged in user. listResourcesInFolder(String type, String parentFolder) - Lists resources of the given type in the folder. listResourcesUnderFolder(String type, String ancestorFolder) - Lists resources of the given type in the folder and the entire tree beneath that folder.

There is a shortcut for the list operation to get the list of data sources available in the repository. To do so, set the requests LIST_DATASOURCES argument to true.
<request operationName="list" locale="en"> <argument name="LIST_DATASOURCES">true</argument> </request>

Java sample code:

ResourceDescriptor rd = new ResourceDescriptor(); rd.setWsType( ResourceDescriptor.TYPE_FOLDER ); rd.setUriString("/"); List lst = wsclient.list(rd);

In the above sample, wsclient is an instance of PHP sample:

$result = ws_list("/");

com.jaspersoft.jasperserver.irplugin.wsclient.WSClient.

if (get_class($result) == 'SOAP_Fault') { $errorMessage = $result->getFault()->faultstring; } else { $folders = getResourceDescriptors($result); }

This PHP sample uses the client.php file found in the PHP sample provided with JasperServer. This file defines the most important constants you may find useful when integrating with the JasperServer web services, as well as useful functions that wrap the list, get, and the runReport operations. 2.3.2 Get

The get operation is used to obtain information about a resource. In the case of file resources, such as images, fonts, JRXML files, and JAR files, the resource file is attached to the response message. This methods behavior differs, depending on the type of object specified:

Generally, a simple resource descriptor is returned.

12

JasperServer Web Services Guide

If you get a resource file, the file content is attached to the response; if you do not want the server to attach files to the response, set the requests NO_ATTACHMENT argument to true. If you get a report unit, all the related resources are added as child resource descriptors to the report unit descriptor. If you get an input control that is based on a query, and you set the IC_GET_QUERY_DATA argument to the valid URI of a data source, that data source is used to execute the query and populate the resource descriptor. This can be useful when the input control must be rendered (for example, on a web page) in order to capture a value to pass when executing a report.

The following sample request gets a file resource:

<request operationName="get" locale="en"> <resourceDescriptor name="JRLogo" wsType="img" uriString="/images/JRLogo" isNew="false"> <label>JR logo</label> <description>JR logo</description> </resourceDescriptor> </request>

The service only uses the uriString to identify the resource to get and check for access permissions. This means that other information present in the resource description (such as resource properties, label, and description) are not actually used or required. If a file is attached to the response, the returned resource descriptor has the PROP_HAS_DATA property set to true. By default, the attachments format is MIME. You can use DIME attachments by specifying the USE_DIME_ATTACHMENTS argument in the request. A get call always returns a resource descriptor. If the specified resource is not found, or the user cannot access it, an error with code 2 is returned. Java sample:
String imgUri = "/images/JRLogo"; ResourceDescriptor rdis = new ResourceDescriptor(); rdis.setParentFolder("/images"); rdis.setUriString(imgUri);

ResourceDescriptor result = wsclient.get(rdis, null);

PHP sample:
$result = ws_get($someInputControlUri, array( IC_GET_QUERY_DATA => $someDatasourceUri ) );

The resource descriptor of an input control that includes data obtained by setting the IC_GET_QUERY_DATA argument to true would be similar to the following XML:
<resourceDescriptor name="TEST_LIST" wsType="inputControl" uriString="/MyInputControls/TEST_LIST" isNew="false"> <label>My test list</label> <description>My test list</description> <resourceProperty name="PROP_RESOURCE_TYPE"> <value>com.jaspersoft.jasperserver.api.metadata.common.domain.InputControl</value>

13

</resourceProperty> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/MyInputControls</value> </resourceProperty> <resourceProperty name="PROP_VERSION"> <value>6</value> </resourceProperty> <resourceProperty name="PROP_HAS_DATA"> <value>false</value> </resourceProperty> <resourceProperty name="PROP_IS_REFERENCE"> <value>false</value> </resourceProperty> <resourceProperty name="PROP_INPUTCONTROL_IS_MANDATORY"> <value>true</value> </resourceProperty> <resourceProperty name="PROP_INPUTCONTROL_IS_READONLY"> <value>false</value> </resourceProperty> <resourceProperty name="PROP_INPUTCONTROL_TYPE"> <value>7</value> </resourceProperty> <resourceProperty name="PROP_QUERY_VALUE_COLUMN"> <value>name</value> </resourceProperty> <resourceProperty name="PROP_QUERY_VISIBLE_COLUMNS"> <resourceProperty name="PROP_QUERY_VISIBLE_COLUMN_NAME"> <value>name</value> </resourceProperty> <resourceProperty name="PROP_QUERY_VISIBLE_COLUMN_NAME"> <value>phone_office</value> </resourceProperty> <resourceProperty name="PROP_QUERY_VISIBLE_COLUMN_NAME"> <value>billing_address_city</value> </resourceProperty> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA"> <resourceProperty name="PROP_QUERY_DATA_ROW"> <value>A &amp; L Powers Engineering, Inc</value> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN">

14

JasperServer Web Services Guide

<value>A &amp; L Powers Engineering, Inc</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>738-555-3283</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>Haney</value> </resourceProperty> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW"> <value>A &amp; U Jaramillo Telecommunications, Inc</value> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>A &amp; U Jaramillo Telecommunications, Inc</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>564-555-6913</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>Walla Walla</value> </resourceProperty> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW"> <value>A &amp; U Stalker Telecommunications, Inc</value> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>A &amp; U Stalker Telecommunications, Inc</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>323-555-1226</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>Mill Valley</value> </resourceProperty> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW"> <value>A &amp; X Caravello Engineering, Inc</value> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>A &amp; X Caravello Engineering, Inc</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN">

15

<value>958-555-5890</value> </resourceProperty> <resourceProperty name="PROP_QUERY_DATA_ROW_COLUMN"> <value>Tlaxiaco</value> </resourceProperty> </resourceProperty> </resourceProperty> <resourceDescriptor name="query" wsType="query" uriString="/MyInputControls/TEST_LIST_files/query" isNew="false"> <label>query</label> <description>query</description> <resourceProperty name="PROP_RESOURCE_TYPE"> <value>com.jaspersoft.jasperserver.api.metadata.common.domain.Query</value> </resourceProperty> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/MyInputControls/TEST_LIST_files</value> </resourceProperty> <resourceProperty name="PROP_VERSION"> <value>1</value> </resourceProperty> <resourceProperty name="PROP_HAS_DATA"> <value>false</value> </resourceProperty> <resourceProperty name="PROP_IS_REFERENCE"> <value>false</value> </resourceProperty> <resourceProperty name="PROP_QUERY"> <value>SELECT name, phone_office, billing_address_city FROM accounts order by name</value> </resourceProperty> <resourceProperty name="PROP_QUERY_LANGUAGE"> <value>sql</value> </resourceProperty> <resourceDescriptor name="" wsType="datasource" uriString="" isNew="false"> <label>null</label> <resourceProperty name="PROP_REFERENCE_URI"> <value>/datasources/JServerJdbcDS</value> </resourceProperty> <resourceProperty name="PROP_IS_REFERENCE"> <value>true</value> </resourceProperty> </resourceDescriptor>

16

JasperServer Web Services Guide

</resourceDescriptor> </resourceDescriptor>

The query result is a set of rows that represents the full set of possible values for the input control. For each row, the repository web service returns the value that the runReport service expects for that particular option in the input control. Each row also includes the column values that should be displayed in the input control when prompting users.

The screenshot above shows single and multiple select input controls based on queries, as they are rendered by the iReport plugin for JasperServer. When the web services run report units, the rendering of input controls is left to the client application. The best way to proceed is:

get the report unit;

check for query-based input controls by looking at the PROP_INPUTCONTROL_TYPE resource property or each child resource descriptor where wsType is equal to inputControl;
get each query based input control by setting the IC_GET_QUERY_DATA argument to true;

render the input controls (if used in the report unit), being mindful of the input control properties (such as read only and mandatory). call the runReport service and pass the user-selected values (refer to section 2.3.7 runReport on page 21 for details).

The rows are stored in the PROP_QUERY_DATA resource property: for each row, a child resource property named PROP_QUERY_DATA_ROW contains the value and a set of children that contain the column values; these last resource properties are named PROP_QUERY_DATA_ROW_COLUMN. The following schema may elucidate the whole data structure.
PROP_QUERY_DATA ( PROP_QUERY_DATA_ROW, value (

17

PROP_QUERY_DATA_ROW_COLUMN, value PROP_QUERY_DATA_ROW_COLUMN, value PROP_QUERY_DATA_ROW_COLUMN, value ... )

PROP_QUERY_DATA_ROW, value ( PROP_QUERY_DATA_ROW_COLUMN, value PROP_QUERY_DATA_ROW_COLUMN, value PROP_QUERY_DATA_ROW_COLUMN, value ... )

PROP_QUERY_DATA_ROW, value ( PROP_QUERY_DATA_ROW_COLUMN, value PROP_QUERY_DATA_ROW_COLUMN, value PROP_QUERY_DATA_ROW_COLUMN, value ... ) )

In Java, to simplify response processing, the ResourceDescriptor class provides the getQueryData() method that returns a list of InputControlQueryDataRow, which is a convenient class containing all the row information (row and column values). 2.3.3 Put

The put operation adds new resources to the repository or modifies existing ones. Whether the service adds or modifies a resource depends on whether the requests isNew resource descriptor attribute is set to true. The parent URI of the new resource must exist, and can be the repository root (/). When modifying a resource, you must provide the whole resource descriptor; the changes do not impact child resources. The following XML code creates a folder called test inside the folder /reports/samples:
<request operationName="put" locale="en"> <resourceDescriptor name="test" wsType="folder" uriString="/reports/samples/test" isNew="true"> <label>Test</label> <description>This is a test</description> <resourceProperty name="PROP_PARENT_FOLDER"> <value>/reports/samples</value> </resourceProperty> </resourceDescriptor> </request>

18

JasperServer Web Services Guide When adding a file resource, the data must be added as an attachment to the SOAP request, and the PROP_HAS_DATA property must be set to true. When modifying a file resource, you only need to attach the file if it must be replaced; otherwise PROP_HAS_DATA can be set to false. In this case, the properties you provide are changed (for example, the label and the description). The following Java sample creates a new image resource in the repository using the sample classes provided with JasperServer:
ResourceDescriptor rdis = new ResourceDescriptor(); rdis.setResourceType(ResourceDescriptor.TYPE_IMAGE); rdis.setName("testImageName"); rdis.setLabel("TestImageLabel"); rdis.setDescription("Test Image Description"); rdis.setParentFolder("/images"); rdis.setUriString(rdis.getParentFolder() + "/" + rdis.getName()); rdis.setWsType(ResourceDescriptor.TYPE_IMAGE);

File img = new File("/some/file/logo.jpg"));

rdis.setHasData(true); rdis.setIsNew(true);

ResourceDescriptor result = wsclient.addOrModifyResource(rdis, img);

Working with report units is a bit more complicated. When creating a new report unit, the request must contain a child JRXML resource descriptor where the PROP_RU_IS_MAIN_REPORT property is set to true. This resource becomes the main JRXML of the report unit. If it is defined locally to the report, the file must be attached to the SOAP request (in this case, the parent URI for report units children is not relevant, and can be set to something like <report unit parent uri>/<report unit name>_files). If the the report units main JRXML already resides in the repository, the descriptor is still defined as a JRXML resource (that is, the wsType property must be set to jrxml), and the PROP_FILERESOURCE_REFERENCE_URI property must be set to the URI of the correct JRXML resource in the repository. A second child resource is recognized during creation: a data source descriptor of the data source that the server will use to run the report. This resource is optional, and can be defined either locally to the report unit or as a reference to another resource in the repository:

When the data source is defined locally, the resources wsType must be a valid data source type, such as jdbc, jndi, or bean. If the data source is defined elsewhere in the repository, its wsType must be set to datasource, which indicates an undefined resource that can be used as a data source, and its PROP_FILERESOURCE_IS_REFERENCE property must be set to true. The resources actual URI must be set in the PROP_FILERESOURCE_REFERENCE_URI property.

Other resources such as input controls and subreports, must be added separately using the put operation to modify the report unit.

19

Creating, modifying, and removing resources in a report unit is similar to working with resources in a folder. The main difference is that you must set the requests MODIFY_REPORTUNIT_URI argument to the URI of the report unit you want to modify. You cannot remove the JRXML resource flagged as main JRXML, but can replace or modify it. The repository web service doesnt allow you to add more than a single data source to the report unit; the report unit is always run against this data source. 2.3.4 Delete

This operation deletes resources from the repository. If the specified resource is located in a report unit, you must set the requests MODIFY_REPORTUNIT_URI argument to the URI of the report unit you want to modify. If you are deleting a folder, all its content is removed recursively. There is no way to recover a deleted resource or folder, so use caution when calling this service. The following sample request deletes a resource from a report unit:
<request operationName="delete" locale="en"> <argument name="MODIFY_REPORTUNIT_URI">/reports/JD_New_report</argument> <resourceDescriptor name="test_img" wsType="img" uriString="/reports/JD_New_report_files/test_img"> <label>test image</label> <description>test image</description> </resourceDescriptor> </request>

2.3.5

Move

This operation moves a repository folder or resource to a different location/folder in the repository. The operation exposes the API repository service moveResource and moveFolder methods. The operation expects (as part of the request) a resource descriptor that identifies the resource or folder to be moved. The new location of the resource/folder must be provioded as the value of the DESTINATION_URI request argument. The destination URI must resolve to an existing repository folder. The following request moves the report unit located at /Reports/NewReport to /MyReports:
<request operationName="move" locale="en" <argument name="DESTINATION_URI">/MyReports</argument> <resourceDescriptor name="NewReport" wsType="reportUnit" uriString="/Reports/NewReport"> </resourceDescriptor> </request>

2.3.6

Copy

This operation creates in the repository a copy of an existing resource or folder. The operation exposes the repository service copyResource and copyFolder API methods. The resource or folder to be copied is sent as the resource descriptor of the request; the caller does not need to provide the full resource information but only the information required to locate the resource. The full location of the copy must be provided as the value of the DESTINATION_URI request argument. If this location already exists in the repostiroy at the moment the operation is called, the server automatically changes the name part of the destination URI and saves the resource or folder copy at the new URI. The copy operation response includes a descritpor for the saved resource or folder copy. The response descriptor is particularly useful in determining whether the copy has been created at the specified destination URI or at a different/generated URI. When a folder is being copied, all its subfolders and contained resources are recursively copied.
20

JasperServer Web Services Guide The following request copies the report unit located at /Reports/NewReport to /MyReports/NewReportCopy:
<request operationName="copy" locale="en" <argument name="DESTINATION_URI">/MyReports/NewReportCopy</argument> <resourceDescriptor name="NewReport" wsType="reportUnit" uriString="/Reports/NewReport"> </resourceDescriptor> </request>

2.3.7

runReport

This operation executes a report on the server, and returns the reports results in the specified format. The client application is responsible for prompting users for values to pass to any input controls defined in the report, as shown in the following sample request XML:
<request operationName="runReport" locale="en"> <argument name="RUN_OUTPUT_FORMAT">JRPRINT</argument> <resourceDescriptor name="" wsType="" uriString="/reports/samples/EmployeeAccounts" isNew="false"> <label>null</label> <parameter name="EmployeeID">emil_id</parameter> <parameter name="TEST_LIST" isListItem="true">A &amp; L Powers Engineering, Inc</parameter> <parameter name="TEST_LIST" isListItem="true">A &amp; U Jaramillo Telecom, Inc</parameter> <parameter name="TEST_LIST" isListItem="true">A &amp; U Stalker Telecom, Inc</parameter> </resourceDescriptor> </request>

This example shows a parameter tag: <!ELEMENT parameter (#PCDATA)> 1 2 <!ATTLIST parameter 3 name CDATA #REQUIRED 4 isListItem ( true | false ) false 5
Name (on line 4) refers to the input control to set. If the input control is of type multi-select, the list of selected values is composed of a set of parameter tags that have the same names and have the isListItem attribute set to true,

indicating that the parameter is part of a list. Notes:

Parameter values are all treated as strings; only number, string, and date/time values are allowed. Numbers cannot include punctuation for the digit grouping symbol (thousands separator) and must use a period (.) as the decimal separator (if the relative parameter is not an integer). Dates and date/times must be represented as the number of milliseconds since January 1, 1970, 00:00:00 GMT. Report Output

2.3.7.1

The files produced are attached to the response. Specify the final format of the report by setting the request RUN_OUTPUT_FORMAT argument. Its possible values are: PDF, JRPRINT, HTML, XLS, XML, CSV and RTF. The default is PDF. 21

If the final format is set to JRPRINT, the data attached to the response contains a serialized instance of a JasperPrint object. This is the best format to use for clients in Java environments, because it provides the Java client with access to all of JasperReports export options, and only relies on the server to fill the report. The following Java code shows how to access the serialized object and get the JasperPrint object: FileContent content = null; if (attachments != null && !attachments.isEmpty()) { content = (FileContent)(attachments.values().toArray()[0]); } if (content == null) { throw new Exception("No JasperPrint"); } InputStream is = new ByteArrayInputStream(content.getData()); JasperPrint print = (JasperPrint) JRLoader.loadObject(is); If the specified output format is HTML, the URI for images can be set using the RUN_OUTPUT_IMAGES_URI argument: the default value is images/. If images are found, they are attached to the response. If only a single page needs to be printed, use the RUN_OUTPUT_PAGE argument, which must contain the index of page to fill. 2.3.7.2 Report Locales Reports that have resource bundles for localiztaion can be generated in a specific languages when the locale is passed using the REPORT_LOCALE built-in report parameter. If this parameter is not specified in the web service request, the report locale defaults to the request's locale. If no locale was specified for the reuqest, the report is generated in the server's default locale. The following XML fragment shows a request to run a report in the Italian locale, which is passed as the value of the REPORT_LOCALE built-in report parameter:
<request operationName="runReport" locale="fr"> <argument name="RUN_OUTPUT_FORMAT">JRPRINT</argument> <resourceDescriptor name="" wsType="" uriString="/reports/samples/EmployeeAccounts" isNew="false"> <label>null</label> <parameter name="REPORT_LOCALE"><![CDATA[it]]></parameter> <parameter name="EmployeeID">emil_id</parameter> </resourceDescriptor> </request>

If the built-in report parameter is removed from this request, the report is generated in French, based on the locale attribute of the request.

2.4 Errors and Implementation Suggestions

2.4.1 Errors When the repository web service returns a code other than 0, an error has occurred during the server execution. The exact error is described in the message field of the operation result. If the problem is environmental, such as an incorrect service URL, an incorrect user name or password, network errors, or an unavailable service, a web services error is retuned. The following shows an Axis connection refused error:
AxisFault faultCode: {http://schemas.xmlsoap.org/soap/envelope/}Server.userException

22

JasperServer Web Services Guide

faultSubcode: faultString: java.net.ConnectException: Connection refused: connect faultActor: faultNode: faultDetail: {http://xml.apache.org/axis/}stackTrace:java.net.ConnectException: Connection refused: connect at java.net.PlainSocketImpl.socketConnect(Native Method) at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:333) at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:195) at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:182) at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:366)

The following shows an Axis user name/password error:

AxisFault faultCode: {http://xml.apache.org/axis/}HTTP faultSubcode: faultString: (401)Bad credentials faultActor: faultNode: faultDetail: {}:return code: 401 &lt;html&gt;&lt;head&gt;&lt;title&gt;Apache Tomcat/5.5.16 - Error re port&lt;/title&gt;&lt;style&gt;&lt;!--H1 {font-family:Tahoma,Arial,sans-serif;co lor:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial ,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3 {font-famil y:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P { font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px; }A {color : black;}A.name {color : black;}HR {color : #525D76;}--&gt;&lt;/style& gt; &lt;/head&gt;&lt;body&gt;&lt;h1&gt;HTTP Status 401 - Bad credentials&lt;/h1& gt;&lt;HR size=&quot;1&quot; noshade=&quot;noshade&quot;&gt;&lt;p&gt;&lt;b&gt;ty pe&lt;/b&gt; Status report&lt;/p&gt;&lt;p&gt;&lt;b&gt;message&lt;/b&gt; &lt;u&gt ;Bad credentials&lt;/u&gt;&lt;/p&gt;&lt;p&gt;&lt;b&gt;description&lt;/b&gt; &lt; u&gt;This request requires HTTP authentication (Bad credentials).&lt;/u&gt;&lt;/ p&gt;&lt;HR size=&quot;1&quot; noshade=&quot;noshade&quot;&gt;&lt;h3&gt;Apache T omcat/5.5.16&lt;/h3&gt;&lt;/body&gt;&lt;/html&gt; {http://xml.apache.org/axis/}HttpErrorCode:401

(401)Bad credentials

23

at org.apache.axis.transport.http.HTTPSender.readFromSocket(HTTPSender.java:744) at org.apache.axis.transport.http.HTTPSender.invoke(HTTPSender.java:144) at org.apache.axis.strategies.InvocationStrategy.visit(InvocationStrategy.java:32) at org.apache.axis.SimpleChain.doVisiting(SimpleChain.java:118) at org.apache.axis.SimpleChain.invoke(SimpleChain.java:83) at org.apache.axis.client.AxisClient.invoke(AxisClient.java:165)

2.4.2

Implementation Suggestions

The iReport plugin for JasperServer relies on the repository web service described in this document. If you use Java, JasperSoft recommends that you familiarize yourself with the plugins source code, as it can help you understand how best to implement your own web services client. It is included in JasperServer Professional and is also available on SourceForge at: http://sourceforge.net/project/showfiles.php?group_id=162962 Download the ZIP file that contains the iReport plugin. In particular, the following classes can be very illuminating:
com.jaspersoft.jasperserver.irplugin.wsclient.WSClient com.jaspersoft.jasperserver.irplugin.JServer

The first class implements the majority of the client code, including invoking the web services, attaching files to requests, and reading files from a response. The second class stores the URL, user name, and password to connect to the web service. With these two classes, it is easy to write an entire client. For example: import net.sf.jasperreports.engine.JasperPrint; 1 import com.jaspersoft.jasperserver.irplugin.JServer; 2 import com.jaspersoft.jasperserver.api.metadata.xml.domain.impl.*; 3 4 public class MyJIClient { 5 6 private JServer server = null; 7 8 public MyJIClient(String webServiceUrl, String username, String password) 9 10 { 11 server = new JServer(); 12 server.setUsername(username); 13 server.setPassword(password); 14 server.setUrl(webServiceUrl); 15 } 16 public java.util.List list(String uri) throws Exception 17 { 18 ResourceDescriptor rd = new ResourceDescriptor(); 19 rd.setWsType( ResourceDescriptor.TYPE_FOLDER); 20 rd.setUriString(uri); 21 return server.getWSClient().list(rd); 22 } 23 public ResourceDescriptor get(String uri) throws Exception 24 { 25 return get(uri, null); 26 } 27 public ResourceDescriptor get(String uri, java.util.List args) throws Exception 28 { 29 ResourceDescriptor rd = new ResourceDescriptor();
24

30 31 32 33 34 35 36 37 38 39 40 41

JasperServer Web Services Guide rd.setWsType( ResourceDescriptor.TYPE_REPORTUNIT); rd.setUriString(uri); return server.getWSClient().get(rd, null,args); } public JasperPrint runReport(String reportUri, java.util.Map parameters) throws Exception { ResourceDescriptor rd = new ResourceDescriptor(); rd.setWsType( ResourceDescriptor.TYPE_REPORTUNIT); rd.setUriString(reportUri); return server.getWSClient().runReport(rd, parameters); } }

This example class allows you to execute the list, get, and runReport operations of the repository web service. Please refer to the iReport plugin for a more extensive implementation of the web services. To compile and use the class, you need the following JAR files (which can be taken from the iReport plugin archive):

activation-1.1.jar axis-1.4.jar commons-discovery-0.2.jar commons-codec-1.3.jar jasperserver-common-ws-1.2.jar jasperserver-ireport-plugin-1.2.jar jaxrpc.jar mail-1.4.jar saaj.jar

wsdl4j-1.5.1.jar Most of these JAR files are from the Axis2 package, with these exceptions (): activation-1.1.jar

mail-1.4.jar
com.jaspersoft.jasperserver.ws.xml.Marshaller com.jaspersoft.jasperserver.ws.xml.Unmarshaller

If necessary, you can marshal and unmarshal request and response objects by using the following classes:

If you use a development environment other than Java (such as .NET), you can easily generate a client from the WSDL.

3 Report Scheduling Web Service

The scheduling web service exposes JasperServers report scheduling functionality to integrating applications by the means of a dedicated web service. The web service is the equivalent of the API report scheduling service (com.jaspersoft.jasperserver.api.engine.scheduling.service.ReportSchedulingService) and exposes the same operations as this API service. The service works via XML-RPC calls that use the SOAP encoding. It uses the HTTP protocol to send and receive requests and responses. By default, it is deployed at /services/ReportScheduler. You can retrieve the service WSDL (Web Service Description Language) document by appending ?wsdl to the service URL. For example: http://localhost:8080/services/ReportScheduler/?wsdl

25

3.1 Types Defined in the WSDL

The WSDL defines several types that are used by the parameters and operation result of the service. The types belong to the http://www.jasperforge.org/jasperserver/ws namespace. This section provides a partial list of the types used for report scheduling; for the complete reference, refer to the the WSDL document. The report scheduling types include:

Job encapsulates all the attributes of a report job. This type is used when full report job details are passed

to or returned by an operation. Its type elements include:

id and version required when updating a report job. reportUnitURI the URI of the report. username set automatically to the name of the calling user when a report job is created. label the job label. simpleTrigger or calendarTrigger the job trigger, which can be either a simple (fixed interval)

trigger or a calendar trigger.

parameters the list of report parameter/input control values. baseOutputFilename the base name for the job output. outputFormats the list of job output formats (as strings). JasperServer has built-in support for the

following formats: PDF, HTML, XLS, RTF and CSV.

outputLocale the String representation of a java.util.Locale to be used as report locale. repositoryDestination the location in the repository where the report output is saved. mailNotification information regarding the email notification that is sent when the job executes.

Set this value to null to suppress notifications.

JobSimpleTrigger a job trigger that fires at fixed intervals. It has the following attributes:

startDate and endDate the start and end dates of the job. timezone the timezone of the start and end dates. occurrenceCount how many times to run the job. If a single run job is wanted, 1 should be used as

occurrence count; if the job is to be fired indefinitely (or until the end date) -1 should be used.
recurrenceInterval and recurrenceIntervalUnit the interval at which the job should recur: MINUTE, HOUR, DAY and WEEK.

JobCalendarTrigger a job trigger that fires at time specified by a CRON-like expression. It has the

following attributes:

startDate and endDate the start and end dates of the job. timezone the timezone of the start and end dates. minutes the minute or minutes of the day when the job is to run. hours the hour or hours of the day when the job is to run. daysType the way that days are specified. Possible values include ALL, WEEK or MONTH. weekDays used when daysType is WEEK, this indicates the week days from Saturday (1) to Sunday

(7).
monthDays used when daysType is MONTH, this indicates the month days. months the months (from 0 to 11) on which the job should be triggered.

JobRepositoryDestination contains information about where to save the report job output in the

repository, including:

folderURI the URI of the folder where the report output will be saved. sequentialFilenames a flag indicating whether to append timestamps to the base output name.

JobMailNotification encapsulates the attributes of the mail notification to send regarding the report

job. It has the following attributes:

26

JasperServer Web Services Guide

toAddresses the list of email addresses to which the notification will be sent. subject the subject of the email notification. resultSendType indicates whether to attach the report ouput to the email; the value is either SEND (only the messages is sent) or SEND_ATTACHMENT (the report output is sent along as a message

attachment).

JobSummary This type is used when a list of report jobs is retrieved via the service. The full report job

information can be retrieved individually for required jobs. The job summary includes:

id the unique identifier of the job. label the display label of the job. state the state of the job. For example, NORMAL indicates that the job is waiting for next execution; EXECUTING means the job is running. previousFireTime the last/previous run time. nextFireTime the next run time.

3.2 Operations in the Scheduling Service

3.2.1 Operation Descriptions The report scheduling web service consists of the following operations:

getAllJobs returns the list of all accessible report jobs. getReportJobs returns the list of of all accessible report jobs for a specific report (whose URL is sent

as a parameter).
scheduleJob schedules a new job. The job details must be sent as parameters; the operation returns the

saved job details as its result.

updateJob updates an existing job. The full job details (as retrieved via getJob) must be sent as a

parameter; the operation returns the updated job details as saved by the JasperServer scheduling service.
getJob returns the full job details of a report job whose ID is sent as a parameter. deleteJob and deleteJobs delete a single or several report job specified by their IDs. These

operations do not return any information. If an exception occurs while processing an operation request, the exception is converted to a SOAP fault which is sent as its response. In this case, the exception stacktrace is included in the response, and can be used for debugging. Exceptions thrown by the JasperServer code have localizable messages. The operation caller can specify the locale in which the messages of such exceptions are returned by setting a SOAP envelope header. The header should be named locale and should use http://www.jasperforge.org/jasperserver/ws as namespace; the header value is a string representation of the desired message locale. For more information, refer to 2.2 Request and Operation Result on page 7. 3.2.2 Example Request and Operation Result

This is the full SOAP request for a scheduleJob operation that creates a job with four report parameters:
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <ns1:scheduleJob soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://www.jasperforge.org/jasperserver/ws"> <job xsi:type="ns1:Job"> <reportUnitURI xsi:type="xsd:string">/reports/samples/ SalesByMonth</reportUnitURI> <username xsi:type="xsd:string" xsi:nil="true"/> <label xsi:type="xsd:string">Label 3</label> <description xsi:type="xsd:string">Description 3</description> <simpleTrigger xsi:type="ns1:JobSimpleTrigger">

27

<timezone xsi:type="xsd:string" xsi:nil="true"/> <startDate xsi:type="xsd:dateTime">2008-1009T09:25:00.000Z</startDate> <endDate xsi:type="xsd:dateTime" xsi:nil="true"/> <occurrenceCount xsi:type="xsd:int">1</occurrenceCount> <recurrenceInterval xsi:type="xsd:int" xsi:nil="true"/> <recurrenceIntervalUnit xsi:type="ns1:IntervalUnit" xsi:nil="true"/> </simpleTrigger> <calendarTrigger xsi:type="ns1:JobCalendarTrigger" xsi:nil="true"/> <parameters soapenc:arrayType="ns1:JobParameter[4]" xsi:type="soapenc:Array" xmlns:soapenc="http://schemas.xmlsoap.org/soap/ encoding/"> <parameters xsi:type="ns1:JobParameter"> <name xsi:type="xsd:string">TextInput</name> <value xsi:type="soapenc:int">22</value> </parameters> <parameters xsi:type="ns1:JobParameter"> <name xsi:type="xsd:string">CheckboxInput</name> <value xsi:type="soapenc:boolean">true</value> </parameters> <parameters xsi:type="ns1:JobParameter"> <name xsi:type="xsd:string">ListInput</name> <value xsi:type="soapenc:string">2</value> </parameters> <parameters xsi:type="ns1:JobParameter"> <name xsi:type="xsd:string">DateInput</name> <value xsi:type="xsd:dateTime">2007-10-09T09:00:00.000Z</value> </parameters> </parameters> <baseOutputFilename xsi:type="xsd:string">Sales3</baseOutputFilename> <outputFormats soapenc:arrayType="xsd:string[1]" xsi:type="soapenc:Array" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> <outputFormats xsi:type="xsd:string">PDF</outputFormats> </outputFormats> <outputLocale xsi:type="xsd:string" xsi:nil="true"/> <repositoryDestination xsi:type="ns1:JobRepositoryDestination"> <folderURI xsi:type="xsd:string">/ContentFiles</folderURI> <sequentialFilenames xsi:type="xsd:boolean">false</sequentialFilenames> <overwriteFiles xsi:type="xsd:boolean">false</overwriteFiles> </repositoryDestination> <mailNotification xsi:type="ns1:JobMailNotification" xsi:nil="true"/> </job> </ns1:scheduleJob> </soapenv:Body> </soapenv:Envelope> The response of the request contains the job details as saved by the server: <?xml version="1.0" encoding="utf-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <ns1:scheduleJobResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://www.jasperforge.org/jasperserver/ws"> <scheduleJobReturn xsi:type="ns1:job"> <id xsi:type="xsd:long">7</id> <version xsi:type="xsd:int">0</version> <reportUnitURI xsi:type="xsd:string">/reports/samples/SalesByMonth</reportUnitURI> <username xsi:type="xsd:string">tomcat</username> <label xsi:type="xsd:string">Label 3</label> <description xsi:type="xsd:string">Description 3</description> <simpleTrigger xsi:type="ns1:jobSimpleTrigger"> <id xsi:type="xsd:long">7</id> <version xsi:type="xsd:int">0</version> <timezone xsi:type="xsd:string">Europe/Minsk</timezone> <startDate xsi:type="xsd:dateTime">2008-1028

JasperServer Web Services Guide

09T09:25:00.000Z</startDate> <endDate xsi:type="xsd:dateTime" xsi:nil="true"/> <occurrenceCount xsi:type="xsd:int">1</occurrenceCount> <recurrenceInterval xsi:type="xsd:int" xsi:nil="true"/> <recurrenceIntervalUnit xsi:type="ns1:IntervalUnit" xsi:nil="true"/> </simpleTrigger> <calendarTrigger xsi:type="ns1:JobCalendarTrigger" xsi:nil="true"/> <parameters soapenc:arrayType="ns1:JobParameter[4]" xsi:type="soapenc:Array" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> <parameters xsi:type="ns1:jobParameter"> <name xsi:type="xsd:string">CheckboxInput</name> <value xsi:type="soapenc:boolean">true</value> </parameters> <parameters xsi:type="ns1:jobParameter"> <name xsi:type="xsd:string">TextInput</name> <value xsi:type="soapenc:int">22</value> </parameters> <parameters xsi:type="ns1:jobParameter"> <name xsi:type="xsd:string">DateInput</name> <value xsi:type="xsd:dateTime">2007-10-09T09:00:00.000Z</value> </parameters> <parameters xsi:type="ns1:jobParameter"> <name xsi:type="xsd:string">ListInput</name> <value xsi:type="soapenc:string">2</value> </parameters> </parameters> <baseOutputFilename xsi:type="xsd:string">Sales3</baseOutputFilename> <outputFormats soapenc:arrayType="xsd:string[1]" xsi:type="soapenc:Array" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> <outputFormats xsi:type="xsd:string">PDF</outputFormats> </outputFormats> <outputLocale xsi:type="xsd:string" xsi:nil="true"/> <repositoryDestination xsi:type="ns1:jobRepositoryDestination"> <id xsi:type="xsd:long">7</id> <version xsi:type="xsd:int">0</version> <folderURI xsi:type="xsd:string">/ContentFiles</folderURI> <sequentialFilenames xsi:type="xsd:boolean">false</sequentialFilenames> <overwriteFiles xsi:type="xsd:boolean">false</overwriteFiles> </repositoryDestination> <mailNotification xsi:type="ns1:JobMailNotification" xsi:nil="true"/> </scheduleJobReturn> </ns1:scheduleJobResponse> </soapenv:Body> </soapenv:Envelope>

3.2.3

Java Client Classes

The JasperServer web service client jars contain classes that can be used by Java clients to easily communicate with the report scheduling web service. XML types used by the report scheduling web service are mapped to Java bean classes found in the com.jaspersoft.jasperserver.ws.scheduling package (for example, Job, JobSimpleTrigger, and CalendarDaysType). Instances of these classes can be used as report job objects that are sent to or returned by the web service. The service itself is represented by Apache Axis-generated client stub classes. A facade (com.jaspersoft.jasperserver.ws.scheduling.ReportSchedulerFacade) has been developed on top of these classes. The facade can be instantiated by providing the information required to locate and connect to a web service (the endpoint URL and the username/password for authentication). JasperSoft recommends using the facade because it handles items such as the Axis client configuration and the messages locale header.

29

Appendix ARepository Service API Constants

The constants that the services require are defined in the following classes:

com.jaspersoft.jasperserver.api.metadata.xml.domain.impl.Argument com.jaspersoft.jasperserver.ws.xml.ResourceDescriptor

The following shows the constant names in quotation marks:

// resource wsTypes TYPE_FOLDER = "folder"; TYPE_REPORTUNIT = "reportUnit"; TYPE_DATASOURCE = "datasource"; TYPE_DATASOURCE_JDBC = "jdbc"; TYPE_DATASOURCE_JNDI = "jndi"; TYPE_DATASOURCE_BEAN = "bean"; TYPE_IMAGE = "img"; TYPE_FONT = "font"; TYPE_JRXML = "jrxml"; TYPE_CLASS_JAR = "jar"; TYPE_RESOURCE_BUNDLE = "prop"; TYPE_REFERENCE = "reference"; TYPE_INPUT_CONTROL = "inputControl"; TYPE_DATA_TYPE = "dataType"; TYPE_OLAP_MONDRIAN_CONNECTION = "olapMondrianCon"; TYPE_OLAP_XMLA_CONNECTION = "olapXmlaCon"; TYPE_MONDRIAN_SCHEMA = "olapMondrianSchema"; TYPE_XMLA_CONNTCTION = "xmlaConnection"; TYPE_UNKNOW = "unknow"; TYPE_LOV = "lov"; // List of values... TYPE_QUERY = "query"; // These constants are copied here from DataType for facility DT_TYPE_TEXT = 1; DT_TYPE_NUMBER = 2; DT_TYPE_DATE = 3; DT_TYPE_DATE_TIME = 4; // These constants are copied here from InputControl for facility IC_TYPE_BOOLEAN = 1; IC_TYPE_SINGLE_VALUE = 2; IC_TYPE_SINGLE_SELECT_LIST_OF_VALUES = 3; IC_TYPE_SINGLE_SELECT_QUERY = 4; IC_TYPE_MULTI_VALUE = 5; IC_TYPE_MULTI_SELECT_LIST_OF_VALUES = 6; IC_TYPE_MULTI_SELECT_QUERY = 7;

30

JasperServer Web Services Guide

IC_TYPE_SINGLE_SELECT_LIST_OF_VALUES_RADIO = 8; IC_TYPE_SINGLE_SELECT_QUERY_RADIO = 9; IC_TYPE_MULTI_SELECT_LIST_OF_VALUES_CHECKBOX = 10; IC_TYPE_MULTI_SELECT_QUERY_CHECKBOX = 11; PROP_VERSION = "PROP_VERSION"; PROP_PARENT_FOLDER = "PROP_PARENT_FOLDER"; PROP_RESOURCE_TYPE = "PROP_RESOURCE_TYPE"; PROP_CREATION_DATE = "PROP_CREATION_DATE"; // File resource properties PROP_FILERESOURCE_HAS_DATA = "PROP_HAS_DATA"; PROP_FILERESOURCE_IS_REFERENCE = "PROP_IS_REFERENCE"; PROP_FILERESOURCE_REFERENCE_URI = "PROP_REFERENCE_URI"; PROP_FILERESOURCE_WSTYPE = "PROP_WSTYPE"; // Datasource properties PROP_DATASOURCE_DRIVER_CLASS = "PROP_DATASOURCE_DRIVER_CLASS"; PROP_DATASOURCE_CONNECTION_URL = "PROP_DATASOURCE_CONNECTION_URL"; PROP_DATASOURCE_USERNAME = "PROP_DATASOURCE_USERNAME"; PROP_DATASOURCE_PASSWORD = "PROP_DATASOURCE_PASSWORD"; PROP_DATASOURCE_JNDI_NAME = "PROP_DATASOURCE_JNDI_NAME"; PROP_DATASOURCE_BEAN_NAME = "PROP_DATASOURCE_BEAN_NAME"; PROP_DATASOURCE_BEAN_METHOD = "PROP_DATASOURCE_BEAN_METHOD"; // ReportUnit resource properties PROP_RU_DATASOURCE_TYPE = "PROP_RU_DATASOURCE_TYPE"; PROP_RU_IS_MAIN_REPORT = "PROP_RU_IS_MAIN_REPORT"; PROP_RU_INPUTCONTROL_RENDERING_VIEW = "PROP_RU_INPUTCONTROL_RENDERING_VIEW"; PROP_RU_REPORT_RENDERING_VIEW = "PROP_RU_REPORT_RENDERING_VIEW"; // DataType resource properties PROP_DATATYPE_STRICT_MAX = "PROP_DATATYPE_STRICT_MAX"; PROP_DATATYPE_STRICT_MIN = "PROP_DATATYPE_STRICT_MIN"; PROP_DATATYPE_MIN_VALUE = "PROP_DATATYPE_MIN_VALUE"; PROP_DATATYPE_MAX_VALUE = "PROP_DATATYPE_MAX_VALUE"; PROP_DATATYPE_PATTERN = "PROP_DATATYPE_PATTERN"; PROP_DATATYPE_TYPE = "PROP_DATATYPE_TYPE"; // ListOfValues resource properties PROP_LOV = "PROP_LOV"; PROP_LOV_LABEL = "PROP_LOV_LABEL"; PROP_LOV_VALUE = "PROP_LOV_VALUE"; // InputControl resource properties PROP_INPUTCONTROL_TYPE = "PROP_INPUTCONTROL_TYPE"; PROP_INPUTCONTROL_IS_MANDATORY = "PROP_INPUTCONTROL_IS_MANDATORY"; PROP_INPUTCONTROL_IS_READONLY = "PROP_INPUTCONTROL_IS_READONLY";

31

// SQL resource properties PROP_QUERY = "PROP_QUERY"; PROP_QUERY_VISIBLE_COLUMNS = "PROP_QUERY_VISIBLE_COLUMNS"; PROP_QUERY_VISIBLE_COLUMN_NAME = "PROP_QUERY_VISIBLE_COLUMN_NAME"; PROP_QUERY_VALUE_COLUMN = "PROP_QUERY_VALUE_COLUMN"; PROP_QUERY_LANGUAGE = "PROP_QUERY_LANGUAGE"; // SQL resource properties (data) PROP_QUERY_DATA = "PROP_QUERY_DATA"; PROP_QUERY_DATA_ROW = "PROP_QUERY_DATA_ROW"; PROP_QUERY_DATA_ROW_COLUMN = "PROP_QUERY_DATA_ROW_COLUMN";

// Arguments MODIFY_REPORTUNIT = "MODIFY_REPORTUNIT_URI"; CREATE_REPORTUNIT = "CREATE_REPORTUNIT_BOOLEAN"; LIST_DATASOURCES = "LIST_DATASOURCES"; IC_GET_QUERY_DATA = "IC_GET_QUERY_DATA"; VALUE_TRUE = "true"; VALUE_FALSE = "false"; RUN_OUTPUT_FORMAT = "RUN_OUTPUT_FORMAT"; RUN_OUTPUT_FORMAT_PDF = "PDF"; RUN_OUTPUT_FORMAT_JRPRINT = "JRPRINT"; RUN_OUTPUT_FORMAT_HTML = "HTML"; RUN_OUTPUT_FORMAT_XLS = "XLS"; RUN_OUTPUT_FORMAT_XML = "XML"; RUN_OUTPUT_FORMAT_CSV = "CSV"; RUN_OUTPUT_FORMAT_RTF = "RTF"; RUN_OUTPUT_IMAGES_URI = "IMAGES_URI"; RUN_OUTPUT_PAGE = "PAGE";

32