Migrating to PSML

This document is a guide on how to migrate existing documents from PS Standard XML format to PSML format.

Preparation

1. Become familiar with PSML by reading the following:

1. Universal format

2. “PSML Quick Reference” and “PS Standard versus PSML” can be downloaded from Documents.

3. PSML element reference

4. PSML Samples

5. Document types

2. Choose a project to convert to PSML. It needs to be done one project at a time.

3. Convert the existing PS Standard configuration files by clicking Convert configuration to PSML on the Dev > Document config page for the project (in developer perspective). Note: This won't convert schematron, CSS or Ant publish script files.

4. Create a test group under the project and ensure that all the document types can be created and edited:

1. Creation through the New Document page should be tested for all document types.

2. Existing PS standard documents in the project can also be exported as Universal Format and uploaded to the test group.

5. Convert the existing Schematron, CSS and Ant publish scripts to work with PSML documents and check them in the test group. See the following documentation:

1. PSML Schematron

2. PSML document styles (CSS)

3. <publishing>

4. PSML Ant scripts

6. If the PS project configuration is in a code repository like Mercurial or Git, then copy the converted configuration files to the repository. For example click Export in the Project Files page in PageSeeder and the Publish Engine, then unzip the files and copy them to Eclipse and Commit/Push to the repository.

Conversion details

PS label values

Content inside <section ... format="pslabelvalues"/> is converted to <properties-fragment>.

PS xref list

Content inside <section ... format="psxreflist"/> or containing <xref type="replace|include" /> is converted to <xref-fragment>.

Section tables

Content inside <section ...><title level="table"> is converted to <media-fragment mediatype="text/plain">.

Checkbox

For consistency, the PS standard conversion to PSML has been changed so that all values generated by the label values editor type=checkbox appear in the @value attribute and multiple values is comma-separated, for example:

<property name="language" value="English"/>
<property name="language" value="English,Spanish"/>

Previously these would have been converted as the following:

<property name="language" value="English"/>
<property name="language">
  <value>English</value>
  <value>Spanish</value>
</property

Alternatively, all content can be modified after conversion to PSML (by downloading, transforming, uploading or editing individually in dev perspective) to have multiple <value> and count="n" on the <property> element. The document-template.psml would also need to be updated.

Data type

After conversion, the @datatype attribute on <property> element is only set if the property is not empty, for example:

<property name="related" value=""/>
...
<property name="related" datatype="xref" count="n"><xref ... /></property>

If the @datatype attribute is important in the project, all content might be modified after conversion to PSML (by downloading, transforming, uploading or editing individually in dev perspective) to have the correct @datatype and @count attributes. The document-template.psml would also need to be updated.

Conversion

The following needs to be done for each group in the project:

1. Go to the Group Manage page located under the Admin tab and click Convert. Administrators can use the PSML migration page located under the Dev tab to convert whole projects at once.
2. If the number of archived documents is large, they might be cleaned up by deleting some as they can take a long time to convert. To enable the delete function, add adminEnable=delete-documents in the template.properties.
1. Alternatively, the archive folder can be moved to another group and converted at another time. For this, a backup group under the project containing a folder with the name of the group could be used.
3. Leave Validate Only ticked and click Start.
4. If there are validation warnings/errors, click Show Logs then click the View next to each document with errors and fix it as described below. It can be useful to click ‘Show Warnings and Errors only’ or to view the logs in a larger window go to the Admin > Console or Admin > Group Console and view the Process logs.
1. Warnings (in orange) can usually be ignored. Validation errors on the original PS Standard XML appear as warnings. If these can not be corrected by the conversion, they also appear as errors (in red), similar messages might appear twice.
2. The warning Conversion will change xref type to ‘none’ due to other content in body is because of a “replace/include” xref in a <body> element that also has some other content. If the xref is not required to be transcluded, for example, if only publishing to a website which doesn’t require it, then this message can be ignored. Otherwise, the other content (including  ) can be removed or the xref can be replaced with an xref type embed.
3. The warning Invalid Doc ID “[x]¨ will be removed during conversion means that the Doc ID x is not valid and is removed. If it is not to be removed, then it needs to be changed to something valid through the Properties tab.
4. If the document is no longer required, it can be deleted.
5. Fix validation errors by editing the document. It might be useful to look at the document XML by clicking <f> in the developer tools block and do a find for the start of the element (e.g. <list ).
6. If there are no xrefs to the document fix validation errors by creating a new document, copy/pasting the old content, deleting the original and then renaming the new document.
7. Fix validation errors by downloading the document, editing manually and uploading it again.
8. The error Unable to backup PS standard document:... usually means that document is missing on the file system. To fix this either delete the document or find the missing file and copy it to the server file system.
9. The error URI already exists for:... means that it is trying to convert a file [name].xml to [name].psml but [name].psml already exists. To fix this either archive, delete or rename [name].psml
10. The error PSML different to PS Standard content at text character [n] the last character of “[content]” means that during the conversion the text at the end of [content] would be changed. This is might be because of non xref content under a <section format="psxreflist">. If so it can be fixed by removing the non xref content (including  ) or removing format="psxreflist".
11. The error The value “[x]” of attribute @docid is wrong: expecting a “document-id” means there is an xref or reverse xref pointing to a document with an invalid Doc ID. This can usually be ignored as the conversion should remove the invalid Doc ID. If running the conversion a second time doesn’t fix it , click the xref or reverse xref to go to the document and then modify or delete the invalid Doc ID through the Properties tab.
12. The error Exception parsing PS standard file usually means there is an encoding problem on the file. The document needs to be deleted or if there are no xrefs to the document, fix encoding errors by creating a new document, copy/pasting the old content, deleting the original and then renaming the new document.
13. Some errors might say See document: followed by a path. If there is a View link, the original PS standard document can be viewed in PageSeeder. However, to view the actual document file it must be accessed on the server file system under the pageseeder/documents/[group]/.backup folder. If using FTP , choose the option “show hidden files” to see them (e.g. In FileZilla select Server > Force Showing Hidden Files).
5. Repeat steps 3 and 4 until there are no validation errors.
6. Untick Validate Only and click Start. This does the final conversion of all the PS standard XML documents to PSML.