Embedding an Edit Link that will Launch Web Author

You can control or streamline your documentation review workflow by configuring Edit links that are either sent to reviewers or embedded somewhere and these Edit links will automatically launch a particular document in Oxygen XML Web Author. The Edit link can be embedded in an email, web page, published output, or anywhere that you can provide a usable link. A reviewer then simply clicks the link and they will be redirected to the Oxygen XML Web Author editing page with that particular file open and editable.

URL Parameters

The Edit link can be created with a carefully built target and using URL parameters. The base URL for the link is the URL that you see in the browser when the Dashboard page is opened.

Example: The base URL for Oxygen XML Web Author demo deployment
https://www.oxygenxml.com/oxygen-xml-web-author/

The base URL is then followed by parameters that contain the information about the file to open and the options used to load it.

The allowed URL parameters are as follows:
  • url - The OXY-URL that identifies the file to be opened.
  • ditamap - (Optional parameter for DITA files) The OXY-URL of the DITA Map to use as a context for resolving keys.
  • author - The author name.
  • trackChanges - Flag that controls whether or not the editor should track changes. The possible values are:
    • default - The status of change tracking is determined by the server's global options.
    • enabled - Change tracking is enabled but the user can disable it using a toolbar action.
    • forced - Change tracking is enabled and the user cannot disable it. The user can reject their own changes, but cannot accept or reject changes made by others.
    If you use an option other than default, the server change tracking status (as configured in the Administration Page) should not be "Stored in the document". For more information about this parameter, see Control Change Tracking State
  • autoSaveInterval - The interval of time (in seconds) to wait until an auto-save is performed. If <= 0 or false, auto-save is disabled.
  • expandTopicRefs - If set to true, when a DITA map is opened in Oxygen XML Web Author, the content of all topics referenced in the map will be presented.
  • lang - You can use this parameter to impose a specific language for the Oxygen XML Web Author interface. The possible values are:
    • en_US - English
    • de_DE - German
    • fr_FR - French
    • ja_JP - Japanese
    • nl_NL - Dutch
  • ccOnEnter - If set to true, the content completion popup window is displayed when the user presses Enter. If set to false, the Enter key works similar to the behavior in normal word processors.

Example: OXY-URL for a Sample Deployment

Suppose that the Oxygen XML Web Author is deployed at the following URL:
http://www.example.com/oxygen-sdk-sample-webapp/
The user (John Doe) wants to edit a file (located at http://www.test.com/topics/topic.xml) in the context of a DITA map (located at http://www.test.com/map.xml). In this case, the editing URL should be:
http://www.example.com/oxygen-sdk-sample-webapp/app/oxygen.html
?url=http%3A%2F%2Fwww.test.com%2Ftopics%2Ftopic.xml
&ditamap=http%3A%2F%2Fwww.test.com%2Fmap.xml
&author=John%20Doe
Note: The parameter values are percent encoded before being added to the editing URL.

How to Embed the Edit Link in Published DITA Output

The standalone distributions of Oxygen come bundled with a built-in DITA-OT plugin that can be used to embed your constructed Edit links in the WebHelp and PDF output for each topic.

To embed an Edit link in DITA WebHelp output, follow this procedure:
  1. In a standalone distribution of Oxygen, edit a DITA Map WebHelp Responsive transformation scenario and open the Parameters tab.
  2. Set values for the following parameters:
    • editlink.remote.ditamap.url - The custom OXY-URL of the DITA Map suitable for opening in Oxygen XML Web Author.
    • editlink.web.author.url - The URL of the Web Author installation.
  3. Run the transformation scenario.

Result: In the WebHelp output, all topics will have an Edit link to the right side of the title and clicking the link will launch that particular document in Oxygen XML Web Author.

To embed an Edit link DITA PDF output, follow this procedure:
  1. In a standalone distribution of Oxygen, edit a DITA Map PDF transformation scenario and open the Parameters tab.
  2. Set values for the following parameters:
    • editlink.remote.ditamap.url - The custom OXY-URL of the DITA Map suitable for opening in Oxygen XML Web Author.
    • editlink.web.author.url - The URL of the Web Author installation.
  3. Run the transformation scenario.

Result: In the PDF output, all topics will have an Edit link to the right side of the title and clicking the link will launch that particular document in Oxygen XML Web Author.