atgcimdevguide

Version 10.0.2

CIM Developer’s Guide

Oracle ATG One Main Street Cambridge, MA 02142 USA

CIM Developer’s 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 Oracle’s 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.

C I M D e v e l o p e r ’ s G u i d e

i i i

C o n t e n t s

μ

Contents

1 Introduction 1 Audience 1 Documentation Conventions 1

2 CIM Overview 3 CIM Installed Files 3 CIM Script Elements 4 Executing CIM Plugins 5 Using the Provided CIM Plugins 6

3 Creating CIM Plugins 7 Creating CIM Wizards and Processes 7 Adding Steps to a Process 9

Changing Step Order in Combined Wizards 10 Adding Tasks to Steps 11

Adding a Task with No Properties 11 Adding a Task with Properties 11 Collecting User Input for Tasks 12 Omitting Tasks from Batch Files 13

Using Commands in Steps 13 Task Commands 13 Navigation Commands 14 Compound Commands 15

Using Dynamic Values in Steps 15 Adding Validators 16 Handling Errors in Steps 18 Example CIM Plugin 18

4 Creating CIM Worker Objects 21 Creating Tasks 21

Example: Writing a HelloWorld Task 24 Adding Tasks to the CIM Library 25

Creating Validators 25 Example: Writing a HelloWorld Validator 26 Making Validators Available to CIM 28

Creating Providers 28


i v

C o n t e n t s

μMaking Providers Available to CIM 29

Creating Select Providers 29 Example: Writing a SelectProvider 32 Making Select Providers Available to CIM 33

Creating Navoption Providers 34 Example: Navoption Provider with Two Options 34 Using Navoption Providers in Steps 34

5 Using Product Definition Files 37 Product Definitions 37 Server Instance Types 39 Server Instances 39 Property Files 40

Collecting Property File Values 42 Persistence and Property File Values 43

Using Dynamic Values in Properties Files 44 Product Add-Ons 45 Named Datasources 48 Default EAR Name 48 DB Init Scripts 49 Post-Deployment Options 51 Example Product Definition File 52

6 CIM Script Management 57 CIM Session Context 57 Dynamic ClassPaths 58 Persistence in CIM 58

System Progress 58 /cim/framework/persistence/Lookup 59 /cim/framework/persistence/RecentValueList 59 /cim/framework/persistence/RecentDatasourceList 60

Logging in CIM 60 Creating Online Help for CIM 60

7 CIM JavaBean Reference 63 Task Beans 63

atg.cim.worker.common.CopyDirectoryTask 63 atg.cim.worker.common.CopyFileTask 63 atg.cim.worker.common.DeleteDirectoryTask 64 atg.cim.worker.common.GenericAntExecutionTask 64 atg.cim.worker.common.PropertyFileCreatorTask 65

Validator Beans 65 Input Validators 65

Appendix A: CIM DTDs 69 Product DTD 69


v

C o n t e n t s

μDBInit DTD 74 Provider DTD 76 SelectProvider DTD 76 Task DTD 77 Validator DTD 78 Wizard DTD 78

Index 81


v i

C o n t e n t s

μ


1

1 - I n t r o d u c t i o n

μ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 Explanation

Italics Introduces new terms and indicates emphasis.

Bold Emphasizes important information, or indicates field names, menu items, or button names.

monospace Indicates syntax examples, values that you specify, or results that you receive.

Brackets [ ] Indicates optional items. For example, in the following statement: SELECT [DISTINCT], DISTINCT is an optional keyword.


2

1 - I n t r o d u c t i o n

μ

The directory where you installed ATG is identified as <ATG10dir>. CIM plugins can be created for any version of ATG.


3

2 - C I M O v e r v i e w

μ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.


4


μCIM is installed automatically as a module in the ATG platform, located at <ATG10dir>/CIM. The CIM module includes the following directories:

config—Component configuration properties files.

data—Database used internally by CIM scripts to store user selections. To start from scratch if you have previously used CIM, you can delete the contents of this directory.

lib—CIM .jar files.

log—Contains the cim.log file. If debugging is turned on, this directory also includes XML files that represent templates that have been run.

plugins—Plugin XML files and supporting information for CIM-configurable products.

tmp—A working directory created by some CIM processes.

The CIM executable is located at <ATG10dir>/home/cim.bat|sh.

In addition to the CIM module itself, all CIM-enabled applications should include a /cim directory, which contains the product.xml and dbinit.xml CIM files for that application. For information on these files, see the Using Product Definition Files 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:

Step—Logical groupings of information presented to the user as a unit. For example, a step may prompt the user for input values, provide the user with feedback about collected input, or provide information about the state of the system. See Adding Steps to a Process.

At the completion of a step, CIM has prepared one or more tasks with the values necessary for execution. These tasks are not yet executed. However, each time CIM collects a value from the user it has an opportunity to execute logic. For example, before moving on to the next step, you may want to ensure that the user has not included disallowed characters in their input.

After a step has collected all of the information required to execute its related tasks, CIM prepares these tasks and places them in a buffer for later execution.

Process—A logical grouping of steps. There are no enforced restrictions, but you should contain all task dependencies within the process. Each step in a process should be able to execute on its own, without previous processes running. For example, if a step in a process requires a JDBC connection, that connection should be configured within the process, and should not rely on a step in another process. See Creating CIM Wizards and Processes.


5


μ Wizard—A set of one or more processes executed in order to configure a product. See

Creating CIM Wizards and Processes.

Task—Carries out the work specified in the step. A step can include more than one task. See Adding Tasks to Steps.

Validator—Can check system state to ensure that information is processed correctly, or can validate user input for a variety of possible error conditions, allowing you to alter the script’s flow. See Adding Validators.

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. Start CIM using the –record flag.

2. Go through your normal configuration activities.

3. Select Batch File Save from the Main Menu when finished.

4. 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:


6


μatg.cim.jboss.CreateJbossAppServerInstanceTask.antFile=C:\dev\work\CIM\cim\ant\

cim-ant.xml

atg.cim.jboss.CreateJbossAppServerInstanceTask.jbossPath=C:/jboss/

atg.cim.jboss.CreateJbossAppServerInstanceTask.serverInstanceName=pub_commerce

atg.cim.jboss.CreateJbossAppServerInstanceTask.execute()

atg.cim.dynamo.CreateDynamoServerInstanceTask.antFile=C:\dev\work\CIM\cim\ant\

cim-ant.xml

atg.cim.dynamo.CreateDynamoServerInstanceTask.atgPath=C:/ATG/ATG10.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 Selection—Users select the combination of products they want to configure.

Server Instance Creation—Create ATG servers with the required /config layer information.

Application Server Selection—Users must select the application server to which their application will be deployed, and can perform some optimization tasks.

Database Configuration—Users provide database configuration information, configure datasources, etc. for the products they have selected.

Application Assembly—Users can assemble and deploy their application to the application server.

Custom Wizard Launcher—New CIM wizards you create are added under this menu.

Documentation for these plugins is provided as part of the command-line interface; type H at any prompt to access the help. You may want to familiarize yourself with these plugins before creating your own.


7

3 - C r e a t i n g C I M P l u g i n s

μ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.


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:

8


μ<?xml version="1.0" encoding="UTF-8"?>

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

<wizards>

<wizard id="ID">

<title resource-key="" resource-params="">Title</title>

<detail resource-key="" resource-params="">Detail</detail>

<process id="MyProcess">



</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 wizard’s function.

Note: The wizard-type attribute for the <wizard> element is used only by product configuration wizards, and should not be used in custom scripts. If this attribute is used, the script will not appear in the custom wizard launcher.

If you want your wizard to extend another wizard, use the following:

<wizard id="MyWizard" extends="OtherWizard">

When you extend a wizard, the following items are merged using XML-combine:

MyWizard XML with OtherWizard XML

Supporting files, including tasks.xml, validators.xml, providers.xml, and selectproviders.xml, are combined if the two wizards are located in different plugins; if they are in the same plugin, they both use the same supporting files

MyWizard inherits everything included in the OtherWizard plugin. Note that it does not inherit items from other wizards that are defined in the same plugin as OtherWizard, but only inherits from OtherWizard itself. In addition, MyWizard can access Java classes used in the plugin that contains OtherWizard. See the XML File Combination section of the ATG Programming Guide for general information on XML-combine.

When you run the MyWizard plugin, a combined-MyWizard.xml file containing the combined wizards is saved to the directory where MyWizard’s wizards.xml file is located. This file is deleted if the wizard exits successfully, unless you have turned on debugging. To turn on debugging, edit the <ATG10dir>/CIM/config/GLOBAL.properties file.

The title and detail are shown in CIM menus. For example:


9


μ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>


1 0


μSteps have the following attributes:

id—Uniquely identifies the step to the framework.

insert-after—When combining wizards, identifies the step ID in the base file after which this step should be inserted.

type—Can be standard or template. This attribute is optional, and the default is standard. A standard step acts as part of a simple, linear process with a tightly restricted set of user options, and relies on default worker objects for its behavior. A template step permits dynamic generation of options and greater flexibility, but requires you to write your own components; this is provided for use with future versions of CIM.

class—If a template step, provide the class used to implement the step. This attribute is optional.

Steps contain the following elements:

title—Identifies the step in the user interface.

detail—Additional text that provides any information the user needs to know in order to complete the step.

property— Argument to pass to a template step; not used in standard steps. This allows a single template to be reused, displaying different information depending on the property. For an example, see the Database Configuration menu in CIM, in which a single template displays different options depending on the database selected.

navoption—Provides a framework of options from which the user can select. As part of navigation, commands are fired, some of which are purely navigational, and others of which have to do with tasks that are prepared during the step. Navigation options include Next Step, Redo Step, Jump to Third Step, etc. The default selection is indicated by the attribute default="true", and is executed if no value is entered and the user presses the Enter key.

navoptionprovider—For dynamic navigation, provide the Java class that supplies this feature for your script.

For an example, see the Example CIM Plugin 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, you’ll need to think about the order in which the steps of the combined wizard should be performed. Default behavior is to append your wizard to the wizard you are extending. You can change this by using the insert-after attribute in your step as shown:

<step id="AddedStep" insert-after="OriginalWizardStep" >

</step>

When the script is run, your wizard’s AddedStep is performed immediately after the OriginalWizardStep from the extended wizard.


1 1


μ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 file’s task element must match the id of a task defined in tasks.xml. For an example of a tasks.xml file, see the <ATG10dir>/CIM/plugins/base directory in your 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 element’s property element refers to a component property to which the input should be assigned. Within the input element, you can include a label, which is displayed in the user interface, and one or more validators to check the entered text (see the Adding Validators section of this chapter).

Task examples are shown in the sections that follow.

Adding a Task with No Properties

To add a simple task to a step in a wizard, add the snippet below as a child of a <step> element. Multiple tasks can be included in a single step, in which case they are processed in order.

<step>

…

<task id="CreateDemoFileTask"/>

<task id="DoSomethingTask"/>

…

</step>

Adding a Task with Properties

In the tasks.xml file, the tasks themselves are specified in detail, including which JavaBean does the task’s work, what information is collected, and any validation that should be performed. The property elements point to properties of the bean.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE tasks SYSTEM "http://www.atg.com/dtds/task_1_0.dtd">

<tasks>


1 2


μ <task id="CreateJBossAppServerInstanceTask"

class="atg.cim.jboss.CreateJbossAppServerInstanceTask">

<property name="jbossPath">

<value>c:\jboss</value>

</property>

<property name="serverInstanceName">

<value>pub_commerce</value>

Collecting User Input for Tasks

In addition to retrieving values, your script’s end user may need to set values in order for a task to be completed. CIM has a text-based interface, and users can input information as shown by the bold line in the following example, which allows the user to enter a value for the serverInstanceName property:

<task id="CreateJBossAppServerInstanceTask"

class="atg.cim.jboss.CreateJbossAppServerInstanceTask">



<input type="text">

<label>Enter a unique server instance name:</label>

</input>

etc.

Note that if you use a SelectProvider to set a property, such as the serverInstanceName in the sample above, that SelectProvider must have that property, and it must be of the same type.

CIM supports the following types of input:

text—User enters plain text.

select—User selects from a provided list of options using numeric hotkeys. This option requires that you write a customer Java class that implements iSelectProvider. Identify this class in the selectprovider attribute for the input tag as shown:

<input type="select" selectprovider="provider_class">

See the Creating Select Providers section for information.

password—Text the user enters is masked by asterisks (*) in the user interface.

path—User enters a path to an item; this option includes tab completion for quicker input.


1 3


μ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="GOTO_STEP" value="ThirdStep" />

Task Commands

The following commands can be used in steps to affect tasks:

LAUNCH_WIZARD—Used by the Base plugin to launch wizards. Do not use.

LAUNCH_TEMPLATE—If you are extending CIM, use this command to signal the start of your own template. Requires value="class name of template".

TEMPLATE_COMPLETE—Signals the end of a template, returning program control to the wizard. If you provide a value attribute, it is used as the value of a GO_TO step by the parent plugin.

WIZARD_COMPLETE—Signals the end of a wizard. Do not use.

EXECUTE_QUEUED_TASKS—Executes all tasks on the queue at one time.

DROP_STEP_TASKS—Any configured tasks that have not yet been performed are not executed.

EXECUTE_STEP_TASKS—Executes tasks configured during step, does not execute any queued tasks.

DELETE_QUEUED_TASKS—Clears the queue of all tasks.

DISPLAY_TEXT—Displays text to the UI. Requires value="text to display".


1 4


μ ADD_STEP_TASKS_TO_QUEUE—Moves step tasks to the queue, enabling them to be

processed as a batch at a later time.

The following example involves executing currently configured tasks when the user moves to the next step in the wizard:

<navoption>





</option>

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_STEP—Process the next step in the step list.

REDO_STEP—Process the current step again, using default values.

PREVIOUS_STEP—Process the previous step in the step list.

GOTO_STEP—Process the step given in the required targetId attribute. Requires value="step ID to go to".

REDO_INPUT—Causes CIM to re-render the last label and input request. Can only be used in the POSTINPUT phase of an input validator.

PROCESS_COMPLETE—Notifies CIM that a process has been completed.

QUIT—Shut down CIM with no saving of data.

The following example shows how you can use navigation commands along with task commands in your steps:

<step id="FirstStep">

<title>First Step</title>

<detail>Details of the first step: Demonstrates simple navigation

</detail>

<navoption>





</option>

<option >


1 5


μ <label>Redo Step</label>


<command type="REDO_STEP" />

</option>

<option >

<label>Jump to [T]hird Step</label>



</option>

<option >

<label>Jump to [F]ourth Step</label>


<command type="GOTO_STEP" value="FourthStep" />

</option>

</navoption>

</step>

Note that when adding navigation options, you should surround the hot-key letter with brackets:

Load [W]izard.

If no brackets are present, CIM automatically designates the first letter as the hot key. CIM will throw a runtime error if a single step includes multiple equivalent hotkeys.

Compound Commands

In addition to the task commands and navigation options outlined in the previous sections, CIM also includes the following commands, which combine a task and navigation option:

DROP_REDO—Combines the DROP_STEP_TASKS task command with the REDO_STEP navigation command.

EXECUTE_NEXT—Combines the EXECUTE_STEP_TASKS task command with the NEXT_STEP navigation command.

EXECUTE_GOTO—Combines 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:


1 6


μ${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 provider’s provide() method and refresh the component every time it accesses the component. This is useful if you’re accessing information that changes during the course of running the script.

Adding Validators CIM uses validator objects to check user input for formatting or other errors. Validators return either true or false, and allow you to conditionally display messages or perform navigation commands.

Validators can be used at two levels in a script:

In a step, a validator can perform a check on some system state.

Note that using validators may mean that not all phases of the step execute. For example, if the outcome of a PRESTEP validator commands CIM to navigate to another step, later phases will never execute.

When a task collects input, a validator can check the input immediately.

For each validator, you’ll need to specify:

The step phase in which validation takes place.

Commands to execute if the validator returns true (optional).

Commands to execute if the validator returns false (optional).

Step validators can be described in terms of the point at which they perform their check; this information is required in the phase attribute of the validator tag. The phases are:

PRESTEP—Executed before processing a step starts.

PREINPUT—Executed after title and description UI rendered to user, but before any input collection elements are rendered.

PRENAVIGATION—Executed after UI input collection is complete and tasks are configured, but before navigation options are displayed to the user. at this point no tasks have been executed.

POSTSTEP—Executed after navigation chosen by user, does not execute if the user selects a navigation step that executes a command to move to another step.

To use a validator in a step, add the snippet below as a child of a <step> element. Multiple validators can be added to a single step. They are processed in order depending on their phase attribute.


1 7


μ<step>

other xml...

<validators>

<validator id="DemoFileExistsValidator" phase="PRESTEP" >

<if-true>

<command type="DISPLAY_TEXT" value="file exists at

${DemoFileExistsValidator.absPathToFile}"/>


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



<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.


1 8


μHandling Errors in Steps

In addition to whatever error handling you may build into your Java classes, CIM includes an XML-level form of basic error handling. If one of your steps encounters an error during execution, you can use the <error> element to specify an alternative step.

In this example. the error element checks to see if there have been changes to CIM’s persisted data made outside of CIM; if so, the UI prompts the user to re-select a product for configuration.

<error>

<step id="ProductionSelectionPersistenceCheckErrorStep">

<title>Product Selection Model Update</title>

<detail>

<![CDATA[

The CIM Product object model has been updated.

REQUIRED ACTION: Re-Execute the Product Selection wizard. Select [p]

from the Main Menu.

]]>

</detail>

<navoption id="continue">

<label>Continue</label>


</navoption>

</step>

</error>

Example CIM Plugin The following code shows an example of a wizards.xml file that defines a custom CIM plugin. The plugin helps a user install an ATG hotfix, and shows the elements previously described in this chapter working together.


<!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>


1 9


μ <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>


<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="GOTO_STEP" value="FirstStep"/>

</if-true>

</validator>

</step>

<step id="UninstallHotfix">

<title>Test Hotfix Uninstallation</title>

<detail></detail>


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


2 0


μ <validator id="AlwaysTrueValidator" phase="PRENAVIGATION">

<if-true>


<command type="DISPLAY_TEXT" value="Hotfix has been

uninstalled" />

<command type="GOTO_STEP" value="FirstStep"/>

</if-true>

</validator>

</step>

</process>

</wizard>

</wizards>


2 1

4 - C r e a t i n g C I M W o r k e r O b j e c t s

μ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;

/**


2 2


μ * ITask objects are serializable javabeans that perform an action.

*/

public interface ITask extends Serializable {

/**

* Called by the CIM Framework before calling execute(). Logic checking if the

*task can be executed should be placed in this method.

*

* @return true if the object has all the values needed to execute

*/

public boolean canExecute();

/**

* Logic to perform a task should be placed in this method. Code should update

*the message property so the framework may retrieve the last state of the

*component.

*

* The IProgressMonitor may be null, so logic should test before using this

*argument.

*

* @throws TaskException

*/

public void execute(IProgressMonitor progressMonitor) throws TaskException;

/**

* Called by the CIM Framework before calling undo(). Logic to check should be

*placed in this method.

*

* @return true if the object can undo

*/

public boolean canUndo();

/**

* Logic to return a system to its before-execute state.

*

* The IProgressMonitor may be null, so logic should test before using this

*argument

*

* @throws TaskException

*/

public void undo(IProgressMonitor progressMonitor) throws TaskException;

/**

* Retrieve the text describing the state of the component for UI display.

*

* @return String containing the status of the component.

*/

public String getMessage();

}


2 3


μ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. Should only be

*called once on a given

* IProgressMonitor instance.

*

* @param pTaskMsg - msg to display to the UI

* @param totalWork - the total number of units to be processed. Value may be

*IProgressMonitor.UNKNOWN for

* when the total number of work units is not known in advance

*/

public void beginTask(String pTaskMsg, int pTotalWork);

/**

* Called numerous times by a worker object as a long running task is being

*processed

*

* @param work the number of units of work completed for this call. This is an

*incremental value,

* not the cumulative amount of work performed so far.

*

*/

public void worked(int pWork);

/**

* Called once by worker object when work has been completed


2 4


μ *

*/

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;

}

/**


2 5


μ *

* 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:


<!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.


2 6


μpublic interface IValidator {

/**

* Called by the CIM Framework before calling validate().

*

* @return true if the object can validate values

*/

public boolean canValidate();

/**

* Logic to test a condition should be placed in this method. Code should

* update the message property so the framework may retrieve the last state of

* the component.

*

* @throws ValidatorException

*/

public boolean validate() throws ValidatorException;

/**

* Returns a brief message describing the state of the object.

*

*/

public String getMessage();

}

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;


2 7


μ

private String mTitle;

/**

* Returns the title string

* @return mTitle

*/

public String getTitle() {

return mTitle;

}

/**

* Sets the title

* @param pTitle

*/

public void setTitle(String pTitle) {

mTitle = pTitle;

}

/**

* assert that the title is not null/blank

*

* @return true if input parameter is not null/blank<br>

* false if input parameter is null/blank

*/

public boolean canValidate() {

if( Util.isNullOrBlank(mTitle) ) {

//unable to validate because title is null or blank

mMessage = "HelloWorldValidator cannot validate as string is null or blank";

return false;

} else {

return true;

}

}

/**

* validates that the value of title is "Hello World!"

* @return true if value of title is "Hello World!"; false otherwise

* @throws ValidatorException

*/

public boolean validate() throws ValidatorException {

if ( mTitle.equals("Hello World!") ) {

//title is equal to "Hello World!"

mMessage = "HelloWorldValidator has successfully validated the title" +

mTitle;

return true;

} else {

//title does not equals "Hello World!"


2 8


μ mMessage = "HelloWorldValidator has successfully validated and your title is

not Hello World!. It is " + mTitle;

return false;

}

}

public String getMessage()

{return mMessage;}

}

Making Validators Available to CIM

To make your validator available to the CIM framework, add an XML snippet to any /plugin_name/validators.xml file. For example:


<!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:


/**

* 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 {

/**


2 9


μ * 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:


<!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:


3 0


μ [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 many-to-many. Ranges are numerically based (0-1, 1-1, 5-10 are all valid examples). Users mark their selections by entering a space-separated list. Entering an item that is already selected deselects it. Validation ensures that the selection is within the minOccurs and maxOccurs range.

The ISelectProvider interface is shown here:


import java.util.List;

import atg.cim.model.SelectProviderOption;

/**

* ISelectProvider objects are javabeans that provide values to the CIM Framework

by exposing properties based on a use input. They also provide a list of choices

to the UI */

public interface ISelectProvider {

/**

* Called by the CIM Framework before calling provideChoices().

*

* @return true if the object can provide values

*/

public boolean canProvide();


3 1


μ

/**

* 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.

*

*


*/

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.

*


*/

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();

/**


3 2


μ * called by framework to get the maxOccurs property

*

*/

public int getMaxOccurs();

}

The property name of the SelectProvider has to match the property name of a task that you’re using the SelectProvider for.

Example: Writing a SelectProvider

This example demonstrates how to write a SelectProvider with Yes and No options.

package atg.cim.worker.common;

import 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;

}


3 3


μ

/**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:


<!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>


3 4


μCreating Navoption Providers

A NavOptionProvider generates a list of steps at runtime, from which the user can then select. A step can refer to a NavigationOptionProvider instead of listing each navigation option.

The interface for this class is extremely simple:

public interface INavigationOptionProvider {

/**

* A Navigation provider should create a List of NavigationOptions.

*

*/

public List<NavigationOption> provide() ;

Example: Navoption Provider with Two Options

This example shows a Navigation list with options Yes and No:

public ListNavigationOption provide() {

ListNavigationOption navOptList = new ArrayList<NavigationOption>();

NavigationOption yesNavOpt = new NavigationOption();

yesNavOpt.setId("yesOpt");

yesNavOpt.setHotkey('Y');

yesNavOpt.setDefaultOption(true);

yesNavOpt.setDisplayLabel(new Label("Yes"));

yesNavOpt.addCommand(new Command(CommandType.GOTO_STEP,"YesStepId"));

navOptList.add(yesNavOpt);

NavigationOption noNavOpt = new NavigationOption();

noNavOpt.setId("noOpt");

noNavOpt.setHotkey('N');

noNavOpt.setDefaultOption(true);

noNavOpt.setDisplayLabel(new Label("No"));

noNavOpt.addCommand(new Command(CommandType.GOTO_STEP,"NoStepId"));

navOptList.add(noNavOpt);

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:


3 5


μ<navoptionprovider class="atg.cim.worker.base.MainMenuNavigation">

<property name="someProp">

<value>someValue</value>

</property>

</navoptionprovider>

The provide() method of the MainMenuNavigation object is called when the step is displayed. It returns a list of Navigation Options based on the progress of the user. This is implemented as a provider and not as a static list because the options change based on the plugin state and the user’s selections.


3 6


μ


3 7

5 - U s i n g P r o d u c t D e f i n i t i o n F i l e s

μ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 module’s 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:


3 8


μ<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE product SYSTEM "http://www.atg.com/dtds/product_1_0.dtd">

<product id="commerce" >

<title>Core Commerce</title>

<detail>Configure Core Commerce</detail>

In addition to title and detail, product definition files can include the following elements:

<requires-addon-id id="ADDON_ID"/> Identifies an add-on as required; the add-on is automatically selected if the product is selected. See the Product Add-Ons 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.


3 9


μ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:

4 0


μ<product-addon id="previewOnManagement" >

<title resource-key="">Configure Preview to run on the CA Server</title>

<modify-server-instance id="basic_management">

<add-appassembler-option name="layer" value="preview"/>

</modify-server-instance>

<modify-server-instance id="management_lock">

<add-appassembler-option name="layer" value="preview"/>


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

4 1


μ </optional-config-directory>


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>


4 2


μ </property>

<property name="localTransactionModeInitialization">

<value>false</value>

</property>

</property-group>

</property-file>

You can pass properties to the validator as shown in the following example:

<pass-validation id=" DirectoryExistsValidator "

class="atg.cim.worker.common.DirectoryExistsValidator">

<property name="absPath">

<value>C:\ATG\</value>

</property>

</pass-validation>

Values can be replaced dynamically just as they are with properties files (see Using Dynamic Values in Properties Files).

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:

value—Default value to assign to the property.

input—Label displayed as a prompt for the user.

validator—Validate the user’s input. The validator ID references a validator defined in a validators.xml file in the Base plugin or the product’s \cim directory.

error-message—If the validator returns false, the error message is displayed and the input is asked for again.

The following example shows how to collect property values at runtime:

<property-file file="atg/PropertyFile.properties">


<property name="someProp">

<value>${AppServerPortsProvider.httpPort}</value>

<input type="text">

<label>Prompt</label>

<validator id="PortNumberValidator">

<error-message>Error</error-message>

</validator>

</input>

</value>

</property >


4 3


μ </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 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>


4 4


μ</property-group>

</property-file>

<property-file file="/atg/dynamo/service/ClientLockManager.properties">


<property name="lockServerAddress">

<value>localhost</value>

</property>

<property name="lockServerPort" persist-

key="managementServerLockManagerPort"/>

<property name="useLockServer">

<value>true</value>

</property>

</property-group>

</property-file>

Using Dynamic Values in Properties Files You can specify dynamic values in a product.xml file, allowing product-specific selections when the product is being configured. This is similar to the dynamic values used in steps (see Using Dynamic Values in Steps in the Creating CIM Plugins chapter).

The following options are available for dynamic values in product.xml files:

Property name—Access a property of a particular server instance or server instance type. The syntax for a server instance is:

${ServerInstance[SERVER_INSTANCE_ID].PROPERTY_NAME}

SERVER_INSTANCE_ID is the ID of the server instance.

PROPERTY_NAME is a property of that server instance (see the Property Files section).

The syntax for a server instance type is similar, but uses the instance type ID instead of the individual instance ID:

${ServerInstanceType[ServerInstanceTypeID].Property_Name}

Server instance name—Access the name of the server instance, which is the name of the individual server directory in the <ATG10dir>/home/servers directory. You might think to use ${ServerInstance[ID].name} to retrieve this, but there can be multiple server instances associated with an ID. The syntax is:

${ServerInstanceName}

ServerInstanceName is replaced with the name of the server instance that is currently being processed. This is the only property that changes between instances; use ${ServerInstance[ID].Prop} for all other properties.

Application server—Access a property of the selected application server. The syntax is:


4 5


μ${AppServerSelection.PROPERTY_NAME}

PROPERTY_NAME is a property of the AppServerSelection object. For example, ${AppServerSelection.type} returns the currently selected application server type. The available properties are:

appServerType—The application server, such as JBoss or WebSphere.

drpPort—Recommended default port for the selected app server, not the currently configured port.

httpPort—Recommended default port for the selected app server, not the currently configured port.

httpsPort—Recommended default port for the selected app server, not the currently configured port.

rmiPort—Recommended default port for the selected app server, not the currently configured port.

Datasource name and property—Access a datasource property. The syntax is:

${NamedDatasource[DATASOURCE_ID].PROPERTY_NAME}

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


<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.


4 6


μ<product-addon-group id="datasource_group" min-occurs="1" max-occurs="1">

<title>Choose switching or non-switching datasource :</title>

<product-id-required id="product_id"/>

<requires-product-addon id="product_addon_id"/>

<product-addon id="switchingdatasource" >

<title resource-key="">Switching Datasource</title>

<modify-server-instance-type id="management">

<add-named-datasource>switchingA</add-named-datasource>

<add-named-datasource>switchingB</add-named-datasource>

</modify-server-instance-type>

<modify-server-instance-type id="production">

<add-named-datasource>switchingA</add-named-datasource>

<add-named-datasource>switchingB</add-named-datasource>


</product-addon

<product-addon id="nonswitchingdatasource" >

<title resource-key="">Non-Switching Datasource</title>


<add-named-datasource>nonswitching</add-named-datasource>



<add-named-datasource>nonswitching</add-named-datasource>


</product-addon>

</product-addon-group

You can use the product-id-required and requires-product-addon elements in the product-addon-group to specify other products or add-ons that must be present if the add-on group is selected. If you specify one or more product-id-required products, the add-on-group is only displayed if the user selects all of those products. If you specify one or more add-ons in the requires-product-addon element, the add-on group is only displayed if the required add-on group has been selected. In such a case, the order of the groups is important.

Add-On Combinations

In addition to individual products, you can define combinations as add-ons in the product.xml, then define changes based on the selection of one or more add-ons. This example shows the combination of Search with 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 id="datawarehouse">


4 7


μ <append-module name="ARF.DW.Search"/>


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


<prepend-module>ARF.Base</prepend-module

<add-named-datasource>datawarehouse</add-named-datasource>



<prepend-module>ARF.Base</prepend-module

<add-named-datasource>datawarehouse</add-named-datasource>


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


4 8


μ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-instance-

type="management">

<title resource-key="">Publishing</title>

<jndi>atgpub_ds</jndi>

</named-datasource>

In order for a named datasource to be used, it must be included in a server-instance-type that has at least one server instance. Each server-instance of that type will have the named datasource’s JNDI registered with the application server.

Default EAR Name You can use the product configuration file to provide a default name for the EAR file used for deploying a given product configuration. The element is a child of server-instance-type. For example:

<server-instance>

<ear-file-name>MyATGApp.ear</ear-file-name>

</server-instance>


4 9


μ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. Server instance = “all”, Datasource = “all”

2. Server instance = “all”, Datasource = product selection datasource ID

3. Server instance = product selection server instance ID, Datasource = “all”

4. 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 user’s previous selections.

The data-import element contains database initialization scripts, and includes the following elements:

repository-path—The repository into which the data is imported.

import-file-path—Path to the XML file that contains the data to import.

user—Content Administration user for versioned imports.

workspace—Content Administration workspace, for versioned imports.

comment—Comment is required for versioned imports.


5 0


μ requires-addon-id—During product selection, the user must select the specified

add-ons, or the data import does not run. For example:

<data-import start-up-module="MyModule">

<requires-addon-id id="MyAddOn" />

required-datasources—Identifies data sources that must be created for this import script. The syntax for required-datasources is:

<data-import start-up-module="DAS" required-

datasources="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 element’s 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.


<!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>


5 1


μ <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>


<datasource id="management">

<schema id="versionedSchema"/>

</datasource>


<server-instance-type id="production">

<datasource id="all">

<schema id="nonVersionedSchema"/>

</datasource>


</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.

5 2


μThe post-deployment-option element has two child elements:

requires-app-server—Restricts the application servers for which the option is available.

requires-add-on—The user must include all specified add-ons during product selection in order to view and use the option.

For example:

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


<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.


<!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-instance-

type="management">

<title resource-key="">Versioned CA</title>

<jndi>atgpub_ds</jndi>

5 3


μ </named-datasource>

<named-datasource id="switchingA" modulelist-server-instance-

type="production">

<title resource-key="">SwitchingA</title>

<jndi>atgcataloga_ds</jndi>

</named-datasource>

<named-datasource id="switchingB" modulelist-server-instance-

type="production">

<title resource-key="">SwitchingB</title>

<jndi>atgcatalogb_ds</jndi>

</named-datasource>

<named-datasource id="nonswitchingCore" modulelist-server-instance-

type="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>


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



<append-module name="commerce.motorprise.search"/>


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

5 4


μ <modify-server-instance-type id="management">

<add-named-datasource id="switchingA"/>

<add-named-datasource id="switchingB"/>

<add-named-datasource id="management"/>



<add-named-datasource id="switchingA"/>

<add-named-datasource id="switchingB"/>



<product-addon-combo id="motorprise-nonswitchingdatasource">

<combo-product-addon id="nonswitchingdatasource"/>


<add-named-datasource id="nonswitchingCore"/>

<add-named-datasource id="management"/>



<add-named-datasource id="nonswitchingCore"/>






<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 id="production" >

<title resource-key="MotorpriseCommerceProductionServer.name">Motorprise

5 5


μCommerce Production Server</title>

<append-module name="MotorpriseJSP"/>




<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>


5 6


μ


5 7

6 - C I M S c r i p t M a n a g e m e n t

μ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.


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.


5 8


μDynamic ClassPaths

For CIM scripts, new classpaths can be added at runtime using one of the following static methods:

atg.cim.SessionContext.addClassPath(String);

atg.cim.SessionContext.addClassPath(File);

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] Enter Connection Details – Done

[T] Test Connection – Done

*[S] Create Schema

[I] 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>


5 9


μ </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.get("mykey");

This removes the key-value pair:


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:


List paths = mRecentlyUsedValue.getList("atgpath", 5);


6 0


μThe list atgpath can be cleared with this code snippet:


mRecentlyUsedValue.clearList("atgpath");

/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 CIM’s 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.


6 1


μ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:

stepID—for the entire step

stepID.navID—for 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)


6 2


μ new named datasource (SelectNamedDatasourceStep.newdatasourceID)

new server instance (ServerInstanceSelectionStep.newserverinstanceID)


6 3

7 - C I M J a v a B e a n R e f e r e n c e

μ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.


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:

srcDir—Directory to be copied. For example:

C:/MyDir/DirToBeCopied

targetDir—Destination directory for the copy. For example:

C:/MyDir/Dir1/DestinationDir

antFile—Path 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:


6 4


μ srcFilePath—Path to the file the task will copy. For example:

C:/MyDir/FileToBeCopied.txt

targetFilePath—Location to which the task will copy the file. For example:

C:/MyDir/Dir1/DestinationDir

antFile—Path 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:

dir—Path to the directory that is to be deleted. For example:

C:/MyDir/DirToBeDeleted

antFile—Path to the ant file that contains the script for the directory deletion task. For example:



atg.cim.worker.common.GenericAntExecutionTask

This task executes the specified ant target.

Properties:

antFile—Path to the ant file that contains the script. For example:



antTarget—Target name to be executed in the ant file. For example:

dir.delete

antProperties—Properties 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/


6 5


μatg.cim.worker.common.PropertyFileCreatorTask

This task generates a properties file for a Nucleus component

Properties:

scope—Scope of the Nucleus component.

className— Java class on which the Nucleus component is based.

props—Properties of the Nucleus component. For example:

props=min=10,max=10,blocking=true,maxFree=-1,loggingSQLError=false

propertiesFile—Absolute 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:

filePath—The 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:

absPath—Path entered by the user. For example:

C:/ProgramFiles/MyDirectory


6 6


μatg.cim.worker.common.AllowOnlyAlphanumericInputValidator

This validator returns true if the input contains only alphanumeric characters.

Properties:

textToValidate—Input text to be validated. For example:

HelloWorld

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:

textToValidate—Input to be validated.

atg.cim.worker.common.PortNumberInputValidator

This validator returns true if the input String is between 1 and 65535.

Properties:

textToValidate—Port 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:

textToValidate—Input 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:

absPathToFile—The 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.


6 7


μ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="LOAD_PROCESS" />

</onpass>

</validator>

atg.cim.worker.common.AlwaysTrueValidator

This validator always returns true. See atg.cim.AlwaysFalseValidator for usage suggestions.


6 8


μ


6 9

A p p e n d i x A : C I M D T D s

μAppendix A: CIM DTDs

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


<!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




7 0


μ>

<!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


>

<!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*)>


7 1


μ<!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


before CDATA #IMPLIED

>

<!ELEMENT remove-module EMPTY>

<!ATTLIST remove-module


>

<!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>


7 2


μ<!ATTLIST remove-server-instance

id CDATA #REQUIRED

>

<!ELEMENT add-appassembler-option EMPTY>

<!ATTLIST add-appassembler-option


value CDATA #IMPLIED

>

<!ELEMENT remove-appassembler-option EMPTY>

<!ATTLIST remove-appassembler-option


>

<!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


>

<!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

>


7 3


μ

<!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-app-

server)*,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


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




7 5


μ<!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*,repository-

path,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-file-

path?,files+,file-mapping,folder-mapping)>

<!ATTLIST repository-loader

post-cleanup (true|false) "false"

start-up-module CDATA "Publishing.base"

>

<!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)>


7 6


μ<!ELEMENT requires-addon-id EMPTY>

<!ATTLIST requires-addon-id

id CDATA #REQUIRED

>

Provider DTD


<!ELEMENT providers (provider*)>

<!ELEMENT provider (property*)>

<!ATTLIST provider

id CDATA #REQUIRED


inherit-values-from CDATA #IMPLIED

>

<!ELEMENT property (value)>

<!ATTLIST property


>


SelectProvider DTD


<!ELEMENT selectproviders (selectprovider*)>

<!ELEMENT selectprovider (property*)>

<!ATTLIST selectprovider

id CDATA #REQUIRED



maxOccurs CDATA #IMPLIED

minOccurs CDATA #IMPLIED

>


<!ATTLIST property


7 8


μ phase (PRESTEP|PREINPUT|POSTINPUT|PRENAVIGATION|POSTSTEP) #REQUIRED

>

<!ELEMENT if-true (command*)>

<!ELEMENT if-false (command*)>

<!ELEMENT property (value?, input?)>

<!ATTLIST property


>


Validator DTD



<!ATTLIST property


>

<!ELEMENT validator (property)*>

<!ATTLIST validator

id CDATA #REQUIRED


batch (true|false) "true"

>

<!ELEMENT validators (validator+)>


Wizard DTD


<!ELEMENT title (#PCDATA)>

<!ATTLIST title



>


7 9


μ<!ELEMENT detail (#PCDATA)>

<!ATTLIST detail



>


<!ATTLIST label



>

<!ELEMENT wizards (wizard+)>

<!ELEMENT wizard (title?,detail?,process+)>

<!ATTLIST wizard

id CDATA #REQUIRED


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


>


<!ELEMENT task EMPTY>

<!ATTLIST task

id CDATA #REQUIRED

>

<!ELEMENT validator (property*,if-true?,if-false?)>

<!ATTLIST validator


8 1

I n d e x

μ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


8 2

I n d e x

μdatasources, 48 DB init scripts, 49 DeleteDirectoryTask class, 64 DirectoryExistsValidator class, 65 dynamic classpaths, 58 dynamic values, 15

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

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

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

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


8 3

I n d e x

μ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

U user input, collecting, 12

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

atgcimdevguide

Documents

devworkcimcimant

cim developers

db init scripts

sqldbcomponentsdatabaseversionedddl

atg programming

product definition

serverinstancenamepubcommerce

cim script