Typically, database administrators or business analysts create Domains for end users who understand the structure of the raw data in the database. In the default server installation, those who create Domains must have organization admin privileges.
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 section Creating a View from a Domain and section Creating Topics from Domains.
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.
This chapter refers to both columns and fields. Conventionally, database tables are composed of columns, and the columns divide each row or record into fields. 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 that is computed from the other field values in the same row or record. 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.
Measures are columns or fields that display numeric values or aggregate values in reports. Measures are the quantitative values of a record, such as an amount, as opposed to qualitative values such as name or location. Having a field designated as a measure determines where the item can be placed in the report. For example, measures appear summarized in the center of crosstabs, whereas only non-measures, simply called fields, can be used as row and column groups of the crosstab. In Domains, all items based on numeric fields are designated as measures by default, but you can set them manually as well. By marking items as measures, Domains help report creators find and use the data they need in the Ad Hoc Editor.
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.
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:
In practice, you should 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:
1. As an administrative user, select Add Resource Domain in the repository to open the Add New Domain page of the Domain Designer.
2. Enter a name and optional description for the Domain.
3. Under Data Source, browse to locate a data source.
4. Optionally define localization bundles or data-level security on the Add New Domain page of the Domain Designer.
5. Click Create with Domain Designer to launch the Domain Designer.
The next section includes a detailed example of creating a Domain.