Jump to content
JasperReports Library 7.0 is now available ×
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.


    This section describes functionality that can be restricted by the software license for JasperReports Server. If you don’t see some of the options described in this section, your license may prohibit you from using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

    This chapter explains the limited interaction with Domains that is available through the REST API. The metadata service retrieves the display layer of a Domain containing sets and items and their labels. You can also retrieve the full Domain schema and security files through the resources service, but the API provides no functionality to parse these.

    This chapter includes the following sections:

    The metadata Service
    Fetching a Domain Schema
    Fetching Domain Bundles and Security Files

    The metadata Service

    The rest_v2/domains/metadata service gives access to the sets and items exposed by a Domain for use in Ad Hoc reports. Items are database fields exposed by the Domain, after all joins, filters, and calculated fields have been applied to the database tables selected in the Domain. Sets are groups of items, arranged by the Domain creator for use by report creators.


    A limitation of the metadata service only allows it to operate on Domains with a single data island. A data island is a group of fields that are all related by joins between the database tables in the Domain. Fields that belong to tables that are not joined in the Domain belong to separate data islands.

    If your Domain contains localization bundles you can specify a locale and an optional alternate locale and preference (called q-value, a decimal between 0 and 1).






    Accept-Language: <locale>[, <alt-locale>;q=0.8]

    Accept: application/xml (default)

    Accept: application/json

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The body is XML containing the list of resourceDescriptors.

    404 Not Found – The specified Domain URI is not found in the repository. This service also returns an XML errorDescriptor giving a human-readable error message.

    The response of the metadata service is an XML or JSON structure that describes the sets and items available in the selected Domain. This metadata includes the localized labels for the sets and items, as well as the datatypes of the items. The resourceId of the sets and items are internal to the Domain and not meaningful or otherwise useable.

    For more information about Domains, refer to the JasperReports Server User Guide.

    The following example shows the JSON response for a Domain with:

    A set named expense containing:
         An item named Exp Date of type Date
         An item named Amount of type BigDecimal
    A set named store containing:
         An item named Store Type of type String

    The following example shows the same Domain as returned by the metadata service in XML format:


    Fetching a Domain Schema

    The metadata service returns only the display information about a Domain, not its internal definition. The fields, joins, filters, and calculated fields that define the internal structure of a Domain make up the Domain design. The XML representation of a Domain design is called the Domain schema.

    Currently, there is no REST service to interact with Domain schemas, but you can use the resources service to retrieve the raw schema. First, retrieve the resource descriptor for the Domain. For example, to view the descriptor for the Supermart Domain, use the following request (when logged in as jasperadmin):

    GET http://<host>:<port>/jasperserver-pro/rest_v2/resources/Domains/supermartDomain

    This descriptor contains the Domain schema as an internal resource:

    Use the following request to access the Domain schema file inside the Domain resource:

    GET http://<host>:<port>/jasperserver-pro/rest_v2/resources/Domains/supermartDomain_files/supermartDomain_schema

    The Domain schema is an XML file with a structure explained in the JasperReports Server User Guide. If you wish to modify the schema programmatically, you must write your own parser to access its fields and definitions. You can then replace the schema file in the Domain with one of the file updating methods described in Uploading File Resources.

    Fetching Domain Bundles and Security Files

    Once you have the descriptor of a Domain resource as shown in the previous section, you can access the other files that help define a Domain. For example, you can access the language bundles of the Supermart Domain with the following request:

    GET http://<host>:<port>/jasperserver-pro/rest_v2/resources/Domains/supermartDomain_files/supermart_domain_<locale>.properties

    Language bundles are Java properties files that follow the language bundle naming convention, and that contain the names of the sets and fields in the language of the locale in the filename.

    You can also retrieve the localized set and item names by specifying Accept-Language when using the metadata service. However, by accessing the language bundles through the Domain descriptor, you read the default bundle to see the pattern of keys and values, and then create a bundle for a new locale.

    Domains may also contain a security file that is also stored as an internal resource of the Domain descriptor. Use the following example to request the security file of the Supermart Domain in the sample data:

    GET http://<host>:<port>/jasperserver-pro/rest_v2/resources/Domains/supermartDomain_files/supermart_domain_security

    A security file defines a complex set of access permissions to the data in the rows and columns returned by the Domain, based on the username, roles, or profile attributes of the user running a Domain-based report. As with the Domain schema file, you must write your own parser to interpret this file and modify it.

    You can then upload an updated language bundle or security file for the Domain with one of the methods described in Uploading File Resources.

    For more information about language bundles and security files in Domains, see the JasperReports Server User Guide.

    User Feedback

    Recommended Comments

    There are no comments to display.

    This is now closed for further comments

  • Create New...