Resource Descriptors

This chapter provides a reference by example for every type of resource descriptor that exists in the repository. Use the resources service to get and set resources with these descriptors. For further information, see:

• Working With Resources for general guidelines about using descriptors.
• The resources Service for methods to operate on resources in the repository.

This chapter does not cover descriptors for objects that are not stored in the repository. Descriptors that represent jobs, calendars, organizations, roles, users, and attributes are described with the service that operates on them.

This chapter includes the following sections:

• Common Attributes
• Folder
• JNDI Data Source
• JDBC Data Source
• AWS Data Source
• Virtual Data Source
• Custom Data Source
• Bean Data Source
• Datatypes
• List of Values
• Query
• Input Control
• File
• Report Unit (JRXML Report)
• Report Options
• Domain (semanticLayerDataSource)
• Domain Topic
• XML/A Connection
• Mondrian Connection
• Secure Mondrian Connection
• OLAP Unit
• Mondrian XML/A Definition
• Other Types

Common Attributes

All resource types contain the following attributes. Of these common attributes, only the label and description fields are writable.

In general, writable fields are ones that can be set by the client when sending a descriptor for a write or update operation (PUT or POST). The other fields are read-only fields that the server sets automatically.

application/repository.{resourceType}+json

application/repository.{resourceType}+xml 

{
    "uri" :"/sample/resource/uri", 
    "label":"Sample Label", 
    "description":"Sample Description", 
    "permissionMask":"0",
    "creationDate": "2013-07-04T12:18:47",
    "updateDate": "2013-07-04T12:18:47", 
    "version":"0"
    ... 
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<{resourceType}>
    <uri>/sample/resource/uri</uri>
    <label>Sample Label</label>
    <description>Sample Description
        </description>
    <permissionMask>0</permissionMask>
    <creationDate>2013-07-04T12:18:47
        </creationDate>
    <updateDate>2013-07-04T12:18:47
        </updateDate>
    <version>0</version>
    ...
</{resourceType}>

Only the label, description, and permission fields are writable. The other fields are generated by the server.

Throughout the rest of the resource type sections, the common attributes are included in every descriptor as <commonAttributes> in JSON or {commonAttributes} in XML.

Folder

Folder types do not contain any additional fields beyond the common attributes shown above.

application/repository.folder+json

application/repository.folder+xml 

{
    "uri" :"<resourceURI>", 
    "label":"Sample Label", 
    "description":"Sample Description", 
    "permissionMask":"0",
    "creationDate": "2013-07-04T12:18:47",
    "updateDate": "2013-07-04T12:18:47", 
    "version":"0" 
}

<folder>
    <uri>{resourceURI}</uri>
    <label>Sample Label</label>
    <description>Sample Description
      </description>
    <permissionMask>0</permissionMask>
    <creationDate>2013-07-04T12:18:47
      </creationDate>
    <updateDate>2013-07-04T12:18:47
       </updateDate>
    <version>0</version>
</folder>

Only the label and description fields are writable.

JNDI Data Source

application/repository.jndiJdbcDataSource+json

application/repository.jndiJdbcDataSource+xml 

{
    <commonAttributes>, 
    "jndiName":"<jndiName>",
    "timezone":"<timezone>"
}

<jndiDataSource>
    {commonAttributes}
    <jndiName>{jndiName}</jndiName>
    <timezone>{timezone}</timezone>
</jndiDataSource>

JDBC Data Source

application/repository.jdbcDataSource+json

application/repository.jdbcDataSource+xml 

{
    <commonAttributes>, 
    "driverClass":"<driverClass>", 
    "password":"<password>", 
    "username":"<username>", 
    "connectionUrl":"<connectionURL>",
    "timezone":"<timezone>"
}

<jdbcDataSource>
    {commonAttributes}
    <driverClass>{driverClass}</driverClass>
    <password>{password}</password>
    <username>{username}</username>
    <connectionUrl>
         {connectionURL}
    </connectionUrl>
    <timezone>{timezone}</timezone>
</jdbcDataSource>

AWS Data Source

application/repository.awsDataSource+json

application/repository.awsDataSource+xml 

{
    <commonAttributes>, 
    "driverClass":"<driverClass>", 
    "password":"<password>", 
    "username":"<username>", 
    "connectionUrl":"<connectionURL>",
    "timezone":"<timezone>",
    "accessKey":"<accessKey>", 
    "secretKey":"<secretKey>", 
    "roleArn":"<roleArn>", 
    "region":"<region>", 
    "dbName":"<dbName>", 
    "dbInstanceIdentifier":
        "<dbInstanceIdentifier>", 
    "dbService":"<dbService>"
}

<awsDataSource>
    {commonAttributes}
    <driverClass>{driverClass}</driverClass>
    <password>{password}</password>
    <username>{username}</username>
    <connectionUrl>
         {connectionURL}
    </connectionUrl>
    <timezone>{timezone}</timezone>
    <accessKey>{accessKey}</accessKey> 
    <secretKey>{secretKey}</secretKey> 
    <roleArn>{roleArn}</roleArn> 
    <region>{region}</region> 
    <dbName>{dbName}</dbName> 
    <dbInstanceIdentifier> 
        {dbInstanceIdentifier}
    </dbInstanceIdentifier> 
    <dbService>{dbService}</dbService>
</awsDataSource>

The {region} values are specified in the file .../WEB-INF/application-context.xml, with their corresponding display labels defined in .../WEB-INF/bundles/jasperserver_messages.properties. By default, the following regions are defined:

Values of AWS {region} in
.../WEB-INF/application-context.xml

Labels for AWS regions in
.../WEB-INF/bundles/jasperserver_messages.properties

us-east-1.amazonaws.com

US East (Northern Virginia) Region

us-west-2.amazonaws.com US West (Oregon) Region
us-west-1.amazonaws.com US West (Northern California) Region
eu-west-1.amazonaws.com EU (Ireland) Region
eu-central-1.amazonaws.com EU (Frankfurt) Region
ap-southeast-1.amazonaws.com Asia Pacific (Singapore) Region
ap-southeast-2.amazonaws.com Asia Pacific (Sydney) Region
ap-northeast-1.amazonaws.com Asia Pacific (Tokyo) Region
sa-east-1.amazonaws.com South America (São Paulo) Region

Virtual Data Source

The id of each subDataSource must be unique. The server does not prevent duplicates, and the last one to be defined silently overwrites the previous definition.

application/repository.virtualDataSource+json

application/repository.virtualDataSource+xml 

{
    <commonAttributes>, 
    "subDataSources":[ 
        { 
            "id":"<subDataSourceID>", 
            "uri":"<subDataSourceURI>" 
        }, 
        ...
    ] 
}

<virtualDataSource>
    {commonAttributes}
    <subDataSources>
        <subDataSource>
            <id>{subDataSourceID}</id>
            <uri>{subDataSourceURI}</uri>
        </subDataSource>
        ...
    </subDataSources>
</virtualDataSource>

Custom Data Source

The value of the serviceClass attribute is read-only and depends on the specific type of the custom data source, as defined in the server's applicationContext configuration files.

application/repository.customDataSource+json

application/repository.customDataSource+xml 

{
    <commonAttributes>, 
    "serviceClass":"<serviceClass>",   
    "dataSourceName":"<dataSourceName>", 
    "properties":[ 
        {
            "key":"<key>",
            "value":"<value>"
        }, 
        ...
    ] 
}

<customDataSource>
    {commonAttributes}
    <serviceClass>
        {serviceClass}
    </serviceClass>
    <dataSourceName>
        {dataSourceName}
    </dataSourceName>
    <properties>
        <property>
            <key>{key}</key>
            <value>{value}</value>
        </property>
        ...
    </properties>
</customDataSource>

Bean Data Source

application/repository.beanDataSource+json

application/repository.beanDataSource+xml 

{
    <commonAttributes>, 
    "beanName":"<beanName>", 
    "beanMethod":"<beanMethod>"
}

<beanDataSource>
    {commonAttributes}
    <beanName>{beanName}<beanName>
    <beanMethod>{beanMethod}</beanMethod>
</beanDataSource>

Datatypes

application/repository.dataType+json

application/repository.dataType+xml 

{
    <commonAttributes>, 
    "type":"text|number|date|dateTime|time", 
    "pattern":"<pattern>", 
    "maxValue":"<maxValue>", 
    "strictMax":"true|false", 
    "minValue":"<minValue>", 
    "strictMin":"true|false"   
    "maxLength":"<maxLengthInteger>"
}

<dataType>
    {commonAttributes}
    <type>text|number|date|dateTime|time</type>
    <pattern>{pattern}</pattern>
    <maxValue>{maxValue}</maxValue>
    <strictMax>true|false</strictMax>
    <minValue>{minValue}</minValue>
    <strictMin>true|false</strictMin>
    <maxLength>{maxLengthInteger}</maxLength>
</dataType>

List of Values

application/repository.listOfValues+json

application/repository.listOfValues+xml 

{
    <commonAttributes>, 
    "items":[
        {
            "label":"<label>",
            "value":"<value>"
        },
        ...
    ]
}

<listOfValues>
    {commonAttributes}
    <items>
        <item>
            <label>{label}</label>
            <value>{value}</value>
        </item>
        ...
    </items>
</listOfValues>

Query

The dataSource field of the query may be null. Set an empty dataSource field when you want to remove a local data source, either a reference or a local definition. When the data source of a query is not defined, the query uses the data source of its parent, for example its JRXML report (reportUnit).

application/repository.query+json

application/repository.query+xml 

{
    <commonAttributes>, 
    "value":"<query>", 
    "language":"<language>",
    "dataSource":{
        "dataSourceReference": {
            "uri":"<dataSourceURI>"
        }
    } 
}

<query>
    {commonAttributes}
    <value>{query}</value> 
    <language>{language}</language>
    <dataSourceReference>
        <uri>{dataSourceURI}</uri>
    </dataSourceReference>
</query>

Input Control

Input controls come in several types that require different fields. The following table shows all possible fields, not all of which are mutually compatible.

application/repository.inputControl+json

application/repository.inputControl+xml 

{
    <commonAttributes>, 
    "mandatory":"true|false",  
    "readOnly":"true|false",  
    "visible":"true|false",  
    "type":"<inputControlTypeByteValue>",
    "usedFields":"<field1;field2;...>",
    "dataType": {
        "dataTypeReference": {
            "uri": "<dataTypeResourceURI>"
        }
    },  
    "listOfValues": {
        "listOfValuesReference": {
            "uri": "<listOfValuesResourceURI>"
        }
    }  
    "visibleColumns":["column1", "colum2", ...],  
    "valueColumn":"<valueColumn>",  
    "query": {
        "queryReference": {
            "uri": "<queryResourceURI>"
        }
    }
}

<inputControl>
    {commonAttributes}
    <mandatory>true|false</mandatory>
    <readOnly>true|false</readOnly>
    <visible>true|false</visible>
    <type>{inputControlTypeByteValue}</type>
    <usedFields>{field1;field2;...}</usedFields>
    <dataTypeReference>
        <uri>{dataTypeResourceURI}</uri>
    </dataTypeReference>
    <listOfValuesReference>
        <uri>{listOfValuesResourceURI}</uri>
    </listOfValuesReference>
    <queryReference>
        <uri>{queryResourceURI}</uri>
    </queryReference>
    <visibleColumns>
        <column>{column1}</column>
        <column>{column2}</column>
        <column>...</column>
    </visibleColumns>
    <valueColumn>{valueColumn}</valueColumn>
</inputControl>

The following list shows the numerical code and meaning for {inputControlTypeByteValue}. The input control type determines the other fields that are required. The list of required fields may appear in a field named usedFields, separated by semi-colons (;).

Type

Type of Input Control

Other Fields Required (usedFields)

1

Boolean

None

2

Single value

dataType

3

Single-select list of values

listOfValues

4

Single-select query

query; queryValueColumn

5

Not used

 

6

Multi-select list of values

listOfValues

7

Multi-select query

query; queryValueColumn

8

Single-select list of values radio buttons

listOfValues

9

Single-select query radio buttons

query; queryValueColumn

10

Multi-select list of values check boxes

listOfValues

11

Multi-select query check boxes

query; queryValueColumn

File

The repository.file+<format> descriptor is used to identify the file type.

application/repository.file+json

application/repository.file+xml 

{
    <commonAttributes>, 
    "type":"pdf|html|rtf|csv|odt|txt
            |docx|ods|xlsx|img|font|jrxml
            |jar|prop|jrtx|xml|css
            |olapMondrianSchema
            |accessGrantSchema
            |unspecified",
    "content":"<base64EncodedContent>"
}

<file>
    {commonAttributes}
    <type>pdf|html|rtf|csv|odt|txt
        |docx|ods|xlsx|img|font|jrxml
        |jar|prop|jrtx|xml|css
        |olapMondrianSchema
        |accessGrantSchema|unspecified
    </type>
    <content>{base64EncodedContent}</content>
</file>

The content field is write-only: it is absent when requesting the file resource descriptor and used only when uploading a file resource as base-64 encoded content. For other ways to upload file contents, see Uploading File Resources. To download file contents, see Downloading File Resources.

Report Unit (JRXML Report)

A report unit contains mostly references to the files that make up a report within the server. A report unit is a composite resource that may contain other local resources (see Nested Resources). In this case, the URIs that it references include a URI in the following format:

<reportUnitURI>_files/<localResourceID>

For example, the main JRXML of a sample report is referenced as follows:

/reports/samples/Cascading_multi_select_report_files/Cascading_multi_select_report

The default value for the controlsLayout is popupScreen. The reportRenderingView and the inputControlRenderingView can be left as empty strings (""), while the query can be null.

application/repository.reportUnit+json

application/repository.reportUnit+xml 

{
    <commonAttributes>, 
    "controlsLayout":"<popupScreen|separatePage
          |topOfPage|inPage>",
 
<reportUnit>
    {commonAttributes}
    <controlsLayout>popupScreen|separatePage
        |topOfPage|inPage</controlsLayout>
 
    "alwaysPromptControls":"true|false",
    "inputControlRenderingView":
        "<inputControlRenderingView>",    
    "reportRenderingView":
        "<reportRenderingView>",
    "dataSource":{
        "dataSourceReference": {
            "uri":"<dataSourceURI>"
        }
    },
    "query:" {
        "queryReference": {
            uri: "<queryResourceURI>"
        }
    },  
    "jrxml": {
        "jrxmlFileReference": {
            "uri": "<jrxmlFileResourceURI>"
        } or
        "jrxmlFile": {
            "type": "jrxml",
            "label": "Main jrxml",
            "content": "<base64Encoded>
        }
    },
    "inputControls": [
        {
            "inputControlReference": {
                "uri": "<inputControlURI>"
            }   
        },
        ...
    ],
    "resources": {
        "resource": [{
            "name": "<resourceName>",
            "fileReference": {
                "uri": "<fileResourceURI>"
            }
        }], 
        "resource": [{
            "name": "Logo",
            "file": {
                "fileResource": {
                    "type": "img",
                    "label": "Logo.png",
                    "content":"<base64Encoded>"
                }
            }
        }]
        ...
    }
}
 
    <alwaysPromptControls>true|false
        </alwaysPromptControls>
    <inputControlRenderingView>
        {inputControlRenderingView}
    </inputControlRenderingView>
    <reportRenderingView>
        {reportRenderingView}
    </reportRenderingView>
    <dataSource>
        <dataSourceReference>
            <uri>{dataSourceURI}</uri>
        </dataSourceReference>
    </dataSource>
    <query>
        <queryReference>
            <uri>{queryResourceURI}</uri>
        </queryReference>
    </query>
    <jrxml>  
        <jrxmlFileReference>
            <uri>{jrxmlFileResourceURI}</uri>
        </jrxmlFileReference>
        or <jrxmlFile>
               <type>jrxml</type>
               <label>Main report</label>
               <content>{base64Encoded}
               </content>
           </jrxmlFile>
    </jrxml>
    <inputControls>
        <inputControlReference>
            <uri>{inputControlURI}</uri>
        </inputControlReference>
        ...
    </inputControls>
    <resources>
        <resource>
            <name>{resourceName}</name>
            <fileReference>
                <uri>{fileResourceURI}</uri>
            </fileReference>
        </resource>
        <resource>
            <name>Logo</name>
            <file>
                <type>img</type>
                <label>Logo.png</label>
                <content>{base64Encoded}
                </content>
            </file>
        </resource>
        ...
    </resources>    
</reportUnit>

Report Options

application/repository.reportOptions+json

application/repository.reportOptions+xml 

{
    <commonAttributes>, 
    "reportUri":"<reportURI>",   
    "reportParameters":[  
        { 
            "name":"<parameterName>", 
            "value":[ 
                "value_1", 
                "value_2", 
                ...
            ] 
        },  
        ...    
    ]  
}

<reportOptions>
    {commonAttributes}
    <reportUri>{reportURI}</reportUri>
    <reportParameters>
        <reportParameter>
            <name>{parameterName}</name>
            <value>value_1</value>
            <value>value_2</value>
            ...
        </reportParameter>
        ...
    </reportParameters>
</reportOptions>

Domain (semanticLayerDataSource)

For more information about accessing the schema of a Domain, see Working With Domains.

When the locale property is left empty, the default locale bundle is used.

application/repository.semanticLayerDataSource+json

application/repository.semanticLayerDataSource+xml 

{
    <commonAttributes>, 
    "dataSource":{
        "dataSourceReference": {
            "uri":"<dataSourceURI>"
    }   },
    "schema": {
        "schemaFileReference": {
            "uri": "<schemaFileURI>"
    }   }, 
    "bundles": [{
        "locale": "<localeString>",
        "file": {
            "fileReference": {"uri":
                "<propertiesFileURI>"
        }   }   }, 
        ...
    ], 
    "securityFile": {
        "securityFileReference": {
            "uri": "<securityFileURI>"
}   }   }
 
<semanticLayerDataSource>
    {commonAttributes}
    <dataSourceReference>
        <uri>{dataSourceURI}</uri>
    </dataSourceReference>
    <schemaFileReference>
        <uri>{schemaFileURI}</uri>
    </schemaFileReference>
    <bundles>
        <bundle>
            <locale>{localeString}</locale>
            <fileReference>
    <uri>{propertiesFileURI}</uri>
            </fileReference>
        </bundle> 
        ...
    </bundles> 
    <securityFileReference>
        <uri>{securityFileURI}</uri>
    </securityFileReference>
</semanticLayerDataSource>

Domain Topic

A Domain Topic is a Topic created by selecting database fields from a Domain. It is structurally equivalent to a JRXML report, and thus it has the same type attributes (see Report Unit (JRXML Report)). The only difference is that the data source field will reference a Domain (semanticLayerDataSource).

application/repository.domainTopic+json

application/repository.domainTopic+xml

Same attributes as
application/repository.reportUnit+json

Same attributes as
application/repository.reportUnit+xml

XML/A Connection

application/repository.xmlaConnection+json

application/repository.xmlaConnection+xml 

{
    <commonAttributes>, 
    "url":"<xmlaServiceURL>", 
    "xmlaDataSource":"<xmlaDataSource>", 
    "catalog":"<catalog>", 
    "username":"<username>", 
    "password":"<password>"
}

<xmlaConnection>
    {commonAttributes}
    <url>{xmlaServiceURL}</url>
    <xmlaDataSource>
        {xmlaDataSource}
    </xmlaDataSource>
    <catalog>{catalog}</catalog>
    <username>{username}</username>
    <password>{password}</password>
</xmlaConnection>

Mondrian Connection

Mondrian connections without the access grant schemas are used in the Community edition of JasperReports Server.

application/repository.mondrianConnection+json

application/repository.mondrianConnection+xml 

{
    <commonAttributes>, 
    "dataSource":{
        "dataSourceReference": {
            "uri":"<dataSourceURI>"
        }
    },
    "schema": {
        "schemaReference": {
            "uri": "<schemaFileResourceURI>"
        }
    }
}
 
<mondrianConnection>
    {commonAttributes}
    <dataSourceReference>
        <uri>{dataSourceURI}</uri>
    </dataSourceReference>
    <schemaReference>
        <uri>{schemaFileResourceURI}</uri>
    </schemaReference>
</mondrianConnection>

Secure Mondrian Connection

Secure Mondrian connections are available only in commercial releases of JasperReports Server.

application/repository.secureMondrianConnection+json

application/repository.secureMondrianConnection+xml 

{
    <commonAttributes>, 
    "dataSource":{
        "dataSourceReference": {
            "uri":"<dataSourceURI>"
        }
    }, 
    "schema": {
        "schemaReference": {
            "uri": "<schemaFileResourceURI>"
        }
    }, 
    "accessGrantSchemas": [
        {
            "accessGrantSchemaReference": {
                "uri": "<accessGrantSchemaFileResourceURI>"
            }
        },
        ...
    ]
}

<secureMondrianConnection>
    {commonAttributes}
    <dataSourceReference>
        <uri>{dataSourceURI}</uri>
    </dataSourceReference>
    <schemaReference>
        <uri>{schemaFileResourceURI}</uri>
    </schemaReference>
    <accessGrantSchemas>
        <accessGrantSchemaReference>
            <uri>{accessGrantSchemaFileResourceURI}</uri>
        </accessGrantSchemaReference>
    </accessGrantSchemas>
</secureMondrianConnection>

OLAP Unit

application/repository.olapUnit+json

application/repository.olapUnit+xml 

{
    <commonAttributes>, 
    "mdxQuery":"<mdxQuery>", 
    "olapConnection": { 
        "olapConnectionReference": {         
            "uri": "<olapConnectionReferenceURI>"      
        }  
    } 
}
 
<olapUnit>
    {commonAttributes}
    <mdxQuery>{mdxQuery}</mdxQuery>  
    <olapConnectionReference>
      <uri>{olapConnectionReferenceURI}</uri>
    </olapConnectionReference> 
</olapUnit>

Mondrian XML/A Definition

application/repository.mondrianXmlaDefinition+json

application/repository.mondrianXmlaDefinition+xml 

{
    <commonAttributes>, 
    "catalog":"<catalog>", 
    "mondrianConnection": {
        "mondrianConnectionReference": {
            "uri": "<mondrianConnectionResourceURI>"
        }
    } 
}
 
<mondrianXmlaDefinition>
    {commonAttributes}
    <catalog>{catalog}</catalog>
    <mondrianConnectionReference>
        <uri>{mondrianConnectionResourceURI}</uri>
    </mondrianConnectionReference>
</mondrianXmlaDefinition>

Other Types

The following types are defined in commercial editions of the server and appear in the repository. However, they are meant only to describe the corresponding resources as read-only objects in the repository. The REST API does not support services for clients to create or modify these types.

The types in the following table contain only the common attributes described in Common Attributes.

Type String

Description

application/repository.dashboard+json
application/repository.dashboard+xml

The dashboard resource descriptors are deprecated and subject to change.

application/repository.adhocDataView+json
application/repository.adhocDataView+xml

The Ad Hoc view type is not fully defined yet and subject to change. Ad Hoc views may be referenced as data sources in other repository types, in which case they are called advDataSource.