Attributes are name-value pairs that are associated with users, organizations, or the server. Unlike roles, attributes are not predefined, and thus any attribute name can be assigned any value at any time. When running dashboards, views, or reports, certain advanced features of the server will reference attribute values of the currently logged-in user (or of the organization of the currently logged-in user), so that behavior is customized for that user.

For example, Domain security files and OLAP access grants may reference attributes in addition to roles to grant certain permissions. Attributes may also be referenced when defining the fields of a data source, thereby making database access customized for each user or organization. Finally, application developers may use the attributes service in order access or store information that can enhance their embedded BI solutions.

The rest_v2/attributes service provides methods for reading, writing, and deleting attributes at the server, organization, or user level. Only administrative users may access the attributes service. System admins (superuser) can set attributes anywhere in the server, and organization admins (jasperadmin) can set attributes within their own organization or any sub-organizations. Because of the nature of attributes, organization admins may see attributes from parent organizations and override them if allowed to do so by the parent administrator.

Attributes used to be called profile attributes because they were associated only with users. As of JasperReports Server 6.0, the attributes service applies to users, organization, and the root organization representing the server.

This chapter includes the following sections:

Attribute Descriptors

Attributes are represented as a pair of string fields, one for the name of the attribute, the other for its value. For example, the following JSON structure defines an attribute:

{    "name": "Attr1",    "value": "Value1"}[/code]                    

Each attribute may only have one value, however that value may contain a comma-separated list that, in certain uses, is interpreted by the server as being multi-valued. Such attributes can be used in Domain security filters that match against a collection of values.

{    "name": "Attr2",    "value": "Value2a,Value2b,Value2c"}[/code]                    

Attributes with the same name may be defined on different entities. For example, a user has a specific value for an attribute, the organization he belongs to has a default value for the same attribute, and the server level has yet another value for it. In this example, three separate attributes are defined, but they have the same name because they occur on different entities. The mechanisms described in Referencing Attributes can take advantage of this to implement default values.

Secure Attributes

JasperReports Server 6.0 also introduces the notion of secure attribute that can be used to store sensitive information such as a password. Secure attributes have the following properties:

When reading the value of a secure attribute, the server returns the field "secure": "true" instead of the "value" field. Applications that read attributes must test for this case:

{    "name": "Attr3",    "secure": "true"}[/code]                    

When setting the value of a secure attribute, your application should specify both the secure field and the value field.

{    "name": "Attr3"    "value": "SecureValue3"    "secure": "true"}[/code]                    

Applications that set secure attributes should consider enabling HTTPS so that the clear-text value of the attribute is encrypted in all communication with the server.

Entities with Attributes

The entities that may have attributes are user accounts, organizations, and the server itself, represented by the root organization. The entity is specified in the URL invoking the attributes service. The URL has the following form:

http://<host>:<port>/jasperserver[-pro]/rest_v2/<entity>attributes<parameters>

The syntax of <entity> depends on the target entity for the operation and the type of server.

Permissions for Accessing Attributes

Only API calls that include administrator credentials may view, set, or delete attributes on users, organizations, or the server. Non-administrative users can't view or edit attributes, even on their own user account.

In commercial editions of the server, operations on attributes follow the visibility rules for organizations:

Referencing Attributes

As mentioned, several internal mechanisms of the server read attributes on users and organizations and make use of their values in some way:

The server provides two different methods to reference attributes:

The methods you use to reference attributes will then determine the entities where you need to create attributes and the values of those attributes.

Attribute Limitations

Attributes have the following limitations in the attributes service:

The attributes service detects these conditions and returns errors accordingly:

Some methods of the attributes service operate on multiple attributes on a given entity. Such batch operations are not transactional, meaning the operation terminates with no rollback functionality when encountering an error. Attributes that have been processed (modified or deleted) before the error remain so, and attributes after the error are not processed.

All attribute operations apply to a single specific entity; there are no operations for reading or setting attributes on multiple entities.

Viewing Attributes

The GET method of the attributes service retrieves the list of attributes, if any, defined for the specified entity (a user, an organization, or the server-level). For possible values of <entity> in the URL, see Entities with Attributes.

There are two syntaxes; the following one is for reading multiple attributes or all attributes at once.

The list of attributes includes the name and value of each attribute. The following example shows user-level attributes in JSON format:

GET http://localhost:8080/jasperserver-pro/rest_v2/organizations/organzation_1/users/joeuser/attributes

The second syntax reads a single attribute by specifying its name in the URL:

The response is a single attribute name-value pair. The following example shows an organization-level attribute in JSON format:

GET http://localhost:8080/jasperserver-pro/rest_v2/organizations/organization_1/attributes/Attr2

Setting Attributes

The PUT method of the attributes service adds or replaces attributes on the specified entity (a user, an organization, or the server-level). For possible values of <entity> in the URL, see Entities with Attributes.

There are two syntaxes; the following one is for adding or replacing all attributes at once.

The following example shows how to set all attributes on an organization. The list of attributes in JSON format defines the name and value of each attribute.

PUT http://localhost:8080/jasperserver-pro/rest_v2/organizations/organization_1/attributes

{  "attribute":[    {      "name": "Attr1",      "value":"newValue1"    },    {      "name": "Attr2",      "value":"newValue2a, newValue2b"    },    {      "name": "Attr3"      "value": "SecureValue3"      "secure": "true"    }  ]}[/code]                    

The second syntax of the PUT attributes method is for adding or replacing individual attributes.

The content in the request is a single attribute, for example:

PUT http://localhost:8080/jasperserver-pro/rest_v2/organizations/organization_1/users/

joeuser/attributes/Attr2

{  "name": "Attr2",  "value":"NewValue2"}[/code]                    

Deleting Attributes

The DELETE method of the attributes service removes attributes from the specified entity (a user, an organization, or the server-level). When attributes are removed, both the name and the value of the attribute are removed, not only the value. For possible values of <entity> in the URL, see Entities with Attributes.

There are two syntaxes; the following one is for deleting multiple attributes or all attributes at once.

The second syntax deletes a single attribute named in the URL from the specified entity.