13 Working with Scenarios

This chapter describes how to work with scenarios. A scenario is designed to put a source component (interface, package, procedure, variable) into production. A scenario results from the generation of code (SQL, shell, etc) for this component.

This chapter includes the following sections:

13.1 Introduction to Scenarios

When a component is finished and tested, you can generate the scenario corresponding its actual state. This operation takes place in Designer Navigator.

The scenario code (the language generated) is frozen, and all subsequent modifications of the components which contributed to creating it will not change it in any way.

It is possible to generate scenarios for packages, procedures, interfaces or variables. Scenarios generated for procedures, interfaces or variables are single step scenarios that execute the procedure, interface or refresh the variable.

Scenario variables are variables used in the scenario that should be set when starting the scenario to parameterize its behavior.

Once generated, the scenario is stored inside the work repository. The scenario can be exported then imported to another repository (remote or not) and used in different contexts. A scenario can only be created from a development work repository, but can be imported into both development and execution work repositories.

Scenarios appear in a development environment under the source component in the Projects tree of Designer Navigator, and appear - for development and production environments - in the Scenarios tree of Operator Navigator.

Scenarios can also be versioned. See Chapter 19, "Working with Version Management" for more information.

Scenarios can be launched from a command line, from the Oracle Data Integrator Studio and can be scheduled using the built-in scheduler of the run-time agent or an external scheduler. Scenario execution and scheduling scenarios is covered in Chapter 21, "Running Integration Processes".

13.2 Generating a Scenario

Generating a scenario for an object compiles the code for this object for deployment and execution in a production environment.

To generate a scenario:

  1. In Designer Navigator double-click the Package, Interface, Procedure or Variable under the project for which you want to generate the scenario. The corresponding Object Editor opens.

  2. On the Scenarios tab, click Generate Scenario. The New Scenario dialog appears.

  3. Enter the Name and the Version of the scenario. As this name can be used in an operating system command, the name is automatically uppercased and special characters are replaced by underscores.

    Note that the Name and Version fields of the Scenario are preset with the following values:

    • Name: The same name as the latest scenario generated for the component

    • Version: The version number is automatically incremented (if the latest version is an integer) or set to the current date (if the latest version is not an integer)

    If no scenario has been created yet for the component, a first version of the scenario is automatically created.

    New scenarios are named after the component according to the Scenario Naming Convention user parameter. See Appendix B, "User Parameters" for more information.

  4. Click OK.

  5. If you use variables in the scenario, you can define in the Scenario Variables dialog the variables that will be considered as parameters for the scenario.

    • Select Use All if you want all variables to be parameters

    • Select Use Selected to use the selected variables to be parameters

    • Select None to unselect all variables

  6. Click OK.

The scenario appears on the Scenarios tab and under the Scenarios node of the source object under the project.

13.3 Regenerating a Scenario

An existing scenario can be regenerated with the same name and version number. This lets you replace the existing scenario by a scenario generated from the source object contents. Schedules attached to this scenario are preserved.

To regenerate a scenario:

  1. Select the scenario in the Projects accordion.

  2. Right-click and select Regenerate...

  3. Click OK.

Caution:

Regenerating a scenario cannot be undone. For important scenarios, it is better to generate a scenario with a new version number.

13.4 Generating a Group of Scenarios

When a set of packages, interfaces, procedures and variables grouped under a project or folder is finished and tested, you can generate the scenarios. This operation takes place in Designer Navigator.

To generate a group of scenarios:

  1. Select the Project or Folder containing the group of objects.

  2. Right-click and select Generate All Scenarios...

  3. In the Scenario Generation dialog, select the scenario Generation Mode:

    • Replace: Overwrites for each object the last scenario version with a new one with the same ID, name and version. Sessions, scenario reports and schedules are deleted. If no scenario exists for an object, a scenario with version number 001 is created.

    • Re-generate: Overwrites for each object the last scenario version with a new one with the same id, name and version. It preserves the schedule, sessions and scenario reports. If no scenario exists for an object, no scenario is created using this mode.

    • Creation: Creates for each object a new scenario with the same name as the last scenario version and with an automatically incremented version number. If no scenario exists for an object, a scenario named after the object with version number 001 is created.

    Note:

    If no scenario has been created yet for the component, a first version of the scenario is automatically created.

    New scenarios are named after the component according to the Scenario Naming Convention user parameter. See Appendix B, "User Parameters" for more information

    If the version of the last scenario is an integer, it will be automatically incremented by 1 when selecting the Creation generation mode. If not, the version will be automatically set to the current date.

  4. In the Objects to Generate section, select the types of objects for which you want to generate scenarios.

  5. In the Marker Filter section, you can filter the components to generate according to a marker from a marker group.

  6. Click OK.

  7. If you use variables in the scenario, you can define in the Scenario Variables dialog the variables that will be considered as parameters for the scenario. Select Use All if you want all variables to be parameters, or Use Selected and check the parameter variables.

13.5 Exporting Scenarios

The export (and import) procedure allows you to transfer Oracle Data Integrator objects from one repository to another.

It is possible to export a single scenario or groups of scenarios.

Exporting one single scenario is covered in Section 20.2.4, "Exporting one ODI Object".

To export a group of scenarios:

  1. Select the Project or Folder containing the group of scenarios.

  2. Right-click and select Export All Scenarios... The Export all scenarios dialog opens.

  3. In the Export all scenarios dialog, specify the export parameters as follows:

    Parameter Description

    Export Directory

    Directory in which the export file will be created.

    Note that if the Export Directory is not specified, the export file is created in the Default Export Directory.

    Child components export

    If this option is checked, the objects linked to the object to be exported will be also exported. These objects are those visible under the exported object in the tree. It is recommended to leave this option checked. See Exporting an Object with its Child Components for more details.

    Replace existing files without warning

    If this option is checked, the existing file will be replaced by the ones of the export.


  4. Select the type of objects whose scenarios you want to export.

  5. Set the advanced options. This set of options allow to parameterize the XML output file format. It is recommended that you leave the default values.

  6. Parameter Description

    XML Version

    XML Version specified in the export file. Parameter xml version in the XML file header.

    <?xml version="1.0" encoding="ISO-8859-1"?>

    Character Set

    Encoding specified in the export file. Parameter encoding in the XML file header.

    <?xml version="1.0" encoding="ISO-8859-1"?>

    Java Character Set

    Java character set used to generate the file.


  7. Click OK.

The XML-formatted export files are created at the specified location.

13.6 Importing Scenarios in Production

A scenario generated from Designer can be exported and then imported into a development or execution repository. This operation is used to deploy scenarios in a different repository, possibly in a different environment or site.

Importing a scenario in a development repository is performed via Designer or Operator Navigator. With a execution repository, only Operator Navigator is available for this purpose.

There are two ways to import a scenario:

  • Import uses the standard object import method. During this import process, it is possible to choose to import the schedules attached to the exported scenario.

  • Import Replace replaces an existing scenario with the content of an export file, preserving references from other objects to this scenario. Sessions, scenario reports and schedules from the original scenario are deleted and replaced with the schedules from the export file.

Scenarios can also be deployed and promoted to production using versions and solutions. See Chapter 19, "Working with Version Management" for more information.

13.6.1 Import Scenarios

To import one or more scenarios into Oracle Data Integrator:

  1. In Operator Navigator, select the Scenarios panel.

  2. Right-click and select Import > Import Scenario.

  3. Select the Import Type. Refer to Chapter 20, "Exporting/Importing" for more information on the import types.

  4. Specify the File Import Directory.

  5. Check the Import schedules option, if you want to import the schedules exported with the scenarios as well.

  6. Select one or more scenarios to import from the Select the file(s) to import list.

  7. Click OK.

The scenarios are imported into the work repository. They appear in the Scenarios tree of the Operator Navigator. If this work repository is a development repository, these scenario are also attached to their source Package, Interface, Procedure or Variable.

13.6.2 Replace a Scenario

Use the import replace mode if you want to replace a scenario with an exported one.

To import a scenario in replace mode:

  1. In Designer or Operator Navigator, select the scenario you wish to replace.

  2. Right-click the scenario, and select Import Replace...

  3. In the Replace Object dialog, specify the scenario export file.

  4. Click OK.

13.6.3 Working with a Scenario from a Different Repository

A scenario may have to be operated from a different work repository than the one where it was generated.

Examples

Here are two examples of organizations that give rise to this type of process:

  • A company has a large number of agencies equipped with the same software applications. In its IT headquarters, it develops packages and scenarios to centralize data to a central data center. These scenarios are designed to be executed identically in each agency.

  • A company has three distinct IT environments for developing, qualifying and operating its software applications. The company's processes demand total separation of the environments, which cannot share the Repository.

Prerequisites

The prerequisite for this organization is to have a work repository installed on each environment (site, agency or environment). The topology of the master repository attached to this work repository must be compatible in terms of its logical architecture (the same logical schema names). The connection characteristics described in the physical architecture can differ.

Note that in cases where some procedures or interfaces explicitly specify a context code, the target topology must have the same context codes. The topology, that is, the physical and logical architectures, can also be exported from a development master repository, then imported into the target repositories. Use the Topology module to carry out this operation. In this case, the physical topology (the servers' addresses) should be personalized before operating the scenarios. Note also that a topology import simply references the new data servers without modifying those already present in the target repository.

To operate a scenario from a different work repository:

  1. Export the scenario from its original repository (right-click, export)

  2. Forward the scenario export file to the target environment

  3. Open Designer Navigator in the target environment (connection to the target repository)

  4. Import the scenario from the export file

13.7 Encrypting and Decrypting a Scenario

Encrypting a scenario allows you to protect valuable code. An encrypted scenario can be executed but cannot be read or modified if it is not decrypted. The commands generated in the log by an encrypted scenario are also unreadable.

Oracle Data Integrator uses a DES Encryption algorithm based on a personal encryption key. This key can be saved in a file and can be reused to perform encryption or decryption operations.

WARNING:

There is no way to decrypt an encrypted scenario or procedure without the encryption key. It is therefore strongly advised to keep this key in a safe location.

To encrypt a scenario:

  1. In Designer or Operator Navigator, select the scenario you want to encrypt.

  2. Right-click and select Encrypt.

  3. In the Encryption Options dialog, you can either:

    • Encrypt with a personal key that already exists by giving the location of the personal key file or by typing in the value of the personal key.

    • Get a new encryption key to have a new key generated.

  4. Click OK to encrypt the scenario. If you have chosen to generate a new key, a dialog will appear with the new key. Click Save to save the key in a file.

Note:

If you type in a personal key with too few characters, an invalid key size error appears. In this case, please type in a longer personal key. A personal key of 10 or more characters is required.

To decrypt a scenario:

  1. Right-click the scenario you want to decrypt.

  2. Select Decrypt.

  3. In the Scenario Decryption dialog, either

    • Select an existing encryption key file

    • or type in (or paste) the string corresponding to your personal key.

A message appears when decryption is finished.