Introduction to Domains

Production databases typically contain data in tables that are optimized for storage and retrieval. Columns with data relevant to users need to be joined across several tables, filtered by business needs, secured against unauthorized access, and labeled using user-friendly names. In relational databases, a view can perform some of these functions. In the server, a Domain performs all these functions and more, such as the localization of report text and permissions based on data values.

A Domain is a virtual view, created and stored in the server without modifying the data source. Through a Domain, users see columns that have been joined, filtered, and labeled for their business needs. Security policies limit the data values users can access through a Domain. Administrators define Domains, and users create reports based on Domains using either the Ad Hoc Editor or iReport.

Domains, like Topics, are used in the Ad Hoc Editor as a basis for designing reports. Users can save a report based on a Domain for others to run, and can also save the settings in a Domain Topic so others can design similar reports.

Using a Domain instead of a Topic has the following advantages:

•    Domains can be created directly through the server user interface.

•    Domain creators can write SQL queries, joins, filter expressions, and security files to specify exactly what data can be accessed, as well as labels and locale bundles to specify how the data appears.

•    When designing a report based on a Domain, the server can optimize database access to allow editing of reports that access huge datasets.

•    A Domain design typically includes data filtering, but users who create reports using the Domain can filter data even further. Users can select a subset of columns to appear in the Ad Hoc Editor and give them custom labels. Users can filter the data for each column.

•    Users who create reports can design prompts for input from report readers to filter data that appears in the document.

For more information, see sections Creating a Report from a Domain and Creating Topics from Domains.

Domain Use Cases

Typically, you base the decision to use Domains, Domain Topics, or saved reports on the complexity of the data and your business needs. Consider the following use cases:

•    Case 1 – Domains and Domain Topics can be designed to give users great freedom in designing reports plus the security features that prevent unauthorized access to data.

•    Case 2 – Administrators can create very targeted Domains and Domain Topics, then use repository access permissions to make sure users cannot modify them.

In the first case, a Domain could contain dozens of tables in several unjoined sets, perform very little filtering but define a strong data-level security policy. Users of the Domain might see only a single set of tables according to their security permissions. They could then perform their own filtering, relabel columns for their own needs, and save their settings as a Domain Topic for future reuse in Ad Hoc reports. In this case, there might be only one Domain within the organization but many Domain Topics that users have created for specific needs.

In the second case, Domains can be used to perform complex joins, have formulae for calculating new columns, filter data, and select a small set of columns for specific users or specific types of reports. Perhaps reports also need to be internationalized, so the administrator creates the corresponding locale bundles. In this scenario, there might be many specific Domains, and each would have corresponding locale bundles and a single Domain Topic. Users would have a wide variety of Domain Topics to choose from, each for a specific purpose, but no opportunity to access the Domains to perform their own filtering.

The preceding examples illustrate two extreme cases, but there are many scenarios that combine some degree of both. The number of users in your production environment and their level of proficiency also determine your general use cases. A small number of users who understand their database might be given administrator privileges to define complex Domains as an extension of the Ad Hoc report design process. On the other hand, with large numbers of users or with users who have limited database skills, administrators want to create Domains that help the users meet their business goals.

The table in section Creating Topics from Domains describes individual use cases for Domains, Domain Topics, and reports based on Domains.

Terminology

This chapter refers to both columns and fields. Conventionally, database tables are composed of columns, and columns are composed of fields in each row. Some Domain operations refer to columns, others to fields, however the two terms refer to the same concept from different perspectives. For example, a calculated field refers to a field in row that is computed from the field values in other columns. But the effect of a calculated field in every row is to create a new calculated column. Similarly, operations such as joins and filters operate on designated field values in a row, but they are defined by the columns that determine the fields involved.

Within a Domain, columns are called items. Because an item may originate from derived tables or calculated fields, it may not correspond to a single column in the database.

Components of a Domain

A Domain is saved as an object in the repository. Like other repository objects, it has a name, optional description, and folder location specified at creation time. A Domain references the following components:

•    A JDBC or JNDI data source whose tables and columns are presented through the Domain. Data sources are selected from previously defined data sources in the repository.

•    The Domain design that specifies tables and columns in data source, queries for derived tables, joins between tables, calculated fields, and labels to display the columns.

•    Optional locale bundles consisting of localized property files that present labels and descriptions in other languages.

•    Optional security file that defines row and column-level access privileges based on users or roles.

The Domain design is either created using the Domain Designer or uploaded from an external XML file. Locale bundles and security files are uploaded from external files. The following sections describe the various dialogs for selecting, creating, or uploading the components of a Domain.

Sample Domains

The following sample Domains are provided in Organization > Domains in the default installation:

•    Simple Domain – Demonstrates basic features of Domains

•     Based on the SugarCRM JNDI sample data source

•     Includes a design file that you can export, as described in section The Domain Design File

•     Used to create Simple Domain Topic in the Organization > Ad Hoc Components > Topics folder, as described in section Creating Topics from Domains

•     Shows how a report creator can see the items in a Domain through a Domain Topic

•    SuperMart Domain – Demonstrates advanced features of Domains

•     Based on the Foodmart sample data source

•     Represents a complex Domain with many tables and joins

•     Includes a design file that you can export, as described in section The Domain Design File

•     Includes the Domain security file and locale bundles that you can download and inspect, as described in section The Domain Design File

You can use the samples to practice designing and using Domains and to see complex reports based on Domains:

Overview of Creating a Domain

In practice, plan Domain features before you begin the creation process. Decide on the data source and define it in the server repository. Know the elements of your design: tables and columns to choose, joins to perform, filters to define, sets you need, and item properties to expose to users. Determine whether the users of the Domain need localized resources, such as translated labels and local formats. Finally, determine a security policy for the data retrieved through the Domain.

To launch the Domain Designer:

The next section includes a detailed example of creating a Domain.