App Studio > Creating Metadata > Generating a Synonym

Generating a Synonym

Topics:

Enhancing a Synonym
Building a Synonym Using the Metadata Tab

How to:

Access the Metadata Canvas

A synonym defines a unique logical name (also known as an alias) for each web services operation. Synonyms are useful because they insulate client applications from changes to the location and identity of a request. You can move or rename a request without modifying the client applications that use it. You need to make only one change, redefining the request synonym on the server. Synonyms provide support for the extended metadata features of the server, such as virtual fields and security mechanisms. Creating a synonym generates a Master File and an Access File.

Often, a synonym already exists on the server, and reporting can begin at once. However, if the synonym you require does not exist on the server, an authorized server or application administrator can create it directly using the Metadata canvas in App Studio.

To begin creating a synonym, you use the Data Source Definition Wizard, which guides you through the steps that you need to follow to open a recently used synonym, create a new synonym, or edit an existing synonym. You use the Metadata canvas, and the available tab and panels, to develop your synonym. This enables you to explore DBMS catalogs and select the objects for which you wish to create synonyms. The Metadata canvas prompts for the information it needs to create a synonym for a particular data source and stores the generated synonym on the server.

In order to generate a synonym, you must be authorized to use the data against which you plan to report and you must have configured an adapter to access that type of data. When you begin to create a synonym, App Studio opens the Select adapter to configure or Select connection to create synonym window. The option to create the synonym becomes available only after the adapter is successfully configured.

Once you have generated a synonym, you can report against the synonym. In many instances, the configured adapter and the generated synonym are all you need to access your data and create reports and graphs.

However, you may wish to enhance the synonym in order to implement particular capabilities that are supported in the WebFOCUS data description language. To do this, you can use the Metadata canvas.

When you use the Metadata canvas, there is no need to know the data description language. All viewable and editable attributes of the synonym components display. If you make changes to the generated synonym, the Metadata canvas validates your entries and displays messages if they violate the underlying syntax of the data description language.

Note: If you are comfortable working directly with syntax, you can open the synonym components in a text editor. For detailed information about the underlying syntax, see the Describing Data With WebFOCUS Language manual.

Enhancing a Synonym

The following are some of the attributes you might want to add to the synonym to enhance your data access and reporting capabilities. You can:

Apply security rules for fields and values to ensure that user access is based on Information Builders data source security (DBA) specifications.
Add virtual columns (DEFINE fields) and columns for aggregated values (COMPUTE fields).
Add filters to specify data selection criteria.
Add group definitions for data sources that support groups.
Add meaningful titles and descriptions, including multilanguage variations.
Change the format of fields (for example, the size of an alphanumeric field or the format of a date field).
Create a cluster join view by linking available synonyms to create a multisegment (multitable) file for reporting.
Create business views of the metadata in order to limit the fields available to any retrieval request that references the business view and to group fields together based on their roles in an application.
Define parent and child hierarchies for cube data sources.

Procedure: How to Access the Metadata Canvas

In App Studio, you create new synonyms and edit existing synonyms using the Metadata canvas. You can access the Metadata canvas through the Data command, in the Content group, on the Home tab.

This launches the Data Source Definition Wizard, where you can open a recently used Master File, create a new Master File, or edit an existing Master File. The Data Source Definition Wizard is shown in the following image.

Click Create New Synonym, which opens the Select Application pane of the Data Source Wizard. Select a location to create your synonym and click Finish to open the Metadata canvas.
Click Open Existing, which opens the Select Data Source pane of the Data Source Wizard. Select a data source to edit and click Finish to open the Metadata canvas.

The Metadata canvas opens, as shown in the following image.

Note: The examples in this document use a multi-fact structure containing multiple Fact tables that have corresponding Dimensions described in the Master File.

Building a Synonym Using the Metadata Tab

Topics:

Restoring Actions Using the Undo/Redo Group
Deleting, Cutting, Copying, and Pasting Using the Clipboard Group
Searching and Revising Text Using the Editing Group
Switching Between Views and Aerial View Using the View Group
Inserting Nodes Using the Insert Group
Running a Sample Data, Data Profiling, or Impact Analysis Report Using the Reports Group
Showing Properties, Data Flow, and View Panels Using the Tools Group
Setting Preferences for the Metadata Canvas Using the Options Dialog Box

The Metadata canvas displays the Metadata tab, which contains all the commands necessary to build your synonym.

The Metadata tab contains groups and commands that provide quick access to commonly performed functions while working in the Metadata canvas. You can use the Metadata tab to undo or redo actions, manipulate selections of data, find and edit text, switch to different view tabs, insert notes, run different reports, and switch between different view modes. The behavior of the command is determined by the selected object. Therefore, certain tab components may be inactive. The Metadata tab is shown in the following image.

Restoring Actions Using the Undo/Redo Group

You can undo and redo actions. The Undo/Redo group is shown in the following image.

The commands are:

Undo: Undoes the last action.
Redo: Restores a previously undone action.

Deleting, Cutting, Copying, and Pasting Using the Clipboard Group

You can delete, cut, copy, and paste sections from the canvas. The Clipboard group is shown in the following image.

The commands are:

Delete: Deletes your selection.
Cut: Cuts your selection.
Copy: Copies your selection.
Paste: Pastes from your clipboard to the designated area.

Searching and Revising Text Using the Editing Group

You can find specific text, select the entire canvas, replace specific text, move to a specific point in the canvas, apply case formatting to text, and add comments. The Editing group is shown in the following image.

The commands are:

Find: Finds specified text.
Find Next: Finds the next instance of specified text.
Find Previous: Finds the previous instance of specified text.
Select All: Selects the entire canvas.
Replace: Replaces the specified text with different text.
Go To: Moves your view of the canvas to the specified area.
Invert Case: Inverts the case of the selected text.
Upper Case: Upper case the selected text.
Lower Case: Lower case the selected text.
Comment Selection: Comment the selected text.
Uncomment Selection: Uncomment the selected text.

Switching Between Views and Aerial View Using the View Group

You can switch between the different views and switch Aerial view on or off. The View group is shown in the following image.

The commands are:

Field

Switches to the Field View. The Field View shows a list of objects on the left, with the attributes and values of the selected item on the right.

Segment

Switches to the Segment View. The Segment View shows the segments that the synonym contains. The Segment View shows a list of objects on the left, with the attributes and values of the selected item on the right.

List

Switches to the List View. The List View shows a list of objects on the left, with the attributes and values of the selected item on the right.

When you right-click a column heading in the List View, a shortcut menu provides options to sort the display based on ascending or descending column values. The display can be sorted by any column.

Modeling

Switches to the Modeling View.

Text

Switches to the Text View tab.

You can print the Master File code by selecting Print from the Application menu, performing search operations, and making changes, if necessary.

Access File Text

Switches to the Access File Text View tab.

The Access File Text View shows the description of the Access File for a synonym, which is used to access the database.

Note: You can print the Access File code by selecting Print from the Application menu, performing search operations, and making changes, if necessary.

Aerial View

Switches between showing and hiding Aerial view. This view is only available when in the Modeling View tab.

Inserting Nodes Using the Insert Group

You can insert a node. The Insert group is shown in the following image.

The commands are:

Insert

Enables you to insert one of the following:

Reference to Existing Synonym as Child: The reference is a pointer to the source synonym using the synonym as a child. If you subsequently make changes to the source synonym, reopening the current synonym will reflect those changes.
Reference to Existing Synonym as Root: The reference is a pointer to the source synonym using the synonym as a root. If you subsequently make changes to the source synonym, reopening the current synonym will reflect those changes.
Copy of Existing Synonym: Adds a static copy of an existing synonym to the current synonym. If you subsequently make changes to the source synonym, the current synonym will not reflect those changes.
Segment via Metadata Import: Enables you to create and add a new synonym to the current synonym using the Create Synonym dialog box.
Segment Manually: Adds a synonym that must be coded manually.
DBA: Adds DBA security to the segment.
Field: Adds a general column to the segment.
Define: Adds a virtual or defined column to the segment.
Filter: Adds a filter to the segment.
Compute: Adds a calculated value to the file.
Sort Object: Adds a Sort Objects folder and a sort object. This option is available only if Support extended options is selected.
Variable: Adds a Variables folder and a variable to the segment.
Style: Adds a Styles folder and a style object. This option is available only if Support extended options is selected.
Subquery: Adds a subquery to the fields list.

Running a Sample Data, Data Profiling, or Impact Analysis Report Using the Reports Group

You can run a Sample Data report, Data Profiling report, or Impact Analysis report. The Reports group is shown in the following image.

The commands are:

Sample Data: Enables you to view and refresh sample data for the selected segment or synonym.
Data Profiling: Runs a Data Profiling report, which provides the data characteristics for synonym columns. The Statistics, Count, and Key Analysis options are available.
Impact Analysis: Runs an Impact Analysis report for the particular column in the workspace. An Impact Analysis report identifies the procedures that access a Master File or column within a Master File.

Showing Properties, Data Flow, and View Panels Using the Tools Group

You can switch between showing or hiding the Properties, DBA, and Business View panels. You can also recreate the default Business View structure and edit the user options. The Tools group is shown in the following image.

The commands are:

Properties

Switches between showing and hiding the Properties panel.

Quick Copy

Generates a simple Data Flow without using the Data Flow designer. For the selected tables, all rows and columns are copied to new tables.

Although no transformations or where conditions are generated, the Data Flow can still be opened as such and additional criteria can be added.

DBA

Switches between showing and hiding the DBA panel.

Business View

Switches between showing and hiding the Business View panel. Enables you to create a Business View and a custom Master File that can use selected columns from the original synonym. In addition, you can customize field names, titles, and descriptions.

Options

Allows you to edit the user options. When you click Options from the Tools Group, the Options dialog box appears. It enables you to set preferences and customize the look of the Metadata canvas.

Setting Preferences for the Metadata Canvas Using the Options Dialog Box

Reference:

Synonym Editor Options Settings
Synonym Editor Format Options Settings
Synonym Editor Column Management Settings
Synonym Editor Run Options Settings

Click the Options button in the Tools group to open the Options dialog box.

Reference: Synonym Editor Options Settings

When you click Options from the Tools group, the options dialog box appears. It enables you to set preferences and customize the look of the Metadata Canvas.

The Synonym Editor settings page has the following fields and options:

Use application directory name with synonym

If this check box is selected, an application directory name is used when you select a synonym name for both referencing an existing synonym and a transformation with db_lookup.

Undo/Redo Limit

Specifies the maximum number of undo and redo operations allowed in the Synonym Editor.

Support extended options

If this check box is selected, both the Sort objects and Styles folders appear when you edit a synonym.

Enable insert copy of existing synonym

If this check box is selected, this option will be available in the shortcut menu when a synonym or segment name is selected.

Insert child segment with snowflakes

Inserts a reference to the selected table and any tables that the base synonym references through foreign keys.

Automatically arrange segments/folders in Modeling View

If you select or drag multiple or individual tables while in Modeling View, they will be automatically arranged for you.

Show parent segments in Join Editor

If this check box is selected, it controls whether or not columns in parent segments are displayed in the Join Editor for a cluster join or a synonym that references or includes, other synonyms.

Automatically detect entry segment

This information is not yet available.

Default Join Type

Sets the default Join type.

Unique. This join indicates a single instance (one-to-one) type of join. At run time, each host record has, at most, one matching record in the cross-referenced file. This value is the default.
Multiple. This join indicates a multiple instance (one-to-many) type of join. At run time, each host record can have many matching records in the cross-referenced file.

Auto Calculate Missing

Allows you to adjust the MISSING attribute.

Prompt. Prompts before adjusting the MISSING attribute.
ON. Adjusts the MISSING attribute without prompting.
OFF. Does not adjust the MISSING attribute.

Modeling View Line Colors

Allows you to set colors for connector lines in the Modeling View.

Default. Changes the color lines in the Modeling View.

Highlighted. Changes the color of the highlighted lines in the Modeling View.

No keys. Changes the color of lines with no keys in the modeling view.

Reset Colors

Restores the default colors.

Reference: Synonym Editor Format Options Settings

The Format pane is available from the Options dialog box. To open the Options dialog box, select Options from the Tools group. Expand the General node, and select Format.

The Fonts section has the following fields and options:

Category: Allows you to set the font for text in the process flow workspace, reports, text views, and log views.
Font: Launches a dialog box for specifying font settings.
Reset Font to Defaults: Restores the default fonts.

Reference: Synonym Editor Column Management Settings

The Column Management pane is available from the Options dialog box. To open the Options dialog box, select Options from the Tools group. Expand the General node, and select Column Management.

Column Management user preferences enable you to choose which columns to display on the grids for transformations, column selection, joins, and sorts. You can also set the column display order. The settings apply to all column-related dialog boxes.

The Column Management pane has the following fields and options:

Customize column display

Lists the column-related dialog boxes that can be customized. Expanding a folder will display check boxes that can be used to add columns to each dialog box.

Reset to default

Restores the default values.

Column name display strategy

Controls the information that appears in trees and grids. The available options are Name, Title, Description, and Alias. If no Title, Description, or Alias exists, the display will default to the Name.

Note: It is recommended that you use Title when working with Business Views.

Function display strategy

Controls how functions are identified on the functions tab in the calculators. By default, the function syntax is displayed. It can be changed to a short description, which displays a brief description of what the function does instead.

Use segment to qualify field reference

Indicates whether to qualify field names with the segment name in which they reside for duplicate field names only or always.

Expand any of the available Customize column display options to see default settings. Not all columns are on every grid. The following columns can be added:

Alias: Assigns an alternative name for a column or the real column name for a DBMS synonym.
Application: Indicates the application where the synonym resides.
Belongs To Segment: Shows the parent segment in the base synonym.
Connection: Indicates the adapter connection name used.
Data Origin: Indicates the date the synonym was created.
Date Modified: Indicates when the synonym was last modified.
Description: Is a description or comments about the column.
Expression: Is the expression for the column.
Extension: Indicates the suffix (data source type) of the synonym.
Field Type: Indicates that a column is an index (I) or is read-only.
Format: Is the type and length of a column data as stored.
Function: Indicates the name of the function.
Geographic Role: Describes the geographic role of the column.
Has Foreign Keys: Indicates that the synonym includes foreign keys.
Index: Indicates an index column.
Join Condition: Indicates the condition for the join.
Join Parent: Indicates the parent of the join.
Join Status: Out of the candidate list, indicates the strongest candidate or candidates for insertion.
Join Strategy: Indicates the strategy for the join.
Join To: Indicates whether you can join to the column.
Keys: Indicates the keys in the synonym.
Length: Is the column length.
Name: Indicates the column name.
Nulls: Indicates whether or not the column can contain null data.
Number of Segments: Indicates the number of segments in the synonym.
Order: Indicates the order of the column in the segment.
Parent(s): Indicates the parent or parents on the active Metadata canvas.
Prefix: Indicates a prefix for the column.
Primary Key Tables: Indicates the primary key for the synonym.
Property: Indicates whether the column is an attribute or a measure.
Real Table Name: Indicates the actual name of the table or the physical file name.
Reference: Indicate a reference for the column to an index column.
Scale: Is the maximum number of digits to the right of the decimal.
SCD Type: Used for processing slowly changing dimensions.
Segment: Indicates the segment name.
Sequence Number in Key: Indicates the sequence number of the field within the key.
Size: Indicates the size of the synonym.
Source: Indicates the source of the synonym.
SQL Conversion Notes: Indicates how SQL is converted.
Table: Is the synonym that contains the column.
Title: Supplies a title to replace the column name normally used in reports.
Type: Is the type of object in an application directory.

Reference: Synonym Editor Run Options Settings

Run Options user preferences include determining the number of rows and columns to retrieve, as well as the default format when sampling data.

The Run Options settings pane has the following fields and options:

Maximum number of rows for test reports

Sets the number of rows retrieved to produce sample data when testing transformations or SQL. The default is 50.

Maximum number of columns for test reports

Sets the number of columns retrieved to produce sample data when testing transformations or SQL. The default is to retrieve all columns (with a highest value setting of 999999).

Test reports default format

Sets the format of reports for retrieving sample data when testing transformations or SQL. The default is Default. The following report formats are available:

Default. Formats numeric and date columns based on edit options in the synonym.
HTML. Produces the report in HTML format.
HTML - plain text. Produces the report in plain text format.
active report. Produces an HTML active report designed for offline analysis.
Excel. Produces the report in Excel format.
PDF. Produces the report in PDF format.
Unformatted. Does not apply formatting to numeric and date columns.

Stop after DBMS error

Sets the number of DBMS-related errors allowed before the server stops running the procedure.

	WebFOCUS

Feedback