Download - CIM Developer's Guide - Oracle

ATG CIM Developer's Guide - product version: 10.1.2Copyright © 1997, 2012 Oracle and/or its affiliates. All rights reserved.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are
trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are
protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any
means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please
report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the
following notice is applicable:
U.S. GOVERNMENT END USERS:
delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and
agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any
operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and
license restrictions applicable to the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended
for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or
hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures
to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties.
Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to
your access to or use of third-party content, products, or services.
The software is based in part on the work of the Independent JPEG Group.
ATG CIM Developer's Guide iii
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
3. Creating CIM Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Creating CIM Wizards and Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Adding Steps to a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Changing Step Order in Combined Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Adding Tasks to Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Adding a Task with No Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Adding a Task with Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Collecting User Input for Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Omitting Tasks from Batch Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Using Commands in Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Task Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Navigation Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Compound Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Adding Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Example CIM Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Creating Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Adding Tasks to the CIM Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Creating Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Creating Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Creating Select Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Making Select Providers Available to CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Creating Navoption Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Using Navoption Providers in Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5. Using Product Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Product Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Persistence and Property File Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Using Dynamic Values in Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Product Add-Ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Named Datasources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
DB Init Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CIM Session Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7. CIM JavaBean Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Task Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
1 Introduction
This book is intended to introduce developers and partners to the Configuration & Installation Manager (CIM). It
describes how to create and extend CIM plugins, which can greatly simplify configuration of your applications.
This chapter includes the following sections:
Audience (page 1)
Audience
To get the most out of this guide, you should be familiar with:
• Nucleus components and their configuration
• Configuration requirements for your product, including database table creation, assembly, and deployment
See the ATG Platform Programming Guide for information on these topics.
Documentation Conventions
Convention Explanation
Italics Introduces new terms and indicates emphasis.
Bold Emphasizes important information, or indicates field names, menu items, or button
names.
monospace Indicates syntax examples, values that you specify, or results that you receive.
Brackets [ ] Indicates optional items. For example, in the following statement: SELECT
[DISTINCT], DISTINCT is an optional keyword.
2 1 Introduction
The directory where you installed the Oracle ATG Web Commerce platform is identified as <ATG10dir>. CIM
plugins can be created for any version of ATG software.
2 CIM Overview 3
2 CIM Overview
A common complaint about enterprise software is the complexity of the installation and configuration
process. CIM is designed to cut down this complexity. A series of text-based wizards guide the user through
configuration procedures, providing these benefits:
• The user knows that steps were performed in the correct order.
• Steps are automated and intelligent defaults provided where possible, avoiding opportunities for input errors.
• All necessary steps are complete.
The result is a working, basic installation that can be used as a starting point for further work. Note that CIM
is not intended to handle the entire configuration process, since much of the work of setting up an Oracle
ATG Web Commerce installation is handled through the administrative user interfaces and through custom
components.
CIM scripts are written in XML and use a library of templates, tasks, and validators, making them easy to create
and extend. This chapter introduces CIM script components and describes how to run the demonstration script
so you can see CIM in action.
This chapter contains the following sections:
CIM Installed Files (page 3)
CIM Script Elements (page 4)
Executing CIM Plugins (page 5)
Using the Provided CIM Plugins (page 6)
CIM Installed Files
CIM consists of two main pieces:
• Plugins, which define wizards that carry out configuration steps for each CIM-enabled application.
• The framework, which executes the plugins.
This guide is focused on creating and extending plugins. Changes to the CIM framework are not supported.
CIM is installed automatically as a module in the Oracle ATG Web Commerce platform, located at <ATG10dir>/
CIM. The CIM module includes the following directories:
• config—Component configuration properties files.
4 2 CIM Overview
• data—Database used internally by CIM scripts to store user selections. To start from scratch if you have
previously used CIM, you can delete the contents of this directory.
• lib—CIM .jar files.
• log—Contains the cim.log file. If debugging is turned on, this directory also includes XML files that
represent templates that have been run.
• plugins—Plugin XML files and supporting information for CIM-configurable products.
• tmp—A working directory created by some CIM processes.
The CIM executable is located at <ATG10dir>/home/cim.bat|sh.
In addition to the CIM module itself, all CIM-enabled applications should include a /cim directory, which
contains the product.xml and dbinit.xml CIM files for that application. For information on these files, see the
Using Product Definition Files (page 35) section.
CIM Script Elements
CIM scripts are a form of domain-specific language. They are written in XML using a tightly constrained set of
elements to achieve a specific purpose. These XML files populate JavaBeans, which perform configuration tasks
on your Oracle ATG Web Commerce Search system.
Scripts have the following elements:
• Step—Logical groupings of information presented to the user as a unit. For example, a step may prompt the
user for input values, provide the user with feedback about collected input, or provide information about the
state of the system. See Adding Steps to a Process (page 9).
At the completion of a step, CIM has prepared one or more tasks with the values necessary for execution.
These tasks are not yet executed. However, each time CIM collects a value from the user it has an opportunity
to execute logic. For example, before moving on to the next step, you may want to ensure that the user has
not included disallowed characters in their input.
After a step has collected all of the information required to execute its related tasks, CIM prepares these tasks
and places them in a buffer for later execution.
• Process—A logical grouping of steps. There are no enforced restrictions, but you should contain all task
dependencies within the process. Each step in a process should be able to execute on its own, without
previous processes running. For example, if a step in a process requires a JDBC connection, that connection
should be configured within the process, and should not rely on a step in another process. See Creating CIM
Wizards and Processes (page 7).
• Wizard—A set of one or more processes executed in order to configure a product. See Creating CIM Wizards
and Processes (page 7).
• Task—Carries out the work specified in the step. A step can include more than one task. See Adding Tasks to
Steps (page 10).
• Validator—Can check system state to ensure that information is processed correctly, or can validate user input
for a variety of possible error conditions, allowing you to alter the script’s flow. See Adding Validators (page
15).
2 CIM Overview 5
The Creating CIM Plugins (page 7) chapter describes how to use each of these elements to guide users
through Oracle ATG Web Commerce Search product configuration.
Executing CIM Plugins
CIM can run in two basic forms. The standard way to run a CIM plugin is using a command line interface to make
selections at each step. To run a CIM plugin with the standard interface, go to:
<ATG10dir>\home\bin
The CIM main menu appears.
You can also run CIM in batch mode. This option is provided for users who must frequently perform identical
installation processes, such as when setting up environments for testing. To use CIM in batch mode, do the
following:
1. Start CIM using the –record flag.
Note that by default CIM records batch files in an encrypted form to protect your passwords. If you need
unencrypted access to your batch files, you can record with the –noencryption flag.
2. Proceed with configuration.
3. Select Batch File Save from the Main Menu when finished.
4. Specify a password to use when running the batch file.
5. Specify a save location.
CIM records your selections in a batch file. To repeat the procedure with those selections, use the following
command to start CIM:
Enter the password when prompted.
Note: When you run a CIM batch file, if any of the data import steps fail, the script exits without continuing on
to configuration steps. If this happens, the log file includes an Error Executing Batch File error message
with information about the failure.
If you are familiar with CIM, you can edit and run batch files without stepping through the UI. The following
example shows a partial batch:
atg.cim.jboss.CreateJbossAppServerInstanceTask.antFile=C:\dev\work\CIM\cim\ant\
6 2 CIM Overview
cim-ant.xml atg.cim.jboss.CreateJbossAppServerInstanceTask.jbossPath=C:/jboss/ atg.cim.jboss.CreateJbossAppServerInstanceTask.serverInstanceName=pub_commerce atg.cim.jboss.CreateJbossAppServerInstanceTask.execute() atg.cim.dynamo.CreateDynamoServerInstanceTask.antFile=C:\dev\work\CIM\cim\ant\ cim-ant.xml atg.cim.dynamo.CreateDynamoServerInstanceTask.atgPath=C:/ATG/ATG10/ atg.cim.dynamo.CreateDynamoServerInstanceTask.serverInstanceName=pub_commerce atg.cim.dynamo.CreateDynamoServerInstanceTask.execute()
When the script is finished, it notifies you that the script completed successfully.
Note: No validation is performed when using batch mode. CIM tasks are executed in order.
Using the Provided CIM Plugins
By default CIM includes a number of plugins already created for configuring Oracle ATG Web Commerce
products. You can build on these plugins as described in this guide, or use them as models for creating your
own. The following are included in CIM:
• Product Selection—Users select the combination of products they want to configure.
• Server Instance Creation—Create Oracle ATG Web Commerce servers with the required /config layer
information.
• Application Server Selection—Users must select the application server to which their application will be
deployed, and can perform some optimization tasks.
• Database Configuration—Users provide database configuration information, configure datasources, etc. for
the products they have selected.
• Application Assembly—Users can assemble and deploy their application to the application server.
• Custom Wizard Launcher—New CIM wizards you create are added under this menu.
Documentation for these plugins is provided as part of the command-line interface; type H at any prompt to
access the help. You may want to familiarize yourself with these plugins before creating your own.
3 Creating CIM Plugins 7
3 Creating CIM Plugins
To create a CIM plugin, you create several XML files that define your plugin and its features. The wizards.xml
file and its associated tasks.xml files define the following:
• What steps the plugin contains
• What order in which to perform the steps
• What user input to accept
• What validation to perform
• What programmatic tasks should be performed
Plugin creation is straightforward, and you can take advantage of many existing components when you create a
new plugin. Your plugins can also use XML-combine to extend existing plugins.
This chapter explains how to write XML code that assembles CIM components into a functioning plugin; for
detailed information on those components, and how to create your own components, see the Creating CIM
Worker Objects (page 21) chapter.
This chapter contains the following sections:
Creating CIM Wizards and Processes (page 7)
Adding Steps to a Process (page 9)
Adding Tasks to Steps (page 10)
Using Commands in Steps (page 12)
Using Dynamic Values in Steps (page 15)
Adding Validators (page 15)
Example CIM Plugin (page 17)
Creating CIM Wizards and Processes
The first step in creating your wizard is to create the base script to which you will add configuration functionality,
validators, and other components.
8 3 Creating CIM Plugins
To create a new CIM script, create a wizards.xml file as shown:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE wizards SYSTEM "http://www.atg.com/dtds/wizard_1_0.dtd">
<wizards> <wizard id="ID"> <title resource-key="" resource-params="">Title</title> <detail resource-key="" resource-params="">Detail</detail> <process id="MyProcess">

Place the wizards.xml file in the <ATG10dir>/cim/plugins/plugin_name/ directory, along with any
supporting files for that plugin. Give the plugin_name directory any name, but note that the name cannot
include spaces. The wizard and process id must both be unique and should be descriptive enough to identify
the wizard’s function.
Note: The wizard-type attribute for the <wizard> element is used only by product configuration wizards,
and should not be used in custom scripts. If this attribute is used, the script will not appear in the custom wizard
launcher.
If you want your wizard to extend another wizard, use the following:
<wizard id="MyWizard" extends="OtherWizard">
When you extend a wizard, the following items are merged using XML-combine:
• MyWizard XML with OtherWizard XML
• Supporting files, including tasks.xml, validators.xml, providers.xml, and selectproviders.xml,
are combined if the two wizards are located in different plugins; if they are in the same plugin, they both use
the same supporting files
MyWizard inherits everything included in the OtherWizard plugin. Note that it does not inherit items from
other wizards that are defined in the same plugin as OtherWizard, but only inherits from OtherWizard itself.
In addition, MyWizard can access Java classes used in the plugin that contains OtherWizard. See the XML File
Combination section of the ATG Platform Programming Guide for general information on XML-combine.
When you run the MyWizard plugin, a combined-MyWizard.xml file containing the combined wizards is
saved to the directory where MyWizard’s wizards.xml file is located. This file is deleted if the wizard exits
successfully, unless you have turned on debugging. To turn on debugging, edit the <ATG10dir>/CIM/config/
GLOBAL.properties file.
The title and detail are shown in CIM menus. For example:
Choose Wizard: *[0] OtherWizard – OtherWizard detail [1] MyWizard - MyWizard detail
The wizard element contains one or more process elements, which contain a logical grouping of steps and
have no attributes of their own (see the Adding Steps to a Process (page 9) section for step information).
For an example, see the Example CIM Plugin (page 17) section of this chapter, or review the wizards.xml file
located at <ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.
Adding Steps to a Process
Steps are where the work of a CIM plugin is outlined. Each step should consist of a logical group that can be
presented to the user as a single entity. When the step is complete, the following events have taken place:
• Relevant information is displayed to the user about what CIM will do
• Input has been collected from the user
• Validators may have checked the input or system state
• Tasks are prepared for execution
• A navigation option is chosen by the user
To insert a step, place the following XML snippet inside a process tag:
<step id="step_ID" insert-after="other_step_ID" type="standard_or_base" class="class_name"> <title/> <detail/> <property name="some_name"> <value>value</value> </property> <navoption> <option default="true"> <label>Next Step</label> <command type="EXECUTE_STEP_TASKS" /> <command type="NEXT_STEP" /> </option> <option > <label>Redo Step</label> <command type="DROP_STEP_TASKS" /> <command type="REDO_STEP" /> </option> </navoption> </step>
Steps have the following attributes:
• id—Uniquely identifies the step to the framework.
• insert-after—When combining wizards, identifies the step ID in the base file after which this step should
be inserted.
• type—Can be standard or template. This attribute is optional, and the default is standard. A standard
step acts as part of a simple, linear process with a tightly restricted set of user options, and relies on default
worker objects for its behavior. A template step permits dynamic generation of options and greater
flexibility, but requires you to write your own components; this is provided for use with future versions of CIM.
• class—If a template step, provide the class used to implement the step. This attribute is optional.
Steps contain the following elements:
• title—Identifies the step in the user interface.
• detail—Additional text that provides any information the user needs to know in order to complete the step.
• property— Argument to pass to a template step; not used in standard steps. This allows a single template
to be reused, displaying different information depending on the property. For an example, see the Database
Configuration menu in CIM, in which a single template displays different options depending on the database
selected.
• navoption—Provides a framework of options from which the user can select. As part of navigation,
commands are fired, some of which are purely navigational, and others of which have to do with tasks that
are prepared during the step. Navigation options include Next Step, Redo Step, Jump to Third Step, etc. The
default selection is indicated by the attribute default="true", and is executed if no value is entered and the
user presses the Enter key.
• navoptionprovider—For dynamic navigation, provide the Java class that supplies this feature for your
script.
For an example, see the Example CIM Plugin (page 17) section of this chapter, or review the wizards.xml file
located at <ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.
Changing Step Order in Combined Wizards
If your wizard extends an existing wizard, you’ll need to think about the order in which the steps of the
combined wizard should be performed. Default behavior is to append your wizard to the wizard you are
extending. You can change this by using the insert-after attribute in your step as shown:
<step id="AddedStep" insert-after="OriginalWizardStep" > </step>
When the script is run, your wizard’s AddedStep is performed immediately after the OriginalWizardStep from the
extended wizard.
You can also use the combination to entirely suppress steps in the base wizard. See the XML File Combination
section of the ATG Platform Programming Guide for general information on XML-combine.
Adding Tasks to Steps
As part of the step, you can specify one or more tasks to be configured and executed. Tasks reside in their own
XML file, named tasks.xml, and are referred to from wizards.xml. The id specified in the wizards.xml file’s
task element must match the id of a task defined in tasks.xml. For an example of a tasks.xml file, see the
<ATG10dir>/CIM/plugins/base directory in your Oracle ATG Web Commerce installation.
In the task, you specify the name and Java class. This identifies to CIM the component that is going to do the
work of the task, so that CIM can set properties on that component. Input passes through the following series of
layers:
CIM user interface > wizards.xml > tasks.xml > JavaBean
The task element’s property element refers to a component property to which the input should be assigned.
Within the input element, you can include a label, which is displayed in the user interface, and one or more
validators to check the entered text (see the Adding Validators (page 15) section of this chapter).
Task examples are shown in the sections that follow.
Adding a Task with No Properties
To add a simple task to a step in a wizard, add the snippet below as a child of a <step> element. Multiple tasks
can be included in a single step, in which case they are processed in order.
<step> … <task id="CreateDemoFileTask"/> <task id="DoSomethingTask"/> … </step>
Adding a Task with Properties
In the tasks.xml file, the tasks themselves are specified in detail, including which JavaBean does the task’s
work, what information is collected, and any validation that should be performed. The property elements point
to properties of the bean.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE tasks SYSTEM "http://www.atg.com/dtds/task_1_0.dtd">
<tasks>
Collecting User Input for Tasks
In addition to retrieving values, your script’s end user may need to set values in order for a task to be completed.
CIM has a text-based interface, and users can input information as shown by the bold line in the following
example, which allows the user to enter a value for the serverInstanceName property:
<task id="CreateJBossAppServerInstanceTask"
class="atg.cim.jboss.CreateJbossAppServerInstanceTask"> <property name="serverInstanceName"> <value>pub_commerce</value>
<input type="text"> <label>Enter a unique server instance name:</label> </input>
etc.
Note that if you use a SelectProvider to set a property, such as the serverInstanceName in the sample
above, that SelectProvider must have that property, and it must be of the same type.
CIM supports the following types of input:
• text—User enters plain text.
• select—User selects from a provided list of options using numeric hotkeys. This option requires that you
write a customer Java class that implements iSelectProvider. Identify this class in the selectprovider
attribute for the input tag as shown:
<input type="select" selectprovider="provider_class">
See the Creating Select Providers (page 28) section for information.
• password—Text the user enters is masked by asterisks (*) in the user interface.
• path—User enters a path to an item; this option includes tab completion for quicker input.
Omitting Tasks from Batch Files
As described in Executing CIM Plugins (page 5), a batch file is a script that can be run as a single unit, without
stepping through the user interface. Some tasks, such as those that store user-entered values, do not add any
value to a batch file and can be omitted.
To omit a task from any batch files saved for it, use the following syntax:
<task id="MyTask" batch="false" class="atg.cim.dynamo.TaskClass"> … </task>
The default batch value is true.
Using Commands in Steps
Commands are used within steps to instruct the CIM framework to either do something with the configured
tasks in that step, or perform navigational functions. Commands are specified using the type attributes of the
command element. For example:
Task Commands
The following commands can be used in steps to affect tasks:
• LAUNCH_WIZARD—Used by the Base plugin to launch wizards. Do not use.
• LAUNCH_TEMPLATE—If you are extending CIM, use this command to signal the start of your own template.
Requires value="class name of template".
• TEMPLATE_COMPLETE—Signals the end of a template, returning program control to the wizard. If you provide
a value attribute, it is used as the value of a GO_TO step by the parent plugin.
• WIZARD_COMPLETE—Signals the end of a wizard. Do not use.
• EXECUTE_QUEUED_TASKS—Executes all tasks on the queue at one time.
• DROP_STEP_TASKS—Any configured tasks that have not yet been performed are not executed.
• EXECUTE_STEP_TASKS—Executes tasks configured during step, does not execute any queued tasks.
• DELETE_QUEUED_TASKS—Clears the queue of all tasks.
• DISPLAY_TEXT—Displays text to the UI. Requires value="text to display".
• ADD_STEP_TASKS_TO_QUEUE—Moves step tasks to the queue, enabling them to be processed as a batch at a
later time.
The following example involves executing currently configured tasks when the user moves to the next step in
the wizard:
<navoption> <option default="true"> <label>Next Step</label> <command type="EXECUTE_STEP_TASKS" /> <command type="NEXT_STEP" /> </option>
For additional examples, see the Example CIM Plugin (page 17) section of this chapter, or review the
wizards.xml file located at <ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.
Navigation Commands
Navigation can be added to steps using commands. The following commands are used for navigation in a step:
• NEXT_STEP—Process the next step in the step list.
• REDO_STEP—Process the current step again, using default values.
• PREVIOUS_STEP—Process the previous step in the step list.
• GOTO_STEP—Process the step given in the required targetId attribute. Requires value="step ID to go
to".
• REDO_INPUT—Causes CIM to re-render the last label and input request. Can only be used in the POSTINPUT
phase of an input validator.
• PROCESS_COMPLETE—Notifies CIM that a process has been completed.
• QUIT—Shut down CIM with no saving of data.
The following example shows how you can use navigation commands along with task commands in your steps:
<step id="FirstStep"> <title>First Step</title> <detail>Details of the first step: Demonstrates simple navigation </detail> <navoption> <option default="true"> <label>Next Step</label> <command type="EXECUTE_STEP_TASKS" /> <command type="NEXT_STEP" /> </option> <option > <label>Redo Step</label> <command type="DROP_STEP_TASKS" /> <command type="REDO_STEP" /> </option> <option > <label>Jump to [T]hird Step</label> <command type="DROP_STEP_TASKS" /> <command type="GOTO_STEP" value="ThirdStep" /> </option> <option > <label>Jump to [F]ourth Step</label> <command type="DROP_STEP_TASKS" /> <command type="GOTO_STEP" value="FourthStep" /> </option> </navoption> </step>
Note that when adding navigation options, you should surround the hot-key letter with brackets:
Load [W]izard.
If no brackets are present, CIM automatically designates the first letter as the hot key. CIM will throw a runtime
error if a single step includes multiple equivalent hotkeys.
Compound Commands
In addition to the task commands and navigation options outlined in the previous sections, CIM also includes
the following commands, which combine a task and navigation option:
• DROP_REDO—Combines the DROP_STEP_TASKS task command with the REDO_STEP navigation command.
• EXECUTE_NEXT—Combines the EXECUTE_STEP_TASKS task command with the NEXT_STEP navigation
command.
command.
Using Dynamic Values in Steps
There are several ways you can use dynamic values in steps. This allows you to refer to component values easily
and to localize your scripts.
To refer to a value in the session context, use the following syntax:
${variableName}
To refer to a bean value, use the following syntax:
${componentID.propertyName}
Where componentID is the id for the task (defined in tasks.xml), validator (defined in validators.xml),
or provider (defined in providers.xml) you want to access. If the JavaBean is a provider (see the Creating
Providers (page 27) section of the Creating CIM Worker Objects (page 21) chapter), the CIM framework will
call the provider’s provide() method and refresh the component every time it accesses the component. This is
useful if you’re accessing information that changes during the course of running the script.
Adding Validators
CIM uses validator objects to check user input for formatting or other errors. Validators return either true or
false, and allow you to conditionally display messages or perform navigation commands.
Validators can be used at two levels in a script:
• In a step, a validator can perform a check on some system state.
Note that using validators may mean that not all phases of the step execute. For example, if the outcome of a
PRESTEP validator commands CIM to navigate to another step, later phases will never execute.
• When a task collects input, a validator can check the input immediately.
For each validator, you’ll need to specify:
• The step phase in which validation takes place.
• Commands to execute if the validator returns true (optional).
• Commands to execute if the validator returns false (optional).
Step validators can be described in terms of the point at which they perform their check; this information is
required in the phase attribute of the validator tag. The phases are:
• PRESTEP—Executed before processing a step starts.
• PREINPUT—Executed after title and description UI rendered to user, but before any input collection elements
are rendered.
• PRENAVIGATION—Executed after UI input collection is complete and tasks are configured, but before
navigation options are displayed to the user. at this point no tasks have been executed.
• POSTSTEP—Executed after navigation chosen by user, does not execute if the user selects a navigation step
that executes a command to move to another step.
To use a validator in a step, add the snippet below as a child of a <step> element. Multiple validators can be
added to a single step. They are processed in order depending on their phase attribute.
<step>
... other xml...
</step>
To use a validator in a task, use the following XML:
<task id="CreateJBossAppServerInstanceTask" class="atg.cim.tasks.CreateJBossAppServerInstanceTask" <property name="serverInstanceName"> <value>pub_commerce</value>
etc.
For an example, see the Example CIM Plugin (page 17) section of this chapter, or review the files located at
<ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.
Handling Errors in Steps
In addition to whatever error handling you may build into your Java classes, CIM includes an XML-level form of
basic error handling. If one of your steps encounters an error during execution, you can use the <error> element
to specify an alternative step.
In this example. the error element checks to see if there have been changes to CIM’s persisted data made
outside of CIM; if so, the UI prompts the user to re-select a product for configuration.
<error> <step id="ProductionSelectionPersistenceCheckErrorStep"> <title>Product Selection Model Update</title> <detail> <![CDATA[ The CIM Product object model has been updated.
REQUIRED ACTION: Re-Execute the Product Selection wizard. Select [p] from the Main Menu. ]]> </detail> <navoption id="continue"> <label>Continue</label> <command type="NEXT_STEP" /> </navoption> </step> </error>
Example CIM Plugin
The following code shows an example of a wizards.xml file that defines a custom CIM plugin. The plugin helps
a user install an Oracle ATG Web Commerce hotfix, and shows the elements previously described in this chapter
working together.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE wizards SYSTEM "http://www.atg.com/dtds/wizard_1_0.dtd"> <wizards> <wizard id="MyPlugin"> <title>Configure ATG10 Hotfix 2</title> <detail>Installs a test hotfix</detail>
<process id="TestProcess"> <step id="FirstStep"> <title>First Step</title> <detail>Choose the task you want to perform:</detail>
<navoption id="install"> <label>[I]nstall hotfix</label> <command type="GOTO_STEP" value="InstallHotfix"/> </navoption> <navoption id="uninstall"> <label>[U]ninstall hotfix</label> <command type="GOTO_STEP" value="UninstallHotfix"/> </navoption>
</step>
<step id="UninstallHotfix"> <title>Test Hotfix Uninstallation</title> <detail></detail> <navoption id="install"> <label>[U]ninstall hotfix</label> <command type="GOTO_STEP" value="RemoveHotfix"/> </navoption> </step>
<step id="RemoveHotfix"> <title>Uninstall Hotfix</title> <detail>Uninstalls the test hotfix</detail>
<task id="RemoveHotfix"/> <task id="RemoveProperties"/>
<validator id="AlwaysTrueValidator" phase="PRENAVIGATION"> <if-true> <command type="EXECUTE_STEP_TASKS" /> <command type="DISPLAY_TEXT" value="Hotfix has been uninstalled" /> <command type="GOTO_STEP" value="FirstStep"/> </if-true> </validator> </step>
</process>
</wizard> </wizards>
4 Creating CIM Worker Objects 21
4 Creating CIM Worker Objects
This chapter describes how to create new worker objects for CIM. Worker object is a general term for a Java
class that performs any sort of functionality relating to the installation and configuration of Oracle ATG Web
Commerce products. Validators, Tasks, and Providers are three types of worker object.
• Task. Use when you want to do something such as copy a file or save data.
• Validator. Use to check user input or system state. For example, ensure that an input string contains only
alphanumeric characters. Validators return true or false values.
• Provider. Use a provider when a wizard needs a value from the system, such as a list of names of the current
JBoss server instances.
• Select Provider. Use when you want to give the user a list of items from which to select. Select providers can
set properties, but do not perform actions.
• Navoption Provider. Use to provide a dynamic list of navigation options that perform tasks when selected.
This chapter includes the following sections:
Creating Tasks (page 21)
Creating Validators (page 25)
Creating Providers (page 27)
Creating Tasks
A Task is a worker object that allows the CIM framework to make a change in the system. Task objects implement
the execute() method in the atg.cim.worker.ITask interface.
ITask defines the methods shown:
package atg.cim.worker; import java.io.Serializable;
22 4 Creating CIM Worker Objects
public interface ITask extends Serializable {
/** * Called by the CIM Framework before calling execute(). Logic checking if the *task can be executed should be placed in this method. * * @return true if the object has all the values needed to execute */ public boolean canExecute(); /** * Logic to perform a task should be placed in this method. Code should update *the message property so the framework may retrieve the last state of the *component. * * The IProgressMonitor may be null, so logic should test before using this *argument. * * @throws TaskException */ public void execute(IProgressMonitor progressMonitor) throws TaskException;
/** * Called by the CIM Framework before calling undo(). Logic to check should be *placed in this method. * * @return true if the object can undo */ public boolean canUndo();
/** * Logic to return a system to its before-execute state. * * The IProgressMonitor may be null, so logic should test before using this *argument * * @throws TaskException */ public void undo(IProgressMonitor progressMonitor) throws TaskException;
}
It is a good practice to end your class names with Task (for example: ATGPathTask).
You can extend the atg.cim.worker.Task class to create custom tasks, as shown in the Example: Writing a
HelloWorld Task (page 23) section.
The progressMonitor method can be used to display a status bar for any task that is defined in its XML
as “long-running.” In the provided configuration scripts, tasks such as schema creation and data import are
considered long-running. It can show progress when the amount of work is unknown (similar to the Windows
spinning hourglass cursor), or to show increments of a known amount of work as they are completed. The
Progress Monitor interface is shown here:
public interface IProgressMonitor {
/** Class version string */ public static final String CLASS_VERSION = "$Change: 509503 $$DateTime: 2008/09/16 13:48:09 $$Author: acollege $";
/** * Constant indicating an unknown amount of work. */ public static final int UNKNOWN = -1;
/** * Called by worker object at the start of a long running task. Should only be *called once on a given * IProgressMonitor instance. * * @param pTaskMsg - msg to display to the UI * @param totalWork - the total number of units to be processed. Value may be *IProgressMonitor.UNKNOWN for * when the total number of work units is not known in advance */ public void beginTask(String pTaskMsg, int pTotalWork);
/** * Called numerous times by a worker object as a long running task is being *processed * * @param work the number of units of work completed for this call. This is an *incremental value, * not the cumulative amount of work performed so far. * */ public void worked(int pWork);
}
Write the following Task object class.
Note: Although undo() methods are included in the worker object API, they are reserved for future use.
package atg.cim.task;
/* This is simply a dummy demo task and prints * Hello World! at the console. */
public class HelloWorldTask implements ITask {
String mMessage;
/** * Simply returns true */ public boolean canExecute() { return true; }
/** * Returns false, as sending output to console * can not be undone * @return false */ public boolean canUndo() { return false; }
/** * * Prints "Hello World!" at console. * * @param pProgressMonitor * @exception TaskException */ public void execute(IProgressMonitor pProgressMonitor) throws TaskException { try { System.out.println("Hello World!"); mMessage = " Executed HelloWorldTask";
} catch(Exception exp) { mMessage = "Error executing HelloWorldTask"; throw new TaskException("Error ", exp); }
}
Adding Tasks to the CIM Library
Tasks are made available to the CIM framework by adding an XML snippet to any /plugin_name/tasks.xml
file as shown in the example:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE tasks SYSTEM "http://www.atg.com/dtds/task_1_0.dtd">
<task id="DeleteFileTask" class="atg.cim.task.DemoTask">
<property name="fileName"> <input type="text"> <label>Enter a file name : </label> </input> </property> </task>
You can now refer to the DeleteFileTask in your wizards.xml file.
Creating Validators
A validator is a class that implements the validate() method of the atg.cim.worker.IValidator. To write
your own validator object, you will need to provide the concrete implementation of the methods defined in the
IValidator class.
public interface IValidator {
/** * Called by the CIM Framework before calling validate(). * * @return true if the object can validate values */ public boolean canValidate();
/** * Logic to test a condition should be placed in this method. Code should * update the message property so the framework may retrieve the last state of * the component. * * @throws ValidatorException */ public boolean validate() throws ValidatorException;
}
It is a good practice to end your class name with Validator (such as ATGLicenseValidator) and include it
under the package atg.cim.validator.
The following is an example of a simple validator class:
package atg.cim.validator;
import atg.cim.util.Util;
import atg.cim.worker.IValidator; import atg.cim.worker.ValidatorException;
/** * This validator class validates if the property "title" * equals "Hello World!" */
public class HelloWorldValidator implements IValidator {
String mMessage;
private String mTitle;
/** * Returns the title string * @return mTitle */ public String getTitle() { return mTitle; }
/** * Sets the title * @param pTitle */ public void setTitle(String pTitle) { mTitle = pTitle; }
/** * assert that the title is not null/blank * * @return true if input parameter is not null/blank<br> * false if input parameter is null/blank */ public boolean canValidate() { if( Util.isNullOrBlank(mTitle) ) { //unable to validate because title is null or blank mMessage = "HelloWorldValidator cannot validate as string is null or blank"; return false; } else { return true; } }
/** * validates that the value of title is "Hello World!" * @return true if value of title is "Hello World!"; false otherwise * @throws ValidatorException */ public boolean validate() throws ValidatorException { if ( mTitle.equals("Hello World!") ) { //title is equal to "Hello World!" mMessage = "HelloWorldValidator has successfully validated the title" + mTitle; return true; } else {
//title does not equals "Hello World!" mMessage = "HelloWorldValidator has successfully validated and your title is not Hello World!. It is " + mTitle; return false; } }
public String getMessage() {return mMessage;} }
Making Validators Available to CIM
To make your validator available to the CIM framework, add an XML snippet to any /plugin_name/
validators.xml file. For example:
<validator id="MyNewValidator" class="atg.cim.validator.HelloWorldValidator"> <title>HelloWorld!</title> </validator>
Now you can refer to the validator MyNewValidator in your wizards.xml file.
Creating Providers
Provider objects are JavaBeans that provide values to the CIM framework by exposing properties. They
implement atg.cim.worker.IProvider, which defines the two methods below. The only difference between
an IProvider object and any other JavaBean is that CIM will always call the provide() method immediately
before accessing any property values.
The IProvider interface is extremely simple:
package atg.cim.worker;
/** * IProvider objects are javabeans that provide values to the CIM Framework by exposing properties. The only real difference between any other nucleus component is that the CIM framework will call the .provide() method before each time a getter is called on a property. **/ public interface IProvider {
/** * Called by the CIM Framework before calling provide(). * * @return true if the object can provide values */ public boolean canProvide();
/** * logic to initialize and set object properties should be placed in this method. CIM Framework calls this method each time a value is accessed from this component * @throws ProviderException */ public void provide() throws ProviderException;
Providers can be used to replace values through a CIM plugin, by including the following syntax:
${ProviderID.property}
CIM calls the provide() method before it replaces the value.
Making Providers Available to CIM
To make your provider available to the CIM framework, add an XML snippet to any /plugin_name/
providers.xml file. For example:
<provider id="MyNewProvider" class="atg.cim.provider.HelloWorldProvider"> </provider>
Now you can refer to the provider MyNewProvider in your wizards.xml file.
Creating Select Providers
The SelectProvider is not a sub-type of Provider, but a distinct type of worker object. Select providers allow
users to select items from a list of options.
They are referenced in the tasks.xml input element; for example:
<input type="select" selectprovider="wizardSelectProvider">
You can constrain users to a single selection or allow multi-select. This example shows a single-select option in
the user interface:
Select one > N
For a multiselect list, a Done option is included automatically:
[1] Reporting *[2] Search [3] Staging Server [D] Done
Select zero or more >
Two properties enable this functionality:
• minOccurs defines the minimum number that must be selected; default is 1
• maxOccurs defines the maximum number that can be selected; default is 1
Infinity is represented by -1.
Single selection is the default, but it can be explicitly instantiated with minOccurs=1 and maxOccurs=1.
The multi-select option allows users to choose multiple selections, separate by spaces. Default selections are
marked with an asterisk. Multiselects can use a range of either zero-to-many, one-to-many, or many-to-many.
Ranges are numerically based (0-1, 1-1, 5-10 are all valid examples). Users mark their selections by entering a
space-separated list. Entering an item that is already selected deselects it. Validation ensures that the selection is
within the minOccurs and maxOccurs range.
The ISelectProvider interface is shown here:
package atg.cim.worker;
import java.util.List;
import atg.cim.model.SelectProviderOption;
/** * ISelectProvider objects are javabeans that provide values to the CIM Framework by exposing properties based on a use input. They also provide a list of choices to the UI */
public interface ISelectProvider { /** * Called by the CIM Framework before calling provideChoices(). * * @return true if the object can provide values */ public boolean canProvide();
/** * create a list of choices to display to the UI. The List will be modified * by the users selection and it will be passed to setUserSelection after user *input. * * * @throws ProviderException */ public List<SelectProviderOption> provideChoices() throws ProviderException;
/** * * This method is called by the framework immediately after a user * makes a selection. * set the bean values to expose depending on the choice from the UI. * The selected options are flaged as Selected in the SelectProviderOption List * that was created from the Provide Method * @param pChoices The list of {@link SelectProviderOption}. Call isSelected on *each * {@link SelectProviderOption} to find what the user has selected. * * @throws ProviderException */ public void setUserSelection(List<SelectProviderOption> pChoices) throws ProviderException;
/** * called by framework to override the minOccurs property * * @param pMinOccurs */ public void setMinOccurs(int pMinOccurs);
/** * called by framework to override the maxOccurs property * * @param pMaxOccurs */ public void setMaxOccurs(int pMaxOccurs);
/** * called by framework to get the minOccurs property * */ public int getMinOccurs();
/** * called by framework to get the maxOccurs property * */ public int getMaxOccurs(); }
The property name of the SelectProvider has to match the property name of a task that you’re using the
SelectProvider for.
Example: Writing a SelectProvider
This example demonstrates how to write a SelectProvider with Yes and No options.
package atg.cim.worker.common;
import atg.cim.model.SelectProviderOption; import atg.cim.worker.ISelectProvider; import atg.cim.worker.SelectProvider;
public class YesNoSelectProvider extends SelectProvider {
private boolean mChoice; /**Get the user selection * @return True if the user selected Yes, False if they selected No */ public boolean isChoice() { return mChoice; } /**Set the users selection * @param pChoice the choice to set */ public void setChoice(boolean pChoice) { mChoice = pChoice; }
/**Always Return true * @return True * @see atg.cim.worker.ISelectProvider#canProvide() */ public boolean canProvide() { return true; }
/**Provides a list with options Yes and No * @return A SelectProviderOtpion list of Yes and No * @see atg.cim.worker.ISelectProvider#provideChoices() */ public List<SelectProviderOption> provideChoices(){ List<SelectProviderOption> choices = new ArrayList<SelectProviderOption>(2); choices.add(0, new SelectProviderOption("yes","Yes")); choices.add(1,new SelectProviderOption("no","No")); return choices; }
/**Set the value from the user's selection * @param pChoices * @see atg.cim.worker.ISelectProvider#setUserSelection(java.util.List) */ public void setUserSelection(List<SelectProviderOption> pChoices){ if(pChoices.get(0).isSelected()) mChoice = true; else mChoice = false; }
}
Making Select Providers Available to CIM
Select providers are declared in selectproviders.xml, using the syntax shown in this example:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE selectproviders SYSTEM "http://www.atg.com/dtds/selectprovider_1_0.dtd">
<selectproviders>
</selectproviders>
Creating Navoption Providers
A NavOptionProvider generates a list of steps at runtime, from which the user can then select. A step can refer
to a NavigationOptionProvider instead of listing each navigation option.
The interface for this class is extremely simple:
public interface INavigationOptionProvider { /** * A Navigation provider should create a List of NavigationOptions. * */ public List<NavigationOption> provide() ;
Example: Navoption Provider with Two Options
This example shows a Navigation list with options Yes and No:
public ListNavigationOption provide() { ListNavigationOption navOptList = new ArrayList<NavigationOption>();
NavigationOption yesNavOpt = new NavigationOption(); yesNavOpt.setId("yesOpt"); yesNavOpt.setHotkey('Y'); yesNavOpt.setDefaultOption(true); yesNavOpt.setDisplayLabel(new Label("Yes")); yesNavOpt.addCommand(new Command(CommandType.GOTO_STEP,"YesStepId")); navOptList.add(yesNavOpt);
NavigationOption noNavOpt = new NavigationOption(); noNavOpt.setId("noOpt"); noNavOpt.setHotkey('N'); noNavOpt.setDefaultOption(true); noNavOpt.setDisplayLabel(new Label("No")); noNavOpt.addCommand(new Command(CommandType.GOTO_STEP,"NoStepId"));
navOptList.add(noNavOpt);
Using Navoption Providers in Steps
Unlike other worker objects, these providers do not have to be registered anywhere in order for CIM to use
them.
To use the navoption provider in a step, use XML as shown:
<navoptionprovider class="atg.cim.worker.base.MainMenuNavigation"> <property name="someProp"> <value>someValue</value> </property> </navoptionprovider>
The provide() method of the MainMenuNavigation object is called when the step is displayed. It returns a list
of Navigation Options based on the progress of the user. This is implemented as a provider and not as a static list
because the options change based on the plugin state and the user’s selections.
5 Using Product Definition Files 35
5 Using Product Definition Files
CIM scripts use product definition files to describe the product combinations they configure and their
dependencies, including possible add-ons and standard configuration options. This product awareness allows
the CIM templates to generate appropriate steps and request information from the user according to the
combination of products they are configuring.
A product.xml file defines the information required to configure a particular Oracle ATG Web Commerce
product. It defines the products themselves, any optional features, and module lists for each product, and may
address multiple versions of a product in the form of server-instance types.
CIM uses the product.xml file to generate a list of top-level modules, which are then used for database
configuration and application assembly.
CIM expects the product.xml file to be under a CIM directory within the application module, as shown:
/some_module /cim product.xml
The product.xml cannot be located any deeper than the second level of the module’s directory structure. The
product definition file defines the options described in the sections that follow:
Product Definitions (page 35)
Server Instances (page 37)
Product Add-Ons (page 42)
Example Product Definition File (page 49)
Product Definitions
The first few elements in the product definition file are used for identification of the product or products
described in the file. The id attribute must uniquely identify the product. The title and detail can be shown
in the user interface. The file must include the DTD declaration shown:
36 5 Using Product Definition Files
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE product SYSTEM "http://www.atg.com/dtds/product_1_0.dtd">
<product id="commerce" > <title>Core Commerce</title> <detail>Configure Core Commerce</detail>
In addition to title and detail, product definition files can include the following elements:
• <requires-addon-id id="ADDON_ID"/>
Identifies an add-on as required; the add-on is automatically selected if the product is selected. See the
Product Add-Ons (page 42) section of this chapter for information.
• <product-id-required id="PRODUCT_ID"/>
Identifies another product as required; the product is automatically selected if the main product is selected.
• <incompatible-product-id id="PRODUCT_ID"/>
Identifies a product as incompatible with this product. If the user selects both, the CIM UI displays an error
message.
Identifies a particular add-on as incompatible with this product. CIM automatically removes this add-on from
the list, so that it cannot be selected.
You can extend an existing product by using the extends attribute. For example:
<product id="commerce" extends="platform">
When you extend one product with another, their product.xml files are merged using XML-combine. If
multiple extensions are involved, the files are combined in extension order.
Note that product.xml files are also merged when end-users select multiple products to configure from the
CIM menu, even if no extension is stated in the XML. The order in which the files are combined varies depending
on the selections. If multiple products are selected that extend other products, the extensions are combined
first, followed by the product selection combinations.
That means that any xml-combine arguments like xml-combine="remove" will only affect the combine with
the “extends” and not with multiple products.
The final XML for combined products is placed in the same directory as the product.xml file that includes
the extension and is called combine-product.xml. For example, if Product A has no extensions, and Product
B extends Product A, after combination, the product.xml directory for Product B also contains a combine-
product.xml.
See the Product DTD (page 65) section of Appendix A, CIM DTDs (page 65) for details on the
product.xml elements and attributes.
Server Instance Types
A server instance type represents a particular type of configuration for the product. It is basically a wrapper
for a list of modules, a group of data sources, and individual server instances (you can have multiple instances
of a server that is of a particular type). This feature does not apply to all Oracle ATG Web Commerce products,
but one common application for it is with ATG Content Administration, which requires configuration of both a
source (often called the publishing server) and a target server.
Each instance-type can have its own list of modules and configuration file information. For example:
<server-instance-type id="management"> <title resource-key="CAServer.name">CA Server</title> <detail resource-key="CAServer.detail"/>
<append-module>BIZUI</add-module> <append-module>PubPortlet</add-module> <append-module>DafEar.Admin</add-module> <add-named-datasource>management</add-named-datasource> <add-server-instance id="ID"> <config-directory> <property-file> … </property-file> </config-directory> <optional-config-directory id="some-option"> <title>Configure these optional properties</title> <detail></detail> <property-file> … </property-file> </optional-config-directory>
</server-instance-type>
You can append modules, add named datasources, and add server instances to an instance type, as shown in the
example above, and configure property files (see the Property Files (page 38) section for more information
on these elements).
Server Instances
A server instance represents a particular implementation of a server instance type. The one thing you can
change at the server instance level but not the server instance type level is runAssembler arguments.
For example, this code fragment provides different assembly options for the basic_management and
management_lock server instances:
</modify-server-instance> <modify-server-instance id="management_lock"> <add-appassembler-option name="layer" value="preview"/> </modify-server-instance> </product-addon>
Property Files
As part of the server-instance-type and server-instance elements, you can specify properties files to
create and configure. If you configure properties files in the server-instance-type element, every server
instance of that type uses the same properties file. If the property file is in the server-instance element, each
instance can have unique configuration.
Property files are specified in the config-directory element of a particular server instance or instance type,
as shown in this example:
<product id="blueprint" extends="commerce"> ... <server-instance id="basic_management" type="management"> ... <config-directory> 
The server-instance-type element supports an additional optional-config-directory element. This
element cannot be used in a server-instance element. It appears as a separate option in the server instance
configuration user interface. For example:
<server-instance-type id="id"> <title>Title</title> <config-directory> <property-file> … </property-file> </config-directory> <optional-config-directory id="some-option"> <title>Configure these optional properties</title> <detail></detail> <property-file> … </property-file> </optional-config-directory> </server-instance-type>
A property file is defined by a file name and a list of properties. The file name is relative to the path
<ATG10dir>/home/servers/server_name/localconfig, and should start with a slash, as shown in the
value element of this example::
<property-file file="atg/dynamo/service/jdbc/JTDataSource.properties"> <property-group id="base">
<property name="dataSource"> <value>/atg/dynamo/service/jdbc/DirectJTDataSource</value> </property> </property-group> </property-file>
You can specify multiple property files. You can also group properties as shown, so that the current product
selection acts to filter subsets of the total property list:
<property-file file="atg/SomeFile.properties"> <property-group id="search-reporting">  <requires-addon-id id="search"/> <requires-addon-id id="reporting"/> <property name="someProperty"> <value>propertyValue</value> </property > </property-group> </property-file>
In order for a property group to be included in a server instance, all of the requires-addon-id identifiers listed
in the property group must be included in the current product selection. If no add-ons are listed, the property
group applies to all product selections. A property-file element can include multiple property-group
elements, but each property-group must have a unique ID.
In addition to requiring addons, you can use the pass-validation tag to specify a validator to test for other
conditions. As with the requires-addon-id tag, all specified validators must pass in order for to execute the
property group. The following example uses pass-validation to add properties if the database is DB2:
<property-file file="GLOBAL.properties"> <property-group id="db2"> <pass-validation id="HasDB2DatasourceValidator" class="atg.cim.worker.databaseconfig.HasDB2DatasourceValidator"/> <property name="handleRangesInMemory"> <value>true</value> </property> <property name="localTransactionModeInitialization"> <value>false</value> </property> </property-group> </property-file>
You can pass properties to the validator as shown in the following example:
<pass-validation id=" DirectoryExistsValidator " class="atg.cim.worker.common.DirectoryExistsValidator"> <property name="absPath"> <value>C:\ATG\</value> </property> </pass-validation>
Values can be replaced dynamically just as they are with properties files (see Using Dynamic Values in Properties
Files (page 41)).
Collecting Property File Values
You can use the property-file element to collect property values from a CIM user at runtime, using the
following additional elements:
• input—Label displayed as a prompt for the user.
• validator—Validate the user’s input. The validator ID references a validator defined in a validators.xml
file in the Base plugin or the product’s \cim directory.
• error-message—If the validator returns false, the error message is displayed and the input is asked for
again.
The following example shows how to collect property values at runtime:
<property-file file="atg/PropertyFile.properties"> <property-group id="base"> <property name="someProp"> <value>${AppServerPortsProvider.httpPort}</value> <input type="text"> <label>Prompt</label> <validator id="PortNumberValidator"> <error-message>Error</error-message> </validator> </input> </value> </property > </property-group> </property-file>
The dynamic value (${…}) replacement is similar to that used elsewhere in CIM (see Using Dynamic Values
in Properties Files (page 41)). The format is ${WORKER_ID.PROPERTY} where WORKER_ID is the ID of a
validator, task, or provider. In the example above, AppServerPortsProvider is a provider ID.
You can use a worker object provided by CIM, or a custom worker object.
Persistence and Property File Values
To persist property values for later use, provide a persist-key attribute for the property, as shown in this
example:
</property-file>
At runtime, if the key references a valid persisted value, that value is used as the default presented to the user.
If the reference does not exist, the value tag is used as the default instead. In both cases, the user input is
persisted to the persist-key specified.
You can also use previously persisted values in a property. In the following example, the second property file
has a lockServerPort property that uses the persisted value from the first property file. Note that the order
is significant; you cannot use a persisted value before it is persisted, so the first time the persisted value is
referenced, the input element must be declared.
<property-file file="/atg/dynamo/service/ServerLockManager.properties"> <property-group id="lock"> <property name="port" persist-key="managementServerLockManagerPort"> <value>9010</value> <input type="text"> <label>Enter Lock Server Port</label> <validator id="PortNumberInputValidator"> <error-message>Invalid Port Number</error-message> </validator> </input> </property> </property-group> </property-file> <property-file file="/atg/dynamo/service/ClientLockManager.properties"> <property-group id="base"> <property name="lockServerAddress"> <value>localhost</value> </property> <property name="lockServerPort" persist- key="managementServerLockManagerPort"/> <property name="useLockServer"> <value>true</value> </property> </property-group> </property-file>
Using Dynamic Values in Properties Files
You can specify dynamic values in a product.xml file, allowing product-specific selections when the product is
being configured. This is similar to the dynamic values used in steps (see Using Dynamic Values in Steps (page
15) in the Creating CIM Plugins (page 7) chapter).
The following options are available for dynamic values in product.xml files:
• Property name—Access a property of a particular server instance or server instance type. The syntax for a
server instance is:
${ServerInstance[SERVER_INSTANCE_ID].PROPERTY_NAME}
SERVER_INSTANCE_ID is the ID of the server instance.
PROPERTY_NAME is a property of that server instance (see the Property Files (page 38) section).
The syntax for a server instance type is similar, but uses the instance type ID instead of the individual instance
ID:
${ServerInstanceType[ServerInstanceTypeID].Property_Name}
• Server instance name—Access the name of the server instance, which is the name of the
individual server directory in the <ATG10dir>/home/servers directory. You might think to use
${ServerInstance[ID].name} to retrieve this, but there can be multiple server instances associated with
an ID. The syntax is:
${ServerInstanceName}
ServerInstanceName is replaced with the name of the server instance that is currently being processed.
This is the only property that changes between instances; use ${ServerInstance[ID].Prop} for all other
properties.
• Application server—Access a property of the selected application server. The syntax is:
${AppServerSelection.PROPERTY_NAME}
PROPERTY_NAME is a property of the AppServerSelection object. For example,
${AppServerSelection.type} returns the currently selected application server type. The available
properties are:
• appServerType—The application server, such as JBoss or WebSphere.
• drpPort—Recommended default port for the selected app server, not the currently configured port.
• httpPort—Recommended default port for the selected app server, not the currently configured port.
• httpsPort—Recommended default port for the selected app server, not the currently configured port.
• rmiPort—Recommended default port for the selected app server, not the currently configured port.
• Datasource name and property—Access a datasource property. The syntax is:
${NamedDatasource[DATASOURCE_ID].PROPERTY_NAME}
PROPERTY_NAME is a property of that datasource.
A PROPERTY_NAME can also specify sub properties. For example,
${NamedDatasource[nonswitchingCore].datasourceValue.jndiName} returns the JNDI Name from the
datasourceValue property of the non-switching datasource.
Product Add-Ons
Add-ons represent additional Oracle ATG Web Commerce products or features that are available separately from
products, but which can be used to add functionality. For example:
<product-addon id="reporting" >
<title resource-key="">Reporting</title> <modify-server-instance id="basic_management"> <add-appassembler-option name="layer" value="Staging"/> <remove-appassembler-option name="layer"/> </modify-server-instance> <prepend-module-list>SearchAdmin.DataWarehouse</prepend-module-list> </product-addon>
Product add-ons can be defined as groups for selection purposes. For instance, the Switching Datasource and
NonSwitching Datasource add-ons are mutually exclusive. They are defined as belonging to a product-addon-
group that allows only one to be selected, using the max-occurs attribute.
<product-addon-group id="datasource_group" min-occurs="1" max-occurs="1"> <title>Choose switching or non-switching datasource :</title> <product-id-required id="product_id"/> <requires-product-addon id="product_addon_id"/>
<product-addon id="switchingdatasource" > <title resource-key="">Switching Datasource</title> <modify-server-instance-type id="management"> <add-named-datasource>switchingA</add-named-datasource> <add-named-datasource>switchingB</add-named-datasource> </modify-server-instance-type> <modify-server-instance-type id="production"> <add-named-datasource>switchingA</add-named-datasource> <add-named-datasource>switchingB</add-named-datasource> </modify-server-instance-type> </product-addon <product-addon id="nonswitchingdatasource" > <title resource-key="">Non-Switching Datasource</title> <modify-server-instance-type id="management"> <add-named-datasource>nonswitching</add-named-datasource> </modify-server-instance-type> <modify-server-instance-type id="production"> <add-named-datasource>nonswitching</add-named-datasource> </modify-server-instance-type> </product-addon> </product-addon-group
You can use the product-id-required and requires-product-addon elements in the product-addon-
group to specify other products or add-ons that must be present if the add-on group is selected. If you specify
one or more product-id-required products, the add-on-group is only displayed if the user selects all of
those products. If you specify one or more add-ons in the requires-product-addon element, the add-on
group is only displayed if the required add-on group has been selected. In such a case, the order of the groups is
important.
Add-On Combinations
In addition to individual products, you can define combinations as add-ons in the product.xml, then define
changes based on the selection of one or more add-ons. This example shows the combination of Search with
reporting, and adds modules to the data warehouse and loader.
<product-addon-combo id="search-reporting"> <combo-product-addon id="search"/> <combo-product-addon id="reporting"/>
<modify-server-instance-type id="datawarehouse_loader"> <append-module name="ARF.DW.Search"/> <append-module name="SearchAdmin.datawarehouse"/> </modify-server-instance-type> <modify-server-instance-type id="datawarehouse"> <append-module name="ARF.DW.Search"/> </modify-server-instance-type> </product-addon-combo>
Modifying Server Instance Types
An add-on might mean that additional modules are required in the EAR, that an additional data source is
needed, or that an entirely different server type can be used; for example, if you add reporting to any Oracle ATG
Web Commerce production combination, a data source is required for the data warehouse, and all potential
server types require additional modules. Use the <modify-server-instance-type> element to specify these
changes:
<modify-server-instance-type id="management"> <prepend-module>ARF.Base</prepend-module <add-named-datasource>datawarehouse</add-named-datasource> </modify-server-instance-type>
<modify-server-instance-type id="production"> <prepend-module>ARF.Base</prepend-module <add-named-datasource>datawarehouse</add-named-datasource> </modify-server-instance-type>
</product-addon
<prepend-module> <append-module> <remove-module> <add-named-datasource> <remove-named-datasource> <add-server-instance>
<prepend-module name="DAS"/>
The append-module element can optionally include a before attribute. For example, the following XML adds
the DSS module before the DAS module, if DAS is found:
<append-module name="DSS" before="DAS"/>
The datasource elements have the following format:
<add-named-datasource id="production"/>
<add-server-instance id="reporting"/>
The server instance added must be defined just like any other instance.
To remove a server instance, use the syntax:
<remove-server-instance id="reporting"/>
Named Datasources
Named datasources represent database connections used by Oracle ATG Web Commerce applications.
The modulelist-server-instance attribute identifies a server-instance-type, which in turn supplies a
list of modules. The dbinit.xml files for each of those modules are then used to generate the SQL and import
scripts that run for the database.
You can declare named datasources in the product.xml file for configuration by end-users.
<named-datasource id="management" modulelist-server-instance- type="management"> <title resource-key="">Publishing</title> <jndi>atgpub_ds</jndi> </named-datasource>
In order for a named datasource to be used, it must be included in a server-instance-type that has at least one
server instance. Each server-instance of that type will have the named datasource’s JNDI registered with the
application server.
Default EAR Name
You can use the product configuration file to provide a default name for the EAR file used for deploying a given
product configuration. The element is a child of server-instance-type. For example:
<server-instance> <ear-file-name>MyATGApp.ear</ear-file-name> </server-instance>
DB Init Scripts
The DB init scripts initialize the database for products being configured, creating schemas and
importing initial data required for some Oracle ATG Web Commerce products. Scripts are declared in the
<ATG10dir>/modul