 | Level: Introductory Debbie Wagner, Software Engineer, IBM
27 Oct 2005 Perform system administrative tasks using IBM® DB2® Content Manager OnDemand XML Batch Administration. Learn from examples that show how to add, update, delete, and export OnDemand objects, such as users, groups, application groups, and folders.
Introduction
DB2 Content Manager OnDemand is an automated archival and retrieval system that stores printed output, such as reports, statements, invoices, and image documents. The printed output is processed and stored onto various types of storage media, including hard disks, optical platters, and tapes. Index values are extracted from the printed output and stored in a relational database, such as DB2 Universal Database™. After the printed output and index values are stored, you can use any of the OnDemand client programs to query and retrieve documents.
OnDemand provides two applications that perform system administrative tasks: the Administrative client and the XML Batch Administration program. The Administrative client runs under Windows®, and the XML Batch Administration program is a command line program that is executed on the OnDemand server. In this article, learn how to use the XML Batch Administration program.
Getting started
The XML Batch Administration program provides the same functionality as the Administrative client. One difference between the two system administrative programs is that input is provided to the Administrative client through a graphical user interface, while the XML Batch Administration program receives input through an XML interface.
XML, or Extensible Markup Language, is a metalanguage that allows you to define your own markup language. The definition and syntax of the markup language is defined in a schema file. The schema file for the OnDemand XML Batch Administration program is called ondemand.xsd. It contains definitions for the OnDemand objects: users, groups, applications, application groups, storage sets, folders, and printers. Each OnDemand object definition contains one or more child objects. For example, a user object has a child object for permissions, and a group object has a child object for users in the group. Figure 1 shows the OnDemand objects and their associated child objects.
Figure 1. Layout of the OnDemand schema file
An input file containing XML is provided to the XML Batch Administration program for processing. The XML input file is parsed to ensure the file contains valid XML according to the schema file, and each object within the file is examined to ensure the attributes of the object are valid according to the object type. The XML Batch Administration program also generates XML when you export OnDemand objects. Generally, the XML is written to an output file, but it can also be written to stdout. XML that is provided to the XML Batch Administration program can also be provided using stdin, rather than an input file.
Exporting OnDemand objects
An easy way to get started using the XML Batch Administration program is to export OnDemand objects that you added using the Administrative client. A simple XML input file can be created and used to export one or more OnDemand objects. The only object information that is required in the XML file is the name of the object. Listing 1 is an example of an XML file that contains a user, group, application, application group, storage set, folder, and printer. The names of the existing OnDemand objects are shown in bold text. You can create a similar XML file and simply replace the object names with the names of the OnDemand objects on your server.
Listing 1. Contents of an XML input file
<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ondemand.xsd" >
<!-- Users -->
<user name="CSRUSER1" >
</user>
<!-- Groups -->
<group name="CSRGROUP" >
</group>
<!-- Applications -->
<application name="Monthly Reports" appGroup="Baxter Bay Credit" >
</application>
<!-- Application groups -->
<applicationGroup name="Baxter Bay Credit" >
</applicationGroup>
<!-- Storage Sets -->
<storageSet name="Cache Only Storage Set" >
</storageSet>
<!-- Folders -->
<folder name="Credit Card Statements" >
</folder>
<!-- Printers -->
<printer name="Department ABC Printer" >
</printer>
</onDemand>
|
Listing 2 shows an example of how to use the XML Batch Administration program to export the objects that are contained in the example XML file shown in Listing 1. The name of the input XML file in Listing 1 is infile1.xml. The XML Batch Administration program, called arsxml, requires a user ID, password, OnDemand Server, the name of the input XML file, and the name of an output file where the exported objects will be written. The output XML file can be used to add the exported OnDemand objects to another OnDemand server, or it can be used as a template for adding new objects on the same server.
Listing 2. Export example
arsxml export -u oduser1 -p odpasswd1 -h odserver1 -i infile1.xml -o outfile.xml -v
|
When the output XML file is created by the export process, attributes that have default values are not included in the object definition. This simplifies the XML file and it also keeps the size of the file to a minimum. Conversely, when you create an input XML file, you don't need to include attributes in the object definition if a default value is used. Listing 3 shows an example of an output XML file that was created using the input XML file in Listing 1. The objects were first created using the Administrative client. In general, default values were used for the attributes within the objects and child objects. For the application group and folder, four fields were added with various data types. Again, the names of the existing OnDemand objects are shown in bold text.
Listing 3. Contents of an XML output file
<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ondemand.xsd" >
<user name="CSRUSER1" passwordEnc="10CO6P6tN49Ig" >
</user>
<group name="CSRGROUP" >
<user name="CSRUSER1" />
</group>
<application name="Monthly Reports" appGroup="Baxter Bay Credit" >
<afpData paperSize="Autosize" >
</afpData>
<preprocessParm dbName="name" />
<preprocessParm dbName="sdate" format="%m/%d/%y" />
<preprocessParm dbName="account" />
<preprocessParm dbName="balance" embedded=",." divideBy="100" />
</application>
<applicationGroup name="Baxter Bay Credit"
storageSet="Cache Only Storage Set" dbTablespaceType="SMS" >
<permission user="*PUBLIC" authority="None" />
<field name="name" stringType="Variable" stringLength="30" >
</field>
<field name="sdate" dataType="Date" segment="Yes" >
</field>
<field name="account" stringLength="11" >
</field>
<field name="balance" dataType="Decimal" >
</field>
</applicationGroup>
<storageSet name="Cache Only Storage Set" >
<node name="batch1" server="*ONDEMAND" loadData="Yes" accessMethod="Cache" />
</storageSet>
<folder name="Credit Card Statements" >
<applicationGroup name="Baxter Bay Credit" >
</applicationGroup>
<field name="Name" >
<mapping dbName="name" appGroup="Baxter Bay Credit" />
<fieldInfo group="*PUBLIC" displayOrder="1" queryOrder="1" />
</field>
<field name="Date" fieldType="Date" >
<mapping dbName="sdate" appGroup="Baxter Bay Credit" />
<fieldInfo group="*PUBLIC" displayOrder="2" queryOrder="2" dateIntLength="3"
dateIntType="Months" default="Yes" />
</field>
<field name="Account Number" >
<mapping dbName="account" appGroup="Baxter Bay Credit" />
<fieldInfo group="*PUBLIC" displayOrder="3" queryOrder="3" />
</field>
<field name="Balance" fieldType="Decimal" >
<mapping dbName="balance" appGroup="Baxter Bay Credit" />
<fieldInfo group="*PUBLIC" displayOrder="4" queryOrder="4" />
</field>
</folder>
<printer name="Department ABC Printer" queue="ip40" >
</printer>
</onDemand>
|
 |
Adding OnDemand objects
One of the benefits of using the XML Batch Administration program is the input XML file can contain multiple objects with different object types. This is especially useful when multiple servers are used, such as a test and a production server. The objects with various object types can be created on the test server using either the Administrative client or the XML Batch Administration program. They can then be exported from the test server and added to the production server using the XML Batch Administration program. Alternatively, if the objects were added using the XML Batch Administration program, the input XML file that was used to add the objects to the test server can also be used to add the objects to the production server.
To illustrate how to add objects using the XML Batch Administration program, the output XML file shown in Listing 3 is used as the input XML file. The objects are added to a different server using the arsxml command shown in Listing 4.
Listing 4. Add example
arsxml add -u oduser2 -p odpasswd2 -h odserver2 -i outfile.xml -v
|
Deleting OnDemand objects
OnDemand objects can be deleted using the XML Batch Administration program. The only attribute that you need to specify to delete the object is the object name. Any attributes that are included in the object other than the name are ignored. This means, for example, the XML file shown in Listing 3 can be used to delete the objects that are included in the XML file. The XML file shown in Listing 1 can also be used to delete the objects. Listing 5 shows the arsxml command that can be used to delete all of the objects that were added to the second server in the previous example. You will be prompted before each object in the XML file is deleted. This gives you the flexibility to delete certain objects within the XML file rather than all of them. If you want to delete all of the objects without being prompted for each delete request, the -x parameter can be added to the command line.
Listing 5. Delete example
arsxml delete -u oduser2 -p odpasswd2 -h odserver2 -i outfile.xml -v
|
Updating OnDemand objects
OnDemand objects can be updated using the XML Batch Administration program. The only attributes that are necessary in the XML file are the attributes that are being updated and the name of the object. Other attributes can be included even if the values aren't being changed. This makes it easier to modify and use an existing XML file to update the objects rather than having to create a new XML file. Only the attributes that are being changed need to be modified in the XML file.
There are some attributes that cannot be updated. For example, the data type of an application group field or folder field cannot be updated. If the data type attribute is included in the XML file, the XML Batch Administration program will output a warning message that indicates the attribute cannot be updated. The application group or folder will still be updated, assuming no other errors are encountered. Listing 6 is an example of an XML input file that can be used to update each of the objects in the XML file by adding the description attribute. In this example, no other attributes are included.
Listing 6. Contents of an XML input file
<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ondemand.xsd" >
<user name="CSRUSER1" description="This is a description for the user">
</user>
<group name="CSRGROUP" description="This is a description for the group">
</group>
<application name="Monthly Reports" appGroup="Baxter Bay Credit"
description="This is a description for the application" >
</application>
<applicationGroup name="Baxter Bay Credit"
description="This is a description for the application group">
</applicationGroup>
<storageSet name="Cache Only Storage Set"
description="This is a description for the storage set">
</storageSet>
<folder name="Credit Card Statements"
description="This is a description for the folder">
</folder>
<printer name="Department ABC Printer"
description="This is a description for the printer" >
</printer>
</onDemand>
|
Listing 7 shows the arsxml command that can be used to update the description of each of the objects that are specified in the XML file shown in Listing 6.
Listing 7. Update example
arsxml update -u oduser2 -p odpasswd2 -h odserver2 -i infile2.xml -v
|
Hints and tips
- Objects can occur in any order in the XML file. The XML Batch Administration program will ensure the objects are added in the correct order. For example, if an application and an application group are being added, the application group will be added first and then the application, even if the application object appears first in the XML file. Performance may be improved if the objects are placed in the XML file to minimize searching for objects. The ideal order of objects in the XML file are printers, users, groups, storage sets, application groups, applications, and folders.
- User and group permissions can be added to an application group by adding a permissions child object to the application group object. User/group permissions for folders are added in a similar manner.
- When a network connection doesn't exist between two servers, OnDemand objects can be exported to an XML file and later used to add the objects to the second server by placing the XML file on an OnDemand system that has network access to the second server. Exporting OnDemand objects to an XML file is also a useful way to provide OnDemand object definitions to the OnDemand support team to help with problem determination.
- The default encoding value for the input XML file is UTF-8. While other encoding values are supported, it isn't necessary to use a different encoding value unless the contents of the file is not UTF-8. For example, if you created the input XML file using an EBCDIC editor, the encoding value in the XML file needs to be set to an EBCDIC encoding value, such as
ibm037. To create an output XML file in an encoding value other than UTF-8, specify the -w flag with the name of the encoding. For example, to create the output file in EBCDIC, you can specify -w ibm037.
- If an error occurs during the processing of one of the objects in the input XML file, the XML Batch Administration program will stop processing the remaining objects in the file. In some cases, an OnDemand object is added even if an error is encountered in one of the child objects. For example, the folder object contains one or more permission child objects. If an error occurs during the processing of one of the permission objects, the folder will still be added because it was added before the permission objects were processed. If you want to process all of the objects in the file regardless of any errors encountered, you can specify
-e c on the command line.
- When an object is exported, you can choose to export the dependent objects as well as the object. For example, if you want to export a group and all of the users in the group, you can specify
-r d on the command line, rather than having to add a user object to the XML file for every user in the group. Also, permissions are not exported by default. If you want to export permissions, such as application group and folder permissions, specify -r p on the command line. To export dependent objects and permissions, specify -r dp. Applications are not considered to be dependent objects of application groups. If you want to export applications contained in the application group as well as the application group, specify -r a.
|
Summary
The XML Batch Administration program provides another way to perform day-to-day OnDemand system administrative tasks. It has an advantage over the Administrative client in that it can process objects with different object types at the same time. It is especially useful when you need to maintain the same OnDemand objects on multiple servers or when multiple updates are needed. Also, because it is a command line program that is included as part of the OnDemand server installation, it is available on more platforms than the Administrative client, making it easy to automate system administrative tasks.
Resources Learn
-
DB2 Content Manager Portfolio: IBM content management helps integrate and deliver critical business information on demand.
-
DB2 Content Manager OnDemand provides enterprise report management and electronic statement presentment. It is high performance middleware to automatically manage formatted computer output and reports.
-
"Choosing a model for IBM OnDemand System Administration" (developerWorks, January 2002): Learn about changes in OnDemand that give greater flexibility in managing and securing large quantities of printed output, such as reports, invoices, or statements.
-
developerWorks DB2 zone: Learn more about DB2. Find technical documentation, how-to articles, education, downloads, product information, and more.
Get products and technologies
Discuss
About the author | | | Debbie Wagner is a Software Engineer for IBM DB2 Content Manager OnDemand for Multiplatforms. |
Rate this page
| |
