Using the Oracle Demantra Business Application Language

This chapter covers the following topics:

Overview

The Business Application Language (BAL) Explorer is a tool that can be used when upgrading to a newer Demantra version or to migrate objects such as worksheets, series, and workflows between two schemas (for example, from a development environment to a test environment).

Demantra Upgrade Options

When you upgrade, the Demantra installer prompts you to select one of two options: Platform Upgrade, or Application and Platform Upgrade. During the planning stage of the upgrade, you should determine which of these upgrade options is relevant for your environment.

Platform Upgrade Only

With a Platform upgrade, the installer applies changes to the software platform including the generic features such as the engine, web applications, administration tools and database objects. You should perform a Platform upgrade if any of the following apply to your Demantra Implementation:

Application and Platform Upgrade

With an Application and Platform upgrade, the installer applies the platform upgrade as well as new application features. This may include changes to objects such as levels, worksheets, series, methods, workflows, and integration interfaces. After the platform changes have been made, the Application upgrade compares the existing schema to a baseline image and then proceeds to reconcile differences between the two. Seeded objects may be added or modified.

You should perform an Application and Platform upgrade if your Demantra implementation uses the standard Demantra applications, and has minimal customizations. In this case, it is recommended to perform an Application and Platform upgrade so that your implementation can take advantage of future application enhancements.

Note: It is important to continually perform Application and Platform upgrades even if the upgrade adds functionality that you do not plan to use in the future.

A few examples of data model changes that will impact the ability to perform an Application and Platform upgrade are:

A few examples of data model changes that will not impact the ability to perform an Application and Platform upgrade are:

Important: Changes made to standard objects could be potentially overwritten or modified by the Application and Platform upgrade, based on the default upgrade actions settings. For more information, see Table of Default Upgrade Actions. Any customizations to the data model should be documented before proceeding with the upgrade.

Using the BAL Explorer

BAL Explorer Screen Elements

The BAL Explorer main screen, shown below, is comprised of two main components:

the picture is described in the document text

The Schema Browser Pane

The Schema Browser displays all the schemas currently defined in the BAL Explorer. These schemas can be expanded to display the objects contained within the schema. Depending on the type of object you select, the attributes are displayed with icons representing their data type. For example, time attributes are displayed with a clock icon.

The Schema Browser also provides information about how objects are related.

Object Details Pane

The Object Details pane provides information about the object currently selected in the Schema browser, including:

Legend

For a better understanding of the many icons used in the BAL Explorer, a legend is available.

To view the legend:

  1. From the View menu, select Legend. The Legend window appears on the far right.

  2. Close the Legend window when you are not using it.

Status Bar

To view the progress of an upgrade, you can activate the status bar.

To turn on the status bar, from the View menu, select Status Bar.

Understanding Objects, Schemas, Folders, Files and Repositories

A schema object is a logical data storage structure. Schema objects do not have a one-to-one correspondence to physical files on the disk that stores their information. Oracle stores a schema object logically within a tablespace of the database. The data of each object is physically contained in one or more of the datafiles of the tablespace. For example, each Demantra object generally corresponds to a row in a particular table of the Demantra database, and further details might be located in other tables.

A schema is a collection of schema objects that also defines how they relate to one another. No relationship exists between schemas and tablespaces: a tablespace can contain objects from different schemas, and the objects for a schema can be contained in different tablespaces.

Configuration files describe the target Demantra schema. BAL compares these configuration files to the source database. Presently, Demantra recommends using standard configuration files for upgrading purposes.

The BAL Explorer organizes objects into folders for convenience and readability. By default, the BAL Explorer groups the objects by type and displays each type in separate folders, as follows:

The default folders used to display different types of objects have no inherent meaning aside from organizing the object information for viewing purposes.

When the BAL Explorer first connects to a schema, it creates a BAL repository, saving the information it needs in its own internal tables. This repository can reside either within the same database user or a different database user so that nothing new is introduced into the original repository.

Schema Procedures

Note: If you are upgrading your schema from the installer, the schema definition is created automatically. Go to Upgrading Schemas for detailed instructions.

Creating a Schema Connection

To view the contents of a Demantra database or compare databases, you must create a visual representation of the schema. This alias schema appears in the Schema Browser pane.

Caution: Do not use any unusual characters when defining the name such as apostrophes, brackets, and so on. This usage might cause your comparison report to not save.

Important: When you create a schema, you can create the repository in the current database user or a different user. If you choose the latter, make sure that the second database user exists before creating the schema.

To create a schema connection:

  1. Click Open Schema. The Schema Configuration dialog box appears.

    the picture is described in the document text

  2. Click New. The New Connection dialog box appears.

    the picture is described in the document text

  3. Enter the following data in the following fields:

    Field Description
    Server Name The name of the server where your database resides.
    User Name The user name of the database.
    Password The password of the database.
    Save Password Check this option if you want the password to be saved permanently for future sessions. If not checked, you will be prompted for the password the every time you connect with the schema. It is also possible to check the Save Password option from the prompt.
    SID If you are using an Oracle database, enter the SID.
    Port The port your database is using. The default is 1521.
    TNS The TNS name.
    Alias User-friendly name for the server. For example, "Test Environment"

  4. Click Test Connection to see if your schema is properly configured.

  5. Click Apply. The new schema alias appears in the Schemas Configuration dialog box.

  6. Click Close. The new schema appears in the Schema Configuration Page.

Editing a Schema Connection

To edit a schema connection:

  1. Click Open Schema.

  2. Select the schema connection that you want to modify from the list of schema aliases.

  3. Click Modify.

  4. Make the desired changes.

  5. Click Apply.

  6. Click Close.

Creating a Schema Connection Based on Another Schema Connection

To create a schema connection based on another schema connection:

  1. Click Open Schema.

  2. Select the schema connection you want to base your new schema connection on.

  3. Click Create Like. The New Connection dialog box appears with the configuration details of the original schema.

  4. In the Alias field, change the schema alias name.

  5. Make the desired changes.

  6. Click Apply. The new schema appears in the list of schemas.

  7. Click Close. Your new schema appears in the Schemas Configuration Page.

Deleting a Schema Connection

To delete a schema:

  1. Click Open Schema.

  2. Select the schema connection you want to delete.

  3. Click Remove.

  4. Click Yes when prompted for confirmation. The schema alias is removed from the list of schemas in the schemas configuration dialog box.

  5. Click Close. The schema connection no longer appears in the Schemas Browser pane.

Rebuilding a Schema Repository

You rebuild a schema repository if you have made configuration changes to the database since the schema was created in the BAL Explorer (for example, using Business Modeler). Rebuilding the schema repository incorporates all of the latest database contents, including any objects that were already upgraded into the schema. However, any personal folders associated with the schema that have not been upgraded are discarded when the schema is rebuilt.

To rebuild a schema repository:

  1. In the Schema Browser, right-click the schema that you want to rebuild.

  2. Select Rebuild. Your schema repository is rebuilt.

Note: Rebuilding your schema repository also has the effect of connecting your schema

Folder Procedures

Folders are used for testing purposes and to move objects from one schema to another. If you want to upgrade specific objects from schema A to schema B, you create a folder in schema B. All objects that the folder contains will become valid objects in the target schema if the upgrade process completes successfully. The folder itself does not have meaning to Demantra.

Creating Folders

To create a folder:

  1. Right-click the schema in which you want the folder to be located.

  2. Select New Folder. The folder icon appears in the Schema Browser.

  3. Type the name of the folder and press Enter.

Saving Folders to Files

To save a folder:

Renaming Folders

To rename a folder:

  1. Right-click the folder that you want to rename.

  2. Select Rename.

  3. Type the new folder name and press Enter. The name has been changed.

Deleting Folders

To delete a folder:

  1. Right-click the folder you want to delete.

  2. Select Delete.

  3. Click OK when Prompted to confirm the deletion. The folder and its contents are deleted.

Copying Objects from a Schema to a Folder

Within the BAL Explorer, you can copy objects from more than one schema to a folder. You can use the Shift or Control keys to copy more than one object at a time. The Shift key enables you to copy adjacent objects. The Control key enables you to copy multiple objects that are not adjacent.

To copy an object from a schema to a folder:

  1. Right-click the object that you want to copy to a folder.

  2. Select Copy.

  3. Right-click the folder to which you want to copy the object.

  4. Select Paste. The object appears in the target folder.

Deleting an Object from a Folder

Objects can be deleted from a folder, but not from a schema.

To delete an object from a folder:

  1. Right-click the object that you want to delete from a folder.

  2. Select Delete.

  3. Click OK when prompted to confirm the deletion. The object is deleted from the folder, but it remains in the original schema.

Loading an Object from a File

To load a BAL object from a saved file:

Using BAL to Upgrade when Running the Demantra Installer

Overview

Important: Before upgrading to a new version, it is strongly recommended that you take a backup of your existing database.

If you choose to upgrade an existing Demantra schema when running the Demantra installer and choose to perform a Platform and Application Upgrade, then the installer automatically launches BAL. The upgrade schema choices are presented when you install Demantra and configure the database. This diagram shows the placement of the upgrade schema options during the installation process:

the picture is described in the document text

You then choose whether to preform an Automatic or Manual upgrade of the existing schema. If you choose Automatic, then BAL updates the existing schema based on global upgrade settings, which are described later in this section. If you choose Manual, then BAL prompts you to specify a different upgrade action for each object. For new objects, select insert; for overlapping objects, you can select Insert Duplicate, Align to New Object, or Ignore New Object.

The automatic mode runs the BAL Explorer in the background without any user input. For details about the default upgrade actions, see Table of Default Upgrade Actions for Overlapping Objects. For details about modifying these default upgrade settings, see Setting the Global Upgrade Preferences.

If you want to make specific choices about how objects are upgraded to the new schema, then you should choose manual mode. This mode launches the BAL Explorer and enables you to:

The Business Modeler is invoked at the end of each upgrade mode, enabling you to apply any configuration changes identified in the new schema.

The following diagram shows the process involved with the two upgrade schema options:

the picture is described in the document text

When the upgrade is complete, the Business Modeler displays the Upgrade Complete screen, which summarizes the objects that were upgraded.

Important: Oracle strongly recommends that you backup your database before attempting to upgrade from an earlier schema.

Running the Business Modeler as Part of the Upgrade Process

You can configure the BAL Explorer start the Business Modeler to post-process migrated objects as part of the upgrade process. This option to run the Business Modeler as part of the upgrade is enabled by default.

Defining Schema Object Exceptions

Each object type has an upgrade action which depends on the object state. For example, all modified workflows are duplicated and all modified series are aligned. By maintaining a global setting on the object type, you can change the upgrade behavior for a particular object. This exception mechanism allows administrators to pre-configure upgrade settings for an individual object. For example, you may decide to modify a workflow that overwrites customer settings, even though all modified workflows are duplicated.

Upgrade exceptions are defined ahead of time and stored in a separate XML configuration file in the directory: <BAL Root>\configuration\BALExceptions.xml.

To define exceptions for schema objects:

  1. Select a schema.

  2. From the Settings menu, choose Exceptions.

    the picture is described in the document text

  3. The Exception Configuration screen appears. By default, the Show All Objects checkbox is not selected and, only the root objects are shown (for example, users, series, worksheets). When selected, the dependencies are shown as well such as level attributes, level methods, columns, index columns, indexes and tables.

  4. Select individual objects, specify exceptions and click apply. Alternatively, click Apply exception to all objects if you want to make a global change.

    Note: You must define (and select) at least one exception before you can choose the Apply Exception to all Objects option.

  5. Click Save.

To define exceptions for a selected package:

  1. Select a package inside the schema.

  2. Right-click the Set Exceptions button. The Exception Configuration screen appears.

  3. Select a package and specify the exception.

  4. Click Save.

Setting the Global Upgrade Preferences

When you upgrade an existing schema to a new schema definition, conflicts can occur between the two schemas. The Upgrade Settings option provides guidance to the BAL Explorer when performing an upgrade. New objects are always inserted. Overlapping objects can be duplicated, aligned to the new object, or ignored.

There is a set of default options available for new and overlapping objects. The default options by object type are listed in a table below. When you choose the “Automatic Upgrade” option when installing, you are not able to interact with the BAL Explorer to change the default options. When you choose the “Manual Upgrade” option when installing, an upgrade package is created by BAL with the same default options but you can choose to change or override the default options in the BAL Explorer.

By default:

Integration Interfaces and Data Profiles

Type of Upgrade Result
Automatic BAL Explorer aligns modified standard integration interfaces and associated data profiles to the new version,
Manual Same as the Automatic Upgrade except you can change the default upgrade action.

After you upgrade:

Worksheets

Type of Upgrade Result
Automatic BAL Explorer retains customized standard worksheets in your existing schema and duplicates them in the new schema. See 'Naming convention for duplicate objects' for more details.
Manual Same as the Automatic Upgrade except you can change the default upgrade action.

Note: Only those standard worksheets that have changes between the two versions will be duplicated. If a worksheet has not changed between your version and the new upgrade version, it is not duplicated.

After you upgrade, Oracle recommends that you evaluate each worksheet and:

Note: Workflow schemas also follow the same upgrade behavior as worksheets.

Naming Convention for Duplicate Objects

For objects that are duplicated during the upgrade, certain naming conventions are followed. During an upgrade, if an object has to be duplicated, the following naming conventions are used:

Table of Default Upgrade Actions for Overlapping Objects

This table describes the upgrade reconciliation actions for overlapping objects when you choose the Default upgrade option:

Object Sub-Objects Reconciliation Action Comments
Series - Align Existing series definition is aligned to the new series definition.
To prevent issues with client expressions that may refer to seeded series names, any seeded series names that were changed will revert back to their original text during the upgrade. Therefore, if you renamed seeded series, you must restore the modification after the upgrade is complete.

Note: Custom series hint message changes are not impacted by the upgrade.
Worksheet - Duplicate If there is a change in the worksheet definition between the existing version and the new version, then the new version of worksheets are created as duplicate objects. Existing worksheets are retained in their original version.
After the upgrade, it is recommended that you manually merge your pre-upgrade customizations from the pre-upgrade version to the new version and use the new version of the worksheet thereafter.
Level - Ignore Existing levels are retained in their original version. BAL ignores modified levels, but processes child objects, such as level attributes, level methods, and so on.
Level Method Align Existing methods are aligned to new version.
Level Method Input Arguments Align Input arguments are aligned to the new version.
Level Method Output Arguments Align Output arguments are aligned to the new version.
Level Level Attributes Ignore Level attributes are retained.
Level Unit Levels Align Unit Levels are aligned to the new population attribute definition in the new version.
Level Population Attributes Align Population attributes are aligned to the population attribute definition in the new version.
Level Level Member Defaults Ignore Customer level member defaults are retained.
Integration Interface - Align If there is a change in the integration interface, data profile, or level profile between the existing and new application versions, the existing version of the integration interface is aligned (overwritten) with the new version. When an integration interface is aligned, any data profiles within it are also aligned to the new version.
Therefore, customizations made to the standard integration interfaces are not preserved during the upgrade process.
After the upgrade:
- Review your pre-upgrade schema backup for the integration interfaces that have been aligned
-Add back any customizations you have made to the new version of the integration interface.
Workflow Schema - Duplicate If there is a change in the workflow schema between the existing and new application version, then the new version of the workflow schema is created as a duplicate object.
After upgrade, it is recommended that you manually merge your pre-upgrade customizations from the pre-upgrade version to the new version and use the new version of the workflow.
Users - Align If there is a change in users between the existing and new application versions, then the existing users are aligned (overwritten) with the new version.
Model - Align If there is a change in the model between the existing and new application versions, the existing model is aligned (overwritten) with the new version.
Components (Component Wizard of the Business Modeler) All sub-objects

  • Component Series

  • Component Levels

  • Component Units

  • Component Indexes

  • Worksheet for Levels

  • Engine Profiles

 Align with Merge All sub-objects under Components (for example, component levels, series, units, and so on) are merged with the new version so that the original and new settings are available.
For example, if a customer has associated a COGS unit to a component and in the newer version, there is a new unit XYZ associated with this component, then both COGS and XYZ units are available after the upgrade.

Note: The existing component level permissions are overwritten by the new level permissions. It is important to keep track of the existing component level permissions before the upgrade. After the upgrade, these component level permissions can be re-configured in the Business Modeler to match the pre-upgrade settings.
Group Users - Align with Merge Any users a customer has added to a user group are merged with any users associated with this group in the new version.
Indexes

Note: These are not database indexes, but rather indexes created in Business Modeler through the Configure > Configure Indexes menu option.

 - Ignore Current indexes are retained.
Series Group - Align with Merge Custom series added to existing series group will be retained along with any standard series in that group.
Tables - Ignore Existing tables are retained.
Columns - Ignore Existing columns are retained.
Indexes - Ignore Existing indexes are retained.
Index Columns - Ignore Existing index columns are retained.
Engine Profiles - Ignore Existing engine profiles are retained.
SPF Series Definitions - Aligned If there is a change in the model between the existing and new SPF series definitions, the existing model is aligned (overwritten) with the new version.
Component Content Groups - Ignore All sub-objects under Component Content Groups are ignored.
User Content Groups - Ignore All sub-objects under User Content Groups are ignored.
Portal User Childpanes - Ignore Existing user childpanes are retained.
INIT_PARAMS   Ignore Existing parameters are retained.
SYS_PARAMS   Ignore Existing parameters are retained.
APS_PARAMS   Ignore Existing parameters are retained.
Any other objects not mentioned in this table - Align Objects not specifically mentioned in this table are aligned to the new version.

Based on your settings, the Object Resolution dialog box displays default upgrade suggestions for each object during the upgrade process. Choices can be changed on an object-by-object basis using the Set Object Resolution option.

To set the global upgrade preferences:

  1. From the Settings menu, select Upgrade Settings. The Upgrade Settings dialog box appears.

    the picture is described in the document text

    Note: New objects are always inserted.

  2. For Overlapping Objects, select:

    • Insert Duplicate Object: Objects exist in both the original and new schema definitions. The original object is suffixed as "objectname_version number_build number", while the new object is created as a duplicate object with the same name as in the Demantra standard schema. See Naming Convention for Duplicate Objects for more information.

      Note: Only overlapping objects that have changed between the current and new versions are duplicated.

    • Align to New Object: Original objects are merged with the objects in the new version schema definition. In cases where the table indicates "Align with Merge", the original objects are merged with the new objects; both exist after the upgrade.

    • Ignore New Object: Existing object is retained in its original form; new version of the object is ignored.

    • Default: Objects and sub-objects are upgraded based on the action type specified in the Table of Default Upgrade Actions for Overlapping Objects, earlier in this guide.

  3. Click Apply. All upgrade suggestions are based on these upgrade setting preferences from this point forward.

Upgrading the Objects in a Folder

To add objects from one schema to another, you create a folder in the target schema. Once you have added objects to the folder, you can upgrade these objects to the target schema database. During the upgrade process, the BAL Explorer checks to see whether all the necessary related objects, such as levels and series, exist in the schema. If not, you are prompted to substitute other objects or cancel the operation. Some objects may require configuration changes. These changes can be implemented through the Business Modeler.

Note: If you want to add more objects after you have upgraded a folder, add the objects to a new folder and, when ready, upgrade that folder.

To upgrade objects in a folder:

  1. Right-click the folder that you want to upgrade.

  2. Select Upgrade.

Upgrading Schemas

Upgrading a schema begins with comparing two schemas to detect differences. The BAL Explorer compares the schemas object by object, and it returns a detailed report that itemizes the differences. This report can be saved in html format for future reference. If you are satisfied with the comparison, you can prepare the upgrade package. Once the upgrade package has been prepared, you can start the upgrade process.

Note: When upgrading from the installer, the BAL Explorer automatically performs the comparison of the two schemas and displays the report. The upgrade package is created automatically.

If you have chosen the upgrade setting that allows you to change the resolution action, you will be able to choose how to handle the differences between schemas on an object-by-object basis. BAL then processes the schema upgrade. Finally, the Business Modeler launches and you activate the configuration changes to complete the upgrade. The following diagram illustrates the upgrade process:

the picture is described in the document text

The schema repository, which contains all upgrades to that particular schema, is not deleted after the upgrade unless you choose to remove it completely. It is updated with future upgrades.

To upgrade a schema:

Note: If you are upgrading manually from the installer, go directly to the Compare Results step. The other steps are performed automatically.

  1. Click the source schema (the original schema).

  2. Ctrl-click the target schema (the new schema).

  3. For manual upgrades, right-click one of the selected schemas and select Compare. The Compare Results screen appears, listing the objects that differ between the two schemas. The system displays the source schema on the left (AS_V122_TIMESTAMP) and the target schema on the right (TS_V122_TIMESTAMP).

    The installer takes you directly to the Compare Results screen.

    Note: Once you have selected the manual upgrade, the installer begins to upgrade the schema and prepare the BAL repositories. The Manual Upgrade screen appears while the BAL Explorer is comparing the source and target schemas. Both the Next and the Previous buttons are grayed out during this process. The comparison may take a long time, and during this time, the BAL Explorer may appear to be gray for the most part. To see whether the comparison is still running, note the bottom left-hand corner in the BAL Explorer. A status bar displays the comparison currently being done.

    the picture is described in the document text

  4. Click Show full details to show the specific differences between the schemas.

  5. Click Save to save the report in html format for future reference. The html reports are saved in the <Demantra install folder>\Demand Planner\BAL\logs\AS_V122_Timestamp to TS_V122_Timestamp folder. You can print the report from the saved document. Review the html comparison reports in detail to determine the optimum upgrade actions to use on your schema.

  6. If you are not upgrading from the installer, click Prepare Upgrade for <schema alias name>. A progress bar appears so you can monitor the production of the upgrade package. When complete, the upgrade package appears in the Schema Browser before the schema object folder. In the following example, the AS_V122_20080221_2031 schema was prepared for upgrading. The upgrade folder appears before the schema object folder:

    the picture is described in the document text

  7. Click Close to close the Compare Results dialog box.

  8. From the Settings menu, select Set Object Resolution. This selection enables you to modify the upgrade suggestions for each object individually.

  9. Right-click the upgrade package and select Upgrade. The Object Resolution dialog box appears. The type of object conflict appears with the action suggested based on your global upgrade settings.

    the picture is described in the document text

  10. Choose how you want to handle each new or overlapping object.

    For each new object, your options are:

    • Insert: Add the new object to the target database.

    • Default: Add the new object to the target database.

    For each overlapping object, your options are:

    • Align to New: Align the source object with the target schema object.

    • Insert Duplicate: Create the new version of the object as a duplicate in the target schema.

      Note: This option may not be available depending on the type of object.

    • Ignore: Retain the source object in its original form and ignore the new version of the object in the target schema.

    • Default: Objects and their sub-objects are upgraded according to the Table of Default Upgrade Actions for Overlapping Objects. .

  11. Click Apply when done. The source schema is upgraded to the target schema format based on your upgrade choices. A progress bar appears.

  12. If there are any issues that need your intervention to resolve, the activation issues list is displayed. These issues can occur if you accidentally delete any objects that are referred to by other objects in the upgrade package.

    the picture is described in the document text

    For each issue displayed, you can accept the default Drop Reference which removes the link between the new objects and the existing object.

  13. When you have specified how to deal with all the issues presented, click OK.

  14. A prompt appears when the BAL application upgrade is complete. The following prompt is displayed for those upgrading using the installer. A different prompt appears if you are running the BAL without the installer.

    the picture is described in the document text

    Important: Do not close the BAL utility before receiving the prompt or the upgrade may fail.

    Click OK to continue.

  15. Close the BAL Explorer. If you are upgrading through the installer, the Business Modeler application opens automatically (this may take a few minutes). Otherwise, start the Business Modeler to continue the upgrade process.

  16. The Validate BAL Import screen appears. If you are not updating from the installer, from the Configuration menu, select Validate BAL Import, and select the update package to continue.

    the picture is described in the document text

  17. Click the Activate button. The configuration changes are made through the Business Modeler to the database.

  18. Close the Business Modeler. A prompt appears that indicates that warnings were encountered while trying to activate some objects.

  19. Click Resume (recommended) to return to the installer. Alternatively, click View to log file or Exit to quit the installation.

  20. Click Done to complete the installation. For more details about the upgrade, review the bal_bm.log.

Using BAL to Migrate Application Objects

You can use the BAL Explorer to migrate objects (for example series, levels, and worksheets) between schemas – for example between test and production environments. The BAL Explorer organizes objects together as packages, so that you can open previously-used packages, and manage their contents by adding or deleting objects. With packages you can break down schemas into separate solutions and maintain them in the BAL Explorer.

Important: The source and destination schemas must be from the same Demantra version and patch level. BAL cannot be used to migrate database tables, indexes, procedures, as well as content in the INIT_PARAMS_%, SYS_PARAMS, and APS_PARAMS tables.

When you copy an object to a package all its dependencies are copied as well. For example, by copying a series to a package its users are copied too as references. At a high level, migrating your Oracle Demantra configuration is done via BAL in two steps:

  1. Building the BAL repository.

  2. Migrate the objects using either a standard or custom upgrade folder.

Building the BAL Repository

To build the BAL repository:

  1. Start the BAL Explorer. On the machine where Demantra is installed, navigate to the <Demantra Install>\Demand Planner\BAL\ and double-click on the file 'bal.bat'.

  2. Make sure you have a connection to the schemas that you want to migrate. For more information, see Creating a Schema Connection.

  3. Right-click on each of the schema connections and then click Rebuild. This builds the BAL repository for this schema.

Migrating Objects Using a Standard Upgrade Folder

Oracle recommends this option if you have many objects to migrate, or if you were not aware of all the specific differences between the two schemas.

To migrate objects using a standard upgrade folder:

  1. Compare the schemas. Select both schemas, and then right-click and click Compare.

    BAL Explorer compares the schemas for differences, which may take a few minutes to complete. Once the comparison is complete, BAL Explorer displays a report of the differences.

  2. Review the comparison report, and then save it by clicking the Save button.

    This saves the reports in an HTML format in: <Demantra Install Folder>\Demand Planner\BAL\Logs

  3. Open the HTML report file that starts with the name 'Summary_'.

  4. Review the details of the summary report and ensure you see the overlapping and/or new objects that you expect to see in each schema.

  5. Create the upgrade package. Return to the BAL Comparison screen click on the Prepare Upgrade for <schema alias name> button. This creates an upgrade package, UPGRADE_DEV_SCHEMA to PROD_SCHEMA.

  6. Select your upgrade settings:

    1. From the Settings menu, choose Upgrade Settings.

      The Upgrade Settings dialog box appears.

    2. Select the global upgrade settings:

      • Default - Objects are handled in their default manner. For a list of default operations, see the Table of Default Upgrade Actions.

      • Insert Duplicate Object – The object in PROD_SCHEMA is retained as-is and the corresponding object from DEV_SCHEMA is inserted into PROD_SCHEMA as a duplicate object, with a application version suffix (i.e. _7.2.0.2, _12.2).

      • Align to New Object – The object in PROD_SCHEMA is replaced by the object in DEV_SCHEMA.

      • Ignore New Object – The object in PROD_SCHEMA is retained as-is and the object definition as in DEV_SCHEMA is not applied to PROD_SCHEMA.

      Note: Selections made here apply to all objects.

  7. Selectively override the global upgrade settings at the object level:

    1. From the Settings menu, select Object Resolution.

    2. Click on the upgrade package created, and right-click and then click Upgrade.

    3. Select the upgrade action for those objects for which you want to override the global default:

      • Default - Objects are handled in their default manner. For a list of default operations, see the Table of Default Upgrade Actions.

      • Insert Duplicate Object – The object in PROD_SCHEMA is retained as-is and the corresponding object from DEV_SCHEMA is inserted into PROD_SCHEMA as a duplicate object, with a application version suffix (that is, _7.2.0.2, _12.2).

      • Align to New Object – The object in PROD_SCHEMA is replaced by the object in DEV_SCHEMA.

      • Ignore New Object – The object in PROD_SCHEMA is retained as-is and the object definition as in DEV_SCHEMA isl not applied to PROD_SCHEMA.

    4. After overriding the selections, click Apply in the Object Resolution window.

      This starts the process of migrating the objects from DEV_SCHEMA to PROD_SCHEMA. This will take some time depending on the number of objects to be migrated.

  8. The Demantra Business Modeler opens at the end of the migration process and lists the objects that need to be activated for the migration to be complete.

    Note: Only levels, series, integration profiles, users, data model, and units require Business Modeler activation.

  9. To complete the migration, click the Activate button.

    Note: The activation process can take a few minutes and when the process completes successfully a message displays indicating that the activation is complete.

Migrating Objects using a Custom Upgrade Folder

Demantra recommends this option when you know specific list of objects to be migrated, or want to create a custom upgrade package.

  1. Create the custom upgrade folder:

    1. Right click on PROD_SCHEMA and then click Create Folder.

    2. Enter a name for the custom folder and then press Enter.

  2. Copy and paste the objects to be migrated to the custom folder:

    1. Expand DEV_SCHEMA and select the objects that you want to migrate.

    2. Right-click the selected objects and then click Copy.

    3. Click on the custom folder and right-click and click Paste.

      This moves the objects from the DEV_SCHEMA into the custom folder.

    4. Repeat this process for all objects that you want to migrate.

  3. From the Settings menu, choose Upgrade Settings.

    1. From the Settings menu, choose Upgrade Settings.

      The Upgrade Settings dialog box appears.

    2. Select the global upgrade settings:

      • Insert Duplicate Object – The object in PROD_SCHEMA is retained as-is and the corresponding object from DEV_SCHEMA is inserted into PROD_SCHEMA as a duplicate object, with a application version suffix (i.e. _7.2.0.2, _12.2).

      • Align to New Object – The object in PROD_SCHEMA is replaced by the object in DEV_SCHEMA.

      • Ignore New Object – The object in PROD_SCHEMA is retained as-is and the object definition as in DEV_SCHEMA isl not applied to PROD_SCHEMA.

      Note: Selections made here apply to all objects.

  4. Selectively override the global upgrade settings at the object level:

    1. From the Settings menu, select Object Resolution.

    2. Click on the upgrade package created, and right-click and then click Upgrade.

    3. Select the upgrade action for those objects for which you want to override the global default.

    4. After overriding the selections, click Apply in the Object Resolution window.

      This starts the process of migrating the objects from DEV_SCHEMA to PROD_SCHEMA. This will take some time depending on the number of objects to be migrated.

  5. The Demantra Business Modeler opens at the end of the migration process and lists the objects that need to be activated for the migration to be complete.

  6. To complete the migration, click the Activate button.

    Note: The activation process can take a few minutes and at the end of it a message will be displayed indicating that the activation is complete.

Loading and Saving BAL Packages

Each BAL package contains a set of objects which form a business solution. Administrators can manually create their own package and copy-paste BAL objects into the package. These packages can be saved into a file and then used to upgrade the schema using this new package.

To load a BAL package:

  1. Right-click on a schema in the Schema Browser pane and then click Load from File.

    The Open dialog box appears.

  2. Select the appropriate XML package to load and then click Open.

To save a BAL package:

  1. Right-click on a schema in the Schema Browser pane and then click Save to File.

    The Save dialog box appears.

  2. Select the destination folder and then click Save.

Validating Packages

A package can have references to objects which are not part of the schema that you want to update. It is important to validate packages to make sure that they do not have unresolved references.

To validate a package:

  1. In the BAL Explorer, right click on the package and select Validate.

    The Select Schema dialog box appears.

  2. Choose the schema from which you want to validate the package against and click OK.

    Demantra validates the package against the selected schema and displays the results in the Validation window.

  3. To resolve any outstanding issues, click the Add Unresolved Objects to the Package button.

  4. Click Close.

Troubleshooting

Starting The BAL Explorer Application

For the following troubleshooting options, you must start the BAL Explorer manually. From the <Demantra install directory>\Demand Planner\BAL, and double-click on bal.bat.

Viewing Transactions

The View Transactions window displays information about all the schema upgrades that have been made within BAL, including the status, description, root, column, object table, type, and error message. You can filter the results by schema or transaction.

To view transactions, open the BAL Explorer application, select Transactions. The View Transactions window appears.

the picture is described in the document text

Including the Upgrade SQL in the Log File

You can view the PL/SQL run by the BAL Explorer during the upgrade once the upgrade is complete. The SQL appears in the bal_log.txt file located in the <Demantra install directory>\Demand Planner\BAL\Logs directory. This option provides you with many more details about the upgrade than would normally be captured.

To include the upgrade SQL in the bal_log.txt file:

  1. From the View menu, select View Upgrade SQL.

  2. Perform a folder or schema upgrade.

  3. When complete, open the <Demantra install directory>\Demand Planner\BAL\Logs\bal_log.txt file to view the upgrade details.

Viewing Log Files

If your upgrade fails, you may find the reasons for the failure in the log file. The bal_log.txt file and the log.properties files are located as follows:

You can customize the amount of detail shown in the bal_log.txt file by altering the settings in this file.

Note: BAL creates a table “bal_version_history” which records rebuild and upgrade actions done by BAL. This table is useful for debugging or identifying if a schema went through an application upgrade.