How-To Guide Casewise Suite: OVERVIEW

How-To Guide
Casewise Suite: Enable Object Revision History
OVERVIEW
Description
This document explains how to enable Object Revision History.
The process of enabling Object Revision History involves three steps:
1. Your SQL Database Administrator must grant dbo privileges to the
user/login you use to access the Casewise repository.
2. You must run the ValidateRepository tool to update the repository.
3. Only if you have upgraded to Casewise Suite 2013 - Your SQL
Database Administrator must run a script file to give Casewise users
the correct permissions for Object Revision History.
Who needs to do
this?
You only need to enable Object Revision History if you want to use that
feature with models in your repository.
Enabling Object Revision History typically needs two people – a Database
Administrator who can change user permissions on the database server, and
a Casewise Suite user who will run the Validate Repository command-line
tool to make the necessary changes.
Note: You cannot enable Object Revision History if your repository is on
Oracle. Only SQL Server databases can have this feature.
Casewise Suite
versions
You can only enable Object Revision History with Casewise Suite 2013
onwards. To check which version you have, launch one of the Casewise Suite
applications and go to Help > About.
Important notes
Enabling Object Revision History changes your database schema. This means
that any models that are not in the repository at the time you enable
Object revision History may no longer be compatible with the database
anymore. This would affect models that have previously been exported and
archived as MDB or XML files, or models that are in a repository that has
been upgraded to 2013 but has not had Object Revision History enabled.
To understand the potential issues importing these models can cause – and
how to resolve them, see Importing older models into the updated repository
below, before you enable Object Revision History.
Page | 1
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:
Page | 2
validaterepository -Username:<your_Casewise_username>
-Password:<your_Casewise_password> -Connection:<your_connection_name>
-ApplyFixes
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:
validaterepository -Username:<your_Casewise_username>
-Password:<your_Casewise_password> -Connection:<your_connection_name>
-EnableAudit:True
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.
Page | 3
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.
Page | 4
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.
Page | 5