AUTOCONFIG

Introduction:

Oracle Applications 11i consists of lots of configuration files and lots of profile options, which need

to be all correctly set for the applications to work. Managing these profile options and

configuration files manually is error prone. Autoconfig is a tool provided by the Oracle E-Business

Suite to maintain these files and profile options. In this article, you will see how autoconfig works,

what it does, what it does not do, over and above how to customize it to meet our requirements.

Background:

Oracle Applications has a complex architecture with many pieces of technology plugged in

together. For example Apache Web server, Apache Jserv, Forms Listener servlet (or forms

server) etc. Each of these pieces of technology has its own set of configuration files (and there

are lots of them), which need to be set up correctly for them to function. Moreover Oracle

Applications uses many profile options (e.g. Applications Web Agent, Applications Framework

Agent etc) and other bits of information in the database to make the navigation seamless. These

also need to be set correctly for the whole architecture to function seamlessly.

Before autoconfig these configuration files and profile options had to be maintained manually. If

there were a need to change some configuration option, such as web server port or web domain

name, the DBA would have to change all the files and profile options manually. This was quite

error prone on two fronts. One the DBA needs to know and remember all the places where the

change has to be made and secondly it introduces significant risks of typographical or other

errors. These errors will (note I say will not may) result in long but unnecessary downtime.

This manual process is no longer recommended or supported by Oracle.

What is AutoConfig?

In short autoconfig is an 11i configuration tool (set of java classes run from perl/shell scripts)

introduced in 11.5.4, which obviates the need to manually maintain these configuration files and

profile options.

Autoconfig maintains the environment specific values for the 11i environment in an xml file (stored

in $APPL_TOP/admin). When autoconfig is run it overwrites the existing configuration files with

new ones that it creates by merging the templates and the context file, it also updates the

database by running the script it instantiates (merging a template with the values in the context file

is termed as instantiating the template in Oracle parlance) from the script templates. That’s

essentially what autoconfig does i.e. Instantiating configuration files from templates and updating

database with values from the xml file. It does not move directories, check for availability of ports,

update DNS entries and so on. These have to be done by you before running autoconfig.

How does it work?

Each configuration file has one (sometimes two, one for NT and one for UNIX) corresponding

template file (provided by autoconfig patches, stored in $PROD_TOP/admin/template directory).

Profile options and other instance specific information in the database is maintained by many sql

scripts, called from wrapper shell/perl scripts. These scripts also have corresponding template

files (also provided by autoconfig patches, stored in $PROD_TOP/admin/templates). In these

template files all the environment specific values are replaced by placeholders (like "%

s_webhost%).

For e.g.

Following entry in httpd.conf

Timeout 300

is replaced by following in its template $FND_TOP/admin/template/httpd_ux_ias1022.conf

Timeout %s_ohstimeout%

Environment specific values for this placeholder is stored in an environment specific xml file

(called application context file) stored in $APPL_TOP/admin.

For e.g. For

the above placeholder the value stored in the xml file is:

<ohstimeout oa_var="s_ohstimeout">300</ohstimeout>

Each placeholder has a corresponding xml node in the context file. The placeholder name is the

value for the “oa_var” attribute of the xml node, the placeholder name without the prefix “s_”

(generally) is the node name for the xml node and the value is stored as a child text node. These

xml nodes are termed as context variables by Oracle documentation and each node primarily is

identified by its oa_var attribute value. So effectively we can say that in the above case we replace

“300” by context variable “ohstimeout” whose oa_var value is “s_ohstimeout”.

Configuration files can be easily created from the template file by just replacing all the

placeholders with the corresponding values from the context file. This process is termed as

“instantiating the template” in Oracle documentation.

Driver files (stored in $PROD_TOP/admin/driver) store information about what to do with each

template (e.g. instantiate it and replace the existing configuration file with it, instantiate it and run

it). These files are named as <PROD_NAME>tmpl.drv (e.g. adtmpl.drv, fndtmpl.drv etc.) They

contain one line for each template they manage.

When autoconfig (adconfig.pl or adconfig.sh) runs it just processes the driver file for each

product, line by line doing what the driver file instructs it to do. The order of execution of each line

is not sequential as we shall see later. The diagram below depicts the autoconfig functionality.

2 The Context File:

Oracle stores all the environment specific values in an xml file stored in $APPL_TOP/admin

directory, which they call an application context file. This file is created by running

adbldxml.sh/adbldxml.pl (Located in $AD_TOP/bin). Adbldxml.sh in turn runs

oracle.apps.ad.context.GenerateContext java class.

Context file is generated by plugging in environment specific values in the context file template

(don’t confuse this template with the configuration file templates)

$AD_TOP/admin/template/adxmlctx.tmp. In older versions of 11i these replacement values were

gotten from config.txt file (created by rapidwiz during installation), but in later versions, these

values are gotten from the information, in existing configuration files and the database.

Adbldxml.sh/adbldxml.pl (in newer versions of autoconfig) creates a detailed log file, detailing the

source for each context variable.

Following is an example entry for the context variable “domainname” from the log file of

adbldxml.pl run:

[ s_domainname ]

SEVERITY : INFO

SOURCE SEARCHED : Using System commands to get Domain name value

SEARCH RESULTS : Domainname could not be found using system commands.

SOURCE SEARCHED : Database table - GLOBAL_NAME

SEARCH RESULTS : Query on database table GLOBAL_NAME returned - XXXX.WORLD;

Table is hosting incorrect value for domain.

SOURCE SEARCHED : Prompting the user for the domain name.

SEARCH RESULTS : Value accepted from the user - its.yale.edu

VALUE ASSIGNED : its.yale.edu

USER ACTION : No action required

The above entry shows the sources searched, search results for each search and the final

assignment for the context variable domainname. As you can see adbldxml.pl provides the search

information in great detail in its log file. This log file helps a lot in debugging adbldxml.pl behavior.

Each placeholder in the template file has a corresponding xml node (a context variable) in the

context file. They all have a mandatory attribute called oa_var, the attribute value for this attribute

is the placeholder name. Each node is primarily identified by the oa_var attribute value and can

optionally have other attributes like oa_type, oa_enabled scope and default. The node's only child

is a text node, which stores the placeholder’s environment specific value. From here on I will refer

to this text value as the “text value of the context variable”. The description of these context

variables along with their oa_var value can be seen in adctxinf.tmp (stored in

$AD_TOP/admin/template).

Context variables in the context file are organized in a hierarchical order, hence the choice of xml

to store them. These context variables mainly lie under five top level parent nodes i.e. oa_system,

oa_host, oa_install, oa_environments and oa_processes. Each top level parent node is further

divided into further levels before you reach the real context variables.

To change any configuration option in the Oracle Applications environment, we need to change

the value of corresponding context variable in the context file and then run autoconfig for our

changes to take effect. For example if we need to change the web server port then we would

change the text value of the context variable “webport" (oa_var value s_webport), and then run

autoconfig. Since the context file is just an xml file, it can be updated in many ways. I will describe

some of them below.

Editcontext

 is a java application provided by oracle for updating the values in the context file. It is

provided as a patch (patch: 2873456). Editcontext provides a list of all the updatable context

variable values along with their titles. The title is not the variable name or value of oa_var

attribute, but it is derived from adctxinf.xml which comes with the editcontext patch and stores the

title along with the oa_var value for each context variable. Editcontext only lists those context

variables, which are listed in its repository (adxmlctx.tmp). If you find that, not all variables are

listed, then the version of this file is probably lower than the adxmlctx.tmp stored in

$AD_TOP/admin/template. In that case just copy this file from $AD_TOP/admn/template to the

editcontext repository (i.e. <patch unzip directory>/editcontext/etc).

After launching editcontext, we have to find the context variable that we want to update. Once we

find it, we can just change the value and save the new value to the context file (To be precise

editcontext rewrites the whole context file instead of just updating one value). Since the list of

context variables is quite long, it may take a while to find the desired context variable in the list.

Oracle Applications Manager:

Oracle Applications Manager is a web-based portal for managing Oracle Applications. Along with

many other features, this product has a section for updating the context files. This product lists

everything for each context variable i.e. name, oa_var attribute value, description, and real

updateable value. Moreover instead of giving us a long list of context variables to search from, it

divides the context file into many sections and each section is displayed in the xml tree format

making it easier to find a particular context variable. It also provides us with the option of adding

custom context variables (which we will look at in the customization section).

One thing to remember while updating context variables using OAM is that what it displays is

gotten; by parsing the context file stored in fnd_oam_context_files table (Autoconfig at each run

uploads the context file in this table). When we try to update the context file, OAM first update’s

the status flag from ‘S’ to ‘H’(History) for our context file record, it then inserts another row for the

same context file with status ‘S’. (OAM inserts another row instead of updating the existing row to

maintain change history for each context file) It then requests the specific node’s FNDFS listener

for updating the file on the file system (autoconfig uses the file on the file system). So we have to

make sure that the FNDFS listeners are running on all the nodes before using OAM to update the

context file.

With all the features of Oracle Applications Manager mentioned above, updating context files

using Oracle Applications Manager seems to be the direction Oracle is trying to move.

EditContext and Oracle Application Manager are good for updating context file if you need to

update one or two context variables. If you need to modify quite a few variables (for e.g. if you

need to update all the ports in the context file) then using these GUI tools do become

cumbersome. It would be nice to have a scripted way of updating lots of values in the context file

using a data source of changes. I will describe two ways of achieving this using Oracle supplied

code.

The Template Files:

Template files are files, which are merged with the context file (instantiated) to produce

configuration files or scripts to update the database. They are stored in

<PROD_TOP>/admin/templates directory. Autoconfig patches/Technology stack patches install

new templates or upgrade existing templates. Now let’s look at how these template files are

created.

Let’s take a small configuration file REP60_<SID>.ora (Reports server configuration file):

mailprofile="$Header: REP60_server.ora 115.5 2004/03/24 01:10:51 njoseph ship $"

nlssupport=yes

maxconnect=20

cachedir="/u02/app/oracle/product/8.0.6/reports60/server/cache"

cachesize=50

minengine=5

maxengine=10

initengine=5

maxidle=30

security=1

englife=50

If we replace all the environment specific values with context variables from the context file, then

this is what we get:

mailprofile="$Header: REP60_server.ora 115.5 2004/03/24 01:10:51 njoseph ship $"

nlssupport=yes

maxconnect=20

cachedir="%s_tools_oh%/reports60/server/cache"

cachesize=50

minengine=%s_minengine%

maxengine=%s_maxengine%

initengine=0

maxidle=30

security=1

englife=50

And now we have a template file corresponding to the Reports server configuration file. The

placeholder values enclosed by "%" correspond to the context variable in the context file. If we

instantiate this template using the values from the context file we can easily recreate our

configuration file. All the configuration files and sql scripts are converted to templates in similar

fashion and supplied to us by autoconfig patches.

The Driver Files:

Driver files, as the name suggests drives what autoconfig does (stored in

<PROD_TOP>/admin/driver). They are named as <PROD_NAME>tmpl.drv i.e. adtmpl.drv,

fndtmpl.drv etc. Autoconfig patches install and update these driver files. Each driver file has one

line for each template it manages. Each line tells autoconfig what to do with that template. This is

achieved by using a particular syntax that conveys the relevant information to autoconfig.

Following is the syntax for the lines in the driver files.

<PROD> <Location> < Name> <Action> <Dest directory> <Dest file name> <File permission>

For e.g.

ad admin/template adconfig.txt INSTE8 <s_at>/admin adconfig.txt 600

Column Description

<PROD> Product Name

<Location> Directory underneath <PROD_TOP> where the template is located.

Generally "admin/template".

<Name> Name of the template File

<Action> Type of action to be performed on this template (Refer to the following

table for description of different kinds of action)

<Dest directory> Destination directory of the instantiated template file. We can use context

variables enclose In “<>” to specify the destination directory. For example

if we want to specify $APPL_TOP/admin as the destination directory we

would specify it as “<s_at>/admin” in the driver file.

<Dest file name> Destination configuration file name for the instantiated template file. We

can use context variables enclosed in “<>” to specify the destination

configuration file name. For example if the destination file has Database

SID we can specify it as “<s_dbSid>.env” in the driver file.

<File

permission>

Autoconfig generates the configuration file with the provided unix style

permission.

Actions:

Action Description

INSTE8 · Instantiate (replace context variables with values from xml

context file)

· Copy the result to the <Dest directory>/<Dest file name>

overwriting the existing configuration file, if one exists.

· Change the permission to <File permission>

INSTE8_SETUP · Instantiate (replace context variables with values from xml

context file)

· Copy the result to the <Dest directory>/<Dest file name>

overwriting the existing file, if one exists.

· Change the permission to <File permission>

· Execute the instantiated file.

INSTE8_APPLY · Instantiate (replace context variables with values from xml

context file)

· Copy the result to the <Dest directory>/<Dest file name>

overwriting the existing file, if one exists.

· Change the permission to <File permission>

· Execute the instantiated file.

INSTE8_PRF · Instantiate (replace context variables with values from xml

context file)

· Copy the result to the <Dest directory>/<Dest file name>

overwriting the existing file, if one exists.

· Change the permission to <File permission>

· Execute the instantiated file.

INSTALL · Instantiate the template file only if the resulting configuration

file does not already exist.

Though the description of three of the actions is same, they are there to get different execution

order within autoconfig’s execution of each driver file. The execution order in which autoconfig

processes each line is INSTE8, INSTALL, INSTE8_SETUP, INSTE8_APPLY and INSTE8_PRF.

These actions mark the different phases of autoconfig i.e. Setup phase, Apply phase and Profile

phase. It’s also possible to run autoconfig only up to a particular phase.

The driver file syntax also supports if then else branching based on type of node (i.e. web, admin,

forms etc), which is useful in a multi node installation. The syntax also supports the branching

based on the platform type (Unix or Windows). This allows having multiple templates for each

configuration file and instantiating a particular template based on the platform.

For e.g.

if platform NT

ad admin/template APPLSYS_nt.env INSTE8 <s_at> <s_dbSid>.env

endif