Oracle ATG One Main Street Cambridge, MA 02142 USA

Version 10.0.
2 CIM Developers Guide
Oracle ATG One Main Street Cambridge, MA 02142 USA
CIM Developers Guide Document Version

CM10.0.2 CIMDEVv1 4/15/2011
Copyright
Copyright 1997, 2011, Oracle and/or its affiliates. All rights reserved. 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 RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are commercial computer software or commercial technical data pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065. 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. 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 licensed through X/Open Company, Ltd. 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. For information about Oracles commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/us/corporate/accessibility/index.html. Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.
CIM Developers Guide
Contents
Introduction
Audience Documentation Conventions
1
1 1
CIM Overview
CIM Installed Files CIM Script Elements Executing CIM Plugins Using the Provided CIM Plugins
3
3 4 5 6
Creating CIM Plugins

Creating CIM Wizards and Processes Adding Steps to a Process Changing Step Order in Combined Wizards Adding Tasks to Steps Adding a Task with No Properties Adding a Task with Properties Collecting User Input for Tasks Omitting Tasks from Batch Files Using Commands in Steps Task Commands Navigation Commands Compound Commands Using Dynamic Values in Steps Adding Validators Handling Errors in Steps Example CIM Plugin
7
7 9 10 11 11 11 12 13 13 13 14 15 15 16 18 18
Creating CIM Worker Objects

Creating Tasks Example: Writing a HelloWorld Task Adding Tasks to the CIM Library Creating Validators Example: Writing a HelloWorld Validator Making Validators Available to CIM Creating Providers
21
21 24 25 25 26 28 28
iii
Contents

Making Providers Available to CIM Creating Select Providers Example: Writing a SelectProvider Making Select Providers Available to CIM Creating Navoption Providers Example: Navoption Provider with Two Options Using Navoption Providers in Steps
29 29 32 33 34 34 34
Using Product Definition Files

Product Definitions Server Instance Types Server Instances Property Files Collecting Property File Values Persistence and Property File Values Using Dynamic Values in Properties Files Product Add-Ons Named Datasources Default EAR Name DB Init Scripts Post-Deployment Options Example Product Definition File
37
37 39 39 40 42 43 44 45 48 48 49 51 52
CIM Script Management

CIM Session Context Dynamic ClassPaths Persistence in CIM System Progress /cim/framework/persistence/Lookup /cim/framework/persistence/RecentValueList /cim/framework/persistence/RecentDatasourceList Logging in CIM Creating Online Help for CIM
57
57 58 58 58 59 59 60 60 60
CIM JavaBean Reference

Task Beans atg.cim.worker.common.CopyDirectoryTask atg.cim.worker.common.CopyFileTask atg.cim.worker.common.DeleteDirectoryTask atg.cim.worker.common.GenericAntExecutionTask atg.cim.worker.common.PropertyFileCreatorTask Validator Beans Input Validators
63
63 63 63 64 64 65 65 65
Appendix A: CIM DTDs

Product DTD
69
69
iv
Contents
74 76 76 77 78 78
DBInit DTD Provider DTD SelectProvider DTD Task DTD Validator DTD Wizard DTD
Index
81
v
Contents
vi
Contents
1 Introduction
This book is intended to introduce ATG 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 Documentation Conventions
Audience
To get the most out of this guide, you should be familiar with: ATG product development practices Nucleus components and their configuration Configuration requirements for your product, including database table creation, assembly, and deployment
See the ATG Programming Guide for information on these topics.
Documentation Conventions
The following conventions are used throughout the documentation:
Convention Italics Bold
Explanation Introduces new terms and indicates emphasis. Emphasizes important information, or indicates field names, menu items, or button names. Indicates syntax examples, values that you specify, or results that you receive. Indicates optional items. For example, in the following statement: SELECT [DISTINCT], DISTINCT is an optional keyword.
monospace
Brackets [ ]
1
1 - Introduction
The directory where you installed ATG is identified as <ATG10dir>. CIM plugins can be created for any version of ATG.
2
1 - Introduction
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 for ATG products. 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 ATG 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 CIM Script Elements Executing CIM Plugins Using the Provided CIM Plugins
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.
3
2 - CIM Overview

configComponent configuration properties files. libCIM .jar files.
CIM is installed automatically as a module in the ATG platform, located at <ATG10dir>/CIM. The CIM module includes the following directories:
dataDatabase 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.
logContains the cim.log file. If debugging is turned on, this directory also includes
XML files that represent templates that have been run.

pluginsPlugin XML files and supporting information for CIM-configurable
products.
tmpA 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 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 ATG system. Scripts have the following elements: StepLogical 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. 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. ProcessA 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.
4
2 - CIM Overview
WizardA set of one or more processes executed in order to configure a product. See Creating CIM Wizards and Processes. TaskCarries out the work specified in the step. A step can include more than one task. See Adding Tasks to Steps. ValidatorCan 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 scripts flow. See Adding Validators.
The Creating CIM Plugins chapter describes how to use each of these elements to guide users through ATG 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
Then enter the command:

cim
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. 2. 3. 4. Start CIM using the record flag. Go through your normal configuration activities. Select Batch File Save from the Main Menu when finished. 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:
cim -batch path/batch_file.cim
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:
5
2 - CIM Overview

cim-ant.xml cim-ant.xml
atg.cim.jboss.CreateJbossAppServerInstanceTask.antFile=C:\dev\work\CIM\cim\ant\ 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\ atg.cim.dynamo.CreateDynamoServerInstanceTask.atgPath=C:/ATG/ATG10.0.1/ 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 ATG 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 SelectionUsers select the combination of products they want to configure. Server Instance CreationCreate ATG servers with the required /config layer information. Application Server SelectionUsers must select the application server to which their application will be deployed, and can perform some optimization tasks. Database ConfigurationUsers provide database configuration information, configure datasources, etc. for the products they have selected. Application AssemblyUsers can assemble and deploy their application to the application server. Custom Wizard LauncherNew 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.
6
2 - CIM Overview
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 chapter. This chapter contains the following sections: Creating CIM Wizards and Processes Adding Steps to a Process Adding Tasks to Steps Using Commands in Steps Using Dynamic Values in Steps Adding Validators Handling Errors in Steps Example CIM Plugin
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. To create a new CIM script, create a wizards.xml file as shown:
7
3 - Creating CIM Plugins

<?xml version="1.0" encoding="UTF-8"?> <wizards> <wizard id="ID">
<!DOCTYPE wizards SYSTEM "http://www.atg.com/dtds/wizard_1_0.dtd">
<title resource-key="" resource-params="">Title</title> <detail resource-key="" resource-params="">Detail</detail> <process id="MyProcess">  </process> </wizard> </wizards>
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 wizards 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 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 MyWizards 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:
8
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 section for step information). For an example, see the Example CIM Plugin section of this chapter, or review the wizards.xml file located at <ATG10dir>/CIM/plugins/base in your ATG 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>
9

Steps have the following attributes:
idUniquely identifies the step to the framework.
insert-afterWhen combining wizards, identifies the step ID in the base file after which this step should be inserted. typeCan 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.
classIf a template step, provide the class used to implement the step. This attribute is optional.
Steps contain the following elements:

titleIdentifies the step in the user interface. detailAdditional 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.
navoptionProvides 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.
navoptionproviderFor dynamic navigation, provide the Java class that supplies
this feature for your script. For an example, see the Example CIM Plugin section of this chapter, or review the wizards.xml file located at <ATG10dir>/CIM/plugins/base in your ATG installation.
Changing Step Order in Combined Wizards

If your wizard extends an existing wizard, youll 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 wizards AddedStep is performed immediately after the OriginalWizardStep from the extended wizard.
10
You can also use the combination to entirely suppress steps in the base wizard. See the XML File Combination section of the ATG 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 files 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 ATG 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 elements 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 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 tasks 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>
11

<task id="CreateJBossAppServerInstanceTask" <property name="jbossPath"> <value>c:\jboss</value> </property> <property name="serverInstanceName"> <value>pub_commerce</value>
class="atg.cim.jboss.CreateJbossAppServerInstanceTask">
Collecting User Input for Tasks

In addition to retrieving values, your scripts 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:
textUser enters plain text. selectUser 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 section for information.

passwordText the user enters is masked by asterisks (*) in the user interface. pathUser enters a path to an item; this option includes tab completion for quicker input.
12
Omitting Tasks from Batch Files

As described in Executing CIM Plugins, 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:
<command type="EXECUTE_STEP_TASKS" /> <command type="GOTO_STEP" value="ThirdStep" />
Task Commands
The following commands can be used in steps to affect tasks:
LAUNCH_WIZARDUsed by the Base plugin to launch wizards. Do not use. LAUNCH_TEMPLATEIf you are extending CIM, use this command to signal the start of your own template. Requires value="class name of template". TEMPLATE_COMPLETESignals 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_COMPLETESignals the end of a wizard. Do not use. EXECUTE_QUEUED_TASKSExecutes all tasks on the queue at one time. DROP_STEP_TASKSAny configured tasks that have not yet been performed are not
executed.
EXECUTE_STEP_TASKSExecutes tasks configured during step, does not execute any
queued tasks.
DELETE_QUEUED_TASKSClears the queue of all tasks. DISPLAY_TEXTDisplays text to the UI. Requires value="text to display".
13

processed as a batch at a later time.
<navoption> <option default="true"> <label>Next Step</label> <command type="EXECUTE_STEP_TASKS" /> <command type="NEXT_STEP" /> </option>
ADD_STEP_TASKS_TO_QUEUEMoves step tasks to the queue, enabling them to be
The following example involves executing currently configured tasks when the user moves to the next step in the wizard:
For additional examples, see the Example CIM Plugin section of this chapter, or review the wizards.xml file located at <ATG10dir>/CIM/plugins/base in your ATG installation.
Navigation Commands
Navigation can be added to steps using commands. The following commands are used for navigation in a step:
NEXT_STEPProcess the next step in the step list. REDO_STEPProcess the current step again, using default values. PREVIOUS_STEPProcess the previous step in the step list. GOTO_STEPProcess the step given in the required targetId attribute. Requires value="step ID to go to". REDO_INPUTCauses CIM to re-render the last label and input request. Can only be
used in the POSTINPUT phase of an input validator.

PROCESS_COMPLETENotifies CIM that a process has been completed. QUITShut 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 >
14
<label>Redo Step</label> <command type="DROP_STEP_TASKS" /> <command type="REDO_STEP" /> <label>Jump to [T]hird Step</label> <command type="DROP_STEP_TASKS" /> <command type="GOTO_STEP" value="ThirdStep" />
</option> <option >
</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_REDOCombines the DROP_STEP_TASKS task command with the REDO_STEP navigation command. EXECUTE_NEXTCombines the EXECUTE_STEP_TASKS task command with the NEXT_STEP navigation command. EXECUTE_GOTOCombines the EXECUTE_STEP_TASKS task command with the GOTO_STEP navigation 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}
For example:
15

${cim.home}
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 section of the Creating CIM Worker Objects chapter), the CIM framework will call the providers provide() method and refresh the component every time it accesses the component. This is useful if youre 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, youll 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:
PRESTEPExecuted before processing a step starts. PREINPUTExecuted after title and description UI rendered to user, but before any
input collection elements are rendered.

PRENAVIGATIONExecuted 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.
POSTSTEPExecuted 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.
16
<step> other xml... <validators> <validator id="DemoFileExistsValidator" phase="PRESTEP" > <if-true> <command type="DISPLAY_TEXT" value="file exists at ${DemoFileExistsValidator.absPathToFile}"/> <command type="GOTO_STEP" value="ThirdStep" /> </if-true> <if-false> <command type="DISPLAY_TEXT" value="file DOES NOT exist at ${DemoFileExistsValidator.absPathToFile}"/> <command type="GOTO_STEP" value="FirstStep" /> </if-false> </validator> </validators> ... 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> <input type="text"> <label>Enter a unique server instance name:</label> <validator id="NoWhiteSpaceValidator" phase="POSTINPUT"> <if-false> <command type="DISPLAY_TEXT" value="No white space allowed" /> <command type="REDO_INPUT" /> </if-false> </validator> </input> etc.
For an example, see the Example CIM Plugin section of this chapter, or review the files located at <ATG10dir>/CIM/plugins/base in your ATG installation.
17

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 CIMs 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. from the Main Menu. ]]> </detail> <navoption id="continue"> <label>Continue</label> <command type="NEXT_STEP" /> </navoption> </step> </error>
Select [p]
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 ATG 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.0.1 Hotfix 2</title> <detail>Installs a test hotfix</detail> <process id="TestProcess"> <step id="FirstStep"> <title>First Step</title>
18
<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="InstallHotfix"> <title>Test Hotfix Installation</title> <detail></detail> <navoption id="install"> <label>[I]nstall hotfix</label> <command type="GOTO_STEP" value="UnjarHotfix"/> </navoption> </step> <step id="UnjarHotfix"> <title>Test Hotfix Installation</title> <detail></detail> <task id="UnjarHotfix"/> <task id="CreateProperties"/> <validator id="AlwaysTrueValidator" phase="PRENAVIGATION"> <if-true> <command type="EXECUTE_STEP_TASKS" </if-true> </validator> </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"/> /> <command type="GOTO_STEP" value="FirstStep"/>
19

<if-true> uninstalled" /> </if-true> </validator> </step> </process> </wizard> </wizards>
<validator id="AlwaysTrueValidator" phase="PRENAVIGATION"> <command type="EXECUTE_STEP_TASKS" />
<command type="DISPLAY_TEXT" value="Hotfix has been <command type="GOTO_STEP" value="FirstStep"/>
20
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 ATG 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 Creating Validators Creating Providers Creating Select Providers Creating Navoption Providers
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; /**
21
4 - Creating CIM Worker Objects

*/ public interface ITask extends Serializable { /** *
* ITask objects are serializable javabeans that perform an action.
* 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. *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; Code should update *the message property so the framework may retrieve the last state of the
/** * Retrieve the text describing the state of the component for UI display. * * @return String containing the status of the component. */ public String getMessage(); }
22
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 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. *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. *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. *incremental value, * not the cumulative amount of work performed so far. * */ public void worked(int pWork); This is an Value may be Should only be
/** * Called once by worker object when work has been completed
23

* */ public void setTaskComplete(boolean pComplete); }
Example: Writing a HelloWorld Task

Write the following Task object class. Note: Although undo() methods are included in the worker object API, they are reserved for future use and are not supported for ATG 10.
package atg.cim.task; import atg.cim.worker.ITask; import atg.cim.worker.IProgressMonitor; import atg.cim.worker.TaskException;
/* 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; } /**
24
* * 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.
25

public interface IValidator { /** * * @return true if the object can validate values */ public boolean canValidate(); /**
* Called by the CIM Framework before calling validate().
* Logic to test a condition should be placed in this method. * the component. * * @throws ValidatorException */ public boolean validate() throws ValidatorException; /** * Returns a brief message describing the state of the object. * */ public String getMessage(); }
Code should
* update the message property so the framework may retrieve the last state of
It is a good practice to end your class name with Validator (such as ATGLicenseValidator) and include it under the package atg.cim.validator.
Example: Writing a HelloWorld 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;
26
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> * */ 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; } } false if input parameter is null/blank
/** * 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!"
27

not Hello World!. It is " + mTitle; return false; } } public String getMessage() {return mMessage;} }
mMessage = "HelloWorldValidator has successfully validated and your title is
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:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE validators SYSTEM "http://www.atg.com/dtds/validator_1_0.dtd"> <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 { /**
28
* 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:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE providers SYSTEM "http://www.atg.com/dtds/provider_1_0.dtd"> <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:
29

[N] Non Switching Datasource *[S] Switching Datasource 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 manyto-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. 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(); They also provide a list of choices
30
/** * 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(); /**
31

* 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 youre 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 java.util.ArrayList; import java.util.List; import atg.cim.model.SelectProviderOption; import atg.cim.worker.ISelectProvider; import atg.cim.worker.SelectProvider; /**{@link ISelectProvider} that provides a Yes and No option */ 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; }
32
/**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> <selectprovider id="mySelectProvider" class="atg.cim.worker.mode.mySelectProvider"> <property name="myStore"> <value>nucleus:/cim/framework/myStore</value> </property> </selectprovider> </selectproviders>
33

Creating Navoption Providers
The interface for this class is extremely simple:
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.
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); return navOptList; }
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:
34
<property name="someProp"> <value>someValue</value> </property>
<navoptionprovider class="atg.cim.worker.base.MainMenuNavigation">
</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 users selections.
35
36
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 ATG 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 modules directory structure. The product definition file defines the options described in the sections that follow: Product Definitions Server Instance Types Server Instances Product Add-Ons Default EAR Name DB Init Scripts Example Product Definition File
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:
37
5 - Using Product Definition Files

<?xml version="1.0" encoding="UTF-8"?> <product id="commerce" > <title>Core Commerce</title> <detail>Configure Core Commerce</detail>
<!DOCTYPE product SYSTEM "http://www.atg.com/dtds/product_1_0.dtd">
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 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.
<incompatible-addon-id id="ADDON_ID" />
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 section of Appendix A: CIM DTDs for details on the product.xml elements and attributes.
38
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 ATG 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 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:
39

<product-addon id="previewOnManagement" > <modify-server-instance id="basic_management"> </modify-server-instance> <modify-server-instance id="management_lock">
<title resource-key="">Configure Preview to run on the CA Server</title> <add-appassembler-option name="layer" value="preview"/>
<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>
40
</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>
41

</property> <value>false</value> </property> </property-group> </property-file>
<property name="localTransactionModeInitialization">
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).
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:
valueDefault value to assign to the property. inputLabel displayed as a prompt for the user. validatorValidate the users input. The validator ID references a validator defined
in a validators.xml file in the Base plugin or the products \cim directory.

error-messageIf 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 >
42
</property-group> </property-file>
The dynamic value (${}) replacement is similar to that used elsewhere in CIM (see Using Dynamic Values in Properties Files). 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 file="atg/PropFile.properties"> <property-group id="base"> <property name="someProp" persist-key="someKey"> <value>Default value</value> <input type="text"> <label>Prompt to the user</label> </input> </value> </property > </property-group> </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>
43

</property-group> </property-file> <property-group id="base"> <property name="lockServerAddress"> <value>localhost</value> </property> <property name="lockServerPort" persistkey="managementServerLockManagerPort"/> <property name="useLockServer"> <value>true</value> </property> </property-group> </property-file>
<property-file file="/atg/dynamo/service/ClientLockManager.properties">
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 in the Creating CIM Plugins chapter). The following options are available for dynamic values in product.xml files: Property nameAccess 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 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 nameAccess 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 serverAccess a property of the selected application server. The syntax is:
44
${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: appServerTypeThe application server, such as JBoss or WebSphere. drpPortRecommended default port for the selected app server, not the currently configured port. httpPortRecommended default port for the selected app server, not the currently configured port. httpsPortRecommended default port for the selected app server, not the currently configured port. rmiPortRecommended default port for the selected app server, not the currently configured port. Datasource name and propertyAccess a datasource property. The syntax is:
${NamedDatasource[DATASOURCE_ID].PROPERTY_NAME}
DATASOURCE_ID is the ID of a named datasource. 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 ATG products or features that are available separately from products, but which can be used to add functionality such as reporting (provided by ATG Customer Intelligence). 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.
45

<product-id-required id="product_id"/> <requires-product-addon id="product_addon_id"/> <product-addon id="switchingdatasource" >
<product-addon-group id="datasource_group" min-occurs="1" max-occurs="1"> <title>Choose switching or non-switching datasource :</title>
<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 productaddon-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 ACI, 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">
46
<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 ATG 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:
<product-addon id="reporting <title resource-key="">Reporting</title <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
The <modify-server-instance-type> element has the following sub-elements:

<prepend-module> <append-module> <remove-module> <add-named-datasource> <remove-named-datasource> <add-server-instance>
The module-related elements use the following syntax:

<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"/>
47

To add another server instance, use the syntax:
<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 ATG 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-instancetype="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 datasources 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>
48
DB Init Scripts
The DB init scripts initialize the database for products being configured, creating schemas and importing initial data required for some ATG products. Scripts are declared in the <ATG10dir>/module_name/cim/dbinit.xml file. The dbinit.xml file has three top-level elements: schema, data-import, and server-instance-type. The schema element identifies the database schema to be modified, and contains the tasks that do the work of running the scripts. These schema IDs are then specified for a particular server-instance-type and datasource. The IDs for server-instance-type and datasource come from the selected product.xml file. There is a special ID all that can be used for both server-instance-type and datasources. The order for processing is: 1. 2. 3. 4. Server instance = all, Datasource = all Server instance = all, Datasource = product selection datasource ID Server instance = product selection server instance ID, Datasource = all Server instance = product selection server instance ID, Datasource = product selection datasource ID
Which dbinit.xml files are used is based on the module list for the server-instance-type of the datasource. CIM looks at the full list. For every dbinit.xml found, it proceeds through the four steps to create a list of what to run. For example, if you create a custom module that requires DAS, CIM automatically runs the DAS table creation scripts (as long as they match the specified criteria). The server-instance-type element identifies which server-instance-type (as defined in product.xml) is associated with this schema, since many of them have different database needs; for example, a reporting server needs certain utility tables that are not otherwise required by the platform. Within the schema element you can specify SQL scripts and database import scripts to run. To specify a SQL script, use the structure shown in this example:
<create>sql/db_components/${database}/versioned_ddl.sql</create>
The path is relative to the module the dbinit.xml file is in. For example, if the file is in DAS/CIM, the path is relative to the DAS module, and using the example above would end up as DAS/sql/database. The database value is passed in based on the users previous selections. The data-import element contains database initialization scripts, and includes the following elements:
repository-pathThe repository into which the data is imported. import-file-pathPath to the XML file that contains the data to import. userContent Administration user for versioned imports. workspaceContent Administration workspace, for versioned imports. commentComment is required for versioned imports.
49

add-ons, or the data import does not run. For example:
<data-import start-up-module="MyModule"> <requires-addon-id id="MyAddOn" />
requires-addon-idDuring product selection, the user must select the specified
required-datasourcesIdentifies data sources that must be created for this import script. The syntax for required-datasources is: <data-import start-up-module="DAS" requireddatasources="nonswitchingCore,switchingCore">
When a required datasource is identified, CIM creates a properties file for that datasource, using the values configured in CIM and the property file name specified in the
<ATG10dir>/CIM/config/cim/DatasourcePropertyFileMapper.properties
file. The default configuration is:

$class=atg.cim.database.dbsetup.DatasourcePropertyFileMapper datasourcePropertyMap=\ nonswitchingCore=JTDataSource_production.properties,\ switchingCore=JTDataSource_production.properties,\ svcagent=JTDataSource_agent.properties
Add more mappings as needed. In this example, a properties file is created for the nonswitchingCore datasource, with the name JTDataSource_production.properties that point to the connection details for nonswitchingCore. A detailed example follows. Note that data-import element paths are relative to the ATG installation location, while repository-loader paths are relative to the specified source module (src-module). The repository-loader elements post-cleanup attribute is used to clean up data that is used during the installation, but which should not be included in a database used by a running ATG server.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE database-initializer SYSTEM "http://www.atg.com/dtds/dbinit_1_0.dtd"> <database-initializer> <schema id="versionedSchema"> <sql> <path> <create> sql/db_components/${database}/versioned_ddl.sql </create> <drop> sql/uninstall/${database}/drop_versioned_ddl.sql </drop> </path> </sql>
50
<data-import> <repository-path>/atg/epub/file/PublishingFileRepository </repository-path> <import-file-path>/Publishing/base/install/epub-file-repository -data.xml</import-file-path> <user>publishing</user> <workspace>workspace</workspace> <comment>initial_data_import</comment> </data-import> <repository-loader post-cleanup="true"> <files> <src-module>DSS</src-module> <config-path>atg/registry/data/scenarios/DSS</config-path> <file-pattern>*.sdl</file-pattern> </files> <files> <src-module>DSS</src-module> <config-path>atg/registry/data/scenarios/recorders</config-path> <file-pattern>*.sdl</file-pattern> </files> <file-mapping>/atg/epub/file/typemappers/ScenarioTypeMapping </file-mapping> <folder-mapping>/atg/epub/file/typemappers/FileFolderTypeMapping </folder-mapping> </repository-loader> </schema> <server-instance-type id="management"> <datasource id="management"> <schema id="versionedSchema"/> </datasource> </server-instance-type> <server-instance-type id="production"> <datasource id="all"> <schema id="nonVersionedSchema"/> </datasource> </server-instance-type> </database-initializer>
Post-Deployment Options
Post-deployment options allow you to specify actions for CIM to take after deploying the assembled EAR file. CIM displays these options to the user in the Post Deployment Menu.
51

The post-deployment-option element has two child elements: available. For example:
requires-app-serverRestricts the application servers for which the option is
requires-add-onThe user must include all specified add-ons during product selection in order to view and use the option.
<post-deployment-option id="${ServerInstanceName}-${AppServerSelection.appServerType}_store front_static"> <title>Copy Storefront Static HTML/Image Files</title> <requires-app-server>JBoss</requires-app-server> <requires-addon-id id="storefront_demo"/> <requires-addon-id id="previewOnManagement"/> <step id="CopyStoreFrontStaticPostDeploymentOptionStep" type="template" class="atg.cim.storeconfig.deploy.CopyStaticStorefrontTemplate"> <property name="serverInstanceName"> <value>${ServerInstanceName}</value> </property> </step> </post-deployment-option>
Example Product Definition File

This section provides a sample product definition file that shows the elements described in this chapter working together. The sample product.xml defines elements that would be used when configuring the ATG Motorprise reference application.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE product SYSTEM "http://www.atg.com/dtds/product_1_0.dtd"> <product id="motorprise" extends="commerce"> <title resource-key="MotorpriseCommerceProduct.name">Motorprise</title> <detail resource-key="MotorpriseCommerceProduct.detail">Configure Motorprise</detail>
 <named-datasource id="management" modulelist-server-instancetype="management"> <title resource-key="">Versioned CA</title> <jndi>atgpub_ds</jndi>
52
</named-datasource> <named-datasource id="switchingA" modulelist-server-instancetype="production"> <title resource-key="">SwitchingA</title> <jndi>atgcataloga_ds</jndi> </named-datasource> <named-datasource id="switchingB" modulelist-server-instancetype="production"> <title resource-key="">SwitchingB</title> <jndi>atgcatalogb_ds</jndi> </named-datasource> <named-datasource id="nonswitchingCore" modulelist-server-instancetype="production" > <title resource-key="">Core for non-switching</title> <jndi>atgcore_ds</jndi> </named-datasource>  <product-addon-group id="baseaddon_group"> <product-addon id="search"> <title resource-key="">Search</title> <modify-server-instance-type id="management"> <append-module name="commerce.motorprise.search"/> <append-module name="commerce.motorprise.search.Index"/> <append-module name="DCS-UI.Search"/> <append-module name="DCS.Search.CustomCatalogs.Versioned"/> </modify-server-instance-type> <modify-server-instance-type id="production"> <append-module name="commerce.motorprise.search"/> </modify-server-instance-type> </product-addon> <product-addon id="customcatalog" xml-combine="remove" /> <product-addon id="merch" xml-combine="remove" /> </product-addon-group> <product-addon-combo id="motorprise-switchingdatasource"> <combo-product-addon id="switchingdatasource"/>
53

<add-named-datasource id="switchingA"/> <add-named-datasource id="switchingB"/> <add-named-datasource id="management"/> </modify-server-instance-type>
<modify-server-instance-type id="management">
<modify-server-instance-type id="production"> <add-named-datasource id="switchingA"/> <add-named-datasource id="switchingB"/> </modify-server-instance-type> </product-addon-combo> <product-addon-combo id="motorprise-nonswitchingdatasource"> <combo-product-addon id="nonswitchingdatasource"/> <modify-server-instance-type id="management"> <add-named-datasource id="nonswitchingCore"/> <add-named-datasource id="management"/> </modify-server-instance-type> <modify-server-instance-type id="production"> <add-named-datasource id="nonswitchingCore"/> </modify-server-instance-type> </product-addon-combo>  <server-instance-type id="management"> <title resource-key="MotorpriseCommerceCAServer.name">Motorprise Commerce CA Server</title> <detail resource-key="MotorpriseCommerceCAServer.detail"/> <append-module name="DPS-UI"/> <append-module name="DCS-UI"/> <append-module name="VersionedMotorprise"/> </server-instance-type> <server-instance-type id="production" > <title resource-key="MotorpriseCommerceProductionServer.name">Motorprise
54
Commerce Production Server</title> <append-module name="MotorpriseJSP"/> </server-instance-type>
 <server-instance id="basic_management" type="management" > <title>Motorprise Merch CA ServerInstance</title> <ear-file-name>motorprise-pub.ear</ear-file-name> <server-instance-name>motorprise-pub</server-instance-name> </server-instance> <server-instance id="basic_production" type="production" > <title>Motorprise Commerce Production</title> <ear-file-name>motorprise.ear</ear-file-name> <server-instance-name>motorprise</server-instance-name> </server-instance> </product>
55
56
6 CIM Script Management
This section contains topics related to CIM scripting, but not directly concerned with script creation. For information on ATG programming in general, see the ATG Programming Guide. This chapter contains the following sections: CIM Session Context Dynamic ClassPaths Persistence in CIM Logging in CIM
CIM Session Context

Commands may add name-value pairs to the CIM session context. These values are available for lookup by any following commands, validators, providers, or during rendering using ${keyName} notation. Use SessionContext.addToEnvironment(myKey, myObject) to add a pair to the session context. You can then retrieve the value using the following Java code:
Object obj = SessionContext.lookup(myKey)
You can also retrieve the value in a CIM XML file by using the following:
${myKey}
The following values are already available for you to use:

dynamo.root Path to ATG Installation cim.home Path to the CIM Installation cim.plugin.home Path to the currently chosen Plugin file.separator system dependent file separator character
To avoid overwriting keys already in use, be cautious when naming keys.
57
6 - CIM Script Management

Dynamic ClassPaths
atg.cim.SessionContext.addClassPath(String); atg.cim.SessionContext.addClassPath(File);
For CIM scripts, new classpaths can be added at runtime using one of the following static methods:
This is used These methods can be called repeatedly as duplicates are filtered out.
Persistence in CIM
Worker objects that need to persist values between sessions can use CIM persistence objects. CIM uses a Hypersonic database, which is persisted to the CIM/data/ directory. All JDBC dependencies and logic are encapsulated in a few Nucleus components, so there is no need for any interaction with the JDBC layer.
System Progress
CIM provides information to the user on what actions have already been executed. Each menu item displays the combined progress of all actions involved in that menu item. The StatusMonitorStore keeps track of the amount of work needed to be performed to complete some task. This is done by keeping track of work for unique ids. The ids are usually the id for the menu item that starts some action. Each id has total work amount, work done, work left, a done flag, a status message and a list of children ids. The children ids are used to build a hierarchy for related tasks. The children ids are used to calculate the work done and if things are done.
StatusUpdateValidator is used to update when some amount of work was performed.
This example shows a menu with status information:

[C] [T] *[S] [I] Enter Connection Details Done Test Connection Done Create Schema Import Initial Data
A custom persister saves and retrieves progress information from CIM persistence. In order to keep progress information specific to a product selection, all status information is cleared when product selection changes. To set status within a step:
<validator phase="POSTSTEP" id="StatusUpdateValidator"> <property name="statusId"> <value>DATABASE_CONFIGURATION_WIZARDID</value> </property> <property name="statusMsg"> <value>Database Configuration Complete</value>
58
</property>
</validator>
To get a status:
StatusMonitorStore statusMonStore = StatusMonitorStore.getInstance(); //This has no effect if the StatusMonitor aready exists statusMonStore.newStatusMonitor(DATABASE_CONFIGURATION_WIZARDID); boolean dbConfDone = statusMonStore.isDone(DATABASE_CONFIGURATION_WIZARDID);
Similar code would normally be used in a navoption provider, allowing you to modify navigation options based on the tasks the user has already completed.
/cim/framework/persistence/Lookup
The /cim/framework/persistence/Lookup object provides a simple implementation of a persistent lookup table of values. It uses the class atg.cim.persistence.Lookup. Only Strings can be persisted. The following example persists a key-value pair:
mLookup = SessionContext.getLookupPersistence() mLookup.put("mykey", "value1");
Then this snippet retrieves the value:

mLookup = SessionContext.getLookupPersistence() mLookup.get("mykey");
This removes the key-value pair:

mLookup = SessionContext.getLookupPersistence() mLookup.remove("mykey");
/cim/framework/persistence/RecentValueList
This object provides an implementation of a persistent MRU (Most Recently Used) list of values. It uses class atg.cim.persistence.RecentValueList. Only Strings can be persisted. The following example persists the value C:/ATG/ATG10.0.1 as the most recent value to a list named atgpath:
mRecentlyUsedValue = SessionContext.getRecentValueList() mRecentlyUsedValue.addToList("atgpath", "C:/ATG/ATG10.0.1");
The list of the 5 (or less) latest values in the atgpath list can be retrieved with this code snippet:
mRecentlyUsedValue = SessionContext.getRecentValueList() List paths = mRecentlyUsedValue.getList("atgpath", 5);
59

The list atgpath can be cleared with this code snippet:
mRecentlyUsedValue.clearList("atgpath");
mRecentlyUsedValue = SessionContext.getRecentValueList()
/cim/framework/persistence/RecentDatasourceList
This object provides an implementation of a persistent MRU (Most Recently Used) list of datasource value objects. It uses class atg.cim.persistence.RecentDatasourceList. The following example persists a datasource value object:
atg.cim.worker.datasource.DatasourceValue dsVal = new DatasourceValue(); dsVal.setAlias("mydatasource"); dsVal.setDatabaseName("dbName"); dsVal.setDatabaseType(Constants.CIM_DB_TYPE_SOLID); dsVal.setDriverPathsAsString("/path/to/SolidDriver2.1.jar"); dsVal.setHostname("localHost"); dsVal.setJndiName("jndiName"); dsVal.setPassword("password"); dsVal.setPort("1234"); dsVal.setUsername("username"); dsVal.setUrl("/url/to/db"); SessionContext.getRecentDatasourceList().addAliasToList(dsVal.getAlias(), dsVal);
This code retrieves the newest five datasource value objects in a List:
mRecentDatasourceList = new RecentDatasourceList(); // or use nucleus resolve ListDatasourceValue list = mRecentDatasourceList.getList("datasourceAlist",5);
Logging in CIM
CIMs atg.cim.logging class uses standard ATG logging as described in the ATG Programming Guide. By default, log files are written to the \CIM\log directory. The logger is acquired with SessionContext.getLogger(). All log functions have a caller argument, which should be set to the object calling the logger. See the Javadoc for details.
Creating Online Help for CIM

The default CIM scripts ship with online help information. If you add your own custom scripts, you may want to provide assistance for users.
60
CIM help is provided in the form of a JS file, which contains a list of IDs that match CIM objects, and corresponding help text to be displayed when the user works with that object. The format is:
{"id":"CIMItemID","content":"Place your help text here"},
For example:
{"id":"AddOnSelectTask.addOns","content":"Select one or more of the listed add-ons as part of your installation."},
You can place a product-specific online help file in the same directory as the product.xml file. Before the user has selected a product and add-ons, all of the help files present are combined, using no set order. After the user selects a product, the help is based on that product, using the extends attribute in the product.xml files to determine the hierarchy. For example, CRS extends B2C, which extends DCS, which extends the platform. If the user selects CRS, the help file combines available help for those products. The most child product, in this case CRS, takes precedence; if any two of the files include the same help ID, the CRS help is used. For sibling products that do not extend each other, common ancestors are used first, then the sibling products in no defined order. Help IDs are automatically generated using standard formats for each item type. You can turn on debugging in the CIM GLOBAL.properties file to see help IDs displayed whenever you access the help. For property file steps, the ID convention is to replace the dot in the filename with an underscore:
/Nucleus_path/filename_properties.propertyname
For example:
/atg/dynamo/Configuration_properties.httpPort
For a navigation step, the help ID format is:

stepIDfor the entire step stepID.navIDfor each navigation option provided
For task, such as selecting from a list, the help ID format is:
taskID.propertyname.listItemID
For example:
DatasourcePropTask.databaseType.oracle
Some items you may want to add that would benefit from added online help are: new product (ProductSelectTask.products.newproductID) new add-on (AddOnSelectTask.addons.newaddonID)
61
new named datasource (SelectNamedDatasourceStep.newdatasourceID) new server instance (ServerInstanceSelectionStep.newserverinstanceID)
62
7 CIM JavaBean Reference
This chapter provides a description of each of the Java beans included in the atg.cim.common package, including their properties. To use these beans in your CIM scripts, you need to provide <property> and <value> tags, as shown in the Adding a Task with Properties section. This chapter contains the following sections: Task Beans Validator Beans
Task Beans
This section describes the available task beans for use in CIM scripts.
atg.cim.worker.common.CopyDirectoryTask
This task copies a directory and its contents to a target destination, overwriting any contents if present. Properties:
srcDirDirectory to be copied. For example: C:/MyDir/DirToBeCopied
targetDirDestination directory for the copy. For example: C:/MyDir/Dir1/DestinationDir
antFilePath to the ant file that contains the script for the directory copying task. For example: C:/MyDir/demo-ant.xml
This property defaults to <ATG10dir/CIM/plugins/base, and is not required.
atg.cim.worker.common.CopyFileTask
This task copies the specified file to a target destination. Properties:
63
7 - CIM JavaBean Reference
C:/MyDir/FileToBeCopied.txt
srcFilePathPath to the file the task will copy. For example:
targetFilePathLocation to which the task will copy the file. For example: C:/MyDir/Dir1/DestinationDir
antFilePath to the ant file that contains the script for the file copying task. For example: C:/CIM_HOME/cim/ant/cim-ant.xml
atg.cim.worker.common.DeleteDirectoryTask
This task deletes a directory and its contents. Properties:
dirPath to the directory that is to be deleted. For example: C:/MyDir/DirToBeDeleted
antFilePath to the ant file that contains the script for the directory deletion task.
For example:
C:/CIM_HOME/cim/ant/cim-ant.xml
atg.cim.worker.common.GenericAntExecutionTask
This task executes the specified ant target. Properties:
antFilePath to the ant file that contains the script. For example: C:/CIM_HOME/cim/ant/cim-ant.xml

antTargetTarget name to be executed in the ant file. For example: dir.delete
antPropertiesProperties that are passed to the ant file in order to execute the
script. In the example that follows, the ant script can now use a variable ${zip.path}:
antProperties=zip.path=C:/path/to/zip/dir/
64
atg.cim.worker.common.PropertyFileCreatorTask
This task generates a properties file for a Nucleus component Properties:
scopeScope of the Nucleus component. className Java class on which the Nucleus component is based. propsProperties of the Nucleus component. For example: props=min=10,max=10,blocking=true,maxFree=-1,loggingSQLError=false
propertiesFileAbsolute path to the properties file to be written.
Validator Beans
This section describes the available validation beans for use in CIM scripts.
Input Validators
Input validators check user-entered input.
atg.cim.worker.common.AbsolutePathValidator
This bean returns true if the path to a given file is valid. For example:
C:/My_Dir/myFile
The validator determines whether the path to myFile is valid. Note that the validator does not check for the existence of myFile itself. Properties:
filePathThe path entered by the user. For example: C:/ProgramFiles/MyDirectory/MyFile
atg.cim.worker.common.DirectoryExistsValidator
Returns true if the path entered is a valid path to an existing directory. Properties:
absPathPath entered by the user. For example: C:/ProgramFiles/MyDirectory
65

Properties:
textToValidateInput text to be validated. For example: HelloWorld
atg.cim.worker.common.AllowOnlyAlphanumericInputValidator
This validator returns true if the input contains only alphanumeric characters.
atg.cim.worker.common.CannotBeBlankValidator
This validator returns true if the input is not empty. It can be used to ensure that the user did not leave an input field blank. Properties:
textToValidateInput to be validated.
atg.cim.worker.common.PortNumberInputValidator
This validator returns true if the input String is between 1 and 65535. Properties:
textToValidatePort number to be validated. For example: 8080
atg.cim.worker.common.NoWhiteSpaceInputValidator
This validator returns true if the input contains no white-space characters. Properties:
textToValidateInput to be checked for white space. For example: hello world
atg.cim.worker.common.FileExistsValidator
This validator returns true if the input is a path is to a valid file or directory. Properties:
absPathToFileThe path entered by the user. For example: C:/ProgramFiles/MyFile.txt
atg.cim.worker.common.AlwaysFalseValidator
This validator always returns false. Since Validators can be used to control flow in the CIM UI, you can use this validator to command it to do something without actually performing any test.
66
For example, after the user selects a wizard to run, CIM would normally display navigation options. Instead of this default behavior, you can force CIM to load the chosen wizard and then navigate to the next step with this XML snippet:
<validator id="AlwaysTrueValidator" phase="PRENAVIGATION"> <onpass> <command type="EXECUTE_STEP_TASKS" /> <command type="LOAD_PROCESS" /> </onpass> </validator>
atg.cim.worker.common.AlwaysTrueValidator
This validator always returns true. See atg.cim.AlwaysFalseValidator for usage suggestions.
67
68
This section provides the full DTD for each of the XML files described in this guide. Product DTD DBInit DTD Provider DTD SelectProvider DTD Task DTD Validator DTD Wizard DTD
Product DTD
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT product (title?,detail?,requires-addon-id*,product-id-required*, incompatible-product-id*,incompatible-addon-id*,named-datasource*, product-addon-group*,product-addon-combo*,server-instance-type*, server-instance*) <!ATTLIST product id CDATA #REQUIRED extends CDATA #IMPLIED priority CDATA #IMPLIED > <!ELEMENT title (#PCDATA)> <!ATTLIST title resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED > <!ELEMENT detail (#PCDATA)> <!ATTLIST detail resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED >
69

> <!ELEMENT requires-addon-id EMPTY> <!ATTLIST requires-addon-id id CDATA #REQUIRED > <!ELEMENT incompatible-product-id EMPTY> <!ATTLIST incompatible-product-id id CDATA #REQUIRED > <!ELEMENT incompatible-addon-id EMPTY> <!ATTLIST incompatible-addon-id id CDATA #REQUIRED > <!ELEMENT named-datasource (title,detail?,jndi?)> <!ATTLIST named-datasource id CDATA #REQUIRED modulelist-server-instance-type CDATA #REQUIRED extends CDATA #IMPLIED > <!ELEMENT jndi (#PCDATA)>
<!ELEMENT product-addon-group (title,detail?,product-id-required*, requires-product-addon*,incompatible-addon-id*,product-addon+)> <!ATTLIST product-addon-group id CDATA #REQUIRED min-occurs CDATA #IMPLIED max-occurs CDATA #IMPLIED > <!ELEMENT product-id-required EMPTY> <!ATTLIST product-id-required id CDATA #REQUIRED > <!ELEMENT requires-product-addon EMPTY> <!ATTLIST requires-product-addon id CDATA #REQUIRED > <!ELEMENT product-addon (title,detail?,(modify-server-instance-type| modify-server-instance)*)> <!ATTLIST product-addon id CDATA #REQUIRED > <!ELEMENT product-addon-combo (combo-product-addon+, modify-server-instance-type*,modify-server-instance*)>
70
<!ATTLIST product-addon-combo id CDATA #REQUIRED > <!ELEMENT combo-product-addon EMPTY> <!ATTLIST combo-product-addon id CDATA #REQUIRED > <!ELEMENT modify-server-instance-type ((prepend-module|append-module| remove-module|add-named-datasource|add-server-instance| remove-named-datasource|remove-server-instance)*)> <!ATTLIST modify-server-instance-type id CDATA #REQUIRED > <!ELEMENT modify-server-instance ((add-appassembler-option| remove-appassembler-option)*)> <!ATTLIST modify-server-instance id CDATA #REQUIRED > <!ELEMENT prepend-module EMPTY> <!ATTLIST prepend-module name CDATA #REQUIRED > <!ELEMENT append-module EMPTY> <!ATTLIST append-module name CDATA #REQUIRED before CDATA #IMPLIED > <!ELEMENT remove-module EMPTY> <!ATTLIST remove-module name CDATA #REQUIRED > <!ELEMENT add-named-datasource EMPTY> <!ATTLIST add-named-datasource id CDATA #REQUIRED > <!ELEMENT remove-named-datasource EMPTY> <!ATTLIST remove-named-datasource id CDATA #REQUIRED > <!ELEMENT add-server-instance EMPTY> <!ATTLIST add-server-instance id CDATA #REQUIRED > <!ELEMENT remove-server-instance EMPTY>
71

<!ATTLIST remove-server-instance id CDATA #REQUIRED > <!ELEMENT add-appassembler-option EMPTY> <!ATTLIST add-appassembler-option name CDATA #REQUIRED value CDATA #IMPLIED > <!ELEMENT remove-appassembler-option EMPTY> <!ATTLIST remove-appassembler-option name CDATA #REQUIRED >
<!ELEMENT server-instance-type (title,detail?,append-module*, add-named-datasource*,add-server-instance*,config-directory?, optional-config-directory*)> <!ATTLIST server-instance-type id CDATA #REQUIRED extends CDATA #IMPLIED > <!ELEMENT optional-config-directory (title,detail?,(property-file|step)*)> <!ATTLIST optional-config-directory id CDATA #REQUIRED > <!ELEMENT server-instance (title,detail?,ear-file-name,server-instance-name, config-directory,post-deployment?,post-deployment-option*)> <!ATTLIST server-instance id CDATA #REQUIRED type CDATA #REQUIRED min-occurs CDATA #IMPLIED max-occurs CDATA #IMPLIED > <!ELEMENT ear-file-name (#PCDATA)> <!ELEMENT server-instance-name (#PCDATA)> <!ELEMENT config-directory (property-file|step)*> <!ELEMENT property-file (comment?,property-group*)> <!ATTLIST property-file file CDATA #REQUIRED > <!ELEMENT property-group ((requires-addon-id|pass-validation)*,property*)> <!ATTLIST property-group id CDATA #REQUIRED >
72
<!ELEMENT pass-validation (property)*> <!ATTLIST pass-validation id CDATA #REQUIRED class CDATA #REQUIRED > <!ELEMENT post-deployment (step*)> <!ELEMENT post-deployment-option (title,detail?,(requires-addon-id|requires-appserver)*,step*)> <!ATTLIST post-deployment-option id CDATA #REQUIRED > <!ELEMENT requires-app-server (#PCDATA)> <!ELEMENT step (title?,detail?,property*,navoptionprovider?,(task|validator| navoption)*,error?)> <!ATTLIST step id CDATA #REQUIRED type (template) #IMPLIED class CDATA #IMPLIED > <!ELEMENT comment (#PCDATA)> <!ELEMENT property (value?, input?)> <!ATTLIST property name CDATA #REQUIRED persist-key CDATA #IMPLIED > <!ELEMENT if-true (command*)> <!ELEMENT if-false (command*)>
<!ELEMENT validator (property*,error-message?,if-true?,if-false?)> <!ATTLIST validator id CDATA #REQUIRED phase (PRESTEP|PREINPUT|POSTINPUT|PRENAVIGATION|POSTSTEP) #IMPLIED > <!ELEMENT error-message (#PCDATA)> <!ELEMENT value (#PCDATA)>
<!ELEMENT label (#PCDATA)> <!ATTLIST label resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED
73

> <!ELEMENT command (label?)> <!ATTLIST command
type (EXECUTE_STEP_TASKS|DROP_STEP_TASKS|ADD_STEP_TASKS_TO_QUEUE| EXECUTE_QUEUED_TASKS|DELETE_QUEUED_TASKS|UNDO_STEP_TASKS|ADD_TASK| REMOVE_TASK|GOTO_STEP|NEXT_STEP|PREVIOUS_STEP|QUIT|REDO_STEP|LOAD_PROCESS| PROCESS_COMPLETE|LAUNCH_WIZARD|LAUNCH_TEMPLATE|TEMPLATE_COMPLETE| WIZARD_COMPLETE|DROP_REDO|EXECUTE_NEXT|EXECUTE_GOTO|DISPLAY_TEXT| REDO_INPUT) #REQUIRED value CDATA #IMPLIED > <!ELEMENT input (label, validator*)> <!ATTLIST input type (text | password | path | class) #REQUIRED > <!ELEMENT navoption (label,command+)> <!ATTLIST navoption id CDATA #REQUIRED default (true|false) #IMPLIED > <!ELEMENT navoptionprovider (property*)> <!ATTLIST navoptionprovider class CDATA #REQUIRED > <!ELEMENT error (step)> <!ELEMENT task (property*)> <!ATTLIST task id CDATA #REQUIRED >
DBInit DTD
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT database-initializer (schema*,server-instance-type*)> <!ELEMENT schema (sql*,data-import*,repository-loader*)> <!ATTLIST schema id CDATA #REQUIRED >
74
<!ELEMENT sql (path+)> <!ELEMENT path (requires-addon-id*,create,drop)> <!ELEMENT create (#PCDATA)> <!ELEMENT drop (#PCDATA)> <!ELEMENT data-import (requires-addon-id*,incompatible-addon-id*,repositorypath,import-file-path,user?,workspace?,comment?)> <!ATTLIST data-import start-up-module CDATA #IMPLIED required-datasources CDATA #IMPLIED > <!ELEMENT incompatible-addon-id EMPTY> <!ATTLIST incompatible-addon-id id CDATA #REQUIRED > <!ELEMENT repository-path (#PCDATA)> <!ELEMENT import-file-path (#PCDATA)> <!ELEMENT user (#PCDATA)> <!ELEMENT workspace (#PCDATA)> <!ELEMENT comment (#PCDATA)> <!ELEMENT server-instance-type (datasource+)> <!ATTLIST server-instance-type id CDATA #REQUIRED > <!ELEMENT datasource (schema+)> <!ATTLIST datasource id CDATA #REQUIRED > <!ELEMENT repository-loader (requires-addon-id*,cleanup-src-module?,cleanup-filepath?,files+,file-mapping,folder-mapping)> <!ATTLIST repository-loader post-cleanup (true|false) "false" start-up-module CDATA > <!ELEMENT files (src-module,(config-path|file-path),file-pattern)> <!ELEMENT src-module (#PCDATA)> <!ELEMENT config-path (#PCDATA)> <!ELEMENT file-path (#PCDATA)> <!ELEMENT file-pattern (#PCDATA)> <!ELEMENT file-mapping (#PCDATA)> <!ELEMENT folder-mapping (#PCDATA)> <!ELEMENT cleanup-src-module (#PCDATA)> <!ELEMENT cleanup-file-path (#PCDATA)> "Publishing.base"
75

<!ELEMENT requires-addon-id EMPTY> <!ATTLIST requires-addon-id id CDATA #REQUIRED >
Provider DTD
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT providers (provider*)> <!ELEMENT provider (property*)> <!ATTLIST provider id CDATA #REQUIRED class CDATA #REQUIRED inherit-values-from CDATA #IMPLIED > <!ELEMENT property (value)> <!ATTLIST property name CDATA #REQUIRED > <!ELEMENT value (#PCDATA)>
SelectProvider DTD
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT selectproviders (selectprovider*)> <!ELEMENT selectprovider (property*)> <!ATTLIST selectprovider id CDATA #REQUIRED class CDATA #REQUIRED inherit-values-from CDATA #IMPLIED maxOccurs CDATA #IMPLIED minOccurs CDATA #IMPLIED > <!ELEMENT property (value)> <!ATTLIST property
76
name CDATA #REQUIRED > <!ELEMENT value (#PCDATA)>
Task DTD
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT label (#PCDATA)> <!ATTLIST label resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED > <!ELEMENT command (label?)> <!ATTLIST command type (EXECUTE_STEP_TASKS|DROP_STEP_TASKS|ADD_STEP_TASKS_TO_QUEUE| EXECUTE_QUEUED_TASKS|DELETE_QUEUED_TASKS|UNDO_STEP_TASKS|ADD_TASK| REMOVE_TASK|GOTO_STEP|NEXT_STEP|PREVIOUS_STEP|QUIT|REDO_STEP|LOAD_PROCESS| PROCESS_COMPLETE|LAUNCH_WIZARD|LAUNCH_TEMPLATE|TEMPLATE_COMPLETE| WIZARD_COMPLETE|DROP_REDO|EXECUTE_NEXT|EXECUTE_GOTO|DISPLAY_TEXT| REDO_INPUT) #REQUIRED value CDATA #IMPLIED > <!ELEMENT input (label, validator*)> <!ATTLIST input type (text | select | password | path | class) #REQUIRED selectprovider CDATA #IMPLIED > <!ELEMENT task (property*)> <!ATTLIST task id CDATA #REQUIRED class CDATA #REQUIRED longRunning (true|false) #IMPLIED inherit-values-from CDATA #IMPLIED batch (true|false) #IMPLIED > <!ELEMENT tasks (task+)> <!ELEMENT validator (if-true?,if-false?)> <!ATTLIST validator id CDATA #REQUIRED
77

> <!ELEMENT if-true (command*)> <!ELEMENT if-false (command*)> <!ELEMENT property (value?, input?)> <!ATTLIST property name CDATA #REQUIRED > <!ELEMENT value (#PCDATA)>
phase (PRESTEP|PREINPUT|POSTINPUT|PRENAVIGATION|POSTSTEP) #REQUIRED
Validator DTD
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT property (value)> <!ATTLIST property name CDATA #REQUIRED > <!ELEMENT validator (property)*> <!ATTLIST validator id CDATA #REQUIRED class CDATA #REQUIRED batch (true|false) > <!ELEMENT validators (validator+)> <!ELEMENT value (#PCDATA)> "true"
Wizard DTD
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT title (#PCDATA)> <!ATTLIST title resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED >
78
<!ELEMENT detail (#PCDATA)> <!ATTLIST detail resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED > <!ELEMENT label (#PCDATA)> <!ATTLIST label resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED > <!ELEMENT wizards (wizard+)> <!ELEMENT wizard (title?,detail?,process+)> <!ATTLIST wizard id CDATA #REQUIRED extends CDATA #IMPLIED wizard-type (base|fragment) #IMPLIED > <!ELEMENT process (step+)> <!ATTLIST process id CDATA #REQUIRED insert-after CDATA #IMPLIED > <!ELEMENT step (title?,detail?,property?,navoptionprovider?,(task|validator|navoption)*,error?)> <!ATTLIST step id CDATA #REQUIRED insert-after CDATA #IMPLIED type (standard|template) #IMPLIED class CDATA #IMPLIED > <!ELEMENT error (step)> <!ELEMENT property (value?)> <!ATTLIST property name CDATA #REQUIRED > <!ELEMENT value (#PCDATA)> <!ELEMENT task EMPTY> <!ATTLIST task id CDATA #REQUIRED > <!ELEMENT validator (property*,if-true?,if-false?)> <!ATTLIST validator
79

id CDATA #REQUIRED > <!ELEMENT if-true (command+)> <!ELEMENT if-false (command+)> <!ELEMENT command (label?)> <!ATTLIST command type
phase (PRESTEP|PREINPUT|POSTINPUT|PRENAVIGATION|POSTSTEP) #REQUIRED
(GOTO_STEP|NEXT_STEP|PREVIOUS_STEP|QUIT|REDO_STEP|LAUNCH_WIZARD|LAUNCH_TEMPLATE|TE MPLATE_COMPLETE|WIZARD_COMPLETE|DROP_REDO|EXECUTE_NEXT|EXECUTE_GOTO|DROP_STEP_TASK S|EXECUTE_STEP_TASKS|DISPLAY_TEXT) #REQUIRED value CDATA #IMPLIED > <!ELEMENT navoption (label,command+)> <!ATTLIST navoption id CDATA #REQUIRED default (true|false) #IMPLIED > <!ELEMENT navoptionprovider (property*)> <!ATTLIST navoptionprovider class CDATA #REQUIRED >
80
Index
A
AbsolutePathValidator class, 65 AllowOnlyAlphanumericInputValidator class, 66 AlwaysFalseValidator class, 66 AlwaysTrueValidator class, 67 audience, 1
B
batch files, editing, 5 batch mode, 5
C
CannotBeBlankValidator class, 66 cim directory, 4 CIM module, 4 cim.log, 4 classpath, dynamic, 58 commands compound, 15 navigation-related, 14 commands, task-related, 13 component overview, 4 config directory, 4 conventions, 1 CopyDirectoryTask class, 63 CopyFileTask class, 63
D
data directory, 4 database initializing, 49 databases CIM internal, 58
81
Index

datasources, 48 DB init scripts, 49 DeleteDirectoryTask class, 64 DirectoryExistsValidator class, 65 dynamic classpaths, 58 dynamic values, 15
NoWhiteSpaceInputValidator class, 66
P
persistence, 58 plugins example, 18 executing, 5 location, 4 provided, 6 recording, 5 plugins, creating, 7 PortNumberInputValidator class, 66 processes creating, 7 overview, 4 product add-ons, 45 combinations, 46 modifying server instance types, 47 product definition files, 37 example, 52 product.xml file, 37 products, 37 progressMonitor method, 23 PropertyFileCreatorTask class, 65 providers making available, 29 providers, creating, 28
E
EAR name, default, 48 error handling, 18 example plugin, 18 executable, 4 execution modes, 5
F
FileExistsValidator class, 66 files, installed, 3
G
GenericAntExecutionTask class, 64
H
Hypersonic, 58
I
INavigationOptionProvider interface, 34 installed files, 3 IProgressMonitor interface, 23 IProvider interface, 28 ISelectProvider interface, 29 ITask interface, 21 IValidator interface, 25
R
RecentDatasourceList object, 60 RecentValueList object, 59 record flag, 5
S
select providers creating, 29 example, 32 making available, 33 SelectProvider, 12 server instance types, 39 in DB init scripts, 49 modifying, 47 server instances, 39 session context, 15, 57 StatusMonitorStore, 58 StatusUpdateValidator, 58 steps adding, 9 changing order, 10 dynamic values in, 15 handling errors in, 18 overview, 4 using commands in, 13 validation phases of, 16
L
lib directory, 4 log directory, 4 logging, 60 Lookup object, 59
M
multiselect lists, 29
N
named datasources, 48 navigation commands, 14 navoption providers creating, 34 example, 34 using in steps, 34
82
Index
U
user input, collecting, 12
system progress, 58
T
tasks adding, 11 collecting input for, 12 creating, 21 example, 24 making available, 25 navigation in, 14 omitting from batch files, 13 overview, 5 using commands in, 13 with no properties, 11 with properties, 11
V
validators adding, 16 creating, 25 example, 26 making available, 28 overview, 5 phase attribute, 16
W
wizards creating, 7 extending, 8 overview, 5 worker objects, creating, 21
83
Index

Oracle ATG One Main Street Cambridge, MA 02142 USA

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Oracle ATG One Main Street Cambridge, MA 02142 USA

Hochgeladen von

Copyright:

Verfügbare Formate

Version 10.0.

2 CIM Developers Guide

Oracle ATG One Main Street Cambridge, MA 02142 USA

CIM Developers Guide Document Version

CIM Developers Guide

Creating CIM Plugins

Creating CIM Worker Objects

CIM Developers Guide

Using Product Definition Files

CIM Script Management

CIM JavaBean Reference

Appendix A: CIM DTDs

CIM Developers Guide

CIM Developers Guide

CIM Developers Guide

See the ATG Programming Guide for information on these topics.

Convention Italics Bold

CIM Developers Guide

CIM Developers Guide

CIM Installed Files

CIM Developers Guide

XML files that represent templates that have been run.

CIM Script Elements

CIM Developers Guide

Executing CIM Plugins

Then enter the command:

CIM Developers Guide

Using the Provided CIM Plugins

CIM Developers Guide

3 Creating CIM Plugins

Creating CIM Wizards and Processes

CIM Developers Guide

<!DOCTYPE wizards SYSTEM "http://www.atg.com/dtds/wizard_1_0.dtd">

CIM Developers Guide

Adding Steps to a Process

CIM Developers Guide

Steps contain the following elements:

Changing Step Order in Combined Wizards

CIM Developers Guide

Adding Tasks to Steps

Adding a Task with No Properties

<step> <task id="CreateDemoFileTask"/> <task id="DoSomethingTask"/> </step>

Adding a Task with Properties

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE tasks SYSTEM "http://www.atg.com/dtds/task_1_0.dtd"> <tasks>

CIM Developers Guide

Collecting User Input for Tasks

See the Creating Select Providers section for information.

CIM Developers Guide

Omitting Tasks from Batch Files

The default batch value is true.

Using Commands in Steps

CIM Developers Guide

ADD_STEP_TASKS_TO_QUEUEMoves step tasks to the queue, enabling them to be

used in the POSTINPUT phase of an input validator.

CIM Developers Guide

</option> <option >

Using Dynamic Values in Steps

CIM Developers Guide

To refer to a bean value, use the following syntax:

input collection elements are rendered.

CIM Developers Guide

To use a validator in a task, use the following XML: