TIBCO JASPERREPORTS® SERVER WEB SERVICES GUIDE RELEASE 6.1 http://www.jaspersoft.com Copyright ©2005-2015, TIBCO Software Inc. All rights reserved. Printed in the U.S.A. TIBCO, the TIBCO logo, TIBCO Jaspersoft, the TIBCO Jaspersoft logo, TIBCO Jaspersoft iReport Designer, TIBCO JasperReports Library, TIBCO JasperReports Server, TIBCO Jaspersoft OLAP, TIBCO Jaspersoft Studio, and TIBCO Jaspersoft ETL are trademarks and/or registered trademarks of TIBCO Software Inc. 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. This is version 0515-JSP61-24 of the JasperReports Server Web Services Guide. TABLE OF CONTENTS Chapter 1 Introduction to Web Services 9 1.1 REST Web Services Overview 10 1.2 REST Authentication 13 1.2.1 Login Encryption 13 1.2.2 Login Service 14 1.2.3 Security Check 16 1.2.4 Using an SSO Token 17 1.2.5 Using a Pre-Authentication Token 17 1.2.6 Logout 18 1.3 REST Server Information 19 1.4 SOAP Web Services Overview 20 1.5 SOAP Authentication 21 1.6 Syntax of resourceDescriptor 21 1.6.1 Overview 22 1.6.2 wsType Attribute 22 1.6.3 isNew Attribute 24 1.6.4 Resource Descriptor Parameters 24 1.6.5 Examples of resourceDescriptor 24 Chapter 2 REST v2 - Repository Services 27 2.1 The v2/resources Service 27 2.1.1 V2 Resource Descriptors 27 2.1.2 V2 Resource Descriptor Types 32 2.1.3 Searching the Repository 44 2.1.4 Paginating Search Results 45 2.1.5 Viewing Resource Details 49 2.1.6 Downloading File Resources 49 2.1.7 Creating a Resource 50 2.1.8 Modifying a Resource 52 2.1.9 Copying a Resource 54 2.1.10 Moving a Resource 54 2.1.11 Uploading File Resources 55 2.1.12 Updating File Resources 57 TIBCO Software Inc. 3 JasperReports Server Web Services Guide 2.1.13 Deleting Resources 58 2.2 The v2/domains/metadata Service 59 2.2.1 Working with Domain Schemas 63 2.2.2 Accessing Domain Bundles and Security Files 64 2.3 The v2/permissions Service 65 2.3.1 Viewing Multiple Permissions 65 2.3.2 Viewing a Single Permission 67 2.3.3 Setting Multiple Permissions 67 2.3.4 Setting a Single Permission 69 2.3.5 Deleting Permissions in Bulk 70 2.3.6 Deleting a Single Permission 70 2.4 The v2/export Service 70 2.4.1 Checking the Export State 72 2.4.2 Fetching the Export Output 72 2.5 The v2/import Service 72 Chapter 3 REST v2 - Report Services 75 3.1 The v2/reports Service 75 3.1.1 Running a Report 75 3.1.2 Finding Running Reports 77 3.1.3 Terminate Running Report 77 3.2 The v2/reportExecutions Service 78 3.2.1 Running a Report Asynchronously 78 3.2.2 Polling Report Execution 81 3.2.3 Requesting Report Execution Details 82 3.2.4 Requesting Report Output 83 3.2.5 Exporting a Report Asynchronously 85 3.2.6 Modifying Report Parameters 85 3.2.7 Polling Export Execution 86 3.2.8 Finding Running Reports and Jobs 87 3.2.9 Stopping Running Reports and Jobs 89 3.3 The v2/inputControls Service 89 3.3.1 Listing Input Control Structure 89 3.3.2 Listing Input Control Values 91 3.3.3 Setting Input Control Values 92 3.4 The v2/options Service 93 3.4.1 Listing Report Options 93 3.4.2 Creating Report Options 94 3.4.3 Updating Report Options 95 3.4.4 Deleting Report Options 95 3.5 The v2/jobs Service 96 3.5.1 Listing Report Jobs 96 3.5.2 Viewing a Job Definition 97 3.5.3 Extended Job Search 99 3.5.4 Scheduling a Report 101 3.5.5 Viewing Job Status 101 4 TIBCO Software Inc. 3.5.6 Editing a Job Definition 101 3.5.7 Updating Jobs in Bulk 102 3.5.8 Pausing Jobs 102 3.5.9 Resuming Jobs 103 3.5.10 Restarting Failed Jobs 104 3.5.11 Deleting Jobs 104 3.5.12 Specifying FTP Output 105 3.5.13 Specifying File System Output 106 3.5.14 Calendar Exclusion for the Scheduler 106 3.6 The v2/queryExecutor Service 111 3.7 The v2/caches Service 113 Chapter 4 REST v2 - Administration Services 115 4.1 The v2/organizations Service 115 4.1.1 Searching for Organizations 115 4.1.2 Viewing an Organization 117 4.1.3 Creating an Organization 117 4.1.4 Modifying Organization Properties 119 4.1.5 Setting the Theme of an Organization 119 4.1.6 Deleting an Organization 120 4.2 The v2/users Service 120 4.2.1 Searching for Users 120 4.2.2 Viewing a User 122 4.2.3 Creating a User 123 4.2.4 Modifying User Properties 124 4.2.5 Deleting a User 125 4.3 The v2/attributes Service 126 4.3.1 Secure Attributes 126 4.3.2 Entities with Attributes 127 4.3.3 Permissions for Accessing Attributes 128 4.3.4 Referencing Attributes 128 4.3.5 Attribute Limitations 128 4.3.6 Viewing Attributes 129 4.3.7 Setting Attributes 130 4.3.8 Deleting Attributes 132 4.4 The v2/roles Service 133 4.4.1 Searching for Roles 133 4.4.2 Viewing a Role 135 4.4.3 Creating a Role 136 4.4.4 Modifying a Role 137 4.4.5 Setting Role Membership 137 4.4.6 Deleting a Role 137 Chapter 5 REST v1 - Repository Services 139 5.1 The resources Service 139 5.2 The resource Service 141 5.2.1 Requesting the Contents of a JasperReport 143 TIBCO Software Inc. 5 JasperReports Server Web Services Guide 5.2.2 Requesting the Contents of a File Resource 146 5.2.3 Requesting the Values of a Query-Based Input Control 146 5.2.4 Creating a Resource 148 5.2.5 Setting the Temporary Upload Directory 150 5.2.6 Modifying a Resource 150 5.2.7 Copying or Moving a Resource 151 5.2.8 Deleting a Resource 151 5.3 Working with Dashboards 152 5.4 Working with Virtual Data Sources 155 5.5 Working with Domains 156 5.6 The permission Service 158 5.6.1 Viewing Permissions 158 5.6.2 Setting Permissions 160 Chapter 6 REST v1 - Report Services 163 6.1 The report Service 163 6.1.1 Running a Report 163 6.1.2 Downloading Report Output 165 6.1.3 Regenerating Report Output 166 6.2 The jobsummary Service 166 6.3 The job Service 167 6.3.1 Viewing a Job Definition 167 6.3.2 Scheduling a Report 168 6.3.3 Editing a Job Definition 170 6.3.4 Deleting a Job Definition 170 Chapter 7 REST v1 - Administration Services 171 7.1 The organization Service 171 7.1.1 Viewing an Organization 171 7.1.2 Creating an Organization 172 7.1.3 Modifying Organization Properties 173 7.1.4 Deleting an Organization 173 7.2 The user Service 174 7.2.1 Creating a User 175 7.2.2 Editing a User 176 7.2.3 Deleting a User 176 7.3 The attribute Service 176 7.4 The role Service 177 7.4.1 Creating a New Role 178 7.4.2 Editing a Role 179 7.4.3 Deleting a Role 179 Chapter 8 SOAP - Repository Web Service 181 8.1 Request and Operation Result 181 8.2 List Operation 183 8.3 Get Operation 185 8.4 Put Operation 190 6 TIBCO Software Inc. 8.5 Delete Operation 191 8.6 Move Operation 192 8.7 Copy Operation 192 8.8 runReport Operation 193 8.8.1 Report Output 194 8.8.2 Report Locales 195 8.9 Errors 195 8.10 Implementation Suggestions 196 Chapter 9 SOAP - Report Scheduling Web Service 199 9.1 Types Defined in the WSDL 199 9.2 Operations in the Scheduling Service 202 9.2.1 Operation Descriptions 202 9.2.2 Example Request and Operation Result 203 9.3 Java Client Classes 205 Chapter 10 SOAP - Domain Web Service 207 10.1 Types Defined in the WSDL 207 10.2 Operations in the Domain Service 208 10.2.1 The getDomainMetaData Operation 208 10.2.2 The executeDomainQuery Operation 211 10.2.3 Java Client Classes 213 Chapter 11 SOAP - Web Services for Administration 215 11.1 Types Defined in the WSDL 216 11.2 Users and Roles 218 11.2.1 findUsers 218 11.2.2 putUser 219 11.2.3 deleteUser 220 11.2.4 findRoles 220 11.2.5 putRole 221 11.2.6 updateRoleName 221 11.2.7 deleteRole 222 11.3 Organizations/Tenants 222 11.3.1 getTenant 222 11.3.2 getSubTenantList 223 11.3.3 putTenant 223 11.3.4 deleteTenant 224 11.4 Permissions 224 11.4.1 getPermissionsForObject 224 11.4.2 putPermission 224 11.4.3 deletePermission 225 11.5 Related Files 226 Appendix A ResourceDescriptor API Constants 227 TIBCO Software Inc. 7 JasperReports Server Web Services Guide 8 TIBCO Software Inc. CHAPTER 1 INTRODUCTION TO WEB SERVICES JasperReports Server is a component of both a community project and commercial offerings. Each integrates the standard features such as security, scheduling, a web services interface, and much more for running and sharing reports.