This chapter describes how to work with scenarios. A scenario is designed to put a source component (mapping, 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:
When a component is finished and tested, you can generate the scenario corresponding to its actual state. This operation takes place in the 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, mappings, or variables. Scenarios generated for procedures, mappings, or variables are single step scenarios that execute the procedure, mapping, 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, and 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 both the Operator and Designer Navigators, in the Load Plans and Scenarios section. Scenarios can also appear within a project in the Projects section of the Designer navigator.
Scenarios can also be versioned. See Chapter 19, "Using Version Control (Legacy Mode)," 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 "Running Integration Processes" in Administering Oracle Data Integrator.
Generating a scenario for an object compiles the code for this object for deployment and execution in a production environment.
To generate a scenario:
In Designer Navigator double-click the Package, Mapping, Procedure or Variable under the project for which you want to generate the scenario. The corresponding Object Editor opens. Then, on the ODI menu, select Generate and then Scenario. The New Scenario dialog appears.
Alternatively, from the Designer Navigator, right-click a Package, Mapping, Procedure or Variable, and select Generate Scenario.... The New Scenario dialog appears.
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, or set to 001 if no prior numeric version exists
If no scenario has been created yet for the component, a first version of the scenario is automatically created.
Note:
New scenarios are named after the component according to the Scenario Naming Convention user parameter. You can set this parameter by clicking Preferences from the Tools option on the menu bar; expand the ODI node, and then the System node, and select the Scenarios node.Click OK.
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 deselect all variables
Click OK.
The scenario appears on the Scenarios tab and under the Scenarios node of the source object under the project.
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:
Select a scenario in the Projects or Load Plans and Scenarios section of the Designer Navigator.
Right-click and select Regenerate...
Click OK.
Caution:
Regenerating a scenario cannot be undone. For important scenarios, it is better to generate a scenario with a new version number.When a set of packages, mappings, 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:
Select the Project or Folder containing the group of objects.
Right-click and select Generate All Scenarios...
In the Scenario Source Objects section, select the types of objects for which you want to generate scenarios.
In the Marker Filter section, you can filter the components to generate according to a marker from a marker group.
Select the scenario Generation Mode:
Replace: Overwrites for each object the last scenario version with a new one with the same internal 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 internal ID, name and version. It preserves the schedule, sessions, scenario reports, variable selections, and concurrent execution control settings. 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. You can set this parameter by clicking Preferences from the Tools option on the menu bar; expand the ODI node, and then the System node, and select the Scenarios node.
When selecting the Creation generation mode, the version number is automatically incremented, or set to 001 if no prior numeric version exists.
Select Generate scenario as if all underlying objects are materialized to generate the scenario as if the shortcuts were real objects.
Click OK.
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.
By default, nothing prevents two instances of the same scenario or load plan from running simultaneously.
This situation could occur in several ways. For example:
A load plan containing a Run Scenario Step is running in two or more instances, so the Run Scenario Step may be executed at the same time in more than one load plan instance.
A scenario is run from the command line, from ODI Studio, or as scheduled on an agent, while another instance of the same scenario is already running (on the same or a different agent or ODI Studio session.
Concurrent executions of the same scenario or load plan apply across all remote and internal agents.
Concurrent execution of multiple instances of a scenario or load plan may be undesirable, particularly if the job involves writing data. You can control concurrent execution using the Concurrent Execution Control options.
ODI identifies a specific scenario or load plan by its internal ID, and not by the name and version. Thus, a regenerated or modified scenario or load plan having the same internal ID is still treated as the same scenario or load plan. Conversely, deleting a scenario and generating a new one with the same name and version number would be creating a different scenario (because it will have a different internal ID).
While Concurrent Execution Control can be enabled or disabled for a scenario or load plan at any time, there are implications to existing running sessions and newly invoked sessions:
When switching Concurrent Execution Control from disabled to enabled, existing running and queued jobs are counted as executing jobs and new job submissions are processed with the Concurrent Execution Control settings at time of job submission.
When switching Concurrent Execution Control from enabled to disabled for a scenario or load plan, jobs that are already submitted and in waiting state (or those that are restarted later) will carry the original Concurrent Execution Control setting values to consider and wait for running and queued jobs as executing jobs.
However, if new jobs are submitted at that point with Concurrent Execution Control disabled, they could be run ahead of already waiting jobs. As a result, a waiting job may be delayed if, at the time of polling, the system finds executing jobs that were started without Concurrent Execution Control enabled. And, after a waiting job eventually starts executing, it may still be affected by uncontrolled jobs submitted later and executing concurrently.
To limit concurrent execution of a scenario or load plan, perform the following steps:
Open the scenario or load plan by right-clicking it in the Designer or Operator Navigators and selecting Open.
Select the Definition tab and modify the Concurrent Execution Controller options:
Enable the Limit Concurrent Executions check box if you do not want to allow multiple instances of this scenario or load plan to be run at the same time. If Limit Concurrent Executions is disabled (unchecked), no restriction is imposed and more than one instance of this scenario or load plan can be run simultaneously.
If Limit Concurrent Executions is enabled, set your desired Violation Behavior:
Raise Execution Error: if an instance of the scenario or load plan is already running, attempting to run another instance will result in a session being created but immediately ending with an execution error message identifying the session that is currently running which caused the Concurrent Execution Control error.
Wait to Execute: if an instance of the scenario or load plan is already running, additional executions will be placed in a wait status and the system will poll for its turn to run. The session's status is updated periodically to show the currently running session, as well as all concurrent sessions (if any) that are waiting in line to run after the running instance is complete.
If you select this option, the Wait Polling Interval sets how often the system will check to see if the running instance has completed. You can only enter a Wait Polling Interval if Wait to Execute is selected.
If you do not specify a wait polling interval, the default for the executing agent will be used: in ODI 12.1.3, the default agent value is 30 seconds.
Click Save to save your changes.
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 "Exporting one ODI Object".
To export a group of scenarios:
Select the Project or Folder containing the group of scenarios.
Right-click and select Export All Scenarios... The Export all scenarios dialog opens.
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. |
Select the type of objects whose scenarios you want to export.
Set the encryption options. Set an Export Key if you want the exported scenario to preserve and encrypt sensitive data such as passwords. You will need to supply this Export Key when you later import this scenario if you want to import and decrypt the sensitive data.
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.
| Parameter | Description |
|---|---|
| XML Version | XML Version specified in the export file. Parameter xml version in the XML file header.
|
| Character Set | Encoding specified in the export file. Parameter encoding in the XML file header.
|
| Java Character Set | Java character set used to generate the file. |
Click OK.
The XML-formatted export files are created at the specified location.
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 with the Designer or Operator Navigator. With an execution repository, only the 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, "Using Version Control (Legacy Mode)," for more information.
To import one or more scenarios into Oracle Data Integrator:
In Operator Navigator, select the Scenarios panel.
Right-click and select Import > Import Scenario.
Select the Import Type. Refer to Chapter 23, "Exporting and Importing," for more information on the import types.
Specify the File Import Directory.
Check the Import schedules option, if you want to import the schedules exported with the scenarios as well.
Select one or more scenarios to import from the Select the file(s) to import list.
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, Mapping, Procedure, or Variable.
Use the import replace mode if you want to replace a scenario with an exported one.
To import a scenario in replace mode:
In Designer or Operator Navigator, select the scenario you wish to replace.
Right-click the scenario, and select Import Replace...
In the Replace Object dialog, specify the scenario export file.
Click OK.
A scenario may have to be operated from a different work repository than the one where it was generated.
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.
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 mappings 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:
Export the scenario from its original repository (right-click, export)
Forward the scenario export file to the target environment
Open Designer Navigator in the target environment (connection to the target repository)
Import the scenario from the export file
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:
In Designer or Operator Navigator, select the scenario you want to encrypt.
Right-click and select Encrypt.
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.
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.To decrypt a scenario:
Right-click the scenario you want to decrypt.
Select Decrypt.
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.