Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Data Integrator
11g Release 1 (11.1.1)

Part Number E12643-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

21 Running Integration Processes

This chapter describes how to run and schedule integration processes.

This chapter includes the following sections:

21.1 Understanding ODI Executions

An execution takes place when an integration task needs to be performed by Oracle Data Integrator. This integration task may be one of the following:

Oracle Data Integrator generates the code for an execution in the form of a session or in the form of a Load Plan run if a Load Plan is executed.

A run-time Agent processes this code and connects to the sources and targets to perform the data integration. These sources and targets are located by the Agent using a given execution context.

When an execution is started from Oracle Data Integrator Studio, the Execution Dialog is displayed. This dialog contains the execution parameters listed in Table 21-1.

Table 21-1 Execution Parameters

Properties Description

Context

The context into which the session is started.

Agent

The agent which will execute the interface. The object can also be executed using the agent that is built into Oracle Data Integrator Studio, by selecting Local (No Agent).

Log Level

Level of logging information to retain. All session tasks with a defined log level lower than or equal to this value will be kept in the Session log when the session completes. However, if the object execution ends abnormally, all tasks will be kept, regardless of this setting.

Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

Simulation

Check Simulation if you want to simulate the execution and create an execution report. Refer to Section 21.10, "Simulating an Execution" for more information.


Session Lifecycle

This section describes the session lifecycle. See Section 14.1, "Introduction to Load Plans" for more information on Load Plan runs and the Load Plan life cycle.

The lifecycle of a session is as follows:

  1. An execution request is sent to the agent, or the agent triggers an execution from a schedule.

    Note that if the execution is triggered from Oracle Data Integrator Studio on a design-time object (interface, package, etc.), Studio pre-generates in the work repository the code for the session before sending the request. If the execution is started from a scenario, this phase is not necessary as the scenario already contains pre-generated code.

  2. The agent completes code generation for the session: It uses the context provided to resolve the physical information such as data server connections and fully qualified tables names. This resulting code is written into the work repository as a session in Waiting status.

  3. The agent initializes the connections to the source and target data servers that are required for the execution of the session.

  4. The agent acknowledges the execution request. If the execution was started from the Studio, the Session Started Dialog is displayed.

  5. The agent executes each of the tasks contained in this session, using the capabilities of the database servers, operating systems, or scripting engines to run the code contained in the session's tasks.

  6. While processing the session, the agent updates the execution log in the repository, reports execution statistics and error messages.

    Once the session is started, you can monitor it in the log, using for example Operator Navigator. Refer to Chapter 22, "Monitoring Integration Processes" for more information on session monitoring.

  7. When the session completes, tasks are preserved or removed from the log according to the log level value provided when starting for this session.

Note:

A Session is always identified by a unique Session Number (or Session ID). This number can be viewed when monitoring the session, and is also returned by the command line or web service interfaces when starting a session.

When starting an execution from other locations such as a command line or a web service, you provide similar execution parameters, and receive a similar Session Started feedback. If the session is started synchronously from a command line or web service interface, the command line or web service will wait until the session completes, and provide the session return code and an error message, if any.

21.2 Executing Interfaces, Procedures, Packages and Model Operations

Interfaces, procedures, and packages are design-time objects that can be executed from the Designer Navigator of Oracle Data Integrator Studio:

21.3 Executing a Scenario

Scenarios can be executed in several ways:

Note:

Before running a scenario, you need to have the scenario generated from Designer Navigator or imported from a file. Refer to Chapter 13, "Working with Scenarios" for more information.

21.3.1 Executing a Scenario from ODI Studio

You can start a scenario from Oracle Data Integrator Studio from Designer or Operator Navigator.

To start a scenario from Oracle Data Integrator Studio:

  1. Select the scenario in the Projects accordion (in Designer Navigator) or the Scenarios accordion (in Operator Navigator).

  2. Right-click, then select Execute.

  3. In the Execution dialog, set the execution parameters. Refer to Table 21-1 for more information. To execute the scenario with the agent that is built into Oracle Data Integrator Studio, select Local (No Agent).

  4. Click OK.

  5. If the scenario uses variables as parameters, the Variable values dialog is displayed. Select the values for the session variables. Selecting Latest value for a variable uses its current value, or default value if none is available.

When the agent has started to process the session, the Session Started dialog appears.

21.3.2 Executing a Scenario from a Command Line

You can start a scenario from a command line.

Before executing a scenario from a command line, read carefully the following requirements:

  • The command line scripts, which are required for performing the tasks described in this section, are only available if you have installed the Oracle Data Integrator Standalone Agent. See the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for information about how to install the Standalone Agent.

  • To use this command the connection to your repository must be configured in the odiparams file. See Chapter 4, "Managing Agents" for more information.

  • When starting a scenario from a command line, the session is not started by default against a remote run-time agent, but is executed by a local Java process started from the command line. This process can be aborted locally, but cannot receive a session stop signal as it is not a real run-time agent. As a consequence, sessions started this way cannot be stopped remotely.

    This process will be identified in the Data Integrator log after the Local Agent name. You can change this name using the NAME parameter.

    If you want to start the session against a run-time agent, you must use the AGENT_URL parameter.

To start a scenario from a command line:

  1. Change directory to the /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to start a scenario.

    On UNIX systems:

    ./startscen.sh <scenario_name> <scenario_version> <context_code> [<log_level>] [-AGENT_URL=<remote_agent_url>] [-ASYNC=yes|no] [-NAME=<local_agent_name>] [-SESSION_NAME=<session_name>] [-KEYWORDS=<keywords>] [<variable>=<value>]*

    On Windows systems:

    startscen.bat <scenario_name> <scenario_version> <context_code> [<log_level>] [-AGENT_URL=<remote_agent_url>][-ASYNC=yes|no] ["-NAME=<local_agent_name>"] ["-SESSION_NAME=<session_name>"] ["-KEYWORDS=<keywords>"] ["<variable>=<value>"]*

Note:

On Windows platforms, it is necessary to "delimit" the command arguments containing "=" signs or spaces, by using double quotes. The command call may differ from the Unix command call. For example:

On Unix

./startscen.sh DWH 001 GLOBAL SESSION_NAME=MICHIGAN

On Windows

startscen.bat DWH 001 GLOBAL "SESSION_NAME=MICHIGAN"

Table 21-2 lists the different parameters, both mandatory and optional. The parameters are preceded by the "-" character and the possible values are preceded by the "=" character. You must follow the character protection syntax specific to the operating system on which you enter the command.

Table 21-2 Startscen command Parameters

Parameters Description

<scenario_name>

Name of the scenario (mandatory).

<scenario_version>

Version of the scenario (mandatory). If the version specified is -1, the latest version of the scenario is executed.

<context_code>

Code of the execution context (mandatory).

[<log_level>]

Level of logging information to retain.

This parameter is in the format <n> where <n> is the expected logging level, between 0 and 6. The default log level is 5. Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

Example: startscen.bat SCENAR 1 GLOBAL 5

[-AGENT_URL=<remote_agent_url>

URL of the run-time agent that will run this session. If this parameter is set, then NAME parameter is ignored.

[-ASYNC=yes|no]

Set to yes, for an asynchronous execution on the remote agent. If ASYNC is used, AGENT_URL is manadatory.

Note that when the asynchronous execution is used, the session ID of the scenario is returned.

[-NAME=<local_agent_name>]

Agent name that will appear in the execution log for this session, instead of Local Agent. This parameter is ignored if AGENT_URL is used.

Note that using an existing physical agent name in the NAME parameter is not recommended. The run-time agent whose name is used does not have all the information about this session and will not be able to manage it correctly. The following features will not work correctly for this session:

  • Clean stale session: This session will be considered as stale by this agent if this agent is started. The session will be pushed to error when the agent will detect this session

  • Kill Sessions: This agent cannot kill the session when requested.

  • Agent Session Count: This session is counted in this agent's sessions, even if it is not executed by it.

It is recommended to use a NAME that does not match any existing physical agent name.

If you want to start a session on a given physical agent, you must use the AGENT_URL parameter instead.

[-SESSION_NAME=<session_name>]

Name of the session that will appear in the execution log.

[-KEYWORDS=<keywords>]

List of keywords attached to this session. These keywords make session identification easier. The list is a comma-separated list of keywords.

[<variable>=<value>]

Allows to assign a <value> to a <variable> for the execution of the scenario. <variable> is either a project or global variable. Project variables should be named <Project Code>.<Variable Name>. Global variables should be called GLOBAL.<variable Name>.

This parameter can be repeated to assign several variables.

Do not use a hash sign (#) to prefix the variable name on the startscen command line.


21.4 Restarting a Session

Any session that has encountered an error, or has been stopped by the user can be restarted.

Oracle Data Integrator uses JDBC transactions when interacting with source and target data servers, and any open transaction state is not persisted when a session finishes in error state. The appropriate restart point is the task that started the unfinished transaction(s). If such a restart point is not identifiable, it is recommended that you start a fresh session by executing the scenario instead of restarting existing sessions that are in error state.

Only sessions in status Error or Waiting can be restarted. By default, a session restarts from the last task that failed to execute (typically a task in error or in waiting state). A session may need to be restarted in order to proceed with existing staging tables and avoid re-running long loading phases. In that case the user should take into consideration transaction management, which is KM specific. A general guideline is: If a crash occurs during a loading task, you can restart from the loading task that failed. If a crash occurs during an integration phase, restart from the first integration task, because integration into the target is within a transaction. This guideline applies only to one interface at a time. If several interfaces are chained and only the last one performs the commit, then they should all be restarted because the transaction runs over several interfaces.

To restart from a specific task or step:

  1. In Operator Navigator, navigate to this task or step, edit it and switch it to Waiting state.

  2. Set all tasks and steps after this one in the Operator tree view to Waiting state.

  3. Restart the session using one of the following methods:

WARNING:

When restarting a session, all connections and transactions to the source and target systems are re-created, and not recovered from the previous session run. As a consequence, uncommitted operations on transactions from the previous run are not applied, and data required for successfully continuing the session may not be present.

21.4.1 Restarting a Session from ODI Studio

To restart a session from Oracle Data Integrator Studio:

  1. In Operator Navigator, select the session that you want to restart.

  2. Right-click and select Restart.

  3. In the Restart Session dialog, specify the agent you want to use for running the new session.

    To select the agent to execute the session, do one of the following:

    • Select Use the previous agent: <agent name> to use the agent that was used for the previous session execution.

    • Select Choose another agent to select from the list the agent that you want to use for the session execution.

      Note:

      Select Internal to use the ODI Studio built-in Agent.

  4. Select the Log Level. Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

  5. Click OK to restart the indicated session and to close the dialog. Click Cancel if you do not want to restart session.

When Oracle Data Integrator has restarted the session, the Session Started dialog appears.

21.4.2 Restarting a Session from a Command Line

Before restarting a session from a command line, read carefully the following requirements:

  • The command line scripts, which are required for performing the tasks described in this section, are only available if you have installed the Oracle Data Integrator Standalone Agent. See the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for information about how to install the Standalone Agent.

  • To use this command the connection to your repository must be configured in the odiparams file. See Chapter 4, "Managing Agents" for more information.

  • When restarting a session from a command line, the session is not started by default against a remote run-time agent, but is executed by a local Java process started from the command line. This process can be aborted locally, but cannot receive a session stop signal as it is not a real run-time agent. As a consequence, sessions started this way cannot be stopped remotely.

    If you want to start the session against a run-time agent, you must use the AGENT_URL parameter.

To restart a session from a command line:

  1. Change directory to the /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to start a scenario.

    On UNIX systems:

    ./restartsession.sh <session_number> [-log_level][-AGENT_URL=<remote_agent_url>]

    On Windows systems:

    restartsession.bat <session_number> [-log_level]["-AGENT_URL=<remote_agent_url>"]

Table 21-3 lists the different parameters of this command, both mandatory and optional. The parameters are preceded by the "-" character and the possible values are preceded by the "=" character. You must follow the character protection syntax specific to the operating system on which you enter the command.

Table 21-3 restartsess command Parameters

Parameters Description

<session_number>

Number (ID) of the session to be restarted.

[-log_level]

Level of logging information to retain. Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. Note that if this log_level parameter is not provided when restarting a session, the previous log level used for executing the session will be reused. See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

[-AGENT_URL=<remote_agent_url>

URL of the run-time agent that will restart this session. By default the session is executed by a local Java process started from the command line.


Note:

To use this command the connection to your repository must be configured in the odiparams file. See Section 4.3, "Managing Agents" for more information.

Note:

When restarting a session from a command line, the session is not started by default against a remote run-time agent, but is executed by a local Java process started from the command line.

If you want to start the session against a run-time agent, you must use the AGENT_URL parameter.

21.5 Stopping a Session

Any running or waiting session can be stopped. You may want to stop a session when you realize that for example your interface contains errors or when the execution takes a long time.

Note that there are two ways to stop a session:

Note:

The immediate stop works only with technologies and drivers that support task interruption. It is supported if the statement.cancel method is implemented in the JDBC driver.

Note:

Only sessions that are running within a Java EE or standalone Agent can be stopped. Sessions running in the Studio built-in Agent or started with the startscen.sh or startscen.bat script without the AGENT_URL parameter, cannot be stopped. See Section 21.3, "Executing a Scenario" for more information.

Session can be stopped in several ways:

21.5.1 Stopping a Session From ODI Studio

To stop a session from Oracle Data Integrator Studio:

  1. In Operator Navigator, select the running or waiting session to stop from the tree.

  2. Right-click then select Stop Normal or Stop Immediate.

  3. In the Stop Session Dialog, click OK.

The session is stopped and changed to Error status.

21.5.2 Stopping a Session From a Command Line

Before stopping a session from a command line, read carefully the following requirements:

To stop a session from a command line:

  1. Change directory to the /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to start a scenario.

    On UNIX systems:

    ./stopsession.sh <session_id> [-AGENT_URL=<remote_agent_url>] [-STOP_LEVEL=<normal (default) | immediate>]

    On Windows systems:

    stopsession.bat <session_id> ["-AGENT_URL=<remote_agent_url>"] ["-STOP_LEVEL=<normal (default) | immediate>"]

Table 21-3 lists the different parameters of this command, both mandatory and optional. The parameters are preceded by the "-" character and the possible values are preceded by the "=" character. You must follow the character protection syntax specific to the operating system on which you enter the command.

Table 21-4 StopSession command Parameters

Parameters Description

<session_id>

Number (ID) of the session to be restarted.

[-AGENT_URL=<remote_agent_url>

URL of the run-time agent that stops this session. By default the session is executed by a local Java process started from the command line.

[-STOP_LEVEL=<normal (default) | immediate>]

The level used to stop a running session. If it is omitted, normal will be used as the default stop level.


Note:

To use this command the connection to your repository must be configured in the odiparams file. See Section 4.3, "Managing Agents" for more information.

21.6 Executing a Load Plan

Load Plans can be executed in several ways:

Note:

A Load Plan cannot be executed using the ODI Studio built-in agent called Local (No Agent).

21.6.1 Executing a Load Plan from ODI Studio

In ODI Studio, you can run a Load Plan in Designer Navigator or in Operator Navigator.

To run a Load Plan in Designer Navigator or Operator Navigator:

  1. In the Load Plans and Scenarios accordion, select the Load Plan you want to execute.

  2. Right-click and select Execute.

  3. In the Start Load Plan dialog, select the execution parameters:

    • Select the Context into which the Load Plan will be executed.

    • Select the Logical Agent that will run the step.

    • Select the Log Level. All sessions with a defined log level lower than or equal to this value will be kept in the Session log when the session completes. However, if the object execution ends abnormally, all tasks will be kept, regardless of this setting.

      Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

      Select Use Session Task Log Level (default) to use the Session Tasks Log Level value defined in the Load Plan.

    • In the Variables table, enter the Startup values for the variables used in this Load Plan.

  4. Click OK.

  5. The Load Plan Started Window appears.

  6. Click OK.

A new execution of the Load Plan is started: a Load Plan instance is created and also the first Load Plan run. You can review the Load Plan execution in the Operator Navigator.

21.6.2 Executing a Load Plan from a Command Line

You can start a Load Plan from a command line.

Before executing a Load Plan from a command line, read carefully the following requirements:

  • The command line scripts, which are required for performing the tasks described in this section, are only available if you have installed the Oracle Data Integrator Standalone Agent. See the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for information about how to install the Standalone Agent.

  • To use this command, the connection to your repository must be configured in the odiparams file. See Chapter 4, "Managing Agents" for more information.

  • A Load Plan Run is started against a run-time agent identified by the AGENT_URL parameter.

To start a Load Plan from a command line:

  1. Change directory to /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to start a Load Plan.

    On UNIX systems:

    ./startloadplan.sh <load_plan_name> <context_code> [log_level] -AGENT_URL=<agent_url> [-KEYWORDS=<keywords>] [<variable>=<value>]*

    On WINDOWS systems:

    startloadplan.bat <load_plan_name> <context_code> [log_level]"-AGENT_URL=<agent_url>" ["-KEYWORDS=<keywords>"] ["<variable>=<value>"]*

Note:

On Windows platforms, it is necessary to "delimit" the command arguments containing "=" signs or spaces, by using double quotes. The command call may differ from the Unix command call. For example:

On UNIX systems:

./startloadplan.sh DWLoadPlan DEV -AGENT_URL=http://localhost:20910/oraclediagent

On WINDOWS systems:

startloadplan.bat DWLoadPlan DEV "-AGENT_URL=http://localhost:20910/oraclediagent"

Table 21-5 lists the different parameters, both mandatory and optional. The parameters are preceded by the "-" character and the possible values are preceded by the "=" character. You must follow the character protection syntax specific to the operating system on which you enter the command.

Table 21-5 Startloadplan Command Parameters

Parameters Description

<load_plan_name>

Name of the Load Plan to be started (mandatory)

<context_code>

Code of the context used for starting the Load Plan. Note that if this value is not provided, the Load Plan uses the context of the session that calls it (mandatory)

[log_level]

Level of logging information to retain. All sessions with a defined log level lower than or equal to this value will be kept in the Session log when the session completes. However, if the object execution ends abnormally, all tasks will be kept, regardless of this setting.

Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. Default is the Load Plan's Session Tasks Log Level that has been used for starting the Load Plan. See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

["-AGENT_URL=<agent_url>"]

URL of the Physical Agent that starts the Load Plan (mandatory)

["-KEYWORDS=<Keywords>"]

Keywords to improve the organization of ODI logs by session folders and automatic classification. Enter a comma separated list of keywords that will be attached to this Load Plan.

["variable>=<value> "]

Startup values for the Load Plan variables (optional). Note that project variables should be named <project_code>.<variable_name> and global variables should be named GLOBAL.<variable_name>. This list is of the form <variable>=<value>.

The format for Date and Number variables is as follows:

  • Date: yyyy-MM-dd'T'HH:mm:ssZ

    For example: 2009-12-06T15:59:34+0100

  • Number: Integer value

    For example: 29833

For example:

"A_PROJ.A_REFRESH_VAR=bb" "A_PROJ.A_CROSS_PROJ_VAR=aa" "A_PROJ.A_VAR=cc"


21.7 Restarting a Load Plan Run

Restarting a Load Plan, starts a new run for the selected Load Plan instance. Note that when a Load Plan restarts the Restart Type parameter for the steps in error defines how the Load Plan and child sessions will be restarted. See Section 14.2.4.3, "Defining the Restart Behavior" and Section 21.4, "Restarting a Session" for more information.

Note:

Restarting a Load Plan instance depends on the status of its most-recent (highest-numbered) run. Restart is only enabled for the most-recent run, if its status is Error.

Load Plans can be restarted in several ways:

21.7.1 Restarting a Load Plan from ODI Studio

To restart a Load Plan from ODI Studio:

  1. In Operator Navigator, select the Load Plan Run to restart from the Load Plan Executions accordion.

  2. Right-click then select Restart.

  3. In the Restart Load Plan Dialog, select the Agent that restarts the Load Plan. Optionally, select a different log level.

  4. Click OK.

The Load Plan is restarted and a new Load Plan run is created.

21.7.2 Restarting a Load Plan from a Command Line

Before restarting a Load Plan from a command line, read carefully the following requirements:

  • The command line scripts, which are required for performing the tasks described in this section, are only available if you have installed the Oracle Data Integrator Standalone Agent. See the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for information about how to install the Standalone Agent.

  • To use this command the connection to your repository must be configured in the odiparams file. See Chapter 4, "Managing Agents" for more information.

  • A Load Plan Run is restarted against a remote run-time agent identified by the AGENT_URL parameter.

To restart a Load Plan from a command line:

  1. Change directory to /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to restart a Load Plan.

    On UNIX systems:

    ./restartloadplan.sh <load_plan_instance_id> [log_level] -AGENT_URL=<agent_url>

    On WINDOWS systems:

    restartloadplan.bat <load_plan_instance_id> [log_level] "-AGENT_URL=<agent_url>"

Note:

On Windows platforms, it is necessary to "delimit" the command arguments containing "=" signs or spaces, by using double quotes. The command call may differ from the Unix command call.

Table 21-6 lists the different parameters, both mandatory and optional. The parameters are preceded by the "-" character and the possible values are preceded by the "=" character. You must follow the character protection syntax specific to the operating system on which you enter the command.

Table 21-6 Restartloadplan Command Parameters

Parameters Description

<load_plan_instance_id>

ID of the stopped or failed Load Plan instance that is to be restarted (mandatory)

[log_level]

Level of logging information to retain. All sessions with a defined log level lower than or equal to this value will be kept in the Session log when the session completes. However, if the object execution ends abnormally, all tasks will be kept, regardless of this setting.

Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. Default is the log level value used for the Load Plan's previous run.

See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

["-AGENT_URL=<agent_url>"]

URL of the Physical Agent that starts the Load Plan (optional)


21.8 Stopping a Load Plan Run

Any running or waiting Load Plan Run can be stopped. You may want to stop a Load Plan Run when you realize that for example your Load Plan contains errors or when the execution takes a long time.

Note that there are two ways to stop a Load Plan Run:

Load Plans can be stopped in several ways:

21.8.1 Stopping a Load Plan from ODI Studio

To stop a Load Plan Run from ODI Studio:

  1. In Operator Navigator, select the running or waiting Load Plan Run to stop from the Load Plan Executions accordion.

  2. Right-click then select Stop Normal or Stop Immediate.

  3. In the Stop Load Plan Dialog, select the Agent that stops the Load Plan.

  4. Click OK.

The Load Plan run is stopped and changed to Error status.

21.8.2 Stopping a Load Plan Run from a Command Line

Before stopping a Load Plan from a command line, read carefully the following requirements:

  • The command line scripts, which are required for performing the tasks described in this section, are only available if you have installed the Oracle Data Integrator Standalone Agent. See the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for information about how to install the Standalone Agent.

  • To use this command the connection to your repository must be configured in the odiparams file. See Chapter 4, "Managing Agents" for more information.

  • A Load Plan Run signal is sent by a remote run-time agent identified by the AGENT_URL parameter.

To stop a Load Plan run from a command line:

  1. Change directory to /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to start a Load Plan.

    On UNIX systems:

    ./stoploadplan.sh <load_plan_instance_id> [<load_plan_run_count>] -AGENT_URL=<agent_url> [-STOP_LEVEL=<normal (default) | immediate>]

    On WINDOWS systems:

    stoploadplan.bat <load_plan_instance_id> [<load_plan_run_count>] "-AGENT_URL=<agent_url>" ["-STOP_LEVEL=<normal (default) | immediate>"]

Table 21-7 lists the different parameters, both mandatory and optional. The parameters are preceded by the "-" character and the possible values are preceded by the "=" character. You must follow the character protection syntax specific to the operating system on which you enter the command.

Table 21-7 Stoploadplan Command Parameters

Parameters Description

<load_plan_instance_id>

ID of the running Load Plan run that is to be stopped (mandatory)

[<load_plan_run_count>]

Load Plan run count of the load plan instance. It prevents unintentional stopping of a load plan run that happens to be the latest one. If it is omitted, the last Load Plan run count will be used (optional)

["-AGENT_URL=<agent_url>"]

URL of the Physical Agent that starts the Load Plan (optional)

[-STOP_LEVEL=<normal (default) | immediate>]

Level used to stop the Load Plan run. Default is normal.


Note:

On Windows platforms, it is necessary to "delimit" the command arguments containing "=" signs or spaces, by using double quotes. The command call may differ from the Unix command call.

21.9 Scheduling Scenarios and Load Plans

You can schedule the executions of your scenarios and Load Plans using the Oracle Data Integrator built-in scheduler or an external scheduler. Both methods are detailed in this section:

21.9.1 Scheduling a Scenario or a Load Plan with the Built-in Scheduler

You can attach schedules to scenarios and also to Load Plans. Such schedules are managed by the scheduler built-in run-time agent.

It is important to understand that a schedule concerns only one scenario or one Load Plan, while a scenario or a Load Plan can have several schedules and can be scheduled in several ways. The different schedules appear under the Scheduling node of the scenario or Load Plan. Each schedule allows a start date and a repetition cycle to be specified.

For example:

  • Schedule 1: Every Thursday at 9 PM, once only.

  • Schedule 2: Every day from 8 am to 12 noon, repeated every 5 seconds.

  • Schedule 3: Every day from 2 PM to 6 PM, repeated every 5 seconds, with a maximum cycle duration of 5 hours.

21.9.1.1 Scheduling a Scenario or a Load Plan

To schedule a scenario or a Load Plan from Oracle Data Integrator Studio.

  1. Right-click the Scheduling node under a scenario or a Load Plan in the Designer or Operator Navigator.

  2. Select New Scheduling. The Scheduling editor is displayed.

  3. On the Definition tab of the Scheduling editor specify the parameters as follows:

    Properties Description

    Context

    Context into which the scenario or Load Plan is started.

    Agent

    Agent executing the scenario or Load Plan.

    Log Level

    Level of logging information to retain.


    The Status parameters define the activation of the schedule.

    Properties Description

    Active

    The scheduling will be active when the agent is restarted or when the scheduling of the physical agent is updated.

    Inactive

    The schedule is not active and will not run.

    Active for the period

    Activity range of the schedule. A schedule active for a period of time will only run within this given period.


    The Execution parameters define the frequency of execution for each execution cycle.

    Properties Description

    Execution

    Frequency of execution option (annual, monthly,... simple). This option is completed by a set of options that depend on this main option.


  4. On the Execution Cycle tab, specify the parameters for the repeat mode of the scenario as follows:

    Properties Description

    None (Execute once)

    The scenario or Load Plan is executed only one time.

    Many times

    The scenario or Load Plan is repeated several times.

    • Maximum number of repetitions: The maximum number of times the scenario is repeated during the cycle.

    • Maximum Cycle Duration: As soon as the maximum time is reached, the scenario is no longer restarted, and the cycle stops.

    • Interval between repetitions: The downtime between each scenario execution.

    Constraints

    Allows limitations to be placed on one cycle iteration, in the event of a problem during execution.

    • Number of Attempts on Failure: Maximum number of consecutive execution attempts for one iteration.

    • Stop Execution After: Maximum execution time for one iteration. If this time is reached, the scenario or Load Plan is automatically stopped.


  5. On the Variables tab, unselect Latest Value for variables for which you want to provide a Value. Only variables used in the scenario or Load Plan and flagged as parameters for this scenario or Load Plan appear in this tab.

  6. From the File menu, click Save.

The new schedule appears under the Scheduling node of the scenario or Load Plan.

The schedule changes are taken into account by the run-time agent when it starts or when it receives a schedule update request.

21.9.1.2 Updating an Agent's Schedule

An agent reads schedules when starting on all the repositories attached to the master repository it connects to. It is possible, if a schedule was added for this agent in a given repository, to refresh the agent schedule.

To update an agent's schedule:

  1. In Topology Navigator expand the Agents node in the Physical Architecture accordion.

  2. Select the Physical Agent you want to update the schedule.

  3. Right-click and select Update Scheduling...

  4. In the Select Repositories dialog, select the repositories from which you want to read scheduling information. Check Select All Work Repositories to read scheduling information from all these repositories.

  5. Click OK.

The agent refreshes and re-computes its in-memory schedule from the schedules defined in these repositories.

You can also use the OdiUpdateAgentSchedule tool to update an agent's schedule.

21.9.1.3 Displaying the Schedule

You can view the scheduled tasks of all your agents or you can view the scheduled tasks of one particular agent.

Note:

The Scheduling Information is retrieved from the Agent's in-memory schedule. The Agent must be started and its schedule refreshed in order to display accurate schedule information.

Displaying the Schedule for All Agent

To display the schedule for all agents:

  1. Select Connect Navigator >Scheduling... from the Operator Navigator toolbar menu.

The View Schedule dialog appears, displaying the schedule for all agents.

Displaying the Schedule for One Agent

To display the schedule for one agent:

  1. In Topology Navigator expand the Agents node in the Physical Architecture accordion.

  2. Select the Physical Agent you want to update the schedule.

  3. Right-click and select View Schedule.

The Schedule Editor appears, displaying the schedule for this agent.

Note:

The Scheduling Information is retrieved from the Agent's schedule. The Agent must be started and its schedule refreshed in order to display accurate schedule information.

Using the View Schedule Dialog

The schedule is displayed in form of a Gantt diagram. Table 21-8 lists the details of the Schedule dialog.

Table 21-8 Scheduling Details



Selected Agent

Agent for which the Schedule is displayed. You can display also the schedule of all agents by selecting All Agents.

Selected Work Repository

Only the scenarios executed in the selected Work Repository are displayed in the schedule. Default is All Work Repositories.

Scheduling from... to...

Time range for which the scheduling is displayed. Click Refresh to refresh this schedule.

Update

Click Update to update the schedule for the selected agent(s)

Time Range

The time range specified (1 hour, 2 hours, and so forth) allows you to center the diagram on the current time plus this duration. This feature provides a vision of the sessions in progress plus the incoming sessions. You can use the arrows to move the range forward or backward.

Scenarios details

This panel displays the details and execution statistics for each scheduled scenario.


If you select a zone in the diagram (keep the mouse button pressed), you automatically zoom on the select zone.

By right-clicking in the diagram, you open a context menu for zooming, saving the diagram as an image file, printing or editing the display properties.

21.9.2 Scheduling a Scenario or a Load Plan with an External Scheduler

To start a scenario or a Load Plan with an external scheduler, do one of the following:

  • Use the startscen or startloadplan command from the external scheduler

  • Use the web service interface for triggering the scenario or Load Plan execution

For more information, see:

If a scenario or a Load Plan completes successfully, the return code will be 0. If not, the return code will be different than 0. This code will be available in:

  • The return code of the command line call. The error message, if any, is available on the standard error output.

  • The SOAP response of the web service call. The web service response includes also the session error message, if any.

21.10 Simulating an Execution

In Oracle Data Integrator you have the possibility at design-time to simulate an execution. Simulating an execution generates and displays the code corresponding to the execution without running this code. Execution simulation provides reports suitable for code review.

Note:

No session is created in the log when the execution is started in simulation mode.

To simulate an execution:

  1. In the Project view of the Designer Navigator, select the object you want to execute.

  2. Right-click and select Execute.

  3. In the Execution dialog, set the execution parameters and select Simulation. See Table 21-1 for more information.

  4. Click OK.

The Simulation report is displayed.

You can click Save to save the report as.xml or.html file.

21.11 Managing Executions Using Web Services

This section explains how to use a web service to perform run-time operations. It contains the following sections.

21.11.1 Introduction to Run-Time Web Services

Oracle Data Integrator includes web services for performing run-time operations. These web services are located in two places:

  • In the run-time agent, a web service allows starting a scenario or a Load Plan, monitoring a session status or a Load Plan run status, and restarting a session or a Load Plan instance, as well as stopping a Load Plan run. To use operations from this web service, you must first install and configure a standalone or a Java EE agent.

  • A dedicated public web service component provides operations to list the contexts and scenarios available. To use operations from this web service, you must first install and configure this component in a Java EE container.

The following applies to the SOAP request used against the agent and public web services

  • The web services operations accept password in a plain text in the SOAP request. Consequently, it is strongly recommended to use secured protocols (HTTPS) to invoke web services over a non-secured network. You can alternately use external authentication. See Section 21.11.12, "Using the Run-Time Web Services with External Authentication" for more information.

  • Repository connection information is not necessary in the SOAP request as the agent or public web service component is configured to connect to a master repository. Only an ODI user and the name of a work repository are required to run most of the operations.

21.11.2 Executing a Scenario Using a Web Service

The invokeStartScen operation of the agent web service starts a scenario in synchronous or asynchronous mode; in a given work repository. The session is executed by the agent providing the web service.

<OdiStartScenRequest>
         <Credentials>
            <OdiUser>odi_user</OdiUser>
            <OdiPassword>odi_password</OdiPassword>
            <WorkRepository>work_repository</WorkRepository>
         </Credentials>
         <Request>
            <ScenarioName>scenario_name</ScenarioName>
            <ScenarioVersion>scenario_version</ScenarioVersion>
            <Context>context</Context>
            <LogLevel>log_level</LogLevel>
            <Synchronous>synchronous</Synchronous>
            <SessionName>session_name</SessionName>
            <Keywords>session_name</Keywords>
            <Variables>
            <Name>variable_name</name>
            <Value>variable_value</Value>
            </Variables>
         </Request>
      </OdiStartScenRequest>

The scenario execution returns the session ID in a response that depends on the value of the synchronous element in the request.

  • In synchronous mode (Synchronous=1), the response is returned once the session has completed, and reflects the execution result.

  • In asynchronous mode (Synchronous=0), the response is returned once the session is started, and only indicates the fact whether the session was correctly started or not.

This operation returns a response in the following format:

<?xml version = '1.0' encoding = 'ISO-8859-1'?><ns2:OdiStartScenResponse xmlns:ns2="xmlns.oracle.com/odi/OdiInvoke/">   <Session>543001</Session></ns2:OdiStartScenResponse>

21.11.3 Monitoring a Session Status Using a Web Service

The getSessionStatus operation of the agent web service returns the status of one or more sessions in a given repository, identified by their Session Numbers provided in the SessionIds element. It manages both running and completed sessions.

<OdiGetSessionsStatusRequest>
         <Credentials>
            <OdiUser>odi_user</OdiUser>
            <OdiPassword>odi_password</OdiPassword>
            <WorkRepository>work_repository</WorkRepository
         </Credentials>
         <SessionIds>session_number</SessionIds>
      </OdiGetSessionsStatusRequest>

This operation returns a response in the following format:

<SessionStatusResponse>
         <SessionId>session_id</SessionId>
         <SessionStatus>status_code</SessionStatus>
         <SessionReturnCode>return_code</SessionReturnCode>
      </SessionStatusResponse>

The Return Code value is zero for successful sessions and possible status codes are:

  • D: Done

  • E: Error

  • M: Warning

  • Q: Queued

  • R: Running

  • W: Waiting

21.11.4 Restarting a Session Using a Web Service

The invokeRestartSess operation of the agent web service restarts a session identified by its session number (provided in the SessionID element) in a given work repository. The session is executed by the agent providing the web service.

Only sessions in status Error or Waiting can be restarted. The session will resume from the last non-completed task (typically, the one in error).

Note that you can change the value of the variables or use the KeepVariables boolean element to reuse variables values from the previous session run.

<invokeRestartSessRequest> 
         <Credentials> 
            <OdiUser>odi_user</OdiUser> 
            <OdiPassword>odi_password</OdiPassword> 
            <WorkRepository>work_repository</WorkRepository>
         </Credentials> 
         <Request> 
            <SessionID>session_number</SessionID> 
            <Synchronous>synchronous</Synchronous>
            <KeepVariables>0|1</KeepVariables>
            <LogLevel>log_level</LogLevel>
            <Variables>
            <Name>variable_name</name>
            <Value>variable_value</Value>
            </Variables>
         </Request> 
      </invokeRestartSessRequest> 

This operation returns a response similar to InvokeStartScen, depending on the Synchronous element's value.

21.11.5 Executing a Load Plan Using a Web Service

The invokeStartLoadPlan operation of the agent web service starts a Load Plan in a given work repository. The Load Plan is executed by the agent providing the web service. Note the following concerning the parameters of the invokeStartLoadPlan operation:

  • OdiPassword: Use a password in clear text.

  • Context: Use the context code.

  • Keywords: If you use several keywords, enter a comma separated list of keywords.

  • Name: Use the fully qualified name for variables: GLOBAL.variable_name or PROJECT_CODE.variable_name

The following shows the format of the OdiStartLoadPlanRequest.

<OdiStartLoadPlanRequest>
   <Credentials> 
      <OdiUser>odi_user</OdiUser> 
      <OdiPassword>odi_password</OdiPassword> 
      <WorkRepository>work_repository</WorkRepository>
   </Credentials> 
   <StartLoadPlanRequest>
      <LoadPlanName>load_plan_name</LoadPlanName>
      <Context>context</Context>
      <Keywords>keywords</Keywords>
      <LogLevel>log_level</LogLevel>
      <LoadPlanStartupParameters>
         <Name>variable_name</Name>
         <Value>variable_value</Value>
      </LoadPlanStartupParameters>
    </StartLoadPlanRequest>
</OdiStartLoadPlanRequest>

The invokeStartLoadPlan operation returns the following values in the response:

  • Load Plan Run ID

  • Load Plan Run Count

  • Master Repository ID

  • Master Repository timestamp

The following is an example of an OdiStartLoadPlan response:

<?xml version = '1.0' encoding = 'UTF8'?>
<ns2:OdiStartLoadPlanResponse xmlns:ns2="xmlns.oracle.com/odi/OdiInvoke/">
   <executionInfo>
      <StartedRunInformation>
         <OdiLoadPlanInstanceId>2001</OdiLoadPlanInstanceId>
         <RunCount>1</RunCount>
         <MasterRepositoryId>0</MasterRepositoryId>
         <MasterRepositoryTimestamp>1290196542926</MasterRepositoryTimestamp>
      </StartedRunInformation>
   </executionInfo>
</ns2:OdiStartLoadPlanResponse>

21.11.6 Stopping a Load Plan Run Using a Web Service

The invokeStopLoadPlan operation of the agent web service stops a running Load Plan run identified by the Instance ID and Run Number in a given work repository. The Load Plan instance is stopped by the agent providing the web service. Note that the StopLevel parameter can take the following values:

  • NORMAL: Waits until the current task finishes and then stops the session.

  • IMMEDIATE: Stops the session immediately, cancels all open statements and then rolls back the transactions.

See Section 21.8, "Stopping a Load Plan Run" for more information on how to stop a Load Plan run and Section 21.11.5, "Executing a Load Plan Using a Web Service" for more information on the other parameters used by the invokeStopLoadPlan operation.

<OdiStopLoadPlanRequest>
   <Credentials> 
      <OdiUser>odi_user</OdiUser> 
      <OdiPassword>odi_password</OdiPassword> 
      <WorkRepository>work_repository</WorkRepository>
   </Credentials> 
   <OdiStopLoadPlanRequest>
      <LoadPlanInstanceId>load_plan_instance_id</LoadPlanInstanceId>
      <LoadPlanInstanceRunCount>load_plan_run_count</LoadPlanInstanceRunCount>
      <StopLevel>stop_level</StopLevel>
   </OdiStopLoadPlanRequest>
</OdiStopLoadPlanRequest>

The invokeStopLoadPlan operation returns the following values in the response:

  • Load Plan Run ID

  • Load Plan Run Count

  • Master Repository ID

  • Master Repository timestamp

The following is an example of an OdiStopLoadPlan response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:OdiStopLoadPlanResponse xmlns:ns2="xmlns.oracle.com/odi/OdiInvoke/">
         <executionInfo>
            <StoppedRunInformation>
              <OdiLoadPlanInstanceId>3001</OdiLoadPlanInstanceId>
              <RunCount>1</RunCount>
              <MasterRepositoryId>0</MasterRepositoryId>
              <MasterRepositoryTimestamp>1290196542926</MasterRepositoryTimestamp>
            </StoppedRunInformation>
         </executionInfo>
      </ns2:OdiStopLoadPlanResponse>
   </S:Body>
</S:Envelope>

21.11.7 Restarting a Load Plan Instance Using a Web Service

The invokeRestartLoadPlan operation of the agent web service restarts a Load Plan instance identified by the Instance ID in a given work repository. The Load Plan instance is restarted by the agent providing the web service.

<OdiRestartLoadPlanRequest>
   <Credentials> 
      <OdiUser>odi_user</OdiUser> 
      <OdiPassword>odi_password</OdiPassword> 
      <WorkRepository>work_repository</WorkRepository>
   </Credentials> 
   <RestartLoadPlanRequest>
      <LoadPlanInstanceId>load_plan_instance_id</LoadPlanInstanceId>
      <LogLevel>log_level</LogLevel>
   </RestartLoadPlanRequest>
</OdiRestartLoadPlanRequest>

21.11.8 Monitoring a Load Plan Run Status Using a Web Service

The getLoadPlanStatus operation of the agent web service returns the status of one or more Load Plans by their Instance ID and Run Number in a given repository. It manages both running and completed Load Plan instances.

<OdiGetLoadPlanStatusRequest> 
   <Credentials> 
       <OdiUser>odi_user</OdiUser> 
       <OdiPassword>odi_password</OdiPassword> 
      <WorkRepository>work_repository</WorkRepository>
   </Credentials> 
   <LoadPlans> 
      <LoadPlanInstanceId>load_plan_instance_id</LoadPlanInstanceId>
      <LoadPlanRunNumber>load_plan_run_number</LoadPlanRunNumber>
   </LoadPlans> 
</OdiGetLoadPlanStatusRequest> 

The getStopLoadPlanStatus operation returns the following values in the response:

  • Load Plan Run ID

  • Load Plan Run Count

  • Load Plan Run return code

  • Load Plan message

The following is an example of an OdiGetLoadPlanStatus response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:OdiGetLoadPlanStatusResponse xmlns:ns2="xmlns.oracle.com/odi/OdiInvoke/">
         <LoadPlanStatusResponse>
            <LoadPlanInstanceId>3001</LoadPlanInstanceId>
            <LoadPlanRunNumber>1</LoadPlanRunNumber>
            <LoadPlanStatus>E</LoadPlanStatus>
            <LoadPlanReturnCode>ODI-1530</LoadPlanReturnCode>
            <LoadPlanMessage>ODI-1530: Load plan instance was stopped by user request.</LoadPlanMessage>
         </LoadPlanStatusResponse>
      </ns2:OdiGetLoadPlanStatusResponse>
   </S:Body>
</S:Envelope>

21.11.9 Listing Contexts Using a Web Service (Deprecated)

Note:

The listContext operation of the public web service is deprecated in 11.1.1.7 and will be removed in future release.

The listContext operation of the public web service lists of all the contexts present in a master repository.

<listContextRequest> 
      <OdiUser>odi_user</OdiUser> 
      <OdiPassword>odi_password</OdiPassword> 
   <listContextRequest>

21.11.10 Listing Scenarios Using a Web Service (Deprecated)

Note:

The listScenario operation of the public web service is deprecated in 11.1.1.7 and will be removed in future release.

The listScenario operation of the public web service lists of all the scenarios present in a given work repository.

<listScenarioRequest> 
      <OdiUser>odi_user</OdiUser> 
      <OdiPassword>odi_password</OdiPassword> 
      <WorkRepository>work_repository</WorkRepository> 
   <listScenarioRequest>

21.11.11 Accessing the Web Service from a Command Line

Oracle Data Integrator contains two shell scripts for UNIX platforms that use the web service interface for starting and monitoring scenarios from a command line via the run-time agent web service operations:

  • startscenremote.sh starts a scenario on a remote agent on its web service. This scenario can be started synchronously or asynchronously. When started asynchronously, it is possible to have the script polling regularly for the session status until the session completes or a timeout is reached.

  • getsessionstatusremote.sh gets the status of a session via the web service interface. This second script is used in the startscenremote.sh script.

Before accessing a web service from a command line, read carefully the following important notes:

  • The command line scripts, which are required for performing the tasks described in this section, are only available if you have installed the Oracle Data Integrator Standalone Agent. See the Oracle Fusion Middleware Installation Guide for Oracle Data Integrator for information about how to install the Standalone Agent.

  • Unlike the startscen.sh command line, these scripts rely on the lightweight WGET utility installed with the UNIX or Linux platform to perform the web service calls. It does not use any java code and uses a polling mechanism to reduce the number of running processes on the machine. These scripts are suitable when a large number of scenarios and sessions need to be managed simultaneously from a command line.

Starting a Scenario

To start a scenario from a command line via the web service:

  1. Change directory to the /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to start a scenario.

    On UNIX systems:

    ./startscenremote.sh <scenario_name> <scenario_version> <context_code> <work_repository> <remote_agent_url> <odi_user> <odi_password> -l <log_level> -s <sync_mode> -n <session_name> -k <session_keyword> -a <assign_variable> -t <timeout> -i <interval> -h <http_timeout> -v

Table 21-9 lists the different parameters of this command, both mandatory and optional.

Table 21-9 Startscenremote command Parameters

Parameters Description

<scenario_name>

Name of the scenario (mandatory).

<scenario_version>

Version of the scenario (mandatory). If the version specified is -1, the latest version of the scenario is executed.

<context_code>

Code of the execution context (mandatory).

<work_repository>

Name of the work repository containing the scenario.

<remote_agent_url>

URL of the run-time agent that will run this session.

<odi_user>

Name of the user used to run this sessions.

<odi_password>

This user's password.

-l <log_level>

Level of logging information to retain.

This parameter is in the format <n> where <n> is the expected logging level, between 0 and 6. The default log level is 5.

Note that log level 6 has the same behavior as log level 5, but with in addition of variable tracking. See Section 12.2.3.11, "Tracking Variables and Sequences" for more information.

Example: startscen.bat SCENAR 1 GLOBAL 5

-s <sync_mode>

Execution mode:

  • 0: Synchronous

  • 1:Asynchronous (Do not wait for session completion)

  • 2: Asynchronous (Wait for session completion).

-n <session_name>

Name of the session

-k <session_keyword>

List of keywords attached to this session. These keywords make session identification easier. The list is a comma-separated list of keywords.

-a <assign_variable>

Assign variable. Allows to assign a <value> to a <variable> for the execution of the scenario. <variable> is either a project or global variable. Project variables should be named <Project Code>.<Variable Name>. Global variables should be called GLOBAL.<variable Name>.

This parameter can be repeated to assign several variables.

Do not use a hash sign (#) to prefix the variable name on the startscen command line.

For Example: -a PROJ1.VAR1=100

-t <timeout>

Timeout in seconds for waiting for session to complete if sync_mode = 2.

-i <interval>

Polling interval for session status if sync_mode = 2.

-h <http_timeout>

HTTP timeout for the web services calls.

-v

Verbose mode.


Monitoring a Session Status

To monitor the status of a session from a command line via the web service:

  1. Change directory to the /agent/bin directory of the Oracle Data Integrator installation.

  2. Enter the following command to start a scenario.

    On UNIX systems:

    ./getsessionstatusremote.sh <session_number> <work_repository> <remote_agent_url> <odi_user> <odi_password> -w <wait_mode> -t <timeout> -i <interval> -h <http_timeout> -v

Table 21-10 lists the different parameters of this command, both mandatory and optional.

Table 21-10 GetSessionStatusRemote command Parameters

Parameters Description

<session_number>

Number of the session to monitor.

<work_repository>

Name of the work repository containing the scenario.

<remote_agent_url>

URL of the run-time agent that will run this session.

<odi_user>

Name of the user used to run this sessions.

<odi_password>

This user's password.

-w <wait_mode>

Wait mode:

  • 0: Do not wait for session completion, report current status.

  • 1: Wait for session completion then report status.

-t <timeout>

Timeout in seconds for waiting for session to complete if sync_mode = 2.

-i <interval>

Polling interval for session status if sync_mode = 2.

-h <http_timeout>

HTTP timeout for the web services calls.

-v

Verbose mode.


21.11.12 Using the Run-Time Web Services with External Authentication

The web services examples in this chapter use an ODI authentication within the SOAP body, using the OdiUser and OdiPassword elements.

When external authentication is set up for the repository and container based authentication with Oracle Platform Security Services (OPSS) is configured (See Section 24.3.2, "Setting Up External Authentication" for more information), the authentication can be passed to the web service using HTTP basic authentication, WS-Security headers, SAML tokens and so forth. OPSS will transparently handle the authentication on the server-side with the identity provider. In such situation, the OdiUser and OdiPassword elements can be omitted.

The run-time web services will first try to authenticate using OPSS. If no authentication parameters have been provided, OPSS uses anonymous user and the OdiUser and OdiPassword are checked. Otherwise (this is in case of invalid credentials to OPSS) OPSS throws an authentication exception and the web service is not invoked.

Note:

OPSS authentication is only possible for a Public Web Service or JEE Agent deployed in a Oracle WebLogic Server.

21.11.13 Using WS-Addressing

The web services described in this chapter optionally support WS-Addressing. WS-Addressing allows replying on an endpoint when a run-time web service call completes. For this purpose, two endpoints, ReplyTo and FaultTo, can be optionally specified in the SOAP request header.

These endpoints are used in the following way:

  • When the run-time web service call completes successfully, the result of an Action is sent to the ReplyTo endpoint.

  • If an error is encountered with the SOAP request or if Oracle Data Integrator is unable to execute the request, a message is sent to the FaultTo address. If the FaultTo address has not been specified, the error is sent to the ReplyTo address instead.

  • If the Oracle Data Integrator Agent encounters errors while processing the request and needs to raise an ODI error message, this error message is sent back to the ReplyTo address.

Note that callback operations do not operate in callback mode unless a valid ReplyTo address is specified.

The following is an example of a request that is sent to retrieve the session status for session 20001:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:odi="xmlns.oracle.com/odi/OdiInvoke/">
<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Action soapenv:mustUnderstand="1">xmlns.oracle.com/odi/OdiInvoke/getSessionStatus</wsa:Action>
<wsa:ReplyTo soapenv:mustUnderstand="1">
<wsa:Address>http://host001:8080/examples/servlets/servlet/RequestPrinter</wsa:Address>
</wsa:ReplyTo>
<wsa:MessageID soapenv:mustUnderstand="1">uuid:71bd2037-fbef-4e1c-a991-4afcd8cb2b8e</wsa:MessageID>
</soapenv:Header>
   <soapenv:Body>
      <odi:OdiGetSessionsStatusRequest>
         <Credentials>
            <!--You may enter the following 3 items in any order-->
            <OdiUser></OdiUser>
            <OdiPassword></OdiPassword>
            <WorkRepository>WORKREP1</WorkRepository>
         </Credentials>
         <!--Zero or more repetitions:-->
         <SessionIds>20001</SessionIds>
      </odi:OdiGetSessionsStatusRequest>
   </soapenv:Body>
</soapenv:Envelope>
 

The following call will be made to the ReplyTo address (http://host001:8080/examples/servlets/servlet/RequestPrinter).

Note that this call contains the response to the Action specified in the request, and includes the original MessageID to correlate request and response.

<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header>
<To xmlns="http://www.w3.org/2005/08/addressing">http:// host001:8080/examples/servlets/servlet/RequestPrinter</To>
<Action xmlns="http://www.w3.org/2005/08/addressing">xmlns.oracle.com/odi/OdiInvoke/:requestPortType:getSessionStatusResponse</Action>
<MessageID xmlns="http://www.w3.org/2005/08/addressing">uuid:eda383f4-3cb5-4dc2-988c-a4f7051763ea</MessageID>
<RelatesTo xmlns="http://www.w3.org/2005/08/addressing">uuid:71bd2037-fbef-4e1c-a991-4afcd8cb2b8e</RelatesTo>
</S:Header>
<S:Body>
<ns2:OdiGetSessionsStatusResponse xmlns:ns2="xmlns.oracle.com/odi/OdiInvoke/">
<SessionStatusResponse>
               <SessionId>26001</SessionId>
               <SessionStatus>D</SessionStatus>
               <SessionReturnCode>0</SessionReturnCode>
           </SessionStatusResponse>
</ns2:OdiGetSessionsStatusResponse>
    </S:Body>
</S:Envelope>

For more information on WS-Adressing, visit these World Wide Web Consortium (W3C) web sites at the following URLs:

21.11.14 Using Asynchronous Web Services with Callback

Long-running web service operations can be started asynchronously following the pattern of JRF asynchronous web services or asynchronous BPEL processes. These follow a "request-response port pair" pattern.

In this pattern, the web service client implements a callback operation. When the server completes the operation requested by the client, it sends the result to this callback operation.

Two specific operations in the agent web service support this pattern: invokeStartScenWithCallback and invokeRestartSessWithCallback.

These operations provide the following features:

  • They do not return any response. These are one way operations.

  • The client invoking these two operation must implement respectively the invokeStartSceCallback and invokeRestartSessCallback one way operations. Results from the invokeStartScenWithCallback and invokeRestartSessWithCallback actions are sent to these operations.

  • The invocation should provide in the SOAP header the ReplyTo and possibly FaultTo addresses. If the methods are invoked without a ReplyTo address, the operation will execute synchronously (which corresponds to a invokeStartScen or invokeRestartSess operation). When a fault is generated in the operation, it will be sent to the ReplyTo address or FaultTo address.

A scenario or session started synchronously using the invokeStartScenWithCallback and invokeRestartSessWithCallback will start and will not return any SOAP response, as they are one way operations. When the session completes, the response is sent the callback address.

Note:

Oracle BPEL takes care of automatically implementing these operations and sends out WS-Addressing headers that point to these endpoints.