History | Edit

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/webapp-demo-aws/app/oxygen.html
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 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. Possible values:
    • 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.

Example:

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.

OXY-URL

The OXY-URL uses a custom schema according to the file storage system the file comes from.
Tip: For more extensive details about the OXY-URL concept, see OXY-URL: File URLs in Oxygen XML Web Author
GitHub
The URLs have the following format:
gitgh://REPOSITORY_URI/BRANCH/PATH_TO_FILE
where:
  • gitgh = The URL scheme. Note that the GitHub plugin must be configured for this URL scheme to work.
  • REPOSITORY_URI = The URI of the GitHub repository (URI-encoded).
  • BRANCH = The name of the branch where the file is located (URI-encoded).
  • PATH_TO_FILE = The path to the file. Each entry in the path should be URI-encoded.
Example: gitgh://https%3A%2F%2Fgithub.com%2Fuser%2Frepo/master/DITA/topics/intro%20topic.dita
GitLab
The URLs have the following format:
gitgl://REPOSITORY_URI/BRANCH/PATH_TO_FILE
where:
  • gitgl = The URL scheme. Note that the GitLab plugin must be configured for this URL scheme to work.
  • REPOSITORY_URI = The URI of the GitLab repository (URI-encoded).
  • BRANCH = The name of the branch where the file is located (URI-encoded).
  • PATH_TO_FILE = The path to the file. Each entry in the path should be URI-encoded.
Example: gitgl://https%3A%2F%2Fgithub.com%2Fuser%2Frepo/master/DITA/topics/intro%20topic.dita
GitLab On-Premise
The URLs have the following format:
gitgle://REPOSITORY_URI/BRANCH/PATH_TO_FILE
where:
  • gitgle = The URL scheme. Note that the GitLab On-Premise plugin must be configured for this URL scheme to work.
  • REPOSITORY_URI = The URI of the GitLab On-Premise repository (URI-encoded).
  • BRANCH = The name of the branch where the file is located (URI-encoded).
  • PATH_TO_FILE = The path to the file. Each entry in the path should be URI-encoded.
Example: gitgle://https%3A%2F%2Fgitlab-example.com%2Fuser%2Frepo/master/DITA/topics/intro%20topic.dita
Bitbucket
The URLs have the following format:
gitbb://REPOSITORY_URI/BRANCH/PATH_TO_FILE
where:
  • gitbb = The URL scheme. Note that the Bitbucket plugin must be configured for this URL scheme to work.
  • REPOSITORY_URI = The URI of the Bitbucket repository (URI-encoded).
  • BRANCH = The name of the branch where the file is located (URI-encoded).
  • PATH_TO_FILE = The path to the file. Each entry in the path should be URI-encoded.
Example: gitbb://https%3A%2F%2Fbitbucket.com%2Fuser%2Frepo/master/DITA/topics/intro%20topic.dita
Git
The URLs have the following format:
git://REPOSITORY_URI/BRANCH/PATH_TO_FILE
where:
  • git = The URL scheme.
  • REPOSITORY_URI = The URI of the Git repository (URI-encoded).
  • BRANCH = The name of the branch where the file is located (URI-encoded).
  • PATH_TO_FILE = The path to the file. Each entry in the path should be URI-encoded.
Example: git://https%3A%2F%2Fgithub.com%2Fuser%2Frepo/master/DITA/topics/intro%20topic.dita
WebDAV
The URLs have the following format:
webdav-https://dav.box.com/dav/path/to/file.dita

where the WebDAV URL of the file is: https://dav.box.com/dav/path/to/file.dita.

SharePoint
The URL of the file is the SharePoint file URL, prefixed with spo-, as in the following example:
spo-https://mycompany.sharepoint.com/myfolder/Shared%20Documents/myfile.dita
REST
The URLs have the following format:
rest://<server-id>/path/to/file.dita
The format can be further specified by the implementer of the REST API.

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.