IBM Enterprise Records, Version 5.1.+            

Declaring a record

The RM Java™ API provides a framework for declaring one or more documents or multiple versions of a document as a single record. A document stored in any RM-enabled repository can be declared as a record.

To declare a record and file it into a container, call the declare or the declareAllVersions method on an RMRecordContainer object. The methods have two signatures:
  • One method signature takes a document URL as a parameter; the URL uniquely identifies the document in the repository. See Declare using Document URL for more information.
  • The other method signature takes the document repository and an array of document IDs as parameters. See Declare using Document Store for more information.
Attention: You can use either method signatures, regardless of whether the ROS is combined in the same object store as the FPOS or exists in a separate object store.
To successfully declare a document as a record, the document's class must be enabled for declaring records and the document must not already be declared as a record.
  • A document class is enabled for declaring records when the value of its CanDeclare property is set to true. This property specifies whether instances of the class can be declared as records, and by default its value is set to false . Since this is a read-only property, you cannot set its value for a specific instance of the class. For instructions on how to modify the value of CanDeclare property using Enterprise Manager, see "Configure Document classes in the ROS" in the IBM Enterprise Records Installation and Upgrade Guide.
  • A document has not yet been declared as a record if its RecordInformation property does not have a value. The RecordInformation property is an object-valued property that specifies the RecordInfo object with which the Document object is associated. If this property has a value, then the document has already been declared as a record and cannot be declared again.

To verify that a document can be declared as a record, call the canDeclare method of an RMRecordContainer object.

Attention: When a document is declared as a record and that record has been filed in more than one folder (each with its own security setting), the record inherits the security of the first folder only.

Declare using Document URL

The Document URL uniquely identifies a document in a Record Object Store (ROS). It is a combination of the Document ID and the Registration ID of the document that is to be declared as a record. The Document ID is a unique identifier of the document, and is assigned by the custom application. The Registration ID uniquely identifies the connector registration, which identifies the ROS where the document exists. A Document URL is an XML representation of the Document ID and Registration ID. Below is a sample Document URL in XML format:
<RMCONNECTOR_URL>
   <REGISTRATION_ID> {DC783BDE-E175-4763-8902-356A1D4770B9} </REGISTRATION_ID>
   <DOCUMENT_ID> {C4A973F9-4F6B-4FCB-BE59-B1697497EC9C} </DOCUMENT_ID>
</RMCONNECTOR_URL>
To obtain the Registration ID of the connector registration, call the getRegistrationID method on an RMUtil object, passing in the FPOS object, the Content Engine (CE) server name, the repository name which is a combination of CE domain name and ROS name, the repository type, and a boolean value for abCreate , as shown below:
//returns the registration information;
String getRegistrationID(RMObjectStore aoStore, ObjectStore aoROSObjectStore, String asServerName,
   String asCEDomain, boolean abCreate)
{
   try
   {
      //If declare a record in CE
          String lsRepositoryType="CE";
          
          // If declare a record in CE
          String IsRepositoryName=asCEDomain + "." + aoROSObjectStore.getName();
          String IsRepositoryId=new RMUtil ().getRegistrationID(aoStore, IsRepositoryType, 
             asServerName, IsRepositoryName, abCreate);
   } 

   catch(RMException aoRME)
   {
   }
}
Note: If abCreate is false, the getRegistrationID method searches for an existing ConnectorRegistration object for the given parameters. If it does not find an existing ConnectorRegistration object, it returns a null value. However, if abCreate is true, the method creates and returns a new connector object if it does not find the appropriate connector object.
The declare method that takes the Document URL as a parameter has the following method signature:
public RecordInfo declare(String asURL, String[] asVersion, RMFolder[] aoFolder, 
   Properties aoRecordProps, String asRecordInfoClassID, Permissions aoRecordACLs, 
   boolean abAutoname) throws RMException;

In the method signature mentioned above, the Autoname parameter is a boolean indicator that specifies whether the name of the record should be automatically generated or not. If the value is false, the name of the record is taken from the Document Title metadata of the document that is declared as record. If the value is true, the system ignores the Document Title and generates the name of the record, using the registered AutoName implementation. For more information about automatic generation of record names, refer to Defining auto-naming conventions  .

The asRecordInfoClassID parameter specifies the ID of one of the following subclasses: Electronic Record, Marker, or Email Record. This parameter determines the type of RecordInfo object that will be created. To get the class ID of an RM type, use getClassIDs method in RMUtil class. For code example, see Creating a record folder.

The aoRecordProps represents the metadata or properties associated with a record. The required properties associated with the record differ for electronic, email, and marker records. For the same type of records, the required properties differ for different IBM® Enterprise Records installations (BASE, DoD, PRO). See Properties for more information on how to retrieve the property descriptions for required properties, or how to examine which properties are required for an object using Enterprise Manager.

Each time a document in ROS is declared as a record, a RecordInfo object is created in the FPOS and it points to the document object in ROS that is declared as record. As a result, even if the RecordInfo object is moved, exported, or relocated to another repository, the association between the document and RecordInfo object remains unchanged. After a document is declared as a record , an end user can only view the document, but cannot make any changes to that version of the document.

Declare using Document Store

The other method signature of the declare method takes the document store where the document is stored as a parameter. As a result, you are not required to create a Registration ID when declaring records.

This form of the declare method has the following method signature:
public RecordInfo declare(DocumentStore aoDocumentStore , String[] asDocumentsID, 
   RMFolder[] aoFolder, Properties aoRecordProps, String asRecordInfoClassID, 
   Permissions aoRecordACLs, boolean abAutoname) throws RMException;
To obtain the DocumentStore object, call the getDocumentStore method on an RMUtil object, passing in an ObjectStore object(ROS object) as the parameter as shown in the following code snippet:
//returns a DocumentStore object for the ObjectStore.
DocumentStore loDStore = loUtil.getDocumentStore(loObjectStore);
Attention: The object passed to the getDocumentStore method represents the repository where the document resides, such as ROS. All other parameters passed in to this method are the same as the parameters passed into the form of the declare method that takes the Document URL as a parameter.


Feedback

Last updated: August 2011


© Copyright IBM Corporation 2011.
This information center is powered by Eclipse technology. (http://www.eclipse.org)