Managing Attributes

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.

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.

Previously known as profile attributes, attributes were associated only with users. JasperReports Server release 6.1 now includes an interface to define and manage attributes on organizations and at the server level. This release also introduces permissions on attributes, so that system admins or organization admins 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:

Data sources – The host name, port number, database name, user name and user password can be defined through attributes. See Attributes in Data Source Definitions.
Reports – Attribute values can be referenced in calculations as described in Attribute-based Parameters for Queries and Reports.
Domain security files – Access rules for rows and columns can be defined with attributes so that users or organizations may only see data they are allowed to access. See the chapter "Advanced Domain Features" in the JasperReports Server User Guide and a comprehensive example in the chapter "Securing Data in a Domain" in the JasperReports Server Security Guide.
OLAP schemas – Similar to Domains, access rules can be defined with attributes so that users may only see data they are allowed to access. See the Jaspersoft OLAP User Guide.

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

If the value of a user-level attribute is requested, it refers to the attributes of the logged-in user.
If the value of an organization-level attribute is requested, it refers to the attributes of the logged-in user's organization.
If the value of a server-level attribute is requested, the value depends on which server the user is logged into. For example, test and production servers may have a copy of the same repository, but different server-level attributes. For a given server, server-level attributes are shared and thus have the same value for all users in all organizations.

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 of these levels. The definition of each attribute at each level is independent of other attributes at other levels, even if the attributes have the same name (except in the case of permissions described below).

In the places that you reference attributes (see above), there are two ways to determine the value of an attribute:

Categorical value – References the value of a named attribute at a specific level, either user level, organization level, or server level. If the attribute does not exist at the requested level, no value is returned.
Hierarchical value – References the value of a named attribute across all levels, starting at the user level. The server searches for an attribute with the given name in the following order, stopping and returning the first value that it finds:
     At the user level, in the user attributes of the logged-in user.
     At the organization level, in the organization attributes of the logged-in user's organization and all parent organizations.
     At the server level.
     If the attributes does not exist at any level, no value is returned.

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 in organizations and users, 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 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 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 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:

Attribute encryption – Prevents the attribute value from ever being seen. Does not prevent the attribute name from being seen or the value from being redefined at a lower level.

When an attribute value is encrypted, the value stored internally is encrypted and never decrypted in the user interface. The server decrypts the attribute only when it is referenced by one of the features of the server. The decrypted value is then used for internal operations and never visible to the user. 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).

Attribute permissions – Prevents the attribute from being visible or redefined at a lower level. Attribute permissions are described in the next section.

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.

In both cases of categorical and hierarchical value references, administrators need to manage permissions to ensure that only the attribute values they want can be defined.

Attribute permissions provide the following capabilities:

Attribute visibility – Whether lower level admins can see the attribute and its value, or even if the attribute can be referenced.
Attribute priority – Whether admins can create a new attribute with the same name but different value (in accordance with attribute hierarchy).
Delegation of attribute permissions – Whether lower level admins can create a new attribute with the same name and thus control the permissions at their level and below.

It is important to remember that even though the hierarchy of attributes makes the attribute name have scope up the levels, and permissions give the name scope from the top level down, 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).

The attribute permissions and their effects are as follows:

Administer – This is the absence of any restrictions. It allows lower level administrators to define attributes with the same name and set their permissions locally for their sub-organiztions. This is the default permission.
Read Only – The attribute and its value are visible to lower level administrators, but they cannot define an attribute with the same name.
Execute Only – The attribute and its value are not visible to lower level administrators, and they see an error if they try to create an attribute with the same name. However, the attribute returns its value when properly referenced.
No Access – The attribute is explicitly undefined at lower levels, and it cannot be redefined by lower-level administrators. When referenced, an attribute with no access permission returns an error.

As the root user, the system admin (superuser by default) is not restricted by attribute permissions. Therefore, the system admin can see all attributes defined at all levels when viewing and modifying attributes on any organization or user.

The permission system is based on the simple permissions above, but 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:

1. Log in as the system administrator (superuser on commercial editions, jasperadmin on community editions).
2. Select Manage > Server Settings and choose Server Attributes from the left-hand panel.

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

Managing Attributes at the Server Level

3. To create a new server-level 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 a Server Attribute

4. To modify an attribute, click the edit icon . In the edit dialog, modify the desired fields. Click OK to close the dialog and then click Save to modify the attribute.

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:

     Changing the name of an 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. You should give the attribute a new value by clicking the edit icon.
5. To delete an attribute at the server level, click the delete icon in the attribute row and confirm the operation. Because this may impact features that reference attributes, you are asked to confirm the deletion. Click Save to make the deletion take effect.

Managing Organization Attributes

Organization attributes are attributes defined on an organization, regardless of whether its a top-level organization or sub-organization. For example, an attribute with the same name could have different values in each organization, so that the same data source defiition would access a different database specific to each organization. Furthermore, sub-organizations 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 in his own organization, 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 . In the edit dialog, modify the desired fields. Click OK to close the dialog and then click Save to modify the attribute.

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 in the attribute row and confirm the operation. Because this may impact features that reference attributes, you are asked to confirm the deletion. Click Save to make the deletion take effect.

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.

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 (commercial editions only). 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. In the following figure, the system administrator can see that attr2 attribute was redefined at the organization level before being inherited by the user.

Viewing Attributes on the Manage Users Page

5. To create, modify, or delete the attributes on a user, click Edit in the right-hand column, then select the Attributes tab.

Editing User Attributes

6. You can filter attributes in the list to include only the inherited attributes or only the locally defined (not inherited) ones.
7. To create a new user attribute, click Add new attribute. Enter the attribute name and value, as well as an optional description. If the attribute value should not be visible to other administrators, select the Encrypt check box. Click OK to close the dialog and then click Save to submit the new attribute.

Adding a User Attribute

8. To modify an attribute, click the edit icon . In the edit dialog, modify the desired fields. Click OK to close the dialog and then click Save to modify the attribute.

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 server root 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 in the attribute row and confirm the operation. Because this may impact features that reference attributes, you are asked to confirm the deletion. Click Save to make the deletion take effect.

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.
     You cannot delete an inherited attribute because it belongs to a parent 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 on the user anymore.
Version: 
Feedback
randomness