Wednesday, August 29, 2012

How to delete a Documentum repository

For many years the repository served us truly and faithfuly, but the time has come... and we don't need it anymore.
Yes, we will delete it! Unfortunately it's not such trivial as running a single wizzard.
Below are the steps to do a complete removal:

0. Check one more time you're deleting the right repository (and it's not live production) :)

1. Drop (uninstall) the Index Agent
1.1 Stop the Index Agent (from DA or Index Admin page)
1.2 On the Index Server host Start the Index Agent Configuration Program, select 'Delete Index Agent', then select the Index Agent (if you have more).
1.3 From Index Server Admin page (ie: http://localhost:16000/admin) delete the corresponding collection for the docbase.

2. Remove DTS / ADTS service from the repository
2.1 Start the ADTS Configuration Utility. Check that your docbroker and docbase are running before proceeding.
2.2 Choose 'Remove an instance of ADTS from a docbase', then select the repository, enter installation owner credentials and finish the procedure.

3. Stop any other applications or/and services that are using the repository

* If you don't know the content files location, check it now before removing the repository (dm_location object)

4. Remove the docbase service
4.1 Launch Documentum Server Manager, on Utilities tab click Server Configuration and following the wizzard instructions.
4.2 Choose Custom configuration, Delete an existing repository, choose the repository and complete the procedure.

5. Delete DB tablespace(s) and schema.

6. Delete docbase files from the Content Server host
6.1 Delete the content files
6.2 Delete the log files

Congratulations! You've done it! Next repository? :)

Tuesday, August 28, 2012

How to clone a Documentum repository

Why cloning a Documentum repository? Well sometimes it is required to perform some tests (new software/versions/features) on the real production data. Development environment might not be very relevant because usually it has a very reduced set of data. There might be also plenty of other reasons.
Cloning a repository means creating an identic copy of it, with no impcat on the original repository.
This activity is not trivial and requires more steps to be performed:
* Note: The supposed OS is Windows, for other OS some steps might require appropriate changes.

1. Create a new DB schema and clone the data from the schema of the repository.
2. Stop the repository service.
3. Copy the content and configuration files from the source Content Server file system. On Windows you can use the robocopy command, like this:
robocopy [SOURCE_PATH] [DESTINATION_PATH] /NP /MIR /SEC /R:10 /W:10 /LOG:[LOG_FILE] >> [OUTPUT_FILE]

 Copy the following paths:
  a) [DOCUMENTUM]\dba\config\[repository_name]
  b) [DOCUMENTUM]\dba\auth\[repository_name]
  c) Folder with content files (obtain it from the dm_location object)

4. Execute the SQL script (on the new DB schema):
-- Set the clone host name
update dm_server_config_s set r_host_name='[NEW_HOST]';
update dm_mount_point_s set host_name='[NEW_HOST]';
update dm_server_config_s set web_server_loc='[NEW_HOST]';

-- Force server to recreate views
update dm_type_s set views_valid = 0;

-- Set the clone content location
update dm_location_s set file_system_path='[CONTENT_PATH_NEW]' where file_system_path='[CONTENT_PATH_OLD]';
update dm_location_s set file_system_path='[CONTENT_PATH_NEW]\replicate_temp_store' where 
file_system_path='[CONTENT_PATH_OLD]\replicate_temp_store';
update dm_location_s set file_system_path='[CONTENT_PATH_NEW]\replica_content_storage_01' where file_system_path='[CONTENT_PATH_OLD]\replica_content_storage_01';
update dm_location_s set file_system_path='[CONTENT_PATH_NEW]\content_storage_01' where file_system_path='[CONTENT_PATH_OLD]\content_storage_01';
update dm_location_s set file_system_path='[CONTENT_PATH_NEW]\thumbnail_storage_01' where 
file_system_path=' [CONTENT_PATH_OLD]\thumbnail_storage_01';
update dm_location_s set file_system_path='[CONTENT_PATH_NEW]\streaming_storage_01' where file_system_path='[CONTENT_PATH_OLD]\streaming_storage_01';

-- Set job server execution
update dm_job_s set target_server='[DOCBASE_NAME].[DM_SERVER_CONFIG.OBJECT_NAME]@[HOST]' where target_server = '[DOCBASE_NAME_OLD].[DM_SERVER_CONFIG.OBJECT_NAME_OLD]@[HOST_OLD]'

-- Note: If the cloned repository was served by more CS instances (so more dm_server_config objects present) you must run a query like this per each server config object.
-- The value [DM_SERVER_CONFIG.OBJECT_NAME] can be obtained with this query: select object_name from dm_server_config

-- Disable the jobs (will be reactivated later)
update dm_job_s set is_inactive=1;

-- ACS config: assuming the repository is served by 2 CS
update dm_acs_config_r set acs_base_url='http://[NEW_HOST]:[[PORT]/ACS/servlet/ACS' where acs_base_url in ('http://[OLD_HOST_1]:[PORT]/ACS/servlet/ACS', http://[OLD_HOST_2]:[PORT]/ACS/servlet/ACS') ;
-- PORT: default is 9080

-- Reset the crypto key
update dm_docbase_config_s set i_crypto_key = ' ', i_ticket_crypto_key = ' ';
delete from dmi_vstamp_s where i_application = 'dm_docbase_config_crypto_key_init';
delete from dmi_vstamp_s where i_application = 'dm_docbase_config_ticket_crypto_key_init';

delete dm_sysobject_s where r_object_id = (select r_object_id from dm_public_key_certificate_s where key_type = 1);
delete dm_sysobject_r where r_object_id = (select r_object_id from dm_public_key_certificate_s where key_type = 1);
delete dm_public_key_certificate_s where key_type = 1;

delete dm_sysobject_s where r_object_id = (select r_object_id from dm_cryptographic_key_s where key_type = 1);
delete dm_sysobject_r where r_object_id = (select r_object_id from dm_cryptographic_key_s where key_type = 1);
delete dm_cryptographic_key_s where key_type = 1;

-- Old fast index configuration cleanup (if FullText is installed)
update dm_ftengine_config_r set param_value='[FULLTEXT_HOST]' where param_name='fds_config_host';
update dm_ftengine_config_r set param_value='[FULLTEXT_HOST]' where param_name='query_engine_host_name';

delete from dm_ftindex_agent_config_s;
delete from dm_sysobject_s where r_object_type=’dm_ftindex_agent_config’;

-- Old ADTS configuration cleanup (if ADTS is installed)
delete from cts_instance_info_s;
delete from cts_instance_info_r; (16 row deleted)
delete from dm_sysobject_s where r_object_type=’cts_instance_info’;

commit;

5. Content Server update

5.1 Update server.ini
Edit the server.ini file located in %DOCUMENTUM%\dba\config\[DOCBASE_NAME] and update the following fields:
database_conn [NEW_DB_INSTANCE]
[DOCBROKER_PROJECTION_TARGET]
host = [NEW_DOCBROKER]
port = 1489

5.2 Re-encrypt the Database password
cd %DM_HOME%\bin
dm_encrypt_password -docbase [NEW_DOCBASE_NAME] -rdbms -encrypt [DB PASSWORD]

5.3 Windows service.
Execute the following commands script to create the Windows Service for the repository (you can save it in a .bat file and run it):
@echo off
setlocal

set docbase=[DOCBASE_NAME]
set instowner=[INSTALLATION_OWNER]
set iodom=[DOMAIN]
set iopw=[PASSWORD]

set binPath=%DM_HOME%\product\[VERSION]\bin\documentum.exe -docbase_name %docbase% -security acl -init_file E:\Documentum\dba\config\%docbase%\server.ini -run_as_service -install_owner %instowner% -logfile E:\Documentum\dba\log\%docbase%.log

sc create DmServer%docbase% binPath= "%binPath%" start= demand DisplayName= "Documentum Docbase Service %docbase%" obj= %iodom%\%instowner% password= %iopw%

sc description DmServer%docbase% %docbase%_clone

endlocal

5.4 Add port numbers
Edit %WINDIR%\system32\drivers\etc\services and add the following entries at the end of the file:
dm_[DOCBASE_NAME] [N]/tcp #Documentum Docbase Service [DOCBASE_NAME]
dm_[DOCBASE_NAME]_si [N+1]/tcp #Documentum Docbase Service [DOCBASE_NAME] (secure service)

* where N can be the incremented last port used in the list

5.5 Windows Registry update

Export the docbase registry key from the Windows registry on the old machine, from branch:
"HKLM\SOFTWARE\Documentum\DOCBASES\[DOCBASE]"

Open the exported file and update the following keys:

"DM_DOCBASE_CONNECTION" => "[DB_INSTANCE]"
"DM_HOME" => "[PATH]\\product\\[VERSION]" (ie: C:\\Documentum\\product\\6.7)
"DOCUMENTUM" => "[DOCUMENTUM_PATH]" (ie: C:\\Documentum)
Save the file with UTF-8 encoding.

Update the registry on the target machine by importing the reg file.

5.6 Create session logs folder:
[DOCUMENTUM]\dba\log\[DOCBASE]

6. Start the repository service

7. Post-cloning activities

7.1 Reset the inline passwords
Inline passwords must be reset (usualy they are not working anymore because of encryption changes)
Use a DQL like this:
update dm_user objects set user_password=user_name where user_source='inline password' [AND user_name not in (exception_list)]

or provide an explicit list of users:
update dm_user objects set user_password=user_name where user_name in (update_list)
Usualy update_list contains users: dm_bof_registry, dm_fulltext_index_user, dmc_wdk_presets_owner and others.

7.2 Install other required products: Index Agent, ADTS instance, etc.

Tuesday, August 21, 2012

How to change object type

Documentum allows creation of custom types, which defines custom attributes in addition to the inherited ones. Once your custom type is defined and created in the repository, you can create objects - which are instances of that custom type.
If you have created objects of a certain (sub) type, you can still change their type. The easiest way is to use the following DQL:
CHANGE current_type [(ALL)] objects to new_type [update_list] [WHERE qualification]
* ALL - change type of all object versions
* update list - list of updates on objects attributes to perform during change type operation

Obviously current_type must be the supertype or subtype of the new_type. Thus, you can move the object instances through the types hierarchy up and down.
Ok, if you move from a supertype to subtype you get additional attributes that are empty. But what happens when moving from subtype to supertype? The custom attributes' values of the subtype are lost (you can use the update list if you want to copy the values to other attributes, that are not lost).

You should take note of the following constraints on this operation:
1. You can only change the type of objects that are subtypes of dm_sysobject. (If you want to change the object type of not a dm_sysobject, follow the procedure described here: URL).
2. The object's current type and the new type must have the same type identifier (which is the first two characters of the object ID. For example, dm_document has 09).
3. The old and new types can't be at the same level in the type hierarchy. The new type must be a supertype or subtype of the current type.
For example, you have a my_car and its subtypes my_toyota and my_lexus. In order to change an object of my_toyota to type my_lexus, you must do it in 2 steps:
change objects my_ford to my_car;
go;
change objects my_car to my_lexus;
go;

4. You must have DELETE permission on the objects you are changing.