Download - CIM Developer's Guide - Oracle

Version 10.1.2

CIM Developer's Guide

Oracle ATG

One Main Street

Cambridge, MA 02142

USA

ATG CIM Developer's Guide

Product version: 10.1.2

Release date: 12-17-12

Document identifier: CimDevelopersGuide1404301402

Copyright © 1997, 2012 Oracle and/or its affiliates. All rights reserved.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are

trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or

registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are

protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy,

reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any

means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please

report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the

following notice is applicable:

U.S. GOVERNMENT END USERS:

Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation,

delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and

agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any

operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and

license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended

for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or

hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures

to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in

dangerous applications.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties.

Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party

content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to

your access to or use of third-party content, products, or services.

The software is based in part on the work of the Independent JPEG Group.

ATG CIM Developer's Guide iii

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

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

Adding a Task with No Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Adding a Task with Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Collecting User Input for Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Omitting Tasks from Batch Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Using Commands in Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Task Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Navigation Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Compound Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Using Dynamic Values in Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Adding Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Handling Errors in Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Example CIM Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4. Creating CIM Worker Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Creating Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Example: Writing a HelloWorld Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Adding Tasks to the CIM Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Creating Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Example: Writing a HelloWorld Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Making Validators Available to CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Creating Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Making Providers Available to CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Creating Select Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Example: Writing a SelectProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Making Select Providers Available to CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Creating Navoption Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Example: Navoption Provider with Two Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Using Navoption Providers in Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5. Using Product Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Product Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Server Instance Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Server Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Property Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Collecting Property File Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Persistence and Property File Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Using Dynamic Values in Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Product Add-Ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Named Datasources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Default EAR Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

iv ATG CIM Developer's Guide

DB Init Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Post-Deployment Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Example Product Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

6. CIM Script Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

CIM Session Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Dynamic ClassPaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Persistence in CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

System Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

/cim/framework/persistence/Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

/cim/framework/persistence/RecentValueList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

/cim/framework/persistence/RecentDatasourceList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Logging in CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Creating Online Help for CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

7. CIM JavaBean Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Task Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

atg.cim.worker.common.CopyDirectoryTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

atg.cim.worker.common.CopyFileTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

atg.cim.worker.common.DeleteDirectoryTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

atg.cim.worker.common.GenericAntExecutionTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

atg.cim.worker.common.PropertyFileCreatorTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Validator Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Input Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

A. CIM DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Product DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

DBInit DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Provider DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

SelectProvider DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Task DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Validator DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Wizard DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

1 Introduction 1

1 Introduction

This book is intended to introduce developers and partners to the Configuration & Installation Manager (CIM). It

describes how to create and extend CIM plugins, which can greatly simplify configuration of your applications.

This chapter includes the following sections:

Audience (page 1)

Documentation Conventions (page 1)

Audience

To get the most out of this guide, you should be familiar with:

• Nucleus components and their configuration

• Configuration requirements for your product, including database table creation, assembly, and deployment

See the ATG Platform Programming Guide for information on these topics.

Documentation Conventions

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 Introduction

The directory where you installed the Oracle ATG Web Commerce platform is identified as <ATG10dir>. CIM

plugins can be created for any version of ATG software.

2 CIM Overview 3

2 CIM Overview

A common complaint about enterprise software is the complexity of the installation and configuration

process. CIM is designed to cut down this complexity. A series of text-based wizards guide the user through

configuration procedures, providing these benefits:

• The user knows that steps were performed in the correct order.

• Steps are automated and intelligent defaults provided where possible, avoiding opportunities for input errors.

• All necessary steps are complete.

The result is a working, basic installation that can be used as a starting point for further work. Note that CIM

is not intended to handle the entire configuration process, since much of the work of setting up an Oracle

ATG Web Commerce installation is handled through the administrative user interfaces and through custom

components.

CIM scripts are written in XML and use a library of templates, tasks, and validators, making them easy to create

and extend. This chapter introduces CIM script components and describes how to run the demonstration script

so you can see CIM in action.

This chapter contains the following sections:

CIM Installed Files (page 3)

CIM Script Elements (page 4)

Executing CIM Plugins (page 5)

Using the Provided CIM Plugins (page 6)

CIM Installed Files

CIM consists of two main pieces:

• Plugins, which define wizards that carry out configuration steps for each CIM-enabled application.

• The framework, which executes the plugins.

This guide is focused on creating and extending plugins. Changes to the CIM framework are not supported.

CIM is installed automatically as a module in the Oracle ATG Web Commerce platform, located at <ATG10dir>/

CIM. The CIM module includes the following directories:

• config—Component configuration properties files.

4 2 CIM Overview

• data—Database used internally by CIM scripts to store user selections. To start from scratch if you have

previously used CIM, you can delete the contents of this directory.

• lib—CIM .jar files.

• log—Contains the cim.log file. If debugging is turned on, this directory also includes XML files that

represent templates that have been run.

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

• tmp—A working directory created by some CIM processes.

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

In addition to the CIM module itself, all CIM-enabled applications should include a /cim directory, which

contains the product.xml and dbinit.xml CIM files for that application. For information on these files, see the

Using Product Definition Files (page 35) section.

CIM Script Elements

CIM scripts are a form of domain-specific language. They are written in XML using a tightly constrained set of

elements to achieve a specific purpose. These XML files populate JavaBeans, which perform configuration tasks

on your Oracle ATG Web Commerce Search system.

Scripts have the following elements:

• Step—Logical groupings of information presented to the user as a unit. For example, a step may prompt the

user for input values, provide the user with feedback about collected input, or provide information about the

state of the system. See Adding Steps to a Process (page 9).

At the completion of a step, CIM has prepared one or more tasks with the values necessary for execution.

These tasks are not yet executed. However, each time CIM collects a value from the user it has an opportunity

to execute logic. For example, before moving on to the next step, you may want to ensure that the user has

not included disallowed characters in their input.

After a step has collected all of the information required to execute its related tasks, CIM prepares these tasks

and places them in a buffer for later execution.

• Process—A logical grouping of steps. There are no enforced restrictions, but you should contain all task

dependencies within the process. Each step in a process should be able to execute on its own, without

previous processes running. For example, if a step in a process requires a JDBC connection, that connection

should be configured within the process, and should not rely on a step in another process. See Creating CIM

Wizards and Processes (page 7).

• Wizard—A set of one or more processes executed in order to configure a product. See Creating CIM Wizards

and Processes (page 7).

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

Steps (page 10).

• Validator—Can check system state to ensure that information is processed correctly, or can validate user input

for a variety of possible error conditions, allowing you to alter the script’s flow. See Adding Validators (page

15).

2 CIM Overview 5

The Creating CIM Plugins (page 7) chapter describes how to use each of these elements to guide users

through Oracle ATG Web Commerce Search product configuration.

Executing CIM Plugins

CIM can run in two basic forms. The standard way to run a CIM plugin is using a command line interface to make

selections at each step. To run a CIM plugin with the standard interface, go to:

<ATG10dir>\home\bin

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.

Note that by default CIM records batch files in an encrypted form to protect your passwords. If you need

unencrypted access to your batch files, you can record with the –noencryption flag.

2. Proceed with configuration.

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

4. Specify a password to use when running the batch file.

5. Specify a save location.

CIM records your selections in a batch file. To repeat the procedure with those selections, use the following

command to start CIM:

cim -batch path/batch_file.cim

Enter the password when prompted.

Note: When you run a CIM batch file, if any of the data import steps fail, the script exits without continuing on

to configuration steps. If this happens, the log file includes an Error Executing Batch File error message

with information about the failure.

If you are familiar with CIM, you can edit and run batch files without stepping through the UI. The following

example shows a partial batch:

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

6 2 CIM Overview

cim-ant.xmlatg.cim.jboss.CreateJbossAppServerInstanceTask.jbossPath=C:/jboss/atg.cim.jboss.CreateJbossAppServerInstanceTask.serverInstanceName=pub_commerceatg.cim.jboss.CreateJbossAppServerInstanceTask.execute()atg.cim.dynamo.CreateDynamoServerInstanceTask.antFile=C:\dev\work\CIM\cim\ant\cim-ant.xmlatg.cim.dynamo.CreateDynamoServerInstanceTask.atgPath=C:/ATG/ATG10/atg.cim.dynamo.CreateDynamoServerInstanceTask.serverInstanceName=pub_commerceatg.cim.dynamo.CreateDynamoServerInstanceTask.execute()

When the script is finished, it notifies you that the script completed successfully.

Note: No validation is performed when using batch mode. CIM tasks are executed in order.

Using the Provided CIM Plugins

By default CIM includes a number of plugins already created for configuring Oracle ATG Web Commerce

products. You can build on these plugins as described in this guide, or use them as models for creating your

own. The following are included in CIM:

• Product Selection—Users select the combination of products they want to configure.

• Server Instance Creation—Create Oracle ATG Web Commerce servers with the required /config layer

information.

• Application Server Selection—Users must select the application server to which their application will be

deployed, and can perform some optimization tasks.

• Database Configuration—Users provide database configuration information, configure datasources, etc. for

the products they have selected.

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

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

Documentation for these plugins is provided as part of the command-line interface; type H at any prompt to

access the help. You may want to familiarize yourself with these plugins before creating your own.

3 Creating CIM Plugins 7

3 Creating CIM Plugins

To create a CIM plugin, you create several XML files that define your plugin and its features. The wizards.xml

file and its associated tasks.xml files define the following:

• What steps the plugin contains

• What order in which to perform the steps

• What user input to accept

• What validation to perform

• What programmatic tasks should be performed

Plugin creation is straightforward, and you can take advantage of many existing components when you create a

new plugin. Your plugins can also use XML-combine to extend existing plugins.

This chapter explains how to write XML code that assembles CIM components into a functioning plugin; for

detailed information on those components, and how to create your own components, see the Creating CIM

Worker Objects (page 21) chapter.


Creating CIM Wizards and Processes (page 7)

Adding Steps to a Process (page 9)

Adding Tasks to Steps (page 10)

Using Commands in Steps (page 12)

Using Dynamic Values in Steps (page 15)

Adding Validators (page 15)

Handling Errors in Steps (page 17)

Example CIM Plugin (page 17)

Creating CIM Wizards and Processes

The first step in creating your wizard is to create the base script to which you will add configuration functionality,

validators, and other components.

8 3 Creating CIM Plugins

To create a new CIM script, create a wizards.xml file as shown:

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

<wizards> <wizard id="ID"> <title resource-key="" resource-params="">Title</title> <detail resource-key="" resource-params="">Detail</detail> <process id="MyProcess">



</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 Platform Programming Guide for general information on XML-combine.

When you run the MyWizard plugin, a combined-MyWizard.xml file containing the combined wizards is

saved to the directory where MyWizard’s wizards.xml file is located. This file is deleted if the wizard exits

successfully, unless you have turned on debugging. To turn on debugging, edit the <ATG10dir>/CIM/config/

GLOBAL.properties file.

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

Choose Wizard: *[0] OtherWizard – OtherWizard detail [1] MyWizard - MyWizard detail


The wizard element contains one or more process elements, which contain a logical grouping of steps and

have no attributes of their own (see the Adding Steps to a Process (page 9) section for step information).

For an example, see the Example CIM Plugin (page 17) section of this chapter, or review the wizards.xml file

located at <ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.

Adding Steps to a Process

Steps are where the work of a CIM plugin is outlined. Each step should consist of a logical group that can be

presented to the user as a single entity. When the step is complete, the following events have taken place:

• Relevant information is displayed to the user about what CIM will do

• Input has been collected from the user

• Validators may have checked the input or system state

• Tasks are prepared for execution

• A navigation option is chosen by the user

To insert a step, place the following XML snippet inside a process tag:

<step id="step_ID" insert-after="other_step_ID" type="standard_or_base" class="class_name"> <title/> <detail/> <property name="some_name"> <value>value</value> </property> <navoption> <option default="true"> <label>Next Step</label> <command type="EXECUTE_STEP_TASKS" /> <command type="NEXT_STEP" /> </option> <option > <label>Redo Step</label> <command type="DROP_STEP_TASKS" /> <command type="REDO_STEP" /> </option> </navoption></step>

Steps have the following attributes:

• id—Uniquely identifies the step to the framework.

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

be inserted.

• type—Can be standard or template. This attribute is optional, and the default is standard. A standard

step acts as part of a simple, linear process with a tightly restricted set of user options, and relies on default


worker objects for its behavior. A template step permits dynamic generation of options and greater

flexibility, but requires you to write your own components; this is provided for use with future versions of CIM.

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

Steps contain the following elements:

• title—Identifies the step in the user interface.

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

• property— Argument to pass to a template step; not used in standard steps. This allows a single template

to be reused, displaying different information depending on the property. For an example, see the Database

Configuration menu in CIM, in which a single template displays different options depending on the database

selected.

• navoption—Provides a framework of options from which the user can select. As part of navigation,

commands are fired, some of which are purely navigational, and others of which have to do with tasks that

are prepared during the step. Navigation options include Next Step, Redo Step, Jump to Third Step, etc. The

default selection is indicated by the attribute default="true", and is executed if no value is entered and the

user presses the Enter key.

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

script.

For an example, see the Example CIM Plugin (page 17) section of this chapter, or review the wizards.xml file

located at <ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.

Changing Step Order in Combined Wizards

If your wizard extends an existing wizard, you’ll need to think about the order in which the steps of the

combined wizard should be performed. Default behavior is to append your wizard to the wizard you are

extending. You can change this by using the insert-after attribute in your step as shown:

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

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

extended wizard.

You can also use the combination to entirely suppress steps in the base wizard. See the XML File Combination

section of the ATG Platform Programming Guide for general information on XML-combine.

Adding Tasks to Steps

As part of the step, you can specify one or more tasks to be configured and executed. Tasks reside in their own

XML file, named tasks.xml, and are referred to from wizards.xml. The id specified in the wizards.xml file’s

task element must match the id of a task defined in tasks.xml. For an example of a tasks.xml file, see the

<ATG10dir>/CIM/plugins/base directory in your Oracle ATG Web Commerce installation.


In the task, you specify the name and Java class. This identifies to CIM the component that is going to do the

work of the task, so that CIM can set properties on that component. Input passes through the following series of

layers:

CIM user interface > wizards.xml > tasks.xml > JavaBean

The task element’s property element refers to a component property to which the input should be assigned.

Within the input element, you can include a label, which is displayed in the user interface, and one or more

validators to check the entered text (see the Adding Validators (page 15) section of this chapter).

Task examples are shown in the sections that follow.

Adding a Task with No Properties

To add a simple task to a step in a wizard, add the snippet below as a child of a <step> element. Multiple tasks

can be included in a single step, in which case they are processed in order.

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

Adding a Task with Properties

In the tasks.xml file, the tasks themselves are specified in detail, including which JavaBean does the task’s

work, what information is collected, and any validation that should be performed. The property elements point

to properties of the bean.

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

<tasks>

<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"> <property name="serverInstanceName"> <value>pub_commerce</value>

<input type="text"> <label>Enter a unique server instance name:</label> </input>

etc.

Note that if you use a SelectProvider to set a property, such as the serverInstanceName in the sample

above, that SelectProvider must have that property, and it must be of the same type.

CIM supports the following types of input:

• text—User enters plain text.

• select—User selects from a provided list of options using numeric hotkeys. This option requires that you

write a customer Java class that implements iSelectProvider. Identify this class in the selectprovider

attribute for the input tag as shown:

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

See the Creating Select Providers (page 28) section for information.

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

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

Omitting Tasks from Batch Files

As described in Executing CIM Plugins (page 5), a batch file is a script that can be run as a single unit, without

stepping through the user interface. Some tasks, such as those that store user-entered values, do not add any

value to a batch file and can be omitted.

To omit a task from any batch files saved for it, use the following syntax:

<task id="MyTask" batch="false" class="atg.cim.dynamo.TaskClass">…</task>

The default batch value is true.

Using Commands in Steps

Commands are used within steps to instruct the CIM framework to either do something with the configured

tasks in that step, or perform navigational functions. Commands are specified using the type attributes of the

command element. For example:

<command type="EXECUTE_STEP_TASKS" />


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

Task Commands

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

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

• LAUNCH_TEMPLATE—If you are extending CIM, use this command to signal the start of your own template.

Requires value="class name of template".

• TEMPLATE_COMPLETE—Signals the end of a template, returning program control to the wizard. If you provide

a value attribute, it is used as the value of a GO_TO step by the parent plugin.

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

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

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

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

• DELETE_QUEUED_TASKS—Clears the queue of all tasks.

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

• ADD_STEP_TASKS_TO_QUEUE—Moves step tasks to the queue, enabling them to be processed as a batch at a

later time.

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

the wizard:

<navoption> <option default="true"> <label>Next Step</label> <command type="EXECUTE_STEP_TASKS" /> <command type="NEXT_STEP" /> </option>

For additional examples, see the Example CIM Plugin (page 17) section of this chapter, or review the

wizards.xml file located at <ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.

Navigation Commands

Navigation can be added to steps using commands. The following commands are used for navigation in a step:

• NEXT_STEP—Process the next step in the step list.

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

• PREVIOUS_STEP—Process the previous step in the step list.

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

to".


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

phase of an input validator.

• PROCESS_COMPLETE—Notifies CIM that a process has been completed.

• QUIT—Shut down CIM with no saving of data.

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

<step id="FirstStep"> <title>First Step</title> <detail>Details of the first step: Demonstrates simple navigation </detail> <navoption> <option default="true"> <label>Next Step</label> <command type="EXECUTE_STEP_TASKS" /> <command type="NEXT_STEP" /> </option> <option > <label>Redo Step</label> <command type="DROP_STEP_TASKS" /> <command type="REDO_STEP" /> </option> <option > <label>Jump to [T]hird Step</label> <command type="DROP_STEP_TASKS" /> <command type="GOTO_STEP" value="ThirdStep" /> </option> <option > <label>Jump to [F]ourth Step</label> <command type="DROP_STEP_TASKS" /> <command type="GOTO_STEP" value="FourthStep" /> </option> </navoption> </step>

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

Load [W]izard.

If no brackets are present, CIM automatically designates the first letter as the hot key. CIM will throw a runtime

error if a single step includes multiple equivalent hotkeys.

Compound Commands

In addition to the task commands and navigation options outlined in the previous sections, CIM also includes

the following commands, which combine a task and navigation option:

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

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

command.

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

${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 (page 27) section of the Creating CIM Worker Objects (page 21) chapter), the CIM framework will

call the provider’s provide() method and refresh the component every time it accesses the component. This is

useful if you’re accessing information that changes during the course of running the script.

Adding Validators

CIM uses validator objects to check user input for formatting or other errors. Validators return either true or

false, and allow you to conditionally display messages or perform navigation commands.

Validators can be used at two levels in a script:

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

Note that using validators may mean that not all phases of the step execute. For example, if the outcome of a

PRESTEP validator commands CIM to navigate to another step, later phases will never execute.

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

For each validator, you’ll need to specify:

• The step phase in which validation takes place.

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

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

Step validators can be described in terms of the point at which they perform their check; this information is

required in the phase attribute of the validator tag. The phases are:


• PRESTEP—Executed before processing a step starts.

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

are rendered.

• PRENAVIGATION—Executed after UI input collection is complete and tasks are configured, but before

navigation options are displayed to the user. at this point no tasks have been executed.

• POSTSTEP—Executed after navigation chosen by user, does not execute if the user selects a navigation step

that executes a command to move to another step.

To use a validator in a step, add the snippet below as a child of a <step> element. Multiple validators can be

added to a single step. They are processed in order depending on their phase attribute.

<step>

other xml...

<validators> <validator id="DemoFileExistsValidator" phase="PRESTEP" > <if-true> <command type="DISPLAY_TEXT" value="file exists at${DemoFileExistsValidator.absPathToFile}"/> <command type="GOTO_STEP" value="ThirdStep" /> </if-true> <if-false> <command type="DISPLAY_TEXT" value="file DOES NOT exist at${DemoFileExistsValidator.absPathToFile}"/> <command type="GOTO_STEP" value="FirstStep" /> </if-false> </validator> </validators>

... other xml...

</step>

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

<task id="CreateJBossAppServerInstanceTask" class="atg.cim.tasks.CreateJBossAppServerInstanceTask" <property name="serverInstanceName"> <value>pub_commerce</value>

<input type="text"> <label>Enter a unique server instance name:</label> <validator id="NoWhiteSpaceValidator" phase="POSTINPUT"> <if-false> <command type="DISPLAY_TEXT" value="No white space allowed" /> <command type="REDO_INPUT" /> </if-false> </validator> </input>

etc.


For an example, see the Example CIM Plugin (page 17) section of this chapter, or review the files located at

<ATG10dir>/CIM/plugins/base in your Oracle ATG Web Commerce installation.

Handling Errors in Steps

In addition to whatever error handling you may build into your Java classes, CIM includes an XML-level form of

basic error handling. If one of your steps encounters an error during execution, you can use the <error> element

to specify an alternative step.

In this example. the error element checks to see if there have been changes to CIM’s persisted data made

outside of CIM; if so, the UI prompts the user to re-select a product for configuration.

<error> <step id="ProductionSelectionPersistenceCheckErrorStep"> <title>Product Selection Model Update</title> <detail><![CDATA[The CIM Product object model has been updated.

REQUIRED ACTION: Re-Execute the Product Selection wizard. Select [p]from the Main Menu.]]> </detail> <navoption id="continue"> <label>Continue</label> <command type="NEXT_STEP" /> </navoption> </step></error>

Example CIM Plugin

The following code shows an example of a wizards.xml file that defines a custom CIM plugin. The plugin helps

a user install an Oracle ATG Web Commerce hotfix, and shows the elements previously described in this chapter

working together.

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE wizards SYSTEM "http://www.atg.com/dtds/wizard_1_0.dtd"><wizards> <wizard id="MyPlugin"> <title>Configure ATG10 Hotfix 2</title> <detail>Installs a test hotfix</detail>

<process id="TestProcess"> <step id="FirstStep"> <title>First Step</title> <detail>Choose the task you want to perform:</detail>


<navoption id="install"> <label>[I]nstall hotfix</label> <command type="GOTO_STEP" value="InstallHotfix"/> </navoption> <navoption id="uninstall"> <label>[U]ninstall hotfix</label> <command type="GOTO_STEP" value="UninstallHotfix"/> </navoption>

</step>

<step id="InstallHotfix"> <title>Test Hotfix Installation</title> <detail></detail> <navoption id="install"> <label>[I]nstall hotfix</label> <command type="GOTO_STEP" value="UnjarHotfix"/> </navoption> </step> <step id="UnjarHotfix"> <title>Test Hotfix Installation</title> <detail></detail> <task id="UnjarHotfix"/> <task id="CreateProperties"/> <validator id="AlwaysTrueValidator" phase="PRENAVIGATION"> <if-true> <command type="EXECUTE_STEP_TASKS" /> <command type="GOTO_STEP" value="FirstStep"/> </if-true> </validator> </step>

<step id="UninstallHotfix"> <title>Test Hotfix Uninstallation</title> <detail></detail> <navoption id="install"> <label>[U]ninstall hotfix</label> <command type="GOTO_STEP" value="RemoveHotfix"/> </navoption> </step>

<step id="RemoveHotfix"> <title>Uninstall Hotfix</title> <detail>Uninstalls the test hotfix</detail>

<task id="RemoveHotfix"/> <task id="RemoveProperties"/>

<validator id="AlwaysTrueValidator" phase="PRENAVIGATION"> <if-true> <command type="EXECUTE_STEP_TASKS" /> <command type="DISPLAY_TEXT" value="Hotfix has beenuninstalled" /> <command type="GOTO_STEP" value="FirstStep"/> </if-true> </validator> </step>

</process>


</wizard></wizards>


4 Creating CIM Worker Objects 21

4 Creating CIM Worker Objects

This chapter describes how to create new worker objects for CIM. Worker object is a general term for a Java

class that performs any sort of functionality relating to the installation and configuration of Oracle ATG Web

Commerce products. Validators, Tasks, and Providers are three types of worker object.

• Task. Use when you want to do something such as copy a file or save data.

• Validator. Use to check user input or system state. For example, ensure that an input string contains only

alphanumeric characters. Validators return true or false values.

• Provider. Use a provider when a wizard needs a value from the system, such as a list of names of the current

JBoss server instances.

• Select Provider. Use when you want to give the user a list of items from which to select. Select providers can

set properties, but do not perform actions.

• Navoption Provider. Use to provide a dynamic list of navigation options that perform tasks when selected.

This chapter includes the following sections:

Creating Tasks (page 21)

Creating Validators (page 25)

Creating Providers (page 27)

Creating Select Providers (page 28)

Creating Navoption Providers (page 32)

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;

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

22 4 Creating CIM Worker Objects

public interface ITask extends Serializable {

/** * Called by the CIM Framework before calling execute(). Logic checking if the *task can be executed should be placed in this method. * * @return true if the object has all the values needed to execute */ public boolean canExecute();/** * Logic to perform a task should be placed in this method. Code should update *the message property so the framework may retrieve the last state of the *component. * * The IProgressMonitor may be null, so logic should test before using this *argument. * * @throws TaskException */public void execute(IProgressMonitor progressMonitor) throws TaskException;

/** * Called by the CIM Framework before calling undo(). Logic to check should be *placed in this method. * * @return true if the object can undo */public boolean canUndo();

/** * Logic to return a system to its before-execute state. * * The IProgressMonitor may be null, so logic should test before using this *argument * * @throws TaskException */public void undo(IProgressMonitor progressMonitor) throws TaskException;

/** * Retrieve the text describing the state of the component for UI display. * * @return String containing the status of the component. */public String getMessage();

}

It is a good practice to end your class names with Task (for example: ATGPathTask).

You can extend the atg.cim.worker.Task class to create custom tasks, as shown in the Example: Writing a

HelloWorld Task (page 23) section.

The progressMonitor method can be used to display a status bar for any task that is defined in its XML

as “long-running.” In the provided configuration scripts, tasks such as schema creation and data import are

considered long-running. It can show progress when the amount of work is unknown (similar to the Windows

spinning hourglass cursor), or to show increments of a known amount of work as they are completed. The

Progress Monitor interface is shown here:


public interface IProgressMonitor {

/** Class version string */ public static final String CLASS_VERSION = "$Change: 509503 $$DateTime:2008/09/16 13:48:09 $$Author: acollege $";

/** * Constant indicating an unknown amount of work. */ public static final int UNKNOWN = -1;

/** * Called by worker object at the start of a long running task. Should only be *called once on a given * IProgressMonitor instance. * * @param pTaskMsg - msg to display to the UI * @param totalWork - the total number of units to be processed. Value may be *IProgressMonitor.UNKNOWN for * when the total number of work units is not known in advance */ public void beginTask(String pTaskMsg, int pTotalWork);

/** * Called numerous times by a worker object as a long running task is being *processed * * @param work the number of units of work completed for this call. This is an *incremental value, * not the cumulative amount of work performed so far. * */ public void worked(int pWork);

/** * Called once by worker object when work has been completed * */ 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.

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

/** * * Prints "Hello World!" at console. * * @param pProgressMonitor * @exception TaskException */public void execute(IProgressMonitor pProgressMonitor) throws TaskException { try { System.out.println("Hello World!"); mMessage = " Executed HelloWorldTask";

} catch(Exception exp) { mMessage = "Error executing HelloWorldTask"; throw new TaskException("Error ", exp); }

}

Adding Tasks to the CIM Library

Tasks are made available to the CIM framework by adding an XML snippet to any /plugin_name/tasks.xml

file as shown in the example:

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

<task id="DeleteFileTask" class="atg.cim.task.DemoTask">


<property name="fileName"> <input type="text"> <label>Enter a file name : </label> </input> </property></task>

You can now refer to the DeleteFileTask in your wizards.xml file.

Creating Validators

A validator is a class that implements the validate() method of the atg.cim.worker.IValidator. To write

your own validator object, you will need to provide the concrete implementation of the methods defined in the

IValidator class.

public interface IValidator {

/** * Called by the CIM Framework before calling validate(). * * @return true if the object can validate values */ public boolean canValidate();

/** * Logic to test a condition should be placed in this method. Code should * update the message property so the framework may retrieve the last state of * the component. * * @throws ValidatorException */ public boolean validate() throws ValidatorException;

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

private String mTitle;

/** * Returns the title string * @return mTitle */ public String getTitle() { return mTitle; }

/** * Sets the title * @param pTitle */public void setTitle(String pTitle) { mTitle = pTitle;}

/** * assert that the title is not null/blank * * @return true if input parameter is not null/blank<br> * false if input parameter is null/blank */public boolean canValidate() { if( Util.isNullOrBlank(mTitle) ) { //unable to validate because title is null or blank mMessage = "HelloWorldValidator cannot validate as string is null or blank"; return false; } else { return true; }}

/** * validates that the value of title is "Hello World!" * @return true if value of title is "Hello World!"; false otherwise * @throws ValidatorException */public boolean validate() throws ValidatorException { if ( mTitle.equals("Hello World!") ) { //title is equal to "Hello World!" mMessage = "HelloWorldValidator has successfully validated the title" + mTitle; return true; } else {


//title does not equals "Hello World!" mMessage = "HelloWorldValidator has successfully validated and your title isnot 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:

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

<validator id="MyNewValidator" class="atg.cim.validator.HelloWorldValidator"> <title>HelloWorld!</title></validator>

Now you can refer to the validator MyNewValidator in your wizards.xml file.

Creating Providers

Provider objects are JavaBeans that provide values to the CIM framework by exposing properties. They

implement atg.cim.worker.IProvider, which defines the two methods below. The only difference between

an IProvider object and any other JavaBean is that CIM will always call the provide() method immediately

before accessing any property values.

The IProvider interface is extremely simple:

package atg.cim.worker;

/** * IProvider objects are javabeans that provide values to the CIM Framework by exposing properties. The only real difference between any other nucleuscomponent is that the CIM framework will call the .provide() method before eachtime a getter is called on a property.**/public interface IProvider {

/** * Called by the CIM Framework before calling provide(). * * @return true if the object can provide values */ public boolean canProvide();


/** * logic to initialize and set object properties should be placed in this method. CIM Framework calls this method each time a value is accessed from thiscomponent * @throws ProviderException */ public void provide() throws ProviderException;

Providers can be used to replace values through a CIM plugin, by including the following syntax:

${ProviderID.property}

CIM calls the provide() method before it replaces the value.

Making Providers Available to CIM

To make your provider available to the CIM framework, add an XML snippet to any /plugin_name/

providers.xml file. For example:

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

<provider id="MyNewProvider" class="atg.cim.provider.HelloWorldProvider"></provider>

Now you can refer to the provider MyNewProvider in your wizards.xml file.

Creating Select Providers

The SelectProvider is not a sub-type of Provider, but a distinct type of worker object. Select providers allow

users to select items from a list of options.

They are referenced in the tasks.xml input element; for example:

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

You can constrain users to a single selection or allow multi-select. This example shows a single-select option in

the user interface:

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

package atg.cim.worker;

import java.util.List;

import atg.cim.model.SelectProviderOption;

/** * ISelectProvider objects are javabeans that provide values to the CIM Frameworkby exposing properties based on a use input. They also provide a list of choicesto the UI */

public interface ISelectProvider { /** * Called by the CIM Framework before calling provideChoices(). * * @return true if the object can provide values */public boolean canProvide();

/** * create a list of choices to display to the UI. The List will be modified * by the users selection and it will be passed to setUserSelection after user *input. * * * @throws ProviderException */public List<SelectProviderOption> provideChoices() throws ProviderException;


/** * * This method is called by the framework immediately after a user * makes a selection. * set the bean values to expose depending on the choice from the UI. * The selected options are flaged as Selected in the SelectProviderOption List * that was created from the Provide Method * @param pChoices The list of {@link SelectProviderOption}. Call isSelected on *each * {@link SelectProviderOption} to find what the user has selected. * * @throws ProviderException */public void setUserSelection(List<SelectProviderOption> pChoices) throwsProviderException;

/** * called by framework to override the minOccurs property * * @param pMinOccurs */ public void setMinOccurs(int pMinOccurs);

/** * called by framework to override the maxOccurs property * * @param pMaxOccurs */ public void setMaxOccurs(int pMaxOccurs);

/** * called by framework to get the minOccurs property * */ public int getMinOccurs();

/** * called by framework to get the maxOccurs property * */ public int getMaxOccurs();}

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

SelectProvider for.

Example: Writing a SelectProvider

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

package atg.cim.worker.common;

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

/**Provides a list with options Yes and No * @return A SelectProviderOtpion list of Yes and No * @see atg.cim.worker.ISelectProvider#provideChoices() */public List<SelectProviderOption> provideChoices(){ List<SelectProviderOption> choices = new ArrayList<SelectProviderOption>(2); choices.add(0, new SelectProviderOption("yes","Yes")); choices.add(1,new SelectProviderOption("no","No")); return choices;}

/**Set the value from the user's selection * @param pChoices * @see atg.cim.worker.ISelectProvider#setUserSelection(java.util.List) */public void setUserSelection(List<SelectProviderOption> pChoices){ if(pChoices.get(0).isSelected()) mChoice = true; else mChoice = false; }

}

Making Select Providers Available to CIM

Select providers are declared in selectproviders.xml, using the syntax shown in this example:


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

<selectproviders>

<selectprovider id="mySelectProvider" class="atg.cim.worker.mode.mySelectProvider"> <property name="myStore"> <value>nucleus:/cim/framework/myStore</value> </property> </selectprovider>

</selectproviders>

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:

<navoptionprovider class="atg.cim.worker.base.MainMenuNavigation"><property name="someProp"><value>someValue</value></property></navoptionprovider>

The provide() method of the MainMenuNavigation object is called when the step is displayed. It returns a list

of Navigation Options based on the progress of the user. This is implemented as a provider and not as a static list

because the options change based on the plugin state and the user’s selections.


5 Using Product Definition Files 35

5 Using Product Definition Files

CIM scripts use product definition files to describe the product combinations they configure and their

dependencies, including possible add-ons and standard configuration options. This product awareness allows

the CIM templates to generate appropriate steps and request information from the user according to the

combination of products they are configuring.

A product.xml file defines the information required to configure a particular Oracle ATG Web Commerce

product. It defines the products themselves, any optional features, and module lists for each product, and may

address multiple versions of a product in the form of server-instance types.

CIM uses the product.xml file to generate a list of top-level modules, which are then used for database

configuration and application assembly.

CIM expects the product.xml file to be under a CIM directory within the application module, as shown:

/some_module /cim product.xml

The product.xml cannot be located any deeper than the second level of the module’s directory structure. The

product definition file defines the options described in the sections that follow:

Product Definitions (page 35)

Server Instance Types (page 37)

Server Instances (page 37)

Product Add-Ons (page 42)

Default EAR Name (page 45)

DB Init Scripts (page 46)

Example Product Definition File (page 49)

Product Definitions

The first few elements in the product definition file are used for identification of the product or products

described in the file. The id attribute must uniquely identify the product. The title and detail can be shown

in the user interface. The file must include the DTD declaration shown:

36 5 Using Product Definition Files

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

<product id="commerce" > <title>Core Commerce</title> <detail>Configure Core Commerce</detail>

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

• <requires-addon-id id="ADDON_ID"/>

Identifies an add-on as required; the add-on is automatically selected if the product is selected. See the

Product Add-Ons (page 42) section of this chapter for information.

• <product-id-required id="PRODUCT_ID"/>

Identifies another product as required; the product is automatically selected if the main product is selected.

• <incompatible-product-id id="PRODUCT_ID"/>

Identifies a product as incompatible with this product. If the user selects both, the CIM UI displays an error

message.

• <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 (page 65) section of Appendix A, CIM DTDs (page 65) for details on the

product.xml elements and attributes.


Server Instance Types

A server instance type represents a particular type of configuration for the product. It is basically a wrapper

for a list of modules, a group of data sources, and individual server instances (you can have multiple instances

of a server that is of a particular type). This feature does not apply to all Oracle ATG Web Commerce products,

but one common application for it is with ATG Content Administration, which requires configuration of both a

source (often called the publishing server) and a target server.

Each instance-type can have its own list of modules and configuration file information. For example:

<server-instance-type id="management"> <title resource-key="CAServer.name">CA Server</title> <detail resource-key="CAServer.detail"/>

<append-module>BIZUI</add-module> <append-module>PubPortlet</add-module> <append-module>DafEar.Admin</add-module> <add-named-datasource>management</add-named-datasource> <add-server-instance id="ID"> <config-directory> <property-file> … </property-file> </config-directory> <optional-config-directory id="some-option"> <title>Configure these optional properties</title> <detail></detail> <property-file> … </property-file> </optional-config-directory>

</server-instance-type>

You can append modules, add named datasources, and add server instances to an instance type, as shown in the

example above, and configure property files (see the Property Files (page 38) section for more information

on these elements).

Server Instances

A server instance represents a particular implementation of a server instance type. The one thing you can

change at the server instance level but not the server instance type level is runAssembler arguments.

For example, this code fragment provides different assembly options for the basic_management and

management_lock server instances:

<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"/> </modify-server-instance></product-addon>

Property Files

As part of the server-instance-type and server-instance elements, you can specify properties files to

create and configure. If you configure properties files in the server-instance-type element, every server

instance of that type uses the same properties file. If the property file is in the server-instance element, each

instance can have unique configuration.

Property files are specified in the config-directory element of a particular server instance or instance type,

as shown in this example:

<product id="blueprint" extends="commerce">... <server-instance id="basic_management" type="management">... <config-directory> 

The server-instance-type element supports an additional optional-config-directory element. This

element cannot be used in a server-instance element. It appears as a separate option in the server instance

configuration user interface. For example:

<server-instance-type id="id"> <title>Title</title> <config-directory> <property-file> … </property-file> </config-directory> <optional-config-directory id="some-option"> <title>Configure these optional properties</title> <detail></detail> <property-file> … </property-file> </optional-config-directory></server-instance-type>

A property file is defined by a file name and a list of properties. The file name is relative to the path

<ATG10dir>/home/servers/server_name/localconfig, and should start with a slash, as shown in the

value element of this example::

<property-file file="atg/dynamo/service/jdbc/JTDataSource.properties"> <property-group id="base">


<property name="dataSource"> <value>/atg/dynamo/service/jdbc/DirectJTDataSource</value> </property> </property-group></property-file>

You can specify multiple property files. You can also group properties as shown, so that the current product

selection acts to filter subsets of the total property list:

<property-file file="atg/SomeFile.properties"> <property-group id="search-reporting">  <requires-addon-id id="search"/> <requires-addon-id id="reporting"/> <property name="someProperty"> <value>propertyValue</value> </property > </property-group></property-file>

In order for a property group to be included in a server instance, all of the requires-addon-id identifiers listed

in the property group must be included in the current product selection. If no add-ons are listed, the property

group applies to all product selections. A property-file element can include multiple property-group

elements, but each property-group must have a unique ID.

In addition to requiring addons, you can use the pass-validation tag to specify a validator to test for other

conditions. As with the requires-addon-id tag, all specified validators must pass in order for to execute the

property group. The following example uses pass-validation to add properties if the database is DB2:

<property-file file="GLOBAL.properties"> <property-group id="db2"> <pass-validation id="HasDB2DatasourceValidator" class="atg.cim.worker.databaseconfig.HasDB2DatasourceValidator"/> <property name="handleRangesInMemory"> <value>true</value> </property> <property name="localTransactionModeInitialization"> <value>false</value> </property> </property-group></property-file>

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

<pass-validation id=" DirectoryExistsValidator " class="atg.cim.worker.common.DirectoryExistsValidator"> <property name="absPath"> <value>C:\ATG\</value> </property></pass-validation>

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

Files (page 41)).


Collecting Property File Values

You can use the property-file element to collect property values from a CIM user at runtime, using the

following additional elements:

• 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-group id="base"> <property name="someProp"> <value>${AppServerPortsProvider.httpPort}</value> <input type="text"> <label>Prompt</label> <validator id="PortNumberValidator"> <error-message>Error</error-message> </validator> </input> </value> </property > </property-group></property-file>

The dynamic value (${…}) replacement is similar to that used elsewhere in CIM (see Using Dynamic Values

in Properties Files (page 41)). The format is ${WORKER_ID.PROPERTY} where WORKER_ID is the ID of a

validator, task, or provider. In the example above, AppServerPortsProvider is a provider ID.

You can use a worker object provided by CIM, or a custom worker object.

Persistence and Property File Values

To persist property values for later use, provide a persist-key attribute for the property, as shown in this

example:

<property-file file="atg/PropFile.properties"> <property-group id="base"> <property name="someProp" persist-key="someKey"> <value>Default value</value> <input type="text"> <label>Prompt to the user</label> </input> </value> </property > </property-group>


</property-file>

At runtime, if the key references a valid persisted value, that value is used as the default presented to the user.

If the reference does not exist, the value tag is used as the default instead. In both cases, the user input is

persisted to the persist-key specified.

You can also use previously persisted values in a property. In the following example, the second property file

has a lockServerPort property that uses the persisted value from the first property file. Note that the order

is significant; you cannot use a persisted value before it is persisted, so the first time the persisted value is

referenced, the input element must be declared.

<property-file file="/atg/dynamo/service/ServerLockManager.properties"> <property-group id="lock"> <property name="port" persist-key="managementServerLockManagerPort"> <value>9010</value> <input type="text"> <label>Enter Lock Server Port</label> <validator id="PortNumberInputValidator"> <error-message>Invalid Port Number</error-message> </validator> </input> </property></property-group></property-file> <property-file file="/atg/dynamo/service/ClientLockManager.properties"> <property-group id="base"> <property name="lockServerAddress"> <value>localhost</value> </property> <property name="lockServerPort" persist-key="managementServerLockManagerPort"/> <property name="useLockServer"> <value>true</value> </property> </property-group></property-file>

Using Dynamic Values in Properties Files

You can specify dynamic values in a product.xml file, allowing product-specific selections when the product is

being configured. This is similar to the dynamic values used in steps (see Using Dynamic Values in Steps (page

15) in the Creating CIM Plugins (page 7) chapter).

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

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

server instance is:

${ServerInstance[SERVER_INSTANCE_ID].PROPERTY_NAME}

SERVER_INSTANCE_ID is the ID of the server instance.

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


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

ID:

${ServerInstanceType[ServerInstanceTypeID].Property_Name}

• Server instance name—Access the name of the server instance, which is the name of the

individual server directory in the <ATG10dir>/home/servers directory. You might think to use

${ServerInstance[ID].name} to retrieve this, but there can be multiple server instances associated with

an ID. The syntax is:

${ServerInstanceName}

ServerInstanceName is replaced with the name of the server instance that is currently being processed.

This is the only property that changes between instances; use ${ServerInstance[ID].Prop} for all other

properties.

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

${AppServerSelection.PROPERTY_NAME}

PROPERTY_NAME is a property of the AppServerSelection object. For example,

${AppServerSelection.type} returns the currently selected application server type. The available

properties are:

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

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

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

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

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

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

${NamedDatasource[DATASOURCE_ID].PROPERTY_NAME}

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 Oracle ATG Web Commerce products or features that are available separately from

products, but which can be used to add functionality. For example:

<product-addon id="reporting" >


<title resource-key="">Reporting</title> <modify-server-instance id="basic_management"> <add-appassembler-option name="layer" value="Staging"/> <remove-appassembler-option name="layer"/> </modify-server-instance> <prepend-module-list>SearchAdmin.DataWarehouse</prepend-module-list></product-addon>

Product add-ons can be defined as groups for selection purposes. For instance, the Switching Datasource and

NonSwitching Datasource add-ons are mutually exclusive. They are defined as belonging to a product-addon-

group that allows only one to be selected, using the max-occurs attribute.

<product-addon-group id="datasource_group" min-occurs="1" max-occurs="1"> <title>Choose switching or non-switching datasource :</title> <product-id-required id="product_id"/> <requires-product-addon id="product_addon_id"/>

<product-addon id="switchingdatasource" > <title resource-key="">Switching Datasource</title> <modify-server-instance-type id="management"> <add-named-datasource>switchingA</add-named-datasource> <add-named-datasource>switchingB</add-named-datasource> </modify-server-instance-type> <modify-server-instance-type id="production"> <add-named-datasource>switchingA</add-named-datasource> <add-named-datasource>switchingB</add-named-datasource> </modify-server-instance-type> </product-addon <product-addon id="nonswitchingdatasource" > <title resource-key="">Non-Switching Datasource</title> <modify-server-instance-type id="management"> <add-named-datasource>nonswitching</add-named-datasource> </modify-server-instance-type> <modify-server-instance-type id="production"> <add-named-datasource>nonswitching</add-named-datasource> </modify-server-instance-type> </product-addon></product-addon-group

You can use the product-id-required and requires-product-addon elements in the product-addon-

group to specify other products or add-ons that must be present if the add-on group is selected. If you specify

one or more product-id-required products, the add-on-group is only displayed if the user selects all of

those products. If you specify one or more add-ons in the requires-product-addon element, the add-on

group is only displayed if the required add-on group has been selected. In such a case, the order of the groups is

important.

Add-On Combinations

In addition to individual products, you can define combinations as add-ons in the product.xml, then define

changes based on the selection of one or more add-ons. This example shows the combination of Search with

reporting, and adds modules to the data warehouse and loader.

<product-addon-combo id="search-reporting"> <combo-product-addon id="search"/> <combo-product-addon id="reporting"/>


<modify-server-instance-type id="datawarehouse_loader"> <append-module name="ARF.DW.Search"/> <append-module name="SearchAdmin.datawarehouse"/> </modify-server-instance-type> <modify-server-instance-type id="datawarehouse"> <append-module name="ARF.DW.Search"/> </modify-server-instance-type></product-addon-combo>

Modifying Server Instance Types

An add-on might mean that additional modules are required in the EAR, that an additional data source is

needed, or that an entirely different server type can be used; for example, if you add reporting to any Oracle ATG

Web Commerce production combination, a data source is required for the data warehouse, and all potential

server types require additional modules. Use the <modify-server-instance-type> element to specify these

changes:

<product-addon id="reporting <title resource-key="">Reporting</title

<modify-server-instance-type id="management"> <prepend-module>ARF.Base</prepend-module <add-named-datasource>datawarehouse</add-named-datasource> </modify-server-instance-type>

<modify-server-instance-type id="production"> <prepend-module>ARF.Base</prepend-module <add-named-datasource>datawarehouse</add-named-datasource> </modify-server-instance-type>

</product-addon

The <modify-server-instance-type> element has the following sub-elements:

<prepend-module><append-module><remove-module><add-named-datasource><remove-named-datasource><add-server-instance>

The module-related elements use the following syntax:

<prepend-module name="DAS"/>

The append-module element can optionally include a before attribute. For example, the following XML adds

the DSS module before the DAS module, if DAS is found:

<append-module name="DSS" before="DAS"/>

The datasource elements have the following format:


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

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 Oracle ATG Web Commerce applications.

The modulelist-server-instance attribute identifies a server-instance-type, which in turn supplies a

list of modules. The dbinit.xml files for each of those modules are then used to generate the SQL and import

scripts that run for the database.

You can declare named datasources in the product.xml file for configuration by end-users.

<named-datasource id="management" modulelist-server-instance-type="management"> <title resource-key="">Publishing</title> <jndi>atgpub_ds</jndi></named-datasource>

In order for a named datasource to be used, it must be included in a server-instance-type that has at least one

server instance. Each server-instance of that type will have the named datasource’s JNDI registered with the

application server.

Default EAR Name

You can use the product configuration file to provide a default name for the EAR file used for deploying a given

product configuration. The element is a child of server-instance-type. For example:

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


DB Init Scripts

The DB init scripts initialize the database for products being configured, creating schemas and

importing initial data required for some Oracle ATG Web Commerce products. Scripts are declared in the

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

• 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 Oracle ATG Web

Commerce 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 Oracle ATG Web

Commerce server.

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

<schema id="versionedSchema">

<sql> <path> <create> sql/db_components/${database}/versioned_ddl.sql </create> <drop> sql/uninstall/${database}/drop_versioned_ddl.sql </drop> </path> </sql>

<data-import> <repository-path>/atg/epub/file/PublishingFileRepository</repository-path> <import-file-path>/Publishing/base/install/epub-file-repository-data.xml</import-file-path> <user>publishing</user> <workspace>workspace</workspace> <comment>initial_data_import</comment> </data-import>

<repository-loader post-cleanup="true"> <files> <src-module>DSS</src-module> <config-path>atg/registry/data/scenarios/DSS</config-path> <file-pattern>*.sdl</file-pattern> </files> <files>


<src-module>DSS</src-module> <config-path>atg/registry/data/scenarios/recorders</config-path> <file-pattern>*.sdl</file-pattern> </files> <file-mapping>/atg/epub/file/typemappers/ScenarioTypeMapping</file-mapping> <folder-mapping>/atg/epub/file/typemappers/FileFolderTypeMapping</folder-mapping> </repository-loader>

</schema>

<server-instance-type id="management"> <datasource id="management"> <schema id="versionedSchema"/> </datasource></server-instance-type>

<server-instance-type id="production"> <datasource id="all"> <schema id="nonVersionedSchema"/> </datasource></server-instance-type>

</database-initializer>

Post-Deployment Options

Post-deployment options allow you to specify actions for CIM to take after deploying the assembled EAR file.

CIM displays these options to the user in the Post Deployment Menu.

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-optionid="${ServerInstanceName}-${AppServerSelection.appServerType}_storefront_static">

<title>Copy Storefront Static HTML/Image Files</title> <requires-app-server>JBoss</requires-app-server> <requires-addon-id id="storefront_demo"/> <requires-addon-id id="previewOnManagement"/> <step id="CopyStoreFrontStaticPostDeploymentOptionStep" type="template"class="atg.cim.storeconfig.deploy.CopyStaticStorefrontTemplate"> <property name="serverInstanceName"> <value>${ServerInstanceName}</value> </property> </step>


</post-deployment-option>

Example Product Definition File

This section provides a sample product definition file that shows the elements described in this chapter working

together. The sample product.xml defines elements that would be used when configuring the Motorprise

reference application.

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE product SYSTEM "http://www.atg.com/dtds/product_1_0.dtd"><product id="motorprise" extends="commerce">

<title resource-key="MotorpriseCommerceProduct.name">Motorprise</title> <detail resource-key="MotorpriseCommerceProduct.detail">ConfigureMotorprise</detail>

 <named-datasource id="management" modulelist-server-instance-type="management"> <title resource-key="">Versioned CA</title> <jndi>atgpub_ds</jndi> </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>

<modify-server-instance-type id="management"> <append-module name="commerce.motorprise.search"/> <append-module name="commerce.motorprise.search.Index"/> <append-module name="DCS-UI.Search"/>


<append-module name="DCS.Search.CustomCatalogs.Versioned"/> </modify-server-instance-type>

<modify-server-instance-type id="production"> <append-module name="commerce.motorprise.search"/> </modify-server-instance-type>

</product-addon>

<product-addon id="customcatalog" xml-combine="remove" /> <product-addon id="merch" xml-combine="remove" />

</product-addon-group>

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

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

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

<add-named-datasource id="switchingA"/> <add-named-datasource id="switchingB"/> <add-named-datasource id="management"/> </modify-server-instance-type>

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

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

</modify-server-instance-type>

</product-addon-combo>

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

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

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

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


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

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


</product-addon-combo>

 <server-instance-type id="management"> <title resource-key="MotorpriseCommerceCAServer.name">MotorpriseCommerce 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">MotorpriseCommerce 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>


6 CIM Script Management 53

6 CIM Script Management

This section contains topics related to CIM scripting, but not directly concerned with script creation. For

information on Oracle ATG Web Commerce programming in general, see the ATG Platform Programming Guide.


CIM Session Context (page 53)

Dynamic ClassPaths (page 54)

Persistence in CIM (page 54)

Logging in CIM (page 56)

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

54 6 CIM Script Management

To avoid overwriting keys already in use, be cautious when naming keys.

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

To get a status:

StatusMonitorStore statusMonStore = StatusMonitorStore.getInstance();//This has no effect if the StatusMonitor aready existsstatusMonStore.newStatusMonitor(DATABASE_CONFIGURATION_WIZARDID);boolean dbConfDone =statusMonStore.isDone(DATABASE_CONFIGURATION_WIZARDID);

Similar code would normally be used in a navoption provider, allowing you to modify navigation options based

on the tasks the user has already completed.

/cim/framework/persistence/Lookup

The /cim/framework/persistence/Lookup object provides a simple implementation of a persistent lookup

table of values. It uses the class atg.cim.persistence.Lookup. Only Strings can be persisted.

The following example persists a key-value pair:

mLookup = SessionContext.getLookupPersistence()mLookup.put("mykey", "value1");

Then this snippet retrieves the value:

mLookup = SessionContext.getLookupPersistence()mLookup.get("mykey");

This removes the key-value pair:

mLookup = SessionContext.getLookupPersistence()mLookup.remove("mykey");

/cim/framework/persistence/RecentValueList

This object provides an implementation of a persistent MRU (Most Recently Used) list of values. It uses class

atg.cim.persistence.RecentValueList. Only Strings can be persisted.

The following example persists the value C:/ATG/ATG10 as the most recent value to a list named atgpath:

mRecentlyUsedValue = SessionContext.getRecentValueList()


mRecentlyUsedValue.addToList("atgpath", "C:/ATG/ATG10");

The list of the 5 (or less) latest values in the atgpath list can be retrieved with this code snippet:

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

The list atgpath can be cleared with this code snippet:

mRecentlyUsedValue = SessionContext.getRecentValueList()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_ORACLE);dsVal.setDriverPathsAsString("/path/to/OracleDriver");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 resolveListDatasourceValue list = mRecentDatasourceList.getList("datasourceAlist",5);

Logging in CIM

CIM’s atg.cim.logging class uses standard Oracle ATG Web Commerce logging as described in the ATG

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

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

• new named datasource (SelectNamedDatasourceStep.newdatasourceID)

• new server instance (ServerInstanceSelectionStep.newserverinstanceID)

7 CIM JavaBean Reference 59

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 (page 11) section.


Task Beans (page 59)

Validator Beans (page 61)

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:

60 7 CIM JavaBean Reference

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

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

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.

For example, after the user selects a wizard to run, CIM would normally display navigation options. Instead of

this default behavior, you can force CIM to load the chosen wizard and then navigate to the next step with this

XML snippet:

<validator id="AlwaysTrueValidator" phase="PRENAVIGATION"> <onpass> <command type="EXECUTE_STEP_TASKS" /> <command type="LOAD_PROCESS" /> </onpass></validator>


atg.cim.worker.common.AlwaysTrueValidator

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


Appendix A. CIM DTDs 65

Appendix A. CIM DTDs

This section provides the full DTD for each of the XML files described in this guide.

Product DTD (page 65)

DBInit DTD (page 70)

Provider DTD (page 71)

SelectProvider DTD (page 71)

Task DTD (page 72)

Validator DTD (page 73)

Wizard DTD (page 73)

Product DTD

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

<!ELEMENT product (title?,detail?,requires-addon-id*,product-id-required*, incompatible-product-id*,incompatible-addon-id*,named-datasource*, product-addon-group*,product-addon-combo*,server-instance-type*, server-instance*) ><!ATTLIST product id CDATA #REQUIRED extends CDATA #IMPLIED priority CDATA #IMPLIED>

<!ELEMENT title (#PCDATA)><!ATTLIST title resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED>

<!ELEMENT detail (#PCDATA)><!ATTLIST detail resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED>

66 Appendix A. CIM DTDs

<!ELEMENT requires-addon-id EMPTY><!ATTLIST requires-addon-id id CDATA #REQUIRED>

<!ELEMENT incompatible-product-id EMPTY><!ATTLIST incompatible-product-id id CDATA #REQUIRED><!ELEMENT incompatible-addon-id EMPTY><!ATTLIST incompatible-addon-id id CDATA #REQUIRED>

<!ELEMENT named-datasource (title,detail?,jndi?)><!ATTLIST named-datasource id CDATA #REQUIRED modulelist-server-instance-type CDATA #REQUIRED extends CDATA #IMPLIED><!ELEMENT jndi (#PCDATA)>

<!ELEMENT product-addon-group (title,detail?,product-id-required*, requires-product-addon*,incompatible-addon-id*,product-addon+)><!ATTLIST product-addon-group id CDATA #REQUIRED min-occurs CDATA #IMPLIED max-occurs CDATA #IMPLIED>

<!ELEMENT product-id-required EMPTY><!ATTLIST product-id-required id CDATA #REQUIRED>

<!ELEMENT requires-product-addon EMPTY><!ATTLIST requires-product-addon id CDATA #REQUIRED>

<!ELEMENT product-addon (title,detail?,(modify-server-instance-type| modify-server-instance)*)><!ATTLIST product-addon id CDATA #REQUIRED>

<!ELEMENT product-addon-combo (combo-product-addon+, modify-server-instance-type*,modify-server-instance*)><!ATTLIST product-addon-combo id CDATA #REQUIRED>

<!ELEMENT combo-product-addon EMPTY><!ATTLIST combo-product-addon id CDATA #REQUIRED>

<!ELEMENT modify-server-instance-type ((prepend-module|append-module| remove-module|add-named-datasource|add-server-instance| remove-named-datasource|remove-server-instance)*)>


<!ATTLIST modify-server-instance-type id CDATA #REQUIRED>

<!ELEMENT modify-server-instance ((add-appassembler-option| remove-appassembler-option)*)><!ATTLIST modify-server-instance id CDATA #REQUIRED>

<!ELEMENT prepend-module EMPTY><!ATTLIST prepend-module name CDATA #REQUIRED><!ELEMENT append-module EMPTY><!ATTLIST append-module name CDATA #REQUIRED before CDATA #IMPLIED><!ELEMENT remove-module EMPTY><!ATTLIST remove-module name CDATA #REQUIRED><!ELEMENT add-named-datasource EMPTY><!ATTLIST add-named-datasource id CDATA #REQUIRED>

<!ELEMENT remove-named-datasource EMPTY><!ATTLIST remove-named-datasource id CDATA #REQUIRED>

<!ELEMENT add-server-instance EMPTY><!ATTLIST add-server-instance id CDATA #REQUIRED><!ELEMENT remove-server-instance EMPTY><!ATTLIST remove-server-instance id CDATA #REQUIRED>

<!ELEMENT add-appassembler-option EMPTY><!ATTLIST add-appassembler-option name CDATA #REQUIRED value CDATA #IMPLIED>

<!ELEMENT remove-appassembler-option EMPTY><!ATTLIST remove-appassembler-option name CDATA #REQUIRED>

<!ELEMENT server-instance-type (title,detail?,append-module*, add-named-datasource*,add-server-instance*,config-directory?, optional-config-directory*)><!ATTLIST server-instance-type id CDATA #REQUIRED extends CDATA #IMPLIED>


<!ELEMENT optional-config-directory (title,detail?,(property-file|step)*)><!ATTLIST optional-config-directory id CDATA #REQUIRED>

<!ELEMENT server-instance (title,detail?,ear-file-name,server-instance-name, config-directory,post-deployment?,post-deployment-option*)><!ATTLIST server-instance id CDATA #REQUIRED type CDATA #REQUIRED min-occurs CDATA #IMPLIED max-occurs CDATA #IMPLIED>

<!ELEMENT ear-file-name (#PCDATA)>

<!ELEMENT server-instance-name (#PCDATA)>

<!ELEMENT config-directory (property-file|step)*>

<!ELEMENT property-file (comment?,property-group*)><!ATTLIST property-file file CDATA #REQUIRED><!ELEMENT property-group ((requires-addon-id|pass-validation)*,property*)><!ATTLIST property-group id CDATA #REQUIRED>

<!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 name CDATA #REQUIRED persist-key CDATA #IMPLIED>


<!ELEMENT if-true (command*)><!ELEMENT if-false (command*)>

<!ELEMENT validator (property*,error-message?,if-true?,if-false?)><!ATTLIST validator id CDATA #REQUIRED phase (PRESTEP|PREINPUT|POSTINPUT|PRENAVIGATION|POSTSTEP) #IMPLIED><!ELEMENT error-message (#PCDATA)>

<!ELEMENT value (#PCDATA)>

<!ELEMENT label (#PCDATA)><!ATTLIST label resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED>

<!ELEMENT command (label?)><!ATTLIST command type (EXECUTE_STEP_TASKS|DROP_STEP_TASKS|ADD_STEP_TASKS_TO_QUEUE| EXECUTE_QUEUED_TASKS|DELETE_QUEUED_TASKS|UNDO_STEP_TASKS|ADD_TASK|REMOVE_TASK|GOTO_STEP|NEXT_STEP|PREVIOUS_STEP|QUIT|REDO_STEP|LOAD_PROCESS| PROCESS_COMPLETE|LAUNCH_WIZARD|LAUNCH_TEMPLATE|TEMPLATE_COMPLETE| WIZARD_COMPLETE|DROP_REDO|EXECUTE_NEXT|EXECUTE_GOTO|DISPLAY_TEXT| REDO_INPUT) #REQUIRED value CDATA #IMPLIED>

<!ELEMENT input (label, validator*)><!ATTLIST input type (text | password | path | class) #REQUIRED>

<!ELEMENT navoption (label,command+)><!ATTLIST navoption id CDATA #REQUIRED default (true|false) #IMPLIED>

<!ELEMENT navoptionprovider (property*)><!ATTLIST navoptionprovider class CDATA #REQUIRED>

<!ELEMENT error (step)>

<!ELEMENT task (property*)><!ATTLIST task id CDATA #REQUIRED>


DBInit DTD


<!ELEMENT database-initializer (schema*,server-instance-type*)>

<!ELEMENT schema (sql*,data-import*,repository-loader*)><!ATTLIST schema id CDATA #REQUIRED><!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)>

<!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 class CDATA #REQUIRED inherit-values-from CDATA #IMPLIED>

<!ELEMENT property (value)><!ATTLIST property name CDATA #REQUIRED>


SelectProvider DTD


<!ELEMENT selectproviders (selectprovider*)>

<!ELEMENT selectprovider (property*)><!ATTLIST selectprovider id CDATA #REQUIRED class CDATA #REQUIRED inherit-values-from CDATA #IMPLIED maxOccurs CDATA #IMPLIED minOccurs CDATA #IMPLIED>




Task DTD



<!ELEMENT command (label?)><!ATTLIST command type (EXECUTE_STEP_TASKS|DROP_STEP_TASKS|ADD_STEP_TASKS_TO_QUEUE| EXECUTE_QUEUED_TASKS|DELETE_QUEUED_TASKS|UNDO_STEP_TASKS|ADD_TASK|

REMOVE_TASK|GOTO_STEP|NEXT_STEP|PREVIOUS_STEP|QUIT|REDO_STEP|LOAD_PROCESS| PROCESS_COMPLETE|LAUNCH_WIZARD|LAUNCH_TEMPLATE|TEMPLATE_COMPLETE| WIZARD_COMPLETE|DROP_REDO|EXECUTE_NEXT|EXECUTE_GOTO|DISPLAY_TEXT| REDO_INPUT) #REQUIRED value CDATA #IMPLIED>

<!ELEMENT input (label, validator*)><!ATTLIST input type (text | select | password | path | class) #REQUIRED selectprovider CDATA #IMPLIED>

<!ELEMENT task (property*)><!ATTLIST task id CDATA #REQUIRED class CDATA #REQUIRED longRunning (true|false) #IMPLIED inherit-values-from CDATA #IMPLIED batch (true|false) #IMPLIED><!ELEMENT tasks (task+)>

<!ELEMENT validator (if-true?,if-false?)><!ATTLIST validator id CDATA #REQUIRED phase (PRESTEP|PREINPUT|POSTINPUT|PRENAVIGATION|POSTSTEP) #REQUIRED>

<!ELEMENT if-true (command*)><!ELEMENT if-false (command*)>

<!ELEMENT property (value?, input?)><!ATTLIST property name CDATA #REQUIRED>



Validator DTD



<!ELEMENT validator (property)*><!ATTLIST validator id CDATA #REQUIRED class CDATA #REQUIRED batch (true|false) "true"><!ELEMENT validators (validator+)>


Wizard DTD


<!ELEMENT title (#PCDATA)><!ATTLIST title resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED>

<!ELEMENT detail (#PCDATA)><!ATTLIST detail resource-key CDATA #IMPLIED resource-params CDATA #IMPLIED>


<!ELEMENT wizards (wizard+)>

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


id CDATA #REQUIRED extends CDATA #IMPLIED wizard-type (base|fragment) #IMPLIED>

<!ELEMENT process (step+)><!ATTLIST process id CDATA #REQUIRED insert-after CDATA #IMPLIED>

<!ELEMENT step(title?,detail?,property?,navoptionprovider?,(task|validator|navoption)*,error?)><!ATTLIST step id CDATA #REQUIRED insert-after CDATA #IMPLIED type (standard|template) #IMPLIED class CDATA #IMPLIED><!ELEMENT error (step)>

<!ELEMENT property (value?)><!ATTLIST property name CDATA #REQUIRED><!ELEMENT value (#PCDATA)>

<!ELEMENT task EMPTY><!ATTLIST task id CDATA #REQUIRED>

<!ELEMENT validator (property*,if-true?,if-false?)><!ATTLIST validator id CDATA #REQUIRED phase (PRESTEP|PREINPUT|POSTINPUT|PRENAVIGATION|POSTSTEP) #REQUIRED>

<!ELEMENT if-true (command+)><!ELEMENT if-false (command+)>

<!ELEMENT command (label?)><!ATTLIST command type(GOTO_STEP|NEXT_STEP|PREVIOUS_STEP|QUIT|REDO_STEP|LAUNCH_WIZARD|LAUNCH_TEMPLATE|TEMPLATE_COMPLETE|WIZARD_COMPLETE|DROP_REDO|EXECUTE_NEXT|EXECUTE_GOTO|DROP_STEP_TASKS|EXECUTE_STEP_TASKS|DISPLAY_TEXT) #REQUIRED value CDATA #IMPLIED>

<!ELEMENT navoption (label,command+)><!ATTLIST navoption id CDATA #REQUIRED default (true|false) #IMPLIED>

<!ELEMENT navoptionprovider (property*)><!ATTLIST navoptionprovider class CDATA #REQUIRED


>


Index 77

Index

AAbsolutePathValidator class, 61

AllowOnlyAlphanumericInputValidator class, 61

AlwaysFalseValidator class, 62

AlwaysTrueValidator class, 63

audience, 1

Bbatch files, editing, 5

batch mode, 5, 5

CCannotBeBlankValidator class, 62

cim directory, 4

CIM module, 3

cim.log, 4

classpath, dynamic, 54

commands

compound, 14

navigation-related, 13

commands, task-related, 12

component overview, 4

config directory, 3

conventions, 1

CopyDirectoryTask class, 59

CopyFileTask class, 59

Ddata directory, 4

database

initializing, 46

databases

CIM internal, 54

datasources, 45

DB init scripts, 46

DeleteDirectoryTask class, 60

DirectoryExistsValidator class, 61

dynamic classpaths, 54

dynamic values, 15

EEAR name, default, 45

error handling, 17

example plugin, 17

executable, 4

execution modes, 5

FFileExistsValidator class, 62

files, installed, 3

GGenericAntExecutionTask class, 60

HHypersonic, 54

IINavigationOptionProvider interface, 32

installed files, 3

IProgressMonitor interface, 22

IProvider interface, 27

ISelectProvider interface, 28

ITask interface, 21

IValidator interface, 25

Llib directory, 4

log directory, 4

logging, 56

Lookup object, 55

Mmultiselect lists, 28

Nnamed datasources, 45

navigation commands, 13

navoption providers

creating, 32

example, 32

using in steps, 33

NoWhiteSpaceInputValidator class, 62

Ppersistence, 54

plugins

example, 17

executing, 5

location, 4

78 Index

provided, 6

recording, 5

plugins, creating, 7

PortNumberInputValidator class, 62

processes

creating, 7

overview, 4

product add-ons, 42

combinations, 43

modifying server instance types, 44

product definition files, 35

example, 49

product.xml file, 35

products, 35

progressMonitor method, 22

PropertyFileCreatorTask class, 60

providers

making available, 28

providers, creating, 27

RRecentDatasourceList object, 56

RecentValueList object, 55

record flag, 5

Sselect providers

creating, 28

example, 30


SelectProvider, 12

server instance types, 37

in DB init scripts, 46

modifying, 44

server instances, 37

session context, 15, 53

StatusMonitorStore, 54

StatusUpdateValidator, 54

steps

adding, 9

changing order, 10

dynamic values in, 15

handling errors in, 17

overview, 4

using commands in, 12

validation phases of, 15

system progress, 54

Ttasks

adding, 10

collecting input for, 11

creating, 21

example, 23


navigation in, 13

omitting from batch files, 12

overview, 4

using commands in, 12

with no properties, 11

with properties, 11

Uuser input, collecting, 11

Vvalidators

adding, 15

creating, 25

example, 25


overview, 4

phase attribute, 15

Wwizards

creating, 7

extending, 8

overview, 4

worker objects, creating, 21