mirror of
https://github.com/silverstripe/silverstripe-dms
synced 2024-10-22 14:05:56 +02:00
143 lines
5.2 KiB
Markdown
143 lines
5.2 KiB
Markdown
# Migrating to use Document Sets
|
|
|
|
> **Warning!** Please ensure you take a backup of your database before performing any of these migration task steps.
|
|
|
|
Version 2.0.0 of the DMS module introduces document sets as the containing relationship for pages and documents. In
|
|
previous versions of DMS the relationship was between pages and documents directly.
|
|
|
|
If you are migrating from an earlier version of DMS to 2.x, you will need to set up new document sets for each page
|
|
that contained documents and establish the links from the old document-page to the new document set-document, and
|
|
document set-page.
|
|
|
|
We have included a migration build task that you can use to automate this process. It can be access via
|
|
`/dev/tasks/MigrateToDocumentSetsTask`, and will prompt you for the following steps in the migration process:
|
|
|
|
* Create a default document set for all valid pages (see note)
|
|
* Re-assign documents to their original page's new document set
|
|
|
|
## Using the migration build task
|
|
|
|
### Enabling dry run mode
|
|
|
|
For either of the "actions" in this build task, you can enable dry run mode to see what the results will be without
|
|
it actually writing anything in the database. We advise you do this as a first step.
|
|
|
|
You can enable dryrun mode by adding `dryrun=1` as an argument.
|
|
|
|
Example output will contain the following when dryrun mode is enabled:
|
|
|
|
```plain
|
|
NOTE: Dryrun mode enabled. No changes will be written.
|
|
```
|
|
|
|
### 1. Create a default document set
|
|
|
|
The first step of the migration build task will find all pages that do not have documents disabled (see note) and will
|
|
create a document set called "Default" if one does not already exist. In the case where a document set already exists
|
|
for a page, it will be used as the default.
|
|
|
|
Run from command line:
|
|
|
|
```plain
|
|
sake dev/tasks/MigrateToDocumentSetsTask action=create-default-document-set
|
|
```
|
|
|
|
Run from a browser:
|
|
|
|
```plain
|
|
http://yoursite.dev/dev/tasks/MigrateToDocumentSetsTask?action=create-default-document-set
|
|
```
|
|
|
|
An example output from this task might look like this:
|
|
|
|
```plain
|
|
Running Task DMS 2.0 Migration Tool
|
|
|
|
Migrating DMS data to 2.x for document sets
|
|
|
|
Finished:
|
|
+ Default document set added: 6
|
|
+ Skipped: documents disabled: 1
|
|
```
|
|
|
|
This task will only write records for those that are needed. If you run it more than once it will simply not do
|
|
anything.
|
|
|
|
### 2. Re-assign documents
|
|
|
|
> **Note!** If you want to choose specific document sets for documents to be assigned to rather than just the first
|
|
belonging to a page, you will need to run these queries manually (see further in this document).
|
|
|
|
The second step in the migration task is to reassign the relationship from pages to documents to document set to
|
|
documents. This task assumes that the original relationship data is still present in the database, since SilverStripe
|
|
will not remove old columns from the database tables once they've been made obsolete.
|
|
|
|
Run from command line:
|
|
|
|
```plain
|
|
sake dev/tasks/MigrateToDocumentSetsTask action=reassign-documents
|
|
```
|
|
|
|
Run from a browser:
|
|
|
|
```plain
|
|
http://yoursite.dev/dev/tasks/MigrateToDocumentSetsTask?action=reassign-documents
|
|
```
|
|
|
|
An example output from this task might look like this:
|
|
|
|
```plain
|
|
Running Task DMS 2.0 Migration Tool
|
|
|
|
Migrating DMS data to 2.x for document sets
|
|
|
|
Finished:
|
|
+ Reassigned to document set: 4
|
|
```
|
|
|
|
This task will show the same output on the initial and subsequent runs. You can follow the instructions below to clean
|
|
up legacy data after you've validated that everything is working correctly if you'd like to.
|
|
|
|
## Cleanup
|
|
|
|
Since SilverStripe will not remove the old obselete relationship table from the database, you can remove it manually
|
|
if required. Only do this once you've validated that everything has been migrated correctly.
|
|
|
|
```sql
|
|
DROP TABLE `your_ss_database`.`DMSDocument_Pages`;
|
|
```
|
|
|
|
## Migrating data manually
|
|
|
|
As mentioned earlier, if you need to migrate data manually for one reason or another you can do so with a couple of
|
|
manual SQL queries to the database.
|
|
|
|
One example of why you may need to do this is if you don't want your documents to
|
|
be automatically assigned to the "default" document set on a page, but would prefer to choose a specific set to assign
|
|
to. The automated build task cannot make this decision for us, but you can run some queries yourself.
|
|
|
|
In DMS 1.x the relationship of documents to pages is stored in the `DMSDocument_Pages` table. If you run an explain
|
|
query you will see some obviously named foreign key columns for `DMSDocumentID` and `SiteTreeID`.
|
|
|
|
In DMS 2.x the relationship is of document _sets_ to documents, and is stored in `DMSDocumentSet_Documents`.
|
|
|
|
How you manipulate this data is up to you, but an example might be that you want to move a certain range of documents
|
|
by their IDs into a specific document set (by its ID), so you could run the following:
|
|
|
|
```sql
|
|
-- Insert the new records
|
|
INSERT INTO `your_ss_database`.`DMSDocumentSet_Documents`
|
|
(`DMSDocumentSetID`, `DMSDocumentID`)
|
|
SELECT
|
|
-- your document set ID
|
|
123,
|
|
`ID`
|
|
FROM `your_ss_database`.`DMSDocument` WHERE `ID` IN(1, 2, 3, 4); -- your document IDs
|
|
```
|
|
|
|
## Notes
|
|
|
|
> Create a default document set for all valid pages
|
|
|
|
"Valid pages" means that the page class does not have the `documents_enabled` configuration property set to `false`.
|