Open topic with navigation

Editing a Domain

You can edit a Domain by changing, adding to, and deleting its components.

To edit a Domain:

1.     Log in to the server as an administrator and select View  Search Results.

2.     Locate the Domain.

Choose View Search Results.

3.     Right-click an existing Domain and select Edit from the context-menu.

The Edit Domain page appears. This page is similar to the Add New Domain page documented in section Using the Add New Domain Page.

4.     In Name, change the display name of the Domain.

5.     In Description, change the description of the Domain.

6.     In Data Source, browse to locate a new data source for the Domain.

7.     In Domain Design, click Edit with Domain Designer. For instructions, see section Using the Domain Designer. Alternatively, select the Upload option, and browse to locate a schema. You can import the XML file of the Domain design after exporting it and make modifications in an external editor. See also “Maintaining Referential Integrity” below if you need to remove items in the Domain.

8.     To add or replace the security file or locale bundles for the Domain, click Add Security File or Add Locale Bundle in Optional Information. The Resources page is further documented in section The Domain Design File.

9.     When done, click Submit to update the Domain. To close the Domain Designer without modifying the Domain stored in the repository, click Cancel.

After modifying a Domain, you must clear the Ad Hoc cache of all queries based on the Domain. This removes any data that was based on the old instance of the Domain and avoids inconsistencies in new reports. For instructions, see the JasperReports Server Administrator Guide.

Maintaining Referential Integrity

When editing an existing Domain, the user is responsible for maintaining the referential integrity between the items in the Domain and any Domain Topics or reports that have been created from the Domain. Referential integrity means that at the time a Domain Topic or report is opened or run, all the items that the Domain references are still defined in the Domain. If you modify a Domain by removing sets or items, you must be sure that no Domain Topics or reports are based on those sets or items. Even if the underlying tables and columns still exist in the database, the sets and items referenced in the Domain must still exist in the Domain.

Any report that references a deleted item no longer runs, nor can you open it in the Ad Hoc Editor again. A Domain Topic that references a deleted item causes errors when used in the Ad Hoc Editor. You can, however, open a Domain Topic for editing and remove references to deleted items. That action, however, allows only new reports to use the Domain Topic, and does not fix the broken reports based on the items deleted from the Domain Topic.

The granularity of referential integrity is at the individual set and item level. This means that changes to sets and items that are not used in a given report or Topic do not affect the report or Topic. For example, if you delete an item used by Topic A but not Topic B, then Topic A fails and reports based on Topic A that included the item fail. But Topic B and its reports are unaffected, as are any reports based on Topic A that did not include the deleted item.

Fixing Referential Integrity Problems

Generally, to maintain referential integrity, avoid deleting items from a Domain that reports need to use. Sometimes, removing an item or set from a Domain is unavoidable. For example, you included an item erroneously that exposes confidential data to unauthorized users, or the underlying database changes, making the item invalid.

In a typical scenario, an administrator or data analyst creates a Domain and many end-users create Topics and reports based on it. When deleting Domain items in such a situation, tell users beforehand to modify reports to prevent reports from using the item. Inevitably, a user fails to modify a report as requested, and needs to fix the broken report. The server provides a mechanism to simplify fixing the report. The user can replace the deleted item with a placeholder, open the report, and edit it, even after the original item has been removed.

The following procedure assumes a user created a report based on a Domain. The Domain is similar to the one described in section Example of Creating a Domain. The Domain exposes the accounts_opportunities table that contains no useful columns and is necessary only to join the accounts and opportunities tables. Unfortunately, some users were confused by the additional items exposed by the Domain, and used the date_modified item in their reports. You want to delete the accounts_opportunities table from Sets and Items, so it is no longer exposed to users.

To fix referential integrity problems:

1.     Locate the problematic Domain in the repository, right-click, and choose Edit. The Edit Domain page appears.

2.     On the Edit Domain page, click Edit with Domain Designer.

3.     In the Domain Designer, click the Display tab, and select the public_accounts_opportunities set in Sets and Items:

4.     Click Delete Item. The Confirm dialog box appears, indicating that the item is in use and that a potential referential integrity problem exists. The message includes a link, See items that will be deleted, to the Detail dialog box, containing the items you are deleting from the Domain. See "Indication of Referential Integrity Problem" shows the Confirm dialog box.

5.     Click See items to be deleted. For each deleted item, the Detail window lists the item label, the set and items IDs as a path, and the datatype of the item:

6.     Close the Detail dialog box and click OK in the Confirm dialog box.

7.     Click the Calculated Fields tab.

8.     Enter a field name, type, and an expression that returns a constant value of the same type as the deleted item, as shown in See "Creation of Calculated Field as Placeholder for a Deleted Item", and click Save Field.

9.     Click the Display tab.

10.     In Sets and Items, click New Set to create the placeholder set.

11.     In Resources, expand the list of Constants and select ZZdate_modified:

12.     Click to add the ZZdate_modified to the new set.

13.     In Sets and Items, select the placeholder set, newSet1.

14.     In Properties, click Edit and change these properties:

15.     In Sets and Items, select ZZdate_modified.

16.     In Properties, click Edit and change these properties:

See "Modification of ID Properties to Match the Deleted Item" shows the modified properties for the placeholder item.

17.     Click OK in the Domain Designer and then Submit on the Edit Domain page.

Alternatively, you can edit the XML design file of a Domain to fix referential integrity problems. Conceptually, the modifications are the same as described in this procedure, but the order is slightly different.

To fix referential integrity problems in the XML design file of a Domain:

1.     Instead of deleting the item, first create the constant calculated field. You can do this in the Domain Designer even before exporting the design file. You must be familiar with the design file syntax to create the calculated field with the correct type and expression, as described in section Structure of the Design File.

2.     Next, locate the item definition and change its resourceID so that it references the newly created calculated field. This removes the reference to the unwanted column, and replaces it with an item that references the placeholder field.

3.     Update the other properties of the item and its enclosing set, using the values shown in See "Modification of ID Properties to Match the Deleted Item". For more information, see section Representing Sets and Items in XML.

4.     Save the design file and upload it, as described in section Uploading a Design File to a Domain.

Open topic with navigation