Attributes are name-value pairs that are associated with users, organizations, and the server itself. Attribute values can be used to parameterize access to data sources, Domain data, OLAP data, and report output. Attributes were previously known as profile attributes.

For example, when defining a data source, you can specify that the database name be defined by an organization-level attribute called dbname. Each organization then has an attribute called dbname with a different value. You have a single data source in your repository that is accessible in each organization, but when a user runs a report with that data source, it takes data from the database specified by the value of dbname in that user's organization.

As of JasperReports Server release 6.1, attributes also have permissions, so that system admins or organization adminsadministrators can restrict the visibility and use of specific attributes at lower levels.

Referencing Attributes

There are several features of JasperReports Server that can read attributes and use attribute values. The following features can limit or restrict access to data or take different behavior based on the user, organization, or server-level attributes. Each feature reads or references attributes in its own syntax that is described with that feature:

Attributes are always referenced in relation to the currently-logged in user who is performing an operation or running a report:

Attribute Hierarchy

An attribute is a named value that is defined on a user, organization, or root of the server. Any number of attributes with any name can be defined at any or all either or both of these levels. The definition of each attribute at each level is independent of other attributes at other levels. Attributes at different levels may have the same name, unless explicitly forbidden as described in Attribute Permissions.

With hierarchical values, attributes with same name but different values may be defined at several levels and on many users or organizations. Each attribute is a distinct attribute definition, but the hierarchical value referencing takes into account the level and the presence of the definition for every given user and organization.

To help administrators define attributes on users and organizations, the UI displays all attributes that are visible in the attribute hierarchy. If an attribute is defined in a parent organization or at the server level, its hierarchical value is shown at the lower organization level and user level, and the attribute is called inherited. This allows the administrator to see all hierarchical values that are in effect in lower levels, either to override them in the hierarchy or leave them as inherited.

Categorical and hierarchical approaches usually involve different strategies for defining and naming attributes. When using categorical values, you must ensure that each and every user or organization has the attribute defined, and you must handle the case when it is accidentally undefined, such as a new user. When using hierarchical values, you define attributes with the same name at different levels, such that each user may have a custom value, but then the organization server level provides a default value for all users, and the server level provides a default value for all organizations. Each strategy is useful for different applications, depending on your needs to access and protect data. However, both strategies can co-exist and be used by at the same time by different resources, as long as the names of attributes used in each strategy or each resource are kept distinct.

Attribute Encryption

Because of the attribute hierarchy and the way that attributes are referenced, attribute names and values are one of the few mechanisms that allow lower organizations to see items defined in higher organizations. By default, an attribute and its value can be known to administrators throughout the server.

JasperReports Server provides two mechanisms to protect sensitive attributes:

For example, an encrypted attribute could store the password for a database. Once typed in and saved, the UI displays ***** as the value of the attribute. When a report uses that database, the server decrypts the password and sends it as part of the database protocol, so the user and the admin never see the password.

Encrypted attributes are similar to user passwords in the server. Administrators can change the encrypted value to a new value, but they can never view the current value, even the system admin (superuser).

To properly secure an attribute, you should make it encrypted so it cannot be seen and then set permissions so it cannot be overridden.

Attribute Permissions

Because the attribute hierarchy allows attribute values at lower levels to take precedence over attributes with the same name at higher levels, administrators need a mechanism to enforce the priority of higher-level attributes. The permissions on attributes allow admins to prevent the same attribute name from being seen or redefined in lower levels. Otherwise, a low-level organization admin could define an attribute with the same name as a critical server-level attribute defined by the system admin.

The attribute permissions and their effects are as follows:

In servers with only a single default organizationthe Community Project edition, use this permission unless you want to disable an attribute with the no-access permission.

It is important to remember that attributes are always defined individually at each level. When permissions prevent a lower-level admin from "writing" an attribute, in actuality the permission is preventing the lower-level admin from creating a new attribute at his level with the same name (regardless of its value).

As the root user, the system admin (superuser) is not restricted by attribute permissions. Therefore, the system admin can view all attributes defined at all levels and create or modify attributes on any organization or user, regardless of the permission. Thus, the system admin could create an execute-only attribute at the server level and then define an attribute with the same name but different value on an organization or user.

The permission system is based on the permissions above, and when combined with multiple levels of organizations, it can be used to create complex attribute definitions.

Managing Server Attributes

Attributes can be defined at the server level, which is equivalent to the root organization. If a given attribute name is not defined on an organization or a user, it can have a value at the server level to act as a default value. Server-level attributes may also be used as parameters in data source definitions. For example, the same data source may be imported to several servers, such as test and production servers, but a server-level attribute with the same name on each server makes the data source connect to a different database.

To view, create, modify, or delete server-level attributes:

Each server level attribute is listed with its value, encrypted status, and permission. Holding the pointer over an attribute name shows the description associated with the attribute. When an attribute value is encrypted, its value is shown as *** symbols.

4.

To modify an attribute, click the edit icon

You can also modify the attribute's permission and encryption by using the drop down and check box in its table row. After confirming any changes, click Save to make them take effect.

When modifying an attribute, be aware of the following:

5.

To delete an attribute at the server level, click the delete icon

Managing Organization Attributes

Organization attributes are attributes defined on an organization, regardless of whether its a top-level organization or suborganization. For example, an attribute with the same name could have different values in each organization, so that the same data source definition would access a different database specific to each organization. Furthermore, suborganizations could also define the same attribute if they need access to a different database than their parent organization.

Organization attributes are managed by either the system admin or the organization admin. As with all management operations, organization admins can set the attributes in their organization and any of their sub-organizations, and the system admin can set attributes in any organization. If a higher admin wants to restrict access to certain attributes by a lower-level admin, the higher admin must set permissions, as described in Attribute Permissions.

To view, create, modify, or delete organization-level attributes:

1.

Log in as an administrator (jasperadmin in the target organization or any parent organization, or superuser).

2.

Select Manage > Organizations.

3.

Select the parent organization in the left-hand column, then select the target organization in the center column.

The right-hand column displays the properties of the target organization, including a table of all attributes visible at this organization's level. The attributes include locally defined attributes, as well as inherited attributes. An inherited attribute is one defined in a parent organization or at the server-level, and whose permissions allow it to be visible in this organization.

Viewing Attributes on the Manage Organizations Page

In the figure above, the system admin (superuser) is logged in and viewing organization attributes. The system admin can view all attributes at all levels, even inherited attributes, regardless of permissions. Also, the root organization is visible and represents the server level. Selecting root in the Manage Organizations page displays the same attributes and offers the same functionality as the Server Attributes page under Manage > Server Settings. By definition, none of the attributes at the server level are inherited.

4.

To create, modify, or delete the attributes on an organization, click Edit in the right-hand column, then select the Attributes tab. In the following figure, the Finance organization admin is logged in and does not see the userName and password attributes because they are hidden by permissions. Also, inherited attributes with the read-only permission are shown but cannot be modified.

Editing Organization Attributes

5.

You can filter attributes in the list to include only the inherited attributes or only the locally defined (not inherited) ones.

6.

To create a new organization attribute, click Add new attribute. Enter the attribute name and value, as well as an optional description. If desired, set the permission from the drop-down list and select the Encrypt check box. Click OK to close the dialog and then click Save to submit the new attribute.

Adding an Organization Attribute

7.

To modify an attribute, click the edit icon

You can also modify the attribute's permission and encryption by using the drop down and check box in its table row. After confirming any changes, click Save to make them take effect.

When modifying an organization attribute, be aware of the following:

•

Inherited attributes belong to a parent organization or server root and are shown at the organization level to display the hierarchical attribute values. Any modification to an inherited attribute actually creates a local attribute definition with the modified parameters. In the hierarchy for the selected organization, this new attribute takes precedence over the previously inherited attribute.

•

Changing the name of a locally defined attribute is equivalent to deleting the original attribute and adding a new attribute with the same value. Because this may impact features that reference the attribute, you are asked to confirm the name change.

•

Be aware that changing the encryption or permission of an attribute can impact the visibility of an attribute and the features that might rely on referencing its value. Again, this may impact features that reference the attribute, and you are asked to confirm the change.

•

Removing encryption does not decrypt an encrypted attribute. To safeguard encrypted values, removing the encryption on an attribute also erases its value. Click the edit icon to give the attribute a new value.

8.

To delete an organization attribute, click the delete icon

When deleting an organization attribute, be aware of the following:

•

Upon deletion, some attributes remain in the list as inherited attributes. This indicates that the local definition of the attribute was deleted, but another attribute with the same name is visible higher in the attribute hierarchy.

•

You cannot delete an inherited attribute, because it belongs to a higher organization or server root. To remove an inherited attribute, you must find where it is defined then delete it at that level. The system admin can also change the permission of the attribute where it is defined to Execute Only or No Access so it doesn't appear to organization admins in the lower organization anymore.

Managing User Attributes

Attributes on users can provide additional information about a user and can restrict access to data through Domain security files and OLAP schemas. Every user in every organization may have attributes defined, and will also have attribute values inherited through the attribute hierarchy.

Attributes on users do not have permissions because there is no lower level of attributes. Instead, the permissions on organization attributes determine which attributes values apply to a user through the attribute hierarchy.

Attributes on users can provided additional information about a user and can restrict access to data OLAP schemas. Users may also have hierarchical attribute values inherited from server-level attributes. Attributes on users do not have permissions.

Users never see the attributes defined on their user profile; only administrators can view and set user attributes.

To view, create, modify, or delete user-level attributes:

1. Log in as an administrator (jasperadmin in the user's organization or any parent organization, or superuser). 2. Click Manage > Users or, on the Admin Home page, click Manage under Users. 3. In the Organizations panel, select the user's organization. Or select a parent organization and search for the user by name. 4. Select the user in the Users panel. The properties panel includes a table of all attributes for the user, both locally defined and inherited from the attribute hierarchy server level. In the following figure, the system administrator can see that attr2 attribute was redefined at the organization level before being inherited by the user. Adding a User Attribute 8. To modify an attribute, click the edit icon You can also modify the attribute's encryption by using the and check box in its table row. After confirming any changes, click Save to make them take effect. When modifying a user attribute, be aware of the following: •      Inherited attributes belong to a parent organization or the server level and are shown at the user level to display the hierarchical attribute values. Any modification to an inherited attribute actually creates a local attribute definition with the modified parameters. In the hierarchy of attributes for this user, the new attribute takes precedence over the previously inherited attribute. •      Changing the name of a locally defined attribute is equivalent to deleting the original attribute and adding a new attribute with the same value. Because this may impact features that reference attributes, you are asked to confirm the name change. •      Removing encryption does not decrypt an encrypted attribute. To safeguard encrypted values, removing the encryption on an attribute also erases its value. Click the edit icon to give the attribute a new value. 9. To delete a user attribute, click the delete icon When deleting a user attribute, be aware of the following: •      Upon deletion, some attributes remain in the list as inherited attributes. This indicates that the local definition of the attribute was deleted, but another attribute with the same name exists higher in the attribute hierarchy at the server level. •      You cannot delete an inherited attribute because it belongs to a parent organization or the server level. To remove an inherited attribute, you must delete it or set its permission to No Access at the server level. find where it is defined, then delete it at that level. The system admin can also change the permission of the attribute where it is defined to Execute Only or No Access so it doesn't appear on the user anymore.