UC4 Rapid Automation
Oracle Retail Agent Guide
UC4 Software, Inc.
UC4: Rapid Automation
Oracle Retail Agent Guide
By Jack Ireton
Document number: RAOR-042012-en
***
Copyright
UC4® and the UC4 logo® are trademarks owned by UC4 Software GmbH (UC4).
All such trademarks can be used by permission only and are subject to the written
license terms. This software/computer program is proprietary and confidential to
UC4 Software and is only available for access and use under approved written
license terms.
This software/computer program is further protected by copyright laws, international
treaties and other domestic and international laws and any unauthorized access or
use gives rise to civil and criminal penalties. Unauthorized copying or other
reproduction of any form (in whole or in part), disassembly, decompilation, reverse
engineering, modification, and development of any derivative works are all strictly
prohibited, and any party or person engaging in such will be prosecuted by UC4
Software.
No liability is accepted for any changes, mistakes, printing or production errors.
Reproduction in whole or in part without permission is prohibited.
© Copyright UC4 Software GmbH. All rights reserved.
UC4 Rapid Automation Oracle Retail Agent Guide
iii
Contents
1 The Rapid Automation Oracle Retail Agent Integration ............................................. 1
1.1 Introduction ................................................................................................................................ 2
1.2 What's New ................................................................................................................................ 3
2 Working with the Oracle Retail Agent .......................................................................... 5
2.1
2.2
2.3
2.4
2.5
2.6
2.7
Overview of Oracle Retail Administration................................................................................... 6
Creating an Oracle Retail JDBC and Program Connection Objects .......................................... 7
Creating an Oracle Retail Agent Object and Specifying Runtime Values for It.......................... 8
Creating Oracle Retail Jobs ..................................................................................................... 10
Monitoring Oracle Retail Tasks ................................................................................................ 12
Registered Files for Failed Tasks............................................................................................. 13
Setting Trace............................................................................................................................ 14
iv
Contents
1
The Rapid Automation Oracle Retail Agent
Integration
1.
1.1 Introduction ................................................................................................................................... 2
1.2 What's New ................................................................................................................................... 3
2
Chapter 1: The Rapid Automation Oracle Retail Agent Integration
1.1 Introduction
The Oracle Retail Rapid Automation Agent is designed to work with UC4 Automation Platform v9 or greater. It
includes special panels for Connection, Agent, and Job objects.
Oracle is a top provider of innovative and comprehensive industry software for retailers. The Oracle Retail Rapid
Automation Agent allows you to define UC4 Jobs and their parameters.
Supported Versions
The Oracle Retail Agent was developed and tested against Oracle Retail v13.2.3. It requires UC4 v9 or greater.
Opening Help
The help files for the Oracle Retail Rapid Automation Agent are updated when you upgrade your Agent, not when
you upgrade your Automation Platform. Therefore they exist as their own JavaHelp project. To open the Rapid
Automation Agent help, click Oracle Retail Help on the Oracle Retail tab of your Agent or Job objects.
UC4 Rapid Automation Oracle Retail Agent Guide
3
1.2 What's New
Prior to the Rapid Automation Oracle Retail Agent, all Oracle Retail solutions were Applications Manager scripting
solutions.
Prior to the Rapid Automation Oracle Retail Agent, all Oracle Retail solutions were Applications Manager scripting
solutions. Benefits of the Rapid Automation include:
• Automated remote deployment
• No Agent upgrades
• No more waiting for the next software version to upgrade
• Jobs run faster than with scripting solutions
• No new processes are spawned
• Connection object connection pooling saves time and is more efficient
• Highly customizable Agent and Job tabs are integrated into the product
• Agent integration version control
• All resources for an Agent integration are located in a single .jar file
4
Chapter 1: The Rapid Automation Oracle Retail Agent Integration
2
2.
Working with the Oracle Retail Agent
2.1
2.2
2.3
2.4
2.5
2.6
2.7
Overview of Oracle Retail Administration ...................................................................................... 6
Creating an Oracle Retail JDBC and Program Connection Objects ............................................. 7
Creating an Oracle Retail Agent Object and Specifying Runtime Values for It ............................. 8
Creating Oracle Retail Jobs ........................................................................................................ 10
Monitoring Oracle Retail Tasks ................................................................................................... 12
Registered Files for Failed Tasks ................................................................................................ 13
Setting Trace ............................................................................................................................... 14
6
Chapter 2: Working with the Oracle Retail Agent
2.1 Overview of Oracle Retail Administration
The basic steps for implementing the Rapid Automation Oracle Retail Agent integration are described below.
The basic steps for implementing the Rapid Automation Oracle Retail Agent integration include:
1.
Running the aw_retail_recovery.sql Script
2.
Loading the Oracle Retail .jar file into UC4
3.
Creating Oracle Retail JDBC and Program Connection objects
4.
Creating an Oracle Retail Agent Object and Specifying Runtime Values for It
5.
Creating Oracle Retail Jobs
Running the aw_retail_recovery.sql Script
Run the aw_retail_recovery.sql script in the Oracle Retail database as the Oracle Retail user. The
aw_retail_recovery.sql script is provided as part of the Oracle Retail Agent distribution.
Loading the Oracle Retail .jar File into UC4
Load and install the Oracle Retail Agent in the UC4 Automation Platform. For instructions on loading and installing
Rapid Automation Agents in the UC4 Automation Platform, see your Automation Platform help.
Creating Oracle Retail JDBC Connection Object
To link UC4 to Oracle Retail, you must create:
• An Oracle Retail JDBC Connection object for the Agent to connect to the Oracle Retail database.
• One or more Oracle Retail Program Connection objects for the Jobs to connect to Oracle Retail.
For more information, see topic 2.2 Creating an Oracle Retail JDBC and Program Connection Objects.
Creating an Oracle Retail Agent Object and Specifying Runtime Values for It
You create the Oracle Retail Agent as you would create any Agent in UC4 v9, then specify runtime values for it.
For more information, see topic 2.3 Creating an Oracle Retail Agent Object and Specifying Runtime Values for It.
Creating Oracle Retail Jobs
Oracle Retail Jobs include a special Oracle Retail tab, where you specify parameters. Oracle Retail parameters
are also available where Jobs are assigned to Workflows (referred to as ProcessFlows prior to SP 5). Read-only
panels are available for Tasks in the Activities window. For more information on Oracle Retail Jobs, see topic 2.4
Creating Oracle Retail Jobs.
UC4 Rapid Automation Oracle Retail Agent Guide
7
2.2 Creating an Oracle Retail JDBC and Program Connection Objects
To link UC4 to Oracle Retail, you must create an Oracle Retail JDBC Connection object for the Agent to connect to
the Oracle Retail database and one or more Oracle Retail Program Connection objects for the Jobs to connect to
Oracle Retail.
To link UC4 to Oracle Retail, you must create:
• An Oracle Retail JDBC Connection object for the Agent to connect to the Oracle Retail database.
• One or more Oracle Retail Program Connection objects for the Jobs to connect to Oracle Retail.
Creating an Oracle Retail JDBC Connection Object
To create an Oracle Retail JDBC Connection object:
1.
Create a CONN > ORACLERETAILAGENT > JDBCCONNECTION object in client 0 as described in your
Automation Platform help.
2.
On the Oracle Retail tab shown in Figure A, specify values in the fields for your Oracle Retail database.
Figure A. An Oracle Retail JDBC Connection object
Oracle should always be selected in the Database Type field.
The values you select will determine the connect string in the JDBC Connection String field. Alternatively,
you can define your own JDBC connect string by checking Free Form Entry, and entering a connect string
in the JDBC Connection String field.
Creating an Oracle Retail Program Connection Object
To create an Oracle Retail program Connection object:
1.
Create a CONN > ORACLERETAILAGENT > ORACLERETAILCONNECTION object in client 0 as
described in your Automation Platform help.
2.
On the Oracle Retail tab shown in Figure B, specify values in the fields for your Oracle Retail installation.
Figure B. An Oracle Retail
program Connection object
3.
Copy the Connection object to all local (non-zero) Clients where Oracle Retail Jobs will be defined.
You can copy the Connection object to other Clients via Transport Case or Export, or by dragging and
dropping from Client 0 to other open Clients in the UserInterface.
8
Chapter 2: Working with the Oracle Retail Agent
2.3 Creating an Oracle Retail Agent Object and Specifying Runtime Values
for It
Agent runtime values specify configuration settings for the Agent and defaults for the Agent integration.
Creating an Oracle Retail Agent
To create an Oracle Retail Agent:
1.
Create an AGENT > ORACLERETAILAGENT object in client 0 as described in your Automation Platform
help. Make sure you set Read, Write, and Execute authorizations on the Authorizations tab of the AGENT
object.
2.
Start processes for the Agent from the UC4.ServiceManagerDialog. For information on starting AGENT
objects, see your Automation Platform help.
Specifying Agent Runtime Values
When you create a Oracle Retail Agent object in UC4, it includes a special Oracle Retail tab. Agent runtime values
specify configuration settings for the Agent and defaults for the Agent integration.
Figure A. Oracle Retail Agent runtime values
Agent runtime settings are shown in Figure A and described in the table below.
Field
JDBC
Connection
Environment
Source File
Description
The Oracle Retail JDBC Connection object this Agent will use to connect to the Oracle Retail
database. For more information, see topic 2.2 Creating an Oracle Retail JDBC and Program
Connection Objects.
A pathed file that sets the environment variables required for Oracle Retail. This field allows you
to type in command line parameters if they are required for the source file script. For example, if
the script is run from the command line like the following:
/home/retek/internal/bin/chgenv.ksh csrms 13.2 uc4lin
Source File
Prefix
You can use the Select button to select a file. If the file you select and it requires additional
arguments, you can select the file and type in the arguments.
The MMHOME variable sets the Oracle Retail home directory. It is required in the Oracle Retail
Agent's environment and must be set in the environment source file.
The SHELL type prefix to use when calling the Oracle Retail environment source file. For
example, if the source file prefix is /bin/ksh when the script is called, it will execute it like the
following:
/bin/ksh /home/retek/internal/bin/chgenv.ksh csrms 13.2 uc4lin
UC4 Rapid Automation Oracle Retail Agent Guide
Field
Source File
Timeout
Seconds
Execution
Directory
Output
Directory
Status Check
Seconds
Description
The amount of time that the Agent waits for the environment source file script to co,mplete. If it
takes longer than this number of seconds, the script is killed and an error is thrown. This value
applies to both the Agent's Environment Source File field and the Environment Source File
Override field in the Job definitions.
Specifies the directory where the Oracle Retail executable programs reside. You can use the
Select button to select a directory.
The directory where the Oracle Retail program output will be created. You can use the Select
button to select a directory.
How often to check the status while threads are running.
9
10
Chapter 2: Working with the Oracle Retail Agent
2.4 Creating Oracle Retail Jobs
Oracle Retail Jobs include a special Oracle Retail tab, where you specify general and additional parameters.
To create Oracle Retail Jobs:
1.
Create a JOBS > ORACLERETAILAGENT > RETAILJOB object in a local (i.e. non-zero) Client as described
in your Automation Platform documentation. Make sure that you select your AGENT object in the Host field
on the Attributes tab.
2.
Click the Oracle Retail tab. This is where you specify general and additional parameters for the Job.
Oracle Retail parameters are also available where Jobs are assigned to Workflows (referred to as
ProcessFlows prior to SP 4). Read-only panels are also available for Tasks in the Activities window. A
sample Oracle Retail Job is shown in Figure A.
Figure A. An Oracle Retail Job
Defining General Parameters
Define general parameters by responding to the fields in the General Parameters box, which are described in the
table below.
Field
Program
Program Login
Threads
Allow Recovery
Append File Extension
Starting Thread
Threads to Run
Description
The Oracle Retail program to run. The program can be selected from a list using the
Select button.
The Oracle Retail Program Login Connection object to use when running the program.
To determine the Program Login Connection object by user or other variable setting,
use a Variable object in this field.
The number of threads for this program to run.
If ‘Y’, the program supports restart on failure and also displays the number of running,
completed, and aborted program threads for Tasks in the ‘Remote status’ column of
the Activities window.
If ‘Y’, the thread number will be appended to all input files.
The thread number to start with.
Upon restart, specifies which threads should be restarted. If left blank all threads will
be restarted.
UC4 Rapid Automation Oracle Retail Agent Guide
11
Defining Additional Parameters
To define additional parameters: 1.
Click New.
The Add Parameter window in Figure B opens.
Figure B. The Add
Parameter window
2.
Select a type from the Type field. To define the parameter as:
• An input file, select ‘File’.
• A value appended to the Oracle Retail Job command line, select ‘Parameter’.
3.
Enter a description and value for the parameter and click OK to save.
The new parameter is added to the table in the Additional Parameters box.
Input file names and parameters will be put on the command line in the order they appear the table in the
Additional Parameters box. You can edit, delete, or move a parameter by selecting it in the table and using one of
the buttons on the right side of the Additional Parameters box.
Overriding Agent Defaults
Fields at the bottom of the Job definition allow you to override default Agent settings for individual Jobs.
Field
Environment Source
File Override
Description
To override the default environment source file specified in the Environment Source
File field for the Agent, enter a path and file name. This field allows you to type in
command line parameters if they are required for the source file script. For example, if
the script is run from the command line like the following:
/home/retek/internal/bin/chgenv.ksh csrms 13.2 uc4lin
Executable Directory
Override
Output Directory
Override
You can use the Select button to select a file. If the file you select and it requires
additional arguments, you can select the file and type in the arguments.
The MMHOME variable sets the Oracle Retail home directory. It is required in the Oracle
Retail Agent's environment and must be set in the environment source file.
To override the directory specified in the Execution Directory field for the Agent, enter
the directory where the Oracle Retail executable program for this Job resides. You can
use the Select button to select a directory.
To override the directory specified in the Output Directory field for the Agent, enter a
directory where the Oracle Retail program output for this Job will be created. You can
use the Select button to select a directory.
12
Chapter 2: Working with the Oracle Retail Agent
2.5 Monitoring Oracle Retail Tasks
Oracle Retail Tasks show the number of running, completed, and aborted program threads in the ‘Remote status’
column of the Activities window when the Allow Recovery setting is Y in the Jobs’ definition.
Tasks in the Activities window show the number of running, completed, and aborted program threads in the
‘Remote status’ column.
Requirement: In order for the ‘Remote status’ column to display anything for a Task, the Allow Recovery setting
in the Job’s definition must be set to Y.
The format of the ‘Remote status’ column is R<number of running threads> C<number of completed threads>
A<number of aborted threads>. The Task in Figure A has a remote status of R1 C2 A0, which means it has one
running thread, two completed threads, and no aborted threads.
Figure A. Oracle Retail Tasks show the number of running, completed, and
aborted program threads in the ‘Remote status’ column.
UC4 Rapid Automation Oracle Retail Agent Guide
13
2.6 Registered Files for Failed Tasks
When Oracle Retail programs complete in error, the Oracle Retail daily log and any error files are registered with
Tasks to help troubleshoot the problem.
When Oracle Retail programs complete in error, the Oracle Retail Agent registers the following files for the Task
when their timestamps are between the Task’s start and end time:
• Daily Log: The Oracle Retail Agent will look for and register the Oracle Retail daily log.
Note: The default location of the daily log file is $MMHOME/log/[Mon_dd].log. However, you can override
its location and name by defining a DAILY_LOG variable and setting it to a fully pathed file name.
• Error Files: The Oracle Retail Agent will look for and register any error files found in the MMHOME/error
directory matching the syntax [program_name]_[n].[Mon_dd] (for example, err.auditprg_1.Mar_20) and
have timestamps between the Task’s start and end time.
14
Chapter 2: Working with the Oracle Retail Agent
2.7 Setting Trace
You can turn on trace for the Oracle Retail Agent and its Tasks from the System Overview window or ucxjcitx.ini
file.
To turn on trace for the Oracle Retail Agent and its Tasks, do one of the following:
• Go to System Overview, edit properties, and set RA to 9.
• From the ucxjcitx.ini file, set ra=9 as show in bold below:
[TRACE]
file=..\temp\RA_TRACE_##.TXT
max_trace_kb=8000
tcp/ip=0
ra=9
trccount=10
For more information on setting trace, see your UC4 Automation Platform documentation.