arsdoc update

From CMOD.wiki
Jump to: navigation, search

In IBM Content Manager OnDemand, the arsdoc update command is used to change index values of data that is already loaded. This may be used to update a status field used for workflow or tracking, but should not be used to update index data used to search for documents. If you have incorrect document metadata, your first and only solution should be to unload the data from CMOD, and request a new file from the line of business, department, or vendor that created it. Modifying metadata should be an absolute last resort, as making changes to metadata calls into question the reliability of your archive. It will also be said many times in this article -- a mistake in your execution of the arsdoc update command can irrecoverably corrupt the metadata for documents in CMOD. Ensure that you have fresh backups of the entire database, and the tables you're modifying.

Again, if you are a OnDemand Administrator being asked to correct index data due to a data quality issue, the solution should be to improve data quality, NOT to require IBM CMOD to change index data. The alteration of index data as a part of normal processing creates a risk that your system will not be considered a reliable archive, and in a court of law, the accuracy of the system could be called into question.

Attention.png
WARNING: It is not just possible, but extremely easy to irrecoverably damage the data in your Content Manager OnDemand server with the arsdoc update command. The examples below are meant as a guide only, and you are solely responsible for any damage to your OnDemand server. Practice makes perfect!

If you're interested in learning more about Content Manager OnDemand's arsdoc utility, consider attending the Free CMOD Webinar on arsdoc offered at CMOD.Training.

arsdoc update parameters

Here's a copy of the online help, which you can access simply by issuing the command arsdoc update with no parameters:

IBM Content Manager OnDemand arsdoc update parameters  
 $ arsdoc update
 ARS6001I Usage: arsdoc update -h hostname [-u <userid>] [-p <passwd>] [-U <user_alias>] [-v] (-F <parmfile> | ((-i <sql_query> | -l <holdname> | -q <namedquery> | -t <search_str> | -T <search_str> | -X <load_id> | -x <load_id>) [-f <foldername>] [(-g <name> | -G <name>)] -n field1=value1 [-S <startdate,enddate[,format]>])) [-1 <trace_file>] [-2 <trace_level>]
   Version:  10.5.0.0
   -f <foldername> OnDemand folder         	(required in parm file)
   -g <name> Application Group Name
   -h <hostname> OnDemand Hostname         	(command line only)
   -i <sql_query> SQL query string
   -l <holdname> OnDemand hold
   -n <field1=value1> One or more database field names and values
   -p <passwd> OnDemand User Login Password Stash File	(command line only)
   -q <namedquery> Public named query
   -t <search_string> Server text search
   -u <userid> OnDemand User Login Name    	(command line only)
   -v Verbose                              	(command line only)
   -x <load_id> LoadId to use for OnDemand
   -F <parmfile> Requests parameter file   	(command line only)
   -G <name> Application Group Name
   -S <startdate,enddate[,format]> Segment date range
   -T <search_string> Full text search
   -U <user_alias> User alias that appears in System Log messages
   -X <load_id> LoadId to use for OnDemand
   -1 <trace_file> Trace file              	(command line only)
   -2 <trace_level> Trace level            	(command line only)
 Flags in a parameter file must be delimited by brackets EX: [-f foldername]

Preparing to run arsdoc update

Before running arsdoc update, you need to complete two steps. First, identify the Folder or Application Group you will be modifying, and understand the structure -- identify the Folder field names, or Application Group field names, plus the type of data and format of dates fields, and make sure that the fields you'll be changing have the 'Updatable' flag checked in the Application Group Configuration.

Enabling Index Data Changes for Application Groups & Folders

Create the search criteria for arsdoc update

There are two ways to create the criteria that will be used to execute the change. You can perform a search of your new folder, and save the search parameters as a 'Named Query' in the Content Manager OnDemand Windows 'Thick Client', or format your search for arsdoc using the same parameters as arsdoc query.

Insert diagram here - creating a named query

Date formats when using arsdoc update

IBM Content Manager OnDemand date formats are always tricky - it's best to use the date format specified in the folder definition when creating the parameters for your arsdoc update commands. If you choose to update the Application Group, you'll need to understand the underlying date/time format in order to make a successful change.

Double checking the changes with arsdoc query

Before proceeding to the next step, double check the documents you'll be modifying by testing your search criteria with the arsdoc query command. When arsdoc query returns ONLY the documents you want to modify, should you perform the arsdoc update command.

Changing the data with arsdoc update

Attention.png
WARNING: There is no 'undo' command for arsdoc update. The changes you're requesting are usually made in a fraction of a second, and there will be no way to revert the change back to the original state. It is a wise and prudent move to create a full, offline database backup immediately before running arsdoc update, as well as exporting unmodified copies of your tables to revert changes with relative ease. Contact your local DBA for assistance in creating backups of the OnDemand management tables (starting with 'ARS'), and Application Group tables that will be modifed, so they can be restored without requiring a database outage for a full restore.

Formulating the actual arsdoc update command is tricky, and takes practice to get right. Your command should be tested on non-production OnDemand servers, and verified to be providing the correct results BEFORE executing them in a production environment.

Testing the results of the change

After the change is complete, then perform the arsdoc query command again, to ensure the changes have been made according to your wishes. Also, using the CMOD Thick Client, search for other documents to ensure that you change only affected the documents you intended to change.