How do I enable Object Revision History? (4213029)

Overview

BACKGROUND

Object Revision History is an optional Casewise Suite feature available for repositories on Microsoft SQL Server which records the changes users make in your models and allows you to view the history of objects.

Once enabled, you can view all the changes made to any object in a model, allowing you to see when the revision was made, what was changed, and who changed it by.

BACK UP YOUR DATABASE

We strongly recommend that you backup your Casewise database before you proceed any further. This is always good practice when making changes on the database itself.

STEP 1 - ELEVATE YOUR DATABASE PERMISSIONS

Before you can run the ValidateRepository tool to check and update your repository, the user you use to log in to Casewise Suite must use a database connection that has database owner (dbo) privileges.

Exactly what you do to achieve this depends on how your repository is configured; whether you use SQL Server, and whether you use a standard SQL login or use Windows Authentication.

You should ask your Database Administrator to do one of the following:

• Elevate your existing database user to have dbo privileges
• Create a new login with dbo privileges for you to use temporarily to perform this operation – you will need to make a new connection in Casewise Suite to use this login.

 Your Database Administrator can, and should, remove these elevated privileges once you have successfully enabled Object Revision History.

STEP 2 - RUN VALIDATEREPOSITORY

Once your database permissions have been elevated to dbo, you can run the ValidateRepository tool to upgrade your repository.

You can only run this tool on a machine that has Casewise Suite installed.

To run ValidateRepository:

1. On your Casewise Suite machine, launch the Command Prompt
2. Change directories until your current directory is the Casewise ‘Bin’ directory

 This is usually "C:\Program Files\Casewise\CM10\BIN, or C:\Program Files (x86)\Casewise\CM10\BIN" on 64-bit machines

3. Run the following command to check your repository for illegal XML characters and fix any issues:

Do not copy and paste this command, as it will not work in the command-line tool. Do not copy and paste this command, as it will not work in the command-line tool.

Notes:

• If your repository is very large then this step may take several minutes.
• If your password is blank, you can omit the Password parameter.
• If you only have one database connection in Casewise Suite, you can omit the Connection parameter.
• If any of the parameter values have spaces in, enter the entire value in speech marks

4. When you are asked to confirm if you want to run the operation, choose (A)ll
5. When the operation has finished, run the following command to enable Object Revision History in your repository:

Do not copy and paste this command, as it will not work in the command-line tool. Do not copy and paste this command, as it will not work in the command-line tool.

Notes:

• If your password is blank, you can omit the Password parameter.
• If you only have one database connection in Casewise Suite, you can omit the Connection parameter.

STEP 3 - UPDATE DATABASE ROLE PERMISSIONS

You only need to run this step if you have upgraded your repository as part of a general upgrade to Casewise Suite 2013. If your database was created when you installed 2013, then these permissions set by this step will already exist. However, it will not harm your repository if the permissions already exist and you do run this step.

The final step is performed by the SQL Database Administrator and involves ensuring the CasewiseRW database role is given permission to use Object Revision History.

The Database Administrator will need the "GrantAccessToSchemaForCasewiseRWRole.sql" script file in order to do this. You can get this file by downloading the zipped SQL Script Files from the Casewise Suite 2013 download page on www.casewise.com. The file is in the ‘SQL Server’ directory in the zip archive.

To update the database permissions:

1. Open "GrantAccessToSchemaForCasewiseRWRole.sql"
2. Execute the script against the Casewise database

The CasewiseRW role’s permissions are updated.

The repository is now updated and Object Revision History is enabled. The Database Administrator should now remove dbo privileges from the Casewise user/login.

While Object Revision History is now enabled for the repository, this does not mean your models will automatically start recording changes made to objects. To make sure your models start recording changes, you must manually switch on Object Revision History on a model by model basis.

SWITCHING ON OBJECT REVISION HISTORY FOR MODELS

Once Object Revision History is enabled, you can choose which models you want to record object history in.

You must be logged on as a System Manager user to switch on Object Revision History for a model.

To switch on Object Revision History for a model:

1. In the Models tree in Object Explorer or Model Explorer, select the model you want to enable Object Revision History for
2. Go to "Edit > Properties" to view the model's properties
3. Select the "Enable Object Revision History" checkbox

The setting is only visible if your repository has been updated correctly

4. Click "OK"

 Object Revision History is now enabled in the model and you can view the revisions using the History tab on the object properties dialogs.

IMPORTING OLDER MODELS INTO THE UPDATED REPOSITORY

Enabling Object Revision History makes changes to the database schema which means that some older models may no longer be compatible and may not be able to be fully-imported.

This does not affect any models in the repository at the time you enable Object Revision History.

The issue is caused by the 2013 repository being more strict about the quality of data that it contains. The import process checks for illegal XML characters in properties (usually caused by copying and pasting text into Casewise Suite), and issues with how Pictures and Publication Sets are encoded. As a result, if any of this data is found, then those items will not be imported.

These instances are rare, and the likelihood is that your models will be fine.

Models that may be affected by this are:

• Models that have been exported from a previous release of Casewise Suite / Corporate Modeler Suite
• Models that have been exported from a repository that has been upgraded to 2013, but has not had Object revision History enabled.

Models that have been created in a new repository that was created when Casewise Suite 2013 was installed will be fine, as will any models from a repository that has been updated to Casewise Suite 2013 where Object Revision History has been enabled.

How will you know if models are affected?

When you import a model that is affected, the Import Wizard will report exactly which data has been rejected by the import process.

This could be that a Publication Set, Picture, an object instance, or a user-defined property of an object has not been imported.

Recommended procedures

Firstly, if you have more than one repository, such as separate Production and Live environments, ensure that both repositories are upgraded to Casewise Suite 2013 in the same way – with Object Revision History enabled.

If you have a large number of models outside your main repository that fall into the category of those that may be affected by this issue, then we recommend you do one of the following:

• Load them into the repository before you enable Object Revision History, as this fixes any potential issues without loss of data – you can then re-export them or do as you wish, safe in the knowledge that they can be imported at any time without issue.
• Create a separate repository based on your previous version of Casewise Suite, follow the instructions to upgrade this to Casewise Suite 2013, and then run steps 1 to 3 above (you only need to run steps 1 to 4 of the ValidateRepository instructions) to fix any issues. Ensure you have elevated database permissions when you do this.