Content

Doc ID: Note:103418.1 TEXT/PLAIN

Type:
Subject: Beginner's Guide: Create a
Creation
Custom Event Alert to Fire 27-MAR-2000
Date:
against a Custom Table
Last
Type: WHITE PAPER
Revision 18-JUN-2004
Status: PUBLISHED
Date:
Purpose
-------

The article should provide you with a step-by-step guide on how

to create a custom event alert, which will fire when a row in a
custom table is updated. The update can be the result of an
insert or update DML statement. The article assumes a novice
or beginner level.

Overview of Event Alerts

------------------------

An event alert is a database trigger that tells you when data

in an object within the database has been changed. Event alerts
can be configured to trigger an action, like sending an email
to a user. You may use event alerts to audit changes to
standard Oracle Applications objects or custom objects in user
defined database schemas. However, you should note that the
when you use Oracle Alerts to define database triggers, the
event alert will only work from within the context of the
Oracle Applications. For example, any database event that
affects the objects made from within a form accessed by a menu
from within an Oracle Application Responsibility is within the
context of Oracle Applications. Likewise, any registereed
concurrent manager process or report, whether executed from
within the Oracle Application form or executed from the
command line is within the context of Oracle Applications.
However, if you manually update or insert data from the
SQL*Plus environment without setting the Oracle Application
context, you will not trigger the event alert.

If you want to build an alert to fire against a custom table,

then you will need the following information. Unfortunately,
it is not found in the Oracle Alert User's Guide. The article
provides the following information:

a. How to create and register a customer schema in the

Oracle Applications.

b. How to register the Oracle Alert against the custom

table.

Create a Custom Schema, Table and Responsibility

------------------------------------------------
You may find additional reference to setting up a custom schema
in [NOTE:70276.1] and [NOTE:73492.1]. The following provides
a step-by-step approach to creating a customer application and
registering it within Oracle Applications.

1. First, you must create the schema within the database. This
can be done from any user/schema account with the DBA Role
privileges. Please remember that you must grant to the newly
created schema a minimum of "CONNECT" and "RESOURCES" to the
schema for it to be accessed. (Please refer to the Oracle SQL
Reference Guide for your release of the database to secure
more information.) If you would like to follow the Oracle
Application guidelines for naming conventions, please name
your schema with a three character name, like "CUS" - Customer.
Then, prepend it with an "XX" so that you have an user/schema
"XXCUS" name.

Create the user/schema in the database by using SQL*Plus

under any account with DBA Role privileges:

Unix Prompt
-----------
$ sqlplus system/manager

SQL*Plus Prompt
---------------
SQL> create user XXCUS identified by XXCUS;
SQL> grant connect to XXCUS;
SQL> grant resource to XXCUS;

2. When you register your custom application within the

Application Object Library. It is recommended that you prepend
an "XX" to the custom schema short name so it will not conflict
with any future Oracle Application short names.

Log into Applications as the System Administrator and navigate to:

Application --> Register.

For example:

Application Short Name Basepath Description

----------------------------------------------------------------------
-
Custom Application XXCUS XXCUS_TOP Custom
Application

You may refer to your Oracle Applications Developers Guide for

additional information, for example the Oracle Applications
Developers Guide Release 11 contains this information on pages
2-6.

3. You register your custom user/schema as an Oracle user within

 the context of Oracle Applications. When you put the user/schema
within the context of Oracle Applications, you are storing the
information within the Application Object Library tables. The
Application Object Library is a repository of Oracle Application
specific metadata, which is data that defines data, or data that
lets you extend the functionality of standard Oracle Application
System Administration to your customized extensions.

You can register the user with the Application Object

Library. Log into Oracle Applications as the System
Administrator and navigate:

Security --> ORACLE --> Register.

The following is an example row for your user registration:

Database
Username Password Privilege Install Group
Description

----------------------------------------------------------------------
----
XXCUS XXCUS Enabled 0 Custom
Application

You may refer to th Oracle Applications Release 11 System

Administrator's Guide on page 9-5 for more detail.

4. You need to add the custom user/schema to a data group. You can
do this by logging into Oracle Applications as the System
Administrator and navigate:

Security --> ORACLE --> DataGroup.

The following is an example row for your user registration:

Data Group: Standard

Description: Standard Data Group

Application Oracle ID Description

-------------------------------------------------------------
Custom Application APPS Custom Application

5. You can now build an object, in the example the object will be
a table with a single column, and a local stored database object,
which will be a stored procedure in this example. You can log
into SQL*Plus as the custom schema owner, XXCUS, and create the
following database objects:

Create a Repository Object

--------------------------
You can create a simple one column table as noted
below in the sample DDL statement.
 CREATE TABLE my_event_test (v1 NUMBER);

Create a Stored Object Code Module

----------------------------------
1. You can create a stored code module like the one
shown below.

CREATE OR REPLACE PROCEDURE ins_my_event_test

( value IN OUT NUMBER
, errbuf IN OUT VARCHAR2
, retcode IN OUT NUMBER ) AS
BEGIN
INSERT
INTO my_event_test
VALUES (value);

COMMIT;
END;
/

2. You can test your created procedure by writing a small

PL/SQL program that passes variables into the "errbuf"
and "retcode" variables above, which is required
because they are passed by reference. Then, you can
write a sample query to ensure that a row was inserted
based on the example PL/SQL program.

DECLARE
var1 VARCHAR2(1) := 'A';
var2 VARCHAR2(1) := 'B';
BEGIN
ins_my_event('1', var1, var2);
END;
/

SELECT v1
FROM my_event_test;

6. Based on the preceeding example, you should create your custom

tables,
indexes, views and sequences. The Oracle Coding standards suggest
that
you add the WHO audit columns to the definition of the tables and
views.
If you are unfamiliar with the concept of WHO audit columns, they
are
the defined here for your convenience:

General Who-Audit Columns

-------------------------
a. CREATED_BY NUMBER(15)
b. CREATION_DATE DATE
c. LAST_UPDATED_BY NUMBER(15)
d. LAST_UPDATE_DATE DATE
 Special Who-Audit Columns for Concurrent Manager Programs
---------------------------------------------------------
e. REQUEST_ID NUMBER(15)
f. PROGRAM_ID NUMBER(15)
g. PROGRAM_APPLICATION_ID NUMBER(15)
h. PROGRAM_UPDATE_DATE DATE

7. You can register your custom user/schema's tables or views and any
flexfields with the PL/SQL package AD_DD, which is defined below.
After the specification declarations, you will find examples for
registering the tables and columns from SQL*Plus.

Definition of the AD_DD Specification

-------------------------------------

PROCEDURE DELETE_COLUMN
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
P_COL_NAME VARCHAR2 IN
PROCEDURE DELETE_PRIMARY_KEY_COLUMN
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_KEY_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
P_COL_NAME VARCHAR2 IN
DEFAULT
PROCEDURE DELETE_TABLE
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
PROCEDURE REGISTER_COLUMN
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
P_COL_NAME VARCHAR2 IN
P_COL_SEQ NUMBER IN
P_COL_TYPE VARCHAR2 IN
P_COL_WIDTH NUMBER IN
P_NULLABLE VARCHAR2 IN
P_TRANSLATE VARCHAR2 IN
 P_PRECISION NUMBER IN
DEFAULT
P_SCALE NUMBER IN
DEFAULT
PROCEDURE REGISTER_PRIMARY_KEY
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_KEY_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
P_DESCRIPTION VARCHAR2 IN
P_KEY_TYPE VARCHAR2 IN
DEFAULT
P_AUDIT_FLAG VARCHAR2 IN
DEFAULT
P_ENABLED_FLAG VARCHAR2 IN
DEFAULT
PROCEDURE REGISTER_PRIMARY_KEY_COLUMN
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_KEY_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
P_COL_NAME VARCHAR2 IN
P_COL_SEQUENCE NUMBER IN
PROCEDURE REGISTER_TABLE
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
P_TAB_TYPE VARCHAR2 IN
P_NEXT_EXTENT NUMBER IN
DEFAULT
P_PCT_FREE NUMBER IN
DEFAULT
P_PCT_USED NUMBER IN
DEFAULT
PROCEDURE UPDATE_PRIMARY_KEY
Argument Name Type In/Out
Default?
------------------------------ ----------------------- ------
--------
P_APPL_SHORT_NAME VARCHAR2 IN
P_KEY_NAME VARCHAR2 IN
P_TAB_NAME VARCHAR2 IN
P_DESCRIPTION VARCHAR2 IN
P_KEY_TYPE VARCHAR2 IN
DEFAULT
P_AUDIT_FLAG VARCHAR2 IN
DEFAULT
P_ENABLED_FLAG VARCHAR2 IN
DEFAULT

Example Use of the AD_DD.REGISTER_TABLE & AD_DD.REGISTER_COLUMN

---------------------------------------------------------------
You may use the AD_DD.REGISTER_TABLE and AD_DD.REGISTER_COLUMN
to seed the Oracle Applications Object Library with knowledge
about your custom objects. The general form and example
syntax is noted below. For convenience, the general form
illustrates only the mandatory parameters. You will need to
execute these calls to the packages from your "APPS"
user/schema.

General Syntax Form

-------------------
EXECUTE ad_dd.register_table
( P_APPL_SHORT_NAME
, P_TAB_NAME
, P_TAB_TYPE );

EXECUTE ad_dd.register_column
( P_APPL_SHORT_NAME
, P_TAB_NAME
, P_COL_NAME
, P_COL_SEQ
, P_COL_TYPE
, P_COL_WIDTH
, P_NULLABLE
, P_TRANSLATE );

Example Syntax Form

-------------------
EXECUTE ad_dd.register_table
('XXCUS'
,'MY_EVENT_TEST'
,'T');

EXECUTE ad_dd.register_column
('XXCUS'
,'MY_EVENT_TEST'
,'V1'
, 1
,'NUMBER'
, 38
,'N'
,'N');

You can find supplemental material in the Oracle Applications

Developers
Guide Release 11 on page 3-2.

8. After creating and registering your objects and schema, you need
to run
the APPS_DDL and APPS_ARRAY_DDL packages against your user/schema.
You
must run the scripts from the $AD_TOP/admin/sql directory in the
order
noted below. The general form for executing the command is noted
below
and then examples based on the "XXCUS" user/schema and "XXCUS"
password
from above. Please remember that you must run these scripts from
the
"APPS" user/schema account.

1. adaddls.pls
2. adaaddls.pls
3. adaddlb.pls
4. adaaddlb.pls

General Syntax Form

-------------------
SQL> @$AD_TOP/admin/sql/adaddls.pls <SYSTEM_PW> <SCHEMA_NAME>
<SCHEMA_PW>
SQL> @$AD_TOP/admin/sql/adaaddls.pls <SYSTEM_PW> <SCHEMA_NAME>
<SCHEMA_PW>
SQL> @$AD_TOP/admin/sql/adaddlb.pls <SYSTEM_PW> <SCHEMA_NAME>
<SCHEMA_PW>
SQL> @$AD_TOP/admin/sql/adaaddlb.pls <SYSTEM_PW> <SCHEMA_NAME>
<SCHEMA_PW>

Example Syntax Form

-------------------
SQL> @$AD_TOP/admin/sql/adaddls.pls MANAGER XXCUS XXCUS
SQL> @$AD_TOP/admin/sql/adaaddls.pls MANAGER XXCUS XXCUS
SQL> @$AD_TOP/admin/sql/adaddlb.pls MANAGER XXCUS XXCUS
SQL> @$AD_TOP/admin/sql/adaaddlb.pls MANAGER XXCUS XXCUS

9. Based on the examples provided in step #5 above, you should

connect to
SQL*Plus and create the appropriate grants and synonyms. Below
you will
find the necessary grants and synonyms required for the sample
objects
to be accessible by the Oracle Applications.

Grant Priviledges from the Customer Schema to the APPS Schema

-------------------------------------------------------------
SQL> GRANT all ON my_event_test TO apps;
SQL> GRANT execute ON ins_my_event_test TO apps;

Create Synonyms from the APPS Schema to the Custom Schema

---------------------------------------------------------
SQL> CREATE SYNONYM my_event_test FOR xxcus.my_event_test;
SQL> CREATE SYNONYM ins_my_event_test FOR
xxcus.ins_my_event_test;
 You may refer to the Oracle Applications Release 11 Oracle
Applications Installation manual, page A-7, or to the Oracle
SQL Reference manual.

10. You need to create a custom request group that will hold your
custom and/or standard requests within a custom responsibility.
You can do this by logging into Oracle Applications as System
Administrator and navigate:

Security --> Responsibility --> Request.

Example Custom Request Group:

----------------------------
Group: XXCustom
Application: Custom Application
Code:
Description: Custom Application

11. After creating your custom request group, you need to create a
custom responsibility for your custom user/schema. You can do
this by logging into Oracle Applications as System Administrator
and navigate:

Security --> Responsibility --> Define

Example Custom Responsibility:

-----------------------------
+-----------------+
-----------------
Responsibility Name: XXCustom | Effective
Dates |
Application: Custom Application
+-----------------+
Responsibility Key: From: 05-JAN-
1999
Description: Custom Responsibility To:

+------------------------+
+------------------------+
| Available From | | Data Group
|
+------------------------+
+------------------------+
x Oracle Application Name:
Standard
Oracle Self Service Web Applications Application: Custom
Application

+------------------------+
Menu: Requests Menu | Request Group
|
- Other Responsibilities
+------------------------+
Web Host Name: Name: XXCustom
Web Agent Name: Application: Custom
Application

+-------------------------------+
| Function and Menu Exclusions |
+-------------------------------+
Type Name Description

You may refer to the Oracle Applications Release 11 System

Administrator's Guide on page 2-9 for more information.

12. You can now register your test program as a concurrent program
under SQL*Plus execution method. Do register the program, you
need to ensure that the program is located in the $XXCUS_TOP/sql
directory. Then, as System Administrator you should do the
following steps.

a) First, you setup the executable program, which can be done by

navigating:

Concurrent --> Program --> Executable

Executable = xxcus_ins
Short Name = xxcus_ins
Application = PLSQL Test
Description = XXCUS insert into event test
Execution Method = SQL*Plus
Execution File Name = xxcus.sql

b) Second, you define the concurrent program, which can be done

by navigating:

Concurrent --> Program --> Define

Program = xxcus_ins
Short name = xxcus_ins
Application = PLSQL Test
Description = XXCUS insert into event test
Executable Name = xxcus_ins

NOTE: You should leave all other settings as they are set as
defaults.

c) Third, you add the concurrent program to the concurrent

request group, which can be done by navigating:

Security --> Responsibility --> Request

 Group = XXCustom
Application = Custom Application
Code = <not entered>
Description = xxcus_ins
Requests Type = Program
Requests Name = xxcus_ins
Requests Application = XXCustom

You have now completed the steps on how to create and register a
customer
schema in the Oracle Applications. The next section discusses how you
can
create the alert in Oracle Alerts.

Create the Custom Event Alert

-----------------------------
This section will guide you through creating your test event alert
based
on the example in the first section above.

1. You log into the Oracle Applications, choose the Alert Manager
Responsibility and then navigate:

Alert --> Define

You can create a new alert as follows:

a. You enter the appropriate general information for your alert:

Application = xxcus
Name = xxcus_event_alert
Description = My event alert test
Type = Event

b. You enter the Event Alert Details section for your alert and
then check the "After Insert" and "After Update" boxes:

Application = XXCustom
Table = my_event_test

c. You enter the select statement, example is based on the test

components provided above:

SELECT 'Insert into my_event_test table'

INTO &V_OUTPUT1
FROM SYS.DUAL;

2. You can now click on the Action Button and create the detail
action
for your event alert, by the following steps:
 a. You can set the general action parameters:

Action Name = xxcus_event_action

Action Description = xxcus event detail action
Action Level = Detail

b. You can click on action details:

At this point, you can choose an action type, like a message

and
complete the message detail.

NOTE: The article assumes that the integration between Oracle

Applications and an operating system mail server is
already configured correctly.

3. You can navigate back to the main Alert Definition form, and click
on
the Action Set button, which will allow you to enter a new action
set.
Below is a basic example consistent with the example code in this
entry.

Seq = 1
Action Set Name = xxcus_event_actionset

Then, you need to check the "Enabled" check box so that your event
alert is enabled to run. You should set members as follows:

Seq = 1
Action = xxcus_event_action
Type = Action: Message
Seq = 2
Action = Exit Action Set Successfully
Type = Exit from Action Set successfully

Run and View the Custom Alert

-----------------------------

1. You should sign-on to the Oracle Application and navigate to the

submit Concurrent Request form.

2. You should make the request a single request, click the "OK"
button,
choose the "xxcust_ins" Concurrent Manager Program and then submit
the job.

3. After submitting the Concurrent Request, you should close the

Concurrent Request form, click on "View My Requests" and check
that
the request completed without error.

4. If the Concurrent Request completed without error, you should be

able to sign on to SQL*Plus and view an new row in your test
table;
you should also receive an email message based on the event alert.

Related Documents
-----------------

Oracle Alert User's Guide Release 11

<NOTE.70276.1> : HOW TO INTEGRATE APPLICATIONS RELEASE 11 WITH CUSTOM
<NOTE.73492.1> : Creating a PL/SQL Concurrent Program in Oracle
Applications
.

Copyright