Alternatives for implementing a topic review workflow

[grey]

As part of a collaborative project, a couple of users migrated documentation (about 1,000 Word pages) to DITA using oXygen Author and storing the files on a subversion repository. Now other users would continue to author further documentation, which would be reviewed by others, and then translated into multiple languages.

I would appreciate feedback about the potential alternatives to implement a multiuser authoring review workflow with oXygen (for example to transition from Draft to Reviewed to Published). I understand that we should consider using a DITA-enabled CMS to avoid reinventing the wheel. However, many CMSs have either proprietary or database driven storage, and we would like to keep the files on subversion (from where a Maven mojo might publish in batch using the OT, or distribute references to topics that would need revisions, for example).

We would then need to store the editorial revision state of the topic somewhere. We have considered three alternatives:
1. Store the status on either the DITA status attribute or on the Otherprops attribute.
2. Store the status on Subversion properties attached to the file/working copy
3. Storing the status on an issue manager/tracker using the file name as the linkage key

We should be able to leverage the Author API to read the status of the topic, infer and offer appropriate actions to the user, and finally persisting the new status to storage.

After some experimentation with the API it seems feasible (please tell me if I am missing something) to store the status on the topic attributes (option 1), but it would be difficult to prevent the user from changing or deleting the status on the source.

Storing the status on Subversion file properties is attractive, but I don't think we can set them from the Author API (I mean, referencing the working copy being edited).

Linking to a issue repository like Bugzilla seems doable, although there are some challenges to keep content and status synchronized.

Reading at previous posts, it seems that another alternative would be to use the Eclipse plugin version and handle the custom workflow handling status on a plugin outside of Oxygen.

I would very much appreciate guidance, comments or any suggestion. I assume this is an usual scenario, and perhaps oXygen has features facilitating workflow handling that I am missing.

Thanks in advance for your kindness,

Guillermo

[Radu]

Dear Guillermo,

See some answers below:

We should be able to leverage the Author API to read the status of the topic, infer and offer appropriate actions to the user, and finally persisting the new status to storage.

After some experimentation with the API it seems feasible (please tell me if I am missing something) to store the status on the topic attributes (option 1), but it would be difficult to prevent the user from changing or deleting the status on the source.

Yes, you can persist the state either as an attribute on the root element or as a processing instruction before the root element. You can also forbid the user to modify the state attribute (or processing instruction) when editing in the Author page but of course if the user passes to the Text page or uses an external application he can modify the state directly in the XML source. If you are interested in this please let us know and we'll try to give you more details about forbidding the user to edit certain places in the document in the Author page.

Storing the status on Subversion file properties is attractive, but I don't think we can set them from the Author API (I mean, referencing the working copy being edited).

You can find out from the Author API the current edited file's location. You do not have API to set the SVN property for the resource but Oxygen uses SVNKit as a subversion library and it seems possible to invoke from the Author action directly the SVN Kit code to set a custom property on the file. But of course the file needs to be commited in order for the property to be set on the server.

Linking to a issue repository like Bugzilla seems doable, although there are some challenges to keep content and status synchronized.

I guess you could implement an operation which would contact by some protocol (http for example) a server and instruct it that the current resource should have a certain state (or query the state for the current resource).

Or have in the same project a properties file containing mappings between all XML files and their current states and then modify or query that file from the Author operations. Then of course the mappings file needs to be committed to the server by the user after the state for a file is modified.

So if you have one preferred approach you can contact us at support@oxygenxml.com and we'll try to provide some code samples if you give us more details about the actions which would be available to the editors.

Regards,
Radu

[VickieSonnier]

Can you make it so that the user is not allowed to edit the state attribute when they're on their author or user page?

[Radu]

Hi Vickie,

I do not know exactly what you mean by "user page". Are you referring to the Text page?
In the Author page this is possible by using the Author SDK to customize your particular framework:
http://www.oxygenxml.com/developer.html ... horing_SDK

You can set an AuthorDocumentFilter to the AuthorDocumentController and intercept and possibly reject the editing of certain attributes.

This possibility does not exist in the Text page.

Regards,
Radu