QR code for this page

Powered by Titania Delivery

View as Table of Contents

Oxygen XML Web Author 18.1.0

User Guide

Chapter 1: Introduction

Welcome to the User Manual of Oxygen XML Web Author 18.1.0.

Oxygen XML Web Author is a web-based editing platform that utilizes the advanced authoring technology of Oxygen XML Editor to bring XML editing and reviewing to your mobile devices, as well as your desktop systems. You can collaborate with other members of your team to contribute and modify content from anywhere on desktops and mobile devices. It has an innovative mobile-first design that allows you to interact with XML content in the most efficient and productive way possible. It is an independent product, designed to complement the Oxygen XML Web Author suite.

Chapter 2: Using Oxygen XML Web Author

Describes how to use Oxygen XML Web Author

Oxygen XML Web Author web editing platform leverages the advanced authoring technology of Oxygen XML Editor to bring XML editing and reviewing to your mobile devices, as well as your desktop systems. The innovative mobile-first design of the user interface allows you to interact with your XML content like never before.

Oxygen XML Web Author is an independent product, designed to complement the Oxygen XML Editor suite. You can try it on a trial basis by following the procedure in the Installation topic and choosing the Trial type of license configuration.

2.2.1: Web Author Interface

The interface of the Oxygen XML Web Author groups the available actions in the following functional areas:

Upper Toolbar
The upper toolbar includes the following:
  • Icon - Clicking the Oxygen XML Web Author icon at the top-left corner of the screen will open the Dashboard page.
  • Undo - Reverses previous editing actions.
  • Redo - Recreates previous editing actions that were undone.
  • Save - Saves changes in the current file. This action is replaced by Download if you do not have write access to the repository.
  • Search - Opens the Search side panel that allows you to search the current file and replace the search terms.
  • Show Validation Results - Displays a detailed list of validation errors.
  • Repository actions - If you have a Git or SharePoint repository configuration, the toolbar will include actions for committing or checking in/out files.
  • More drop-down menu - Includes the following additional actions:
    • Save as - Opens a dialog box that allows you to choose where to save the current file.
    • Download - Downloads the current file in your current web browser.
    • Print - Opens a print preview pane that allows you to configure printing options for the current document.

      Note

      Review information (such as tracked changes and comments) is also included in the printed output.
    • Edit as XML - Opens the current document in a text editing mode where you can see and edit the XML source code.
    • Preferences - Opens a dialog box that allows you to configure the following options:
      • Tags Display Mode - Includes dedicated tag modes that allow you to control the amount of markup that is displayed. You can choose from the following tag modes: Full Tags with Attributes, Full Tags, Block Tags, Inline Tags, Partial Tags, or No Tags.
      • Enable automatic spell checking - Allows you to enable or disable the automatic spell checking feature.

      Note

      Changes to these preferences apply to the current document, as well as the future ones that are opened in the current browser, but they do not affect other documents that are already opened.
    • Help - Opens a WebHelp version of the Oxygen XML Web Author user manual.
    • Report Problem - You can use this option to open a dialog box that allows you to write the description of a problem that was encountered while using the application. You can also select additional information to be sent to the technical support team in the various tabs.
  • File Name - Displays the name of the current file.

    Note

    Some documents might be locked for editing. This means that you cannot alter their content or add comments to them. A document lock state is indicated by a padlock icon next to the file name.
  • User Name - Displays the current user name. This name comes from the account that is created for your particular type of file repository (such as Dropbox, Google Drive, SharePoint, GitHub, or WebDAV).
  • Toggle Side Panel - Toggles the display of the side panel that allows access to Review, Attributes, and Search views.

Some additional toolbar buttons will be present for certain types of repository connections (for example, SharePoint includes some additional check in/out actions).

On mobile devices, the upper toolbar also allows you to switch between the Edit and Review modes ().

Lower Toolbar
The lower toolbar includes the following groups of actions:
  • Review Actions - Includes actions such as Track Changes, Add Comment, and more.
  • Framework-Specific Actions - Includes actions that are specific for each document type. For example, for DITA documents, the DITA toolbar presents actions that are specific to the DITA framework.
Right Side Panel
The side panel on the right side of the application includes tabs to switch between the Review, Attributes, and Search views. If it is not displayed, use the Toggle Side Panel action on the upper toolbar.

Desktop Version of the Oxygen XML Web Author

Related information:

Editing Actions
Editing Documents
Accessing a File Repository

2.2.2: Creating or Opening Documents

The Oxygen XML Web Author has a user-friendly Dashboard and if a particular plugin registers a create or open action, then it will include sections for creating and opening documents for plugin integrations. You can easily access the Dashboard at any time while editing documents by simply clicking the Oxygen XML Web Author icon at the top-left corner of the screen.

Oxygen XML Web Author Dashboard

Create a New Document

To create a new document, follow these steps:

  1. Go to your Oxygen XML Web Author Dashboard page.
  2. In the New section, click the icon for the particular plugin. This opens a dialog box that allows you to select a new file template.

    Note

    If your connection has not yet been configured, a configuration dialog box will be displayed that provides instructions for configuring and selecting the URL for the connection.
  3. Select a file template and click OK. This opens a dialog box that allows you browse for a destination path.
  4. If you are logged in and have previously chosen a repository, you can use the Edit button to change the repository.
  5. Select a destination path and name for the new document.
  6. Click Save.

The new document will be opened in a new tab.

Open a Document

To open a document, follow these steps:

  1. Go to your Oxygen XML Web Author Dashboard page.
  2. In the Open section, click the icon for the particular plugin. This opens a dialog box that allows you to browse for a file.

    Note

    If your connection has not yet been configured, a configuration dialog box will be displayed that provides instructions for configuring and selecting the URL for the connection.
  3. If you are logged in and have previously chosen a repository, you can use the Edit button to change the repository.

    Tip

    If the file is not already in your repository, you can use the Upload File action at the top-right corner of the dialog box to upload it to the repository before selecting it.
  4. Once you have found the file you want to open, select it and click OK.

The selected document will be opened in a new tab.

Note

If you try to open a file whose format is not supported, a page will be displayed that explains that the document could not be loaded. This page includes a Download file button that allows you to download the file so you can view or edit it in a local system application.

Unlocking a File Stored on a WebDAV Connection

When opening files on a WebDAV server, by default the files are automatically locked to prevent anyone using another connection to that WebDAV server from changing the file. There is an option that can be disabled by a system administrator to change this behavior.

To unlock WebDAV files, a system administrator can follow these steps:

  1. Go to the Administration Page.
  2. Select Plugins.
  3. Click the Configure icon for the WebDAV plugin.
  4. Disable the Lock resources on open option.

2.2.2.1: Predefined Document Types (Frameworks)

Oxygen XML Web Author comes with built-in support for some of the most common XML document types (frameworks). A sample document from each document type is displayed in the Samples section on your Oxygen XML Web Author Dashboard page. The following predefined document types (frameworks) are included in Oxygen XML Web Author:

Related information:

Adding or Removing a Framework

2.2.3: Editing Documents

Oxygen XML Web Author provides an intuitive interface for editing various types of XML documents and includes a variety of powerful features and editing actions to help make your tasks as simple and efficient as possible.

The visual editing mode in Oxygen XML Web Author includes a toolbar with actions that are specific to the type of document you are editing, an editing pane where you add and edit the content, and a menu panel on the right side with some helper views.

Main Editing Area

The main editing pane includes a breadcrumb stripe at the top of the pane that shows the hierarchical XML structure of the current document, from document root to the current element. It is a useful tool that helps you to quickly navigate to specific elements in the document structure and allows you to visualize the XML element structure. The last element listed in the breadcrumb is the element at the current cursor position. The last element also has a thin blue bar above it for easier identification. Clicking an element from the breadcrumb selects the entire element in the editor area. The breadcrumb also includes a contextual menu with some common editing actions (such as Cut, Copy, Paste, and Rename Element).

The main editing pane allows you to create, review, and edit structured content in a visual editor that is similar to common word processors. It includes a large variety of user-friendly authoring features to help even novice users work with XML content, including numerous toolbar, contextual menu, and shortcut actions, a powerful Content Completion Assistant , Smart Paste support, and validation features.

Web Author Main Editing Area

Right-Side Menu Panel

Oxygen XML Web Author also has a panel on the right side of the screen that includes useful views and a variety of editing actions. If this panel is not displayed, use the Toggle Side Panel button from the upper right-side corner (or swipe from right to left on mobile devices).

Web Author Right-Side Menu Panel
The following views can be accessed from the panel on the right side of the editor:
  • Review - Displays the tracked changes and comments that have been added to the document by you or other content authors. Each change or comment includes actions such as Reply, Mark as Done, Accept or Reject changes, and Change or Remove comments. See the How to Perform Common Review Tasks topic for more information.
  • Attributes - Displays the attributes of the selected element and their values.
  • Search - Provides Search and Replace actions for searching the current document.

2.2.3.1: Editing Actions

Oxygen XML Web Author allows you to not only review documents, but to also make changes to them. On mobile devices, to activate the editing mode, tap or click the Edit button in the upper toolbar (or swipe left). A variety of editing actions are available on the toolbar, and on the desktop version, from the contextual menu.

Review Actions Toolbar

The Review toolbar contains actions to assist you with review tasks. On the desktop version, some of these actions are also available in the contextual menu. These actions include:

Toggle Change Tracking
Toggles change tracking mode on or off.
Accept Change
Available on changes when Change Tracking is enabled. It accepts the tracked change located at the cursor position. For an insert change, it means keeping the inserted text and for a delete change, it means removing the content from the document.
Reject Change
Available on changes when Change Tracking is enabled. Rejects the tracked change located at the cursor position. For an insert change, it means removing the inserted text and for a delete change, it means preserving the original content from the document.
Add comment
Allows you to insert a comment on a selected fragment of text. After you add a comment, the content where the comment was added is highlighted in the document and you can see the comment by hovering over the highlighted content or in the Review view.
Edit Comment
Opens the Edit Comment dialog box that allows you to edit the selected comment.
Remove Comment
Removes a selected comment.
Previous Marker
Navigates to the previous change or comment.
Next Marker
Navigates to the next change or comment.
Track Changes Visualization Modes Drop-Down Menu
This drop-down menu includes specialized actions that allow you to switch between the following visualization modes:
  • View All Changes/Comments - This mode is active by default. When you use this mode, all tracked changes are represented.
  • View Final - This mode offers a preview of the document as if all tracked changes (both inserted and deleted) were accepted.
  • View Original - This mode offers a preview of the document as if all tracked changes (both inserted and deleted) were rejected. If you attempt to edit the document in this mode, the view mode will switch to View All Changes/Comments.

Framework-Specific Toolbar Actions

Depending on the type of document you are editing, the toolbar and contextual menu contains a series of actions defined at framework level. On the desktop version, many of these actions are also available in the contextual menu. Oxygen XML Web Author includes built-in actions for DITA, DITA Map, DocBook, TEI, and XHTML document types. These actions include:

Styling actions
Most common styling actions, such as Bold, Italic, Underline.
Insert actions
Actions that allows you to insert a variety of framework-specific objects, such as images, equations, tables, paragraphs, links (for example, cross references, file references, or web links in DITA), topic references (DITA map), reusable content references (DITA), relationship tables (DITA map), and others.
List actions
Actions that allow you to create ordered and unordered lists, and add new items in them.
Table actions
Actions that allow you to create a table and manage its structure (insert and delete rows and columns).
Insert Special Character
Opens a dialog box that allows you to select from a large variety of special characters to insert at the current cursor position. The various types of characters include symbols, emoticons, punctuation, and many more.
Choose DITA Map
For DITA documents, the toolbar includes a Choose DITA Map button that opens a dialog box where you can enter a URL for the DITA Map that you want to be associated with the current document.

Contextual Menu Actions (Desktop Version)

In a desktop web browser, the contextual menu also offers numerous editing actions, along with framework-specific actions. They include the following:

Copy ( Ctrl + C (Command + C on OS X) )
Copies the selected content to the clipboard. You can then use the Ctrl + V (Command + V on OS X) keyboard shortcut to paste the content (or use the Paste Special action from the contextual menu).
Paste Special
Opens a dialog box that allows you to choose how to paste copied content. You have to use the Ctrl + V (Command + V on OS X) keyboard shortcut (or select Paste from the contextual menu) to paste the copied content into the preview window in this Paste Special dialog box and then you can choose to paste it into your document with one of the following choices:
  • Smart Paste - Oxygen XML Web Author will paste the copied content while trying to preserve its structure and if the current location is invalid, Oxygen XML Web Author will attempt to find a possible solution.
  • Paste as Text - The copied content will be pasted as text content.
  • Paste as XML - Copied content that is considered to be valid XML will be pasted with its XML structure preserved.
Cut ( Ctrl + X (Command + X on OS X) )
Removes the selected content and copies it to the clipboard. You can then use the Ctrl + V (Command + V on OS X) keyboard shortcut to paste the content (or use the Paste Special action from the contextual menu).
Undo
This action is available after you make a change.
Redo
This action is available when you use the Undo action.
Insert Element
Inserts an element at current position.
Rename Element
Renames the current element.
Surround With
Allows you to choose a tag to enclose the selected content.
Accept Change
Available on changes when Change Tracking is enabled. It accepts the tracked change located at the cursor position. For an insert change, it means keeping the inserted text and for a delete change, it means removing the content from the document.
Reject Change
Available on changes when Change Tracking is enabled. Rejects the tracked change located at the cursor position. For an insert change, it means removing the inserted text and for a delete change, it means preserving the original content from the document.
Remove Comment
Removes a selected comment.
Reply
Opens a dialog box that allows you to add a reply to a comment or tracked change. After a reply is added, it is displayed with an indentation in the tooltip when hovering over the comment or change, and in the Review view.
Edit Comment
Opens the Edit Comment dialog box that allows you to edit the selected comment.
Add comment
Allows you to insert a comment on a selected fragment of text. After you add a comment, the content where the comment was added is highlighted in the document and you can see the comment by hovering over the highlighted content or in the Review view.
Spelling Errors
For spelling errors, the contextual menu includes a list of suggestions that you can select from to replace the word and an Ignore All option that instructs Oxygen XML Web Author to ignore all occurrences of the reported spelling error in the current document.

Framework-Specific Contextual Menu Actions (Desktop Version)

In a desktop web browser, the contextual menu also offers some editing actions that are specific to the type of document you are working with. Many of these actions are the same actions that are found on the Framework-Specific Toolbar . However, some of the frameworks include additional actions. They include the following:

Generate IDs (DITA, DocBook, TEI)

Oxygen XML Web Author generates unique IDs for the current element (or elements), depending on how the action is invoked:

  • When invoked on a single selection, an ID is generated for the selected element at the cursor position.
  • When invoked on a block of selected content, IDs are generated for all top-level elements and elements from the list in the ID Options dialog box that are found in the current selection.

Note

The Generate IDs action does not overwrite existing ID values. It only affects elements that do not already have an id attribute.

About Element ⇒ Browse DITA Style Guide (DITA only)
Opens the DITA Style Guide Best Practices for Authors in a preview window and displays a topic that is relevant to the element at the cursor position. You can use the Open in new tab button at the bottom of the preview window to open the guide in a separate browser tab.

2.2.3.1.1: How to Perform Common Editing Tasks

This section describes how to perform some of the most common editing operations in Oxygen XML Web Author.

Input Text

  1. Tap or click to move the cursor into the selected document area.
  2. Type the text using the keyboard or screen.

Split a Paragraph

  1. Tap or click to move the cursor at the split position.
  2. Tap or press Enter to open the Content Completion Assistant.
  3. Choose Split p from the list of proposals.

Enter a New XML Element

  1. Tap or click to move the cursor into the document area where you want to enter the new element.
  2. Tap or press Enter to open the Content Completion Assistant.
  3. Select the element name.

Surround a Selection with an XML Element

  1. Tap or click to move the cursor into the selected document area and make a text selection.
  2. Tap or press Enter to open the Content Completion Assistant.
  3. Select the element name that you want the selection to be surrounded with.

Insert an Image

  1. Tap or click the Insert Image action on the toolbar.
  2. Select the image from the file browsing dialog box that appears.

    Tip

    If the image does not already exist in file structure of your repository, you can use the Upload File action at the top-right corner of the dialog box to upload it to the repository before selecting it.

You can also copy an image file from another document, web page, or application (such as a system file browser) and paste it into your document. Oxygen XML Web Author will insert it as a reference to the image file.

Set an Attribute Value
  1. Select the Attributes tab from the panel on the right side of the screen. If it is not displayed, tap or click the Toggle Side Panel button from the upper right-side corner (or swipe from right to left on mobile devices).

    Web Author Attribute Panel

  2. If the attribute is present in the attributes table (it already has a value), you can change its value by tapping or clicking its value. On a desktop system, you can also use Tab or Shift+Tab to cycle through the available attributes and the Enter key to select and modify attribute values.
  3. If the attribute is not present, use the Add Attribute button and tap or click the attribute to set its value. On a desktop system, you can also press Alt + Enter when the cursor is in the document and the focus will change to the Attributes tab with the Add Attribute form control automatically opened.
Remove an Attribute
  1. Select the Attributes tab from the panel on the right side of the screen.. If it is not displayed, tap or click the Toggle Side Panel button from the upper right-side corner (or swipe from right to left on mobile devices).
  2. Find the attribute in the table and tap or click its value.
  3. Use the Delete button (or use the Delete key) to remove the attribute.
Save a Modified XML Document

To save your changes, tap or click the Save button from the upper toolbar. Note that the save operation depends on the integration of the Oxygen XML Web Author with a CMS or other storage mechanism.

Search and Replace Content

  1. Tap or click the Search button from the upper toolbar, or the Search tab on the right side of the screen (if it is not displayed, tap or click the Toggle Side Panel button from the upper right-side corner, or swipe from right to left on mobile devices).
  2. The Search side panel is opened.

    Web Author Search Panel

  3. Type the text you want to find in the Search for input box and tap or click the Search icon in the left side of that same input box.
  4. All matches are highlighted, and the first one is selected. To advance to the next match, tap or click the Search icon again.
  5. To replace content, type the new text in the Replace with input box. To replace the current match, use the Replace button. To replace all matches, use the Replace all button.

Editing MathML Equations

  1. Tap or click the equation to open an editing dialog box.
  2. Edit the XML source of the equation.
  3. Tap or click OK to finish the editing process.

Promote/Demote List Item Nodes

In the desktop version of Oxygen XML Web Author, you can easily promote or demote selected list item nodes within ordered lists or unordered lists by using the following keyboard shortcuts:

Promote (Shift + Tab )
Promotes an entirely selected list item node to be a sibling of its parent node (the list item is moved to the left). It also works for selections of multiple list item nodes as long as all the selected nodes are siblings (on the same hierarchical level).
Demote (Tab )
Demotes an entirely selected list item node (the list item is moved to the right). It also works for selections of multiple list item nodes as long as all the selected nodes are siblings (on the same hierarchical level).

Change DITA Map (For DITA Documents)

To change the DITA Map that is associated with the current document, follow these steps:

  1. With the document opened in Oxygen XML Web Author, select the Choose DITA Map button on the DITA toolbar.
  2. Choose the URL of the DITA Map that you want to be associated with the current document.
  3. To see which DITA Map is currently associated with a document, select the Show Validation Results from the upper toolbar.

Related information:

How to Perform Common Review Tasks

2.2.3.1.2: How to Perform Common Review Tasks

This section describes how to work with the Review panel in Oxygen XML Web Author and how to perform some of the most common review tasks. To open the Review panel, tap or click the Review tab from the panel on the right side of the screen. If it is not displayed, tap or click the Toggle Side Panel button from the upper right-side corner (or swipe from right to left on mobile devices).

Web Author Review Panel

Use the Review Panel to View Comments or Tracked Changes
  1. Tap or click the Review Panel tab on the right side of the screen. If it is not displayed, tap or click the Toggle Side Panel button from the upper right side corner (or swipe from right to left on mobile devices).
  2. Tap or click one of the comments or tracked changes to see it highlighted in the document area.
  3. Hover over or select a comment/change to display actions that are available for that particular item.
Filter Comments and Changes

To filter the comments and changes (for example, to only show items for a particular author or to only show a certain type of review items), type filter queries in the text filter at the top of the panel.

Filter syntax
Filter Description Possible values Example
author Filters by the author name Any author name author:Jane / @Jane
type Filters only the items of the given type comment, change, highlight type:comment some comment
before Filters items before the given date yyyy/mm/dd before:2016/04/22
after Filters items after the given date after:2015/03/15

Example usage: @Jim type:comment before:2016/04/22 example words

Activate Change Tracking
  1. Tap or click the Toggle Change Tracking button from the Review toolbar to enable or disable this feature.

    Note

    If you have access to the Administration Page, you can change the initial state of the Change Tracking feature when you open a document. For example, you can choose to have it Always On.
Accept or Reject Tracked Changes

  1. To accept a change, tap or click the Accept Change button from Review toolbar (on the desktop version you can also select this action from the contextual menu), or select the change in the Review panel and select Accept from the More menu.
  2. To reject a change, tap or click the Reject Change button from Review toolbar (on the desktop version you can also select this action from the contextual menu), or select the change in the Review panel and select Reject from the More menu.

Add a Comment
  1. Make a selection in the document content.
  2. Tap or click the Add comment button from Review toolbar (on the desktop version you can also select this action from the contextual menu).
  3. Input a comment in the displayed dialog box. Tap or click Comment to commit it into the document.
  4. The commented text is highlighted.
Edit or Remove an Existing Comment

  1. You can only edit comments that you added to the document. To do so, select the comment in the main editing area and tap or click the Edit Comment button from Review toolbar (on the desktop version you can also select this action from the contextual menu), or select the comment in the Review panel and select Edit from the More menu.
  2. You can remove any comment, regardless of who added to the document. To do so, select the comment in the main editing area and tap or click the Remove Comment button from Review toolbar (on the desktop version you can also select this action from the contextual menu), or select the change in the Review panel and select Remove from the More menu.

Reply to Comments or Changes

  1. Select the comment or change in the Review panel and select Reply (on the desktop version you can also select this action from the contextual menu). A dialog box will be displayed that allows you to add your reply.
  2. Select OK to add your reply to the comment thread. The replies are displayed with an indentation in the Review panel.

Mark Changes or Comments as Done

  1. Select the change or comment in the Review panel and select Mark as Done. This toggles the check box and marks the change or comment as being done by graying it out in the Review panel. You can mark a whole comment thread as being done by selecting the action on the first (parent) comment or change in the thread.

Navigate Through the Comments or Tracked Changes
  1. Use the left and right arrow buttons () from the Review toolbar to navigate between comments or tracked changes.
  2. The current comment or tracked change is highlighted in the document. Also, it is displayed in the right-side Review panel.

Related information:

How to Perform Common Editing Tasks

2.2.3.2: Content Completion Assistant

Oxygen XML Web Author includes a useful feature called the Content Completion Assistant to help you insert valid XML content. It offers a list of elements, attributes, attribute values, and other options that are valid at the current location. It tries to determine the most logical choice in the current editing context and displays that proposal at the beginning of the list.

Content Completion Assistant in Web Author

It also shows elements that are invalid at the current location, but they are rendered in a lighter shade of gray, italicized, and appear after the valid proposals. You can use the search field at the top of the Content Completion Assistant to quickly navigate to the desired element and it dynamically displays proposals that begin with the characters entered in the search field.

Content Completion Assistant - Search Field

Using the Content Completion Assistant

To activate the feature, tap or press Enter .

On mobile devices, you can swipe up or down to scroll through the list and a proposal can be selected by simply tapping it.

On desktop devices, you can navigate through the list of proposals by using the Up and Down arrow keys and to insert the selection, simply press Enter .

Examples of How the Content Completion Assistant Works

To illustrate how the feature works, consider the following examples for certain contexts:

  • If the cursor is positioned at the beginning or at the end of an element, the first item offered is a New <Element> item. Selecting this item will insert an empty element.

    New Element

  • If the cursor is positioned somewhere inside the element, the first entry is a Split <Element> item. In most cases, you can only split the closest block element to the cursor position, but if it is inside a list item, the list item will also be proposed for split.

    Split Element

  • If the cursor is positioned inside a space preserved element (for example, a codeblock), the first choice is Enter and it will insert a new line in the content of the element.

    ENTER New Line

2.2.3.3: Smart Paste Support

The Oxygen XML Web Author includes support for copy and paste actions using the usual keyboard shortcuts ( Ctrl + C (Command + C on OS X) for copying, Ctrl + X (Command + X on OS X) for cutting, and Ctrl + V (Command + V on OS X) for pasting). This support includes a Smart Paste feature that preserves certain style and structure information. This includes the following scenarios:

  • Paste content from external sources (such as text processors or web browsers) into the document you are editing. Oxygen XML Web Author tries to preserve all associated formatting, such as lists, paragraphs, and text styling. When a valid XML structure is detected in the clipboard content, Oxygen XML Web Author will paste the content with XML structure.
  • Paste content from within a Oxygen XML Web Author session, preserving the XML structure. If the current location is not valid for the copied content, Oxygen XML Web Author will try to find possible solutions (if possible).
  • Paste content from the Oxygen XML Web Author session into external sources. In this case, only the text content is copied.
  • Paste a valid http(s) URL string and Oxygen XML Web Author will automatically insert it as a linking element for the particular document type you are working with. For example, in DITA it would insert an xref element.

On desktop versions of the Oxygen XML Web Author, the Smart Paste feature also includes a Paste Special action in the contextual menu that allows you to choose how to paste copied content. The Paste Special action allows you to choose from the following:

  • Smart Paste - Oxygen XML Web Author will paste the copied content while trying to preserve its structure and if the current location is invalid, Oxygen XML Web Author will attempt to find a possible solution.
  • Paste as Text - The copied content will be pasted as text content.
  • Paste as XML - Copied content that is considered to be valid XML will be pasted with its XML structure preserved.

Notice

On Safari Mobile versions 6 and 7, the copy/paste support ignores all text formatting, keeping only the content.

2.2.3.4: Validating XML Documents

Oxygen XML Web Author automatically checks the document for errors. The errors and warnings reported by the validation engine include problems found in the following:

  • The structural integrity and well-formedness of the document.
  • A set of best practice rules (such as a maximum number of words in a paragraph).

The automatic validation errors appear underlined in red, while warnings underlined in yellow. On the desktop version, if you hover the mouse over the errors or warnings, a tooltip is displayed that provides more information about the problem.

To see a detailed list of errors, tap or click the Validation Results button on the upper toolbar (note the red marker that shows the number of errors found in the document). Every item in the list has an arrow button to its right side. Tap or click that button to go to the location in the document where the issue was found.

2.2.3.5: Automatic Spell Checking

Oxygen XML Web Author automatically checks for spelling errors when a document is loaded and every time a modification is made in the document. Words that are detected as spelling errors are underlined with a jagged red line. If you right-click on the word, you are presented with a list of suggestions that you can select from to replace the word and an Ignore All option that instructs Oxygen XML Web Author to ignore all occurrences of the reported spelling error in the current document.

Note

The spell checking engine in Oxygen XML Web Author overrides any spell checking engines that are part of the browser. To disable this feature, go to the Preferences action from the More drop-down menu on the toolbar and deselect the Enable automatic spell checking option.

Related information:

Adding Custom Dictionaries for the Spell Checker

2.2.4: Accessing a File Repository

When opening Oxygen XML Web Author, you are greeted with a user-friendly Dashboard that contains actions that allow you access XML files stored in various file repositories. Depending on the repository you chose, follow the instructions presented on screen. This section includes information about using Git, WebDAV, and SharePoint repositories with Oxygen XML Web Author.

2.2.4.1: Using a Git Repository

Oxygen XML Web Author includes a Git plugin that allows you to edit files stored in a Git repository (including GitHub integrations). The procedure in this topic assumes that this plugin is enabled in your installation of Oxygen XML Web Author.

Open or Create a File Stored in a Git Repository

To open a file stored in a Git repository, use the dedicated Git icon () in the Open section of the main dashboard (a Choose File dialog box will be displayed that allows you to browse for the file). To create a new file, use the dedicated Git icon () in the New section (a Choose Template dialog box will be displayed). For information, see Creating or Opening Documents.

If your connection has not yet been configured, a dialog box will be displayed that provides instructions for configuring and selecting the URL for the connection. For more information, see Configure a Plugin.

Commit a File to a Git Repository

To commit a file to a Git repository, select the Commit on Git action on the toolbar (or use the Ctrl + S (Command + S on OS X) shortcut). A dialog box will be opened that allows you to enter a commit message and choose the branch for which the commit will be processed (you can also edit the name of the branch in this dialog box). It also includes a Choose a previously entered comment drop-down menu that allows you to select a previously used commit message.

  • When committing on a branch that is different from the branch of the currently opened document and the branch does not exist, Oxygen XML Web Author will attempt to create it.
  • If someone else has committed the current document since you last opened it (causing conflicts), a Commit Status confirmation dialog box will appear.

    Commit Status Dialog Box

    The Commit Status dialog box allows you to choose the following options:

    • Click here link - You can click the link at the top of the dialog box to see the difference between the two commits.
    • Merge and commit - Merges your changes with versions that were committed by other people and commits the merged changes.
    • Commit on a new branch - Creates a new branch that contains your version of the document so that you can merge the changes at a later time, after the conflicts have been solved.
    • Commit only my changes - Commits your changes regardless of whether or not there was a conflict, and the changes made by the other user are lost.
    • Cancel - Cancels the operation and your changes are not committed to the repository. Before canceling, you could click the link at the top to see the differences, correct the conflicts manually, and then commit afterwards using the Commit only my changes option.

Committing to a Repository Without Access

If you try to commit a file on a repository that you do not have access to, a Commit Error dialog box is displayed. It warns you that continuing will commit the file to a new branch and allows you to specify the details for an automatic pull request (assuming the Create Pull Request automatically option is not disabled). The Pull Request Title field allows you to specify a title for the pull request and the Message field allows you to add and optional description.

Commit Error Dialog Box

When you tap or click the Commit button, the Git connector will automatically do the following:

  • Fork the project into your account, if it is not already.
  • Create a new branch from the edited branch.
  • Commit your changes on this newly created branch.
  • Create a pull request from your newly created branch to the originally edited branch.
  • Switch the editor to your branch so further save operations will just add new commits to your branch, thus updating the pull request with new changes.

Related information:

Configuring a Git Plugin to Use GitHub Authentication

2.2.4.2: Using a WebDAV Server

Oxygen XML Web Author includes a WebDAV plugin that enables you to access files stored on a WebDAV-enabled server. To access these files, it is assumed that the WebDAV plugin is enabled in your installation of Oxygen XML Web Author.

Open or Create a File Stored on a WebDAV Server

To open a file stored on a WebDAV-enabled server, use the dedicated WebDAV icon () in the Open section of the main dashboard (a Choose File dialog box will be displayed that allows you to browse for the file). To create a new file, use the dedicated WebDAV icon () in the New section (a Choose Template dialog box will be displayed). For more information, see Creating or Opening Documents. If your connection has not yet been configured, a dialog box will be displayed that allows you to select the URL of your WebDAV server.

Use Built-In WebDAV Server

If the WebDAV Server plugin is installed and enabled, the Choose File dialog box also includes an option to use a built-in WebDAV server that is included with Oxygen XML Web Author. To use this feature, simply click the Use built-in server button and a file structure will be created on your local computer in the following directory: [WEB_AUTHOR_INSTALL_DIR]/tomcat/webapps/oxygen-xml-web-author/webdav-server.

WebDAV Choose File Dialog Box (with WebDAV Server Plugin Installed)

Related information:

Configuring WebDAV Support

2.2.4.3: Using a SharePoint Repository

Oxygen XML Web Author includes a SharePoint plugin that allows you to edit files stored in a SharePoint repository. The procedure in this topic assumes that this plugin is enabled in your installation of Oxygen XML Web Author.

Open or Create File Stored in a SharePoint Repository

To open a file stored in a SharePoint repository, use the dedicated SharePoint icon () in the Open section of the main dashboard (a Choose File dialog box will be displayed that allows you to browse for the file). The first time this dialog box is opened, you will be presented with the available root sites that can be accessed.

Note

The SharePoint plugin can only browse resources from SharePoint Online (URLs like: https://domain.sharepoint.com/) or One Drive (URLs like https://domain-my.sharepoint.com/).

To create a new file, use the dedicated SharePoint icon () in the New section (a Choose Template dialog box will be displayed). For information, see Creating or Opening Documents.

If your connection has not yet been configured, a dialog box will be displayed that provides instructions for configuring and selecting the URL for the connection. For more information, see Configure a Plugin.

Checking in and Checking out SharePoint Resources

SharePoint integrations include some toolbar buttons that allow you to easily check resources in or out. These SharePoint-specific actions are as follows:

Check Out
Use this action to check out the currently edited document. After a successful check out, the file name will be decorated with a distinctive mark () to indicate that the file is currently checked out and this Check Out button becomes unavailable.
Check In

Use this action to check in the currently edited document. The file can only be checked in if it was previously checked out by the current user. If there are unsaved changes, you will be prompted to save the file. Selecting this action will open a dialog box that contains the check in version and allows you to enter a comment. After a successful check in, the check out decorator mark is removed from the file name and this Check In button becomes unavailable.

Discard Check Out

Use this action to discard the check out on the currently edited document. The check out can only be discarded if the file was previously checked out by the current user. When selecting this action, you will be prompted for confirmation. After a successful discard, the check out decorator mark is removed from the file name and this Discard Check Out button becomes unavailable.

Important

All the changes made to the document since the last time the file was checked out will also be discarded and the document will be reloaded.

Related information:

Configuring a SharePoint Plugin Integration

2.2.5: Browser Compatibility

Oxygen XML Web Author was developed and continuously tested on the following major Web browsers:

  • Chrome 20 and newer, running on desktop systems. [Recommended for optimal performance and user experience]
  • Chrome for Android 4.3 and newer, running on Android-enabled devices.
  • Mozilla Firefox 19 and newer, running on desktop systems.
  • Internet Explorer 9 and newer, running on desktop systems.
  • Microsoft Edge running on desktop systems.
  • Opera 15 and newer, running on desktop systems.
  • OS X Safari 6 and newer, running on OS X.
  • Safari Mobile iOS 6 and newer, running on iOS devices.

As an HTML 5 application, it is likely to work on other HTML 5 compliant browsers for various platforms.

Known Issues

Due to implementation particularities, Oxygen XML Web Author may exhibit minor behavioral differences:

  • On Android devices the content completion list of proposals might display undefined elements. To prevent this, go to Settings ⇒ Bandwidth Management ⇒ Reduce data usage and select OFF.
  • On Safari Mobile and Chrome for Android, there is no warning message if you close the browser page without saving the changes made in the document.
  • Input Method Editor (IME) is fully supported only when running Oxygen XML Web Author in a Chrome browser on a Windows platform.
  • On Safari Mobile, the native Bold, Italic, and Underline actions do not work. As a workaround, use the framework-specific markup.
  • On Android devices, the editing works best with Google Keyboard having the Auto-correction option disabled and the Show correction suggestions option set to Always hidden. Alternatively, you can use Google voice typing.

    Note

    Using other keyboards can lead to unpredictable results. If your document gets corrupted, use the Undo button.
  • On Safari Mobile versions 6 and 7, the copy/paste support ignores all text formatting, keeping only the content.

2.2.6: License Issues

Oxygen XML Web Author uses a floating license mechanism, where the license key is stored on a server and individual users consume license seats from a common pool. To run properly, be aware of the following:

  • For the licensing mechanism to run properly, your browser needs to accept cookies. Otherwise, Oxygen XML Web Author will not be loaded.
  • Each browser consumes a license. When you use multiple browsers (for example, Firefox and Chrome) to access the Oxygen XML Web Author at the same time on the same system, you will consume multiple licenses. However, multiple tabs in the same browser consume a single license.
  • A license is automatically released after 30 minutes of inactivity. When resuming work, if there are no available licenses, you can still save the documents you are currently working on.
  • On desktop systems, you may force an immediate license release by closing all editor tabs.

Chapter 3: Deploying Oxygen XML Web Author

Describes how to deploy Oxygen XML Web Author
Server Requirements

Even though the requirements are not very strict, you should consider the following metrics when provisioning the server for running the Oxygen XML Web Author:

  • A processor core can handle 50 to 100 active users.
  • Editing an average DITA file consumes about 10MB of RAM. However, the Oxygen XML Web Author includes a configurable caching mechanism that stores the oldest files to disk when memory resources become low.

Software Requirements

On the server side, the following applications are supported:

  • Servlet container:
    • Apache Tomcat 7 or 8
    • WildFly 10.0.0.Final
    • IBM WebSphere Liberty 8.5.5.8
  • Java Virtual Machine 1.7 or newer (if started in security mode, Java 1.8 is required).

Oxygen Data Directory and Other Important Deployment Notes
  • All Oxygen XML Web Author configuration files are stored in a single folder that can be shared amongst multiple servers in a distributed deployment. It can also be reused when you update the server to a new version or when stored on a shared file system to be used by multiple server instances.

    The default location of this folder depends on the distribution, as follows:

    Windows, Linux, and All Platforms Distributions
    [OXYGEN_WEBAUTHOR_INSTALL_DIR] /tomcat/work/Catalina/localhost/oxygen-xml-web-author
    Web Archive Distribution
    Depends on the servlet container. For example, in Tomcat it is located in work/Catalina/localhost/oxygen-xml-web-author.

    However, the default location can be overridden by the oxygen.data.dir system property.

    Attention

    If the Oxygen XML Web Author is started in security mode, you must set the oxygen.data.dir system property.

    Note

    WildFly and WebSphere will erase the folder with configuration files upon restart. For these servers, you must set the oxygen.data.dir system property to a folder that persists across restarts.
  • It is recommended that you install the Oxygen XML Web Author in its own instance of Tomcat, without sharing it with other applications.
  • If you want to reload the application, you have to restart the server.

Related information:

Setting up an HTTP Floating License Server

3.3.1: Installation

To install the Oxygen XML Web Author, follow these steps:

  1. Go to the Download section of the Web Author website.
  2. Download the type of installation kit that suits your operating system.
  3. Follow the instructions listed on that page.
  4. If you used the Linux, Windows, or All Platforms installation kits, at the end of the installation process you will be directed to a license configuration page where you will choose the type of license configuration that you want to use.

License Configuration Page

In the license Configuration Page, you can choose one of the following types of configurations:

  • Trial - This is recommended if you want to try the Oxygen XML Web Author.

    It will install all the required components on your computer, it will automatically request a trial license based upon the information that you enter in the form, and you will have access to the product for 30 days.

  • Fast setup - This is recommended if you have a commercial license and you want the installation and the license server to be hosted on the same computer.

    The floating license server and Oxygen XML Web Author are already installed and connected. To activate your license key, follow this procedure:

    1. Click the License server setup page button.
    2. Paste your license key in the subsequent form.
    3. Click Activate.

      Note

      This will lock your license key to a particular license server deployment and no multiple uses of the same license key are possible. During the activation process, a code that uniquely identifies your license server deployment is sent to the oXygen servers, which in turn will sign the license key.
    4. Enter the administration credentials that you provided during the initial setup.
    5. You will be redirected to the main page of the license server. Click the Go to Oxygen XML Web Author Dashboard button and start using the product.

  • Flexible setup - This is recommended if you want to have a more complex deployment (for example, a load-balanced pool of Oxygen XML Web Author instances or if you want to have different servers for the testing and production phases).

    Follow this procedure:

    1. Install an external license server.
    2. Activate your license key with the newly installed license server.
    3. Connect Oxygen XML Web Author to the newly installed license server by using the License section of the Administration Page.
    4. Enter the administration credentials that you provided during the initial setup.
    5. Click on the Oxygen XML Web Author logo at the top-left corner of the page to navigate to the Dashboard to start using the product.

3.3.1.1: Increasing the Memory Allocated to Oxygen XML Web Author

If the default amount of memory is not enough for your usage pattern, you can increase the amount of memory allocated to Oxygen XML Web Author. To do so, follow the procedure below for the type of installer you used:

Windows Installer

To increase the amount of memory allocated to Oxygen XML Web Author for a Windows installation, follow these steps:

  1. Go to the installation directory of Oxygen XML Web Author.
  2. Launch Manage Web Author.
  3. Go to the Java tab.
  4. In the Maximum memory pool option, enter the desired amount of memory to allocate to Oxygen XML Web Author.
  5. Restart the application.

Linux Installer or All Platforms Kit

To increase the amount of memory allocated to Oxygen XML Web Author for a Linux or All Platforms installation, follow these steps:

  1. Go to the installation directory of Oxygen XML Web Author.
  2. Edit the oXygenXmlWebAuthor.vmoptions file.
  3. Change the -Xmx1536m property to the desired amount of memory to allocate to Oxygen XML Web Author (for example, 4 GB is represented as -Xmx4g, while 1.5 GB = 1536 MB and is represented as -Xmx1536).
  4. Restart the application.

3.3.1.2: Restarting Oxygen XML Web Author

To restart the Oxygen XML Web Author application, follow the procedure below for the type of installer you used:

Windows Installer
  1. Go to the installation directory of Oxygen XML Web Author.
  2. Launch Manage Web Author.
  3. Go to the General tab.
  4. Click the Stop button and click Start.
  5. Click OK.
Linux Installer
  1. Run the following command:
    sudo service oxygen-xml-web-author restart
All Platforms Distribution for Windows
  1. Run the following command:
    "stop oXygen XML Web Author.bat" && "start oXygen XML Web Author.bat"
All Platforms Distribution for Linux and Mac
  1. Run the following command:
    stop-oXygen-XML-Web-Author.sh && start-oXygen-XML-Web-Author.sh

3.3.2: Licensing

The Oxygen XML Web Author uses a floating license model, where the license key is stored on a server and individual users consume license seats from a common pool.

How it works

The license key contains the maximum number of users that can simultaneously access the Oxygen XML Web Author at any given moment. After a period of inactivity, the license allocated to that user becomes available.

While no personal information is sent to the server, a cookie that identifies the user is auto-generated. Note that the use of two different browsers (for example, Firefox and Chrome) by a single user, will consume two floating licenses. However, using two or more windows or tabs of the same browser, consumes a single floating license.

Licensing

Follow these steps to license a deployment of the Oxygen XML Web Author:

  1. Install a floating license server . You can deploy the HTTP license server in the same Tomcat server, alongside with Oxygen XML Web Author.
  2. Configure the license server connection.

    Note

    Information about your license will be displayed in the About section of the Oxygen XML Web Author Dashboard.
Configuring the License Server Connection

For information on configuring the license server connection with a simple GUI, see Configuring the License Server Connection.

Bundling a default License Server Configuration in the Oxygen XML Web Author

If you need to build the Oxygen XML Web Author with a default license configuration bundled inside, use this method.

The connection to the server should be configured in a properties file located in WEB-INF/license.properties. This file might look like this: 

licensing.server.type=http
licensing.server.url=http://example.com:8080/oxygenLicenseServlet/license-servlet
licensing.server.user=<USER>
licensing.server.password=<CHANGE-ME>

The following keys are supported:

licensing.server.type
Type of licensing server. Set it to http.
licensing.server.url
The URL of the license server.
licensing.server.user
The name of the user with role user used to connect to the license server.
licensing.server.password
The password used for the license server.
licensing.server.encryptedPassword
This is an alternative to licensing.server.password. The value should be the encrypted password.
To encrypt the password, setup the SDK project and run the following command in the oxygen-sample-webapp module:
mvn exec:java -Dexec.mainClass="com.oxygenxml.webapp.EncryptionTool" -Dexec.args="encryptionKey passwd"
where passwd is the password and encriptionKey is the encryption key used to encrypt the password.
backup.licensing.server.url
(optional) For some of the licensing packages we offer a backup license key that can be deployed on a second license server in order to provide higher availability in presence of machine and network failures. This key contains the URL of this backup license server.
backup.licensing.server.user
(optional) The name of the user with role user used to connect to the backup license server.
backup.licensing.server.password
(optional) The password to use for the backup license server.
backup.licensing.server.encryptedPassword
(optional) This is an alternative to backup.licensing.server.password. In order to generate its value, see the instructions for licensing.server.encryptedPassword.

3.3.2.1: Setting Up a Floating License Server

Installing a License Server to Manage Floating Licenses

Oxygen XML Web Author uses floating licenses. To manage them you need to install an Oxygen XML Web Author floating license server.

Activating Floating License Keys

To help you comply with the Oxygen XML Web Author EULA (terms of licensing), all floating licenses require activation. This means that the license key will be locked to a particular license server deployment and no multiple uses of the same license key are possible.

During the activation process, a code that uniquely identifies your license server deployment is sent to the Oxygen XML Web Author servers, which in turn will sign the license key.

Split or Combine License Keys to Work with Your License Servers

A license server can only manage one license key (which can cover any number of floating licenses). If you have multiple license keys for the same Oxygen XML Web Author version and you want to have all of them managed by the same server, or if you have a multiple-user floating license and you want to split it between two or more license servers, please contact support@oxygenxml.com and ask for a new license key.

3.3.2.1.1: Setting up an HTTP Floating License Server

Floating License Server (HTTP Server)

The Oxygen XML Web Author license server is available in several distributions, tailored for covering a variety of deployment configurations:

  • Windows installer - Easy-to-use Windows installation wizard. Requires elevated permissions to run it.
  • All-platform distribution - Script-based deployment that does not require elevated permissions to run it. Provides scripts for Windows, Mac, and Linux.
  • Web Archive (WAR) distribution - Provides more flexibility in your deployment configuration, but it requires an existing HTTP server (such as Apache Tomcat).

Installation Steps for the HTTP License Server Installer Distribution for Windows

  1. Download the HTTP license server installer from the Oxygen XML Web Author website.
  2. Run the installer and follow the on-screen instructions.
  3. You need to configure two sets of credentials:
    1. Administrator credentials - used for accessing the Oxygen XML Web Author license server administrative interface. Optionally you can choose to change the standard 8080 port.
    2. Standard user credentials - used by an Oxygen XML Web Author application to connect to the license server.
  4. Optionally you can choose to install the server as a Windows service. In this case, you can choose the name of the Windows service.

Installation Steps for the HTTP License Server All-Platform Distribution

  1. Download the HTTP license server all-platform archive from the Oxygen XML Web Author website.
  2. Unpack the archive.
  3. Run the license server scripts suitable for your operating system (licenseServer.bat for Windows or licenseServer.sh for Linux and Mac).

    Note

    To specify a different port (other than the default 8080), you can pass the new port number as an argument to the scripts (for example, licenseServer.bat 8082).
  4. On the first run, you will be prompted to set two sets of credentials:
    1. Administrator credentials - used for accessing the Oxygen XML Web Author license server administrative interface.
    2. Standard user credentials - used by an Oxygen XML Web Author application to connect to the license server.

Installation Steps for the HTTP License Server WAR Distribution

  1. Make sure that Apache Tomcat 5.5 or higher is running on the machine you have selected to be the license server. To get it, go to http://tomcat.apache.org.
  2. Download the HTTP license server Web ARchive (.war) from the Oxygen XML Web Author website.
  3. Configure two Tomcat users:
    1. One user with the role user, used by an Oxygen XML Web Author application to connect to the license server. In the subsequent example, this user name is John.
    2. Another user with the roles admin and manager-gui, used for accessing the Oxygen XML Web Author license server administrative interface and the Tomcat management interface. In the subsequent example, this user name is Mary.
    A typical way to achieve this is to edit the tomcat-users.xml file from your Tomcat installation (if using a Tomcat zip/tar.gz distribution, by default this configuration file is found in the /TomcatInstallFolder/conf/ directory). After adding the two users, the configuration file might look like this:
    <tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">
  <!-- ... other user and role definitions ... -->
  <role rolename="user"/>
  <role rolename="admin"/>
  <role rolename="manager-gui"/>
  <user username="John" password="user_pass" roles="user"/>
  <user username="Mary" password="admin_pass" roles="admin,manager-gui"/>
</tomcat-users>
  4. Go to the Tomcat Web Application Manager page and log-in with the user you configured with the manager-gui role (Mary in the example above). In the WAR file to deploy section, choose the WAR file and click the Deploy button. The oXygenLicenseServlet application is now up and running, but the license key is not yet registered.
  5. Go to the oXygen license server administration page by clicking the oXygenLicenseServlet link in the manager page. You will need to authenticate with the user configured with the admin role (Mary in our example).
  6. Activate the floating license key. This process involves binding your license key to your license server deployment. Once the process is completed you cannot activate the floating license with another license server. Follow these steps to activate the license:
    1. Access the HTTP license server by following the link provided by the Tomcat Web Application Manager page. If prompted for authentication, use the credentials configured for the admin or manager users.

      Result: A page is displayed that prompts for a license key.

    2. Paste your floating license key into the form and press Submit. The browser used in the activation process needs to have Internet access.

      Result: You will be redirected to an online form hosted on the Oxygen XML Web Author website. This form is pre-filled with an activation code that uniquely identifies your license server deployment, and your license key.

      Note

      If, for some reason, your browser does not take you to this activation form, refer to the Manual Activation Procedure.

    3. Press Activate.

      If the activation process is successfully completed, your license server is running. Follow the on-screen instructions to configure the Oxygen XML Web Author client applications.

  7. By default, the license server logs its activity in the TomcatInstallDir/logs/oxygenLicenseServlet.log file. To change the log file location, edit the log4j.appender.R2.File property from the TomcatInstallDir/webapps/oXygenLicenseServlet/WEB-INF/lib/log4j.properties configuration file.

Manual License Activation Procedure
  1. Access the HTTP license server by following the link provided by the Tomcat Web Application Manager page. You will be taken to the license registration page.
  2. Copy the license server activation code.
  3. Go to the activation page at http://www.oxygenxml.com/activation/.
  4. Paste the license server activation code and floating license key in the displayed form, then click Activate.
  5. The activated license key is displayed on-screen. Copy the activated license key and paste it in the license registration page of the HTTP server.
Automatic Subscription Renewal

If the HTTP license server is configured with a subscription license, then the license server will automatically check to see if a new subscription license was purchased and will automatically download and install it for you.

Important

This automatic checking procedure implies a connection to a web service located at oxygenxml.com. You can deactivate this automatic behavior by disabling the Automatically check for subscription renewal option from the main management page of the license server.

If the automatic renewal process fails, you can try either of the following possible solutions:

  • If your server uses a proxy to connect to the Internet, go to the main management page of the license server and configure the proxy settings by clicking the Proxy settings link in the Management tasks section.
  • Manually replace the floating license key.

3.3.2.1.1.1: Upgrading Your HTTP Floating License Server

The goal of the following procedure is to help you minimize the downtime when you upgrade the Oxygen XML Web Author HTTP floating license server to its latest version.

Follow this procedure:

  1. Access the license server by following the link provided by the Tomcat Web Application Manager page. If prompted for authentication, use the admin or manager credentials.
  2. Click the View license key link and copy the displayed license key to a file for later use.
  3. Go to the Tomcat Web Application Manager page, log in with the user you configured with the manager role, and Undeploy the floating license server.
  4. Go to Oxygen XML Web Author website and download the HTTP license server.
  5. Deploy the downloaded license server.
  6. Access the license server by following the link provided by the Tomcat Web Application Manager page. If prompted for authentication, use the credentials configured for the admin or manager users.
  7. Paste the license key into the form and register it.

3.3.2.1.1.2: Replacing a Floating License Key in an HTTP Floating License Server

The following procedure assumes that your Oxygen XML Web Author HTTP floating license server contains a previously activated license key and provides instructions for replacing it with another one. The goal of the procedure is to allow you to activate and configure the new license key without any downtime.

This is useful if, for instance, you want to upgrade your existing license to the latest version or if you receive a new license key that accommodates a different number of users.

To replace a floating license key that is activated on your HTTP floating license server with a new one, follow these steps:

  1. Access the license server by following the link provided by the Tomcat Web Application Manager page.
  2. Click the Replace license key link. This will open a page that contains details about the license currently in use.
  3. Click the Yes button to begin the replacement procedure.
  4. Paste the new floating license key in the displayed form, then click Submit. The browser used in the process needs to have Internet access.

    You will be redirected to an online form hosted on the Oxygen XML Web Author website. This form is pre-filled with an activation code that uniquely identifies your license server deployment and your license key.

    Note

    If for some reason your browser does not take you to this activation form, refer to the Manual Activation Procedure.

  5. Press Activate.

    If the activation process is completed successfully, your license server is now running using the new license key. You can click View license key to inspect the key currently used by the license server.

3.3.2.1.1.3: Getting More Information From the Report Page

You can access a license server activity report at http://hostName:port/oXygenLicenseServlet/license-servlet/report.

It displays the following real time information:

  • License load - A graphical indicator that shows how many licenses are available. When the indicator turns red, there are no more licenses available.
  • Floating license server status - General information about the license server status, including the following information:
    • server start time
    • license count
    • rejected and acknowledged requests
    • average usage time
    • license refresh and timeout intervals
    • location of the license key
    • server version
  • License key information - License key data, including the following information:
    • licensed product
    • registration name
    • company name
    • license category
    • number of floating users
    • Maintenance Pack validity
  • Current license usage - Lists all currently acknowledged users, including the following information:
    • user name
    • date and time when the license was granted
    • name and IP address of the computer where Oxygen XML Web Author runs
    • MAC address of the computer where Oxygen XML Web Author runs

Note

The report is also available in XML format at http://hostName:port/oXygenLicenseServlet/license-servlet/report-xml.

3.3.3: Upgrading

Every new version of Oxygen XML Web Author comes with a lot of new features, improvements, bug fixes, and security upgrades. Therefore, you should always use the latest version. However, you may want to perform some internal tests before allowing the users to use the new features. For example, you may want to disable some of the new features to keep the UI simple or to tweak some of the settings.

It is recommended that you make a separate deployment of the new version on a different VM, perform some acceptance tests, and then switch all of your users to the new deployment.

To upgrade Oxygen XML Web Author, follow these steps:

  1. Deploy the new version of Oxygen XML Web Author on a separate virtual machine and connect it to your existing license server. The two deployments will work in parallel, both using the same license pool.
  2. It might be necessary to update your license key. If you receive an error message in regards to the license key version, follow this procedure. Your existing Oxygen XML Web Author deployment will continue to work with a license for the newer version.
  3. Tweak the settings for the new version to suit your needs.
  4. Switch all of the users to the new version. This can be achieved either by changing the DNS entry or configuring the Load Balancer to use the new deployment.

3.3.4: Administration Page

Oxygen XML Web Author includes a user-friendly Administration Page that helps you to configure your instance of the Oxygen XML Web Author. You can use this page to configure a variety of settings. You need to enable the Administration Page before you can access it, but once you do, you can access it from a link on the top-right corner of the Dashboard page.

Enabling the Administration Page

If you used the Linux, Windows, or All Platforms installation kits, the administration page is already enabled.

If you used the Web Application Archive version, you need to manually enable the Administration Page by following these steps:

  1. Configure Tomcat to use a security Realm element. Refer to the Tomcat Documentation for more information.
  2. Edit the tomcat-users.xml file from your Tomcat installation and configure a user for the admin role, as in the following example:
    <tomcat-users>
  <role rolename="admin"/>
  <user username="USERNAME" password="PASSWORD" roles="admin"/>
</tomcat-users>
  3. Your Administration Page is now enabled. To access it, go to the following URL: 
    http://example.com:8080/oxygen-webapp/app/admin.html
    where http://example.com:8080/oxygen-webapp is the URL of your instance of the Oxygen XML Web Author.
  4. You will be prompted for authentication credentials and you will enter those configured in the steps above.

Accessing the Administration Page

You can easily access the Administration page from a link on the Dashboard page.

Administration Page Link

How to Hide the Administration Page Link

You can hide the Administration Page link from regular users by disabling the Show a link to the Administration Page option that is available in the Settings section of the Administration Page.

Show Administration Page Link Option

Types of Settings in the Administration Page

You can click on any of the listed types of settings to access configurable options for each type. The Administration Page allows you to configure settings for the following:

  • General - Allows you to choose the initial state of the Change Tracking feature. You can choose between Stored in document, Always On, and Always Off. This tab also displays the location of logging files.
  • License - Allows you to configure a license server connection.
  • Plugins - Allows you to add and configure plugins for your Oxygen XML Web Author.
  • Frameworks - Allows you to add or remove frameworks for your Oxygen XML Web Author.
  • Connection - Includes an option for automatically accepting invalid security certificates.
  • Connection ⇒ Proxy - Allows you to configure the proxy settings for your Oxygen XML Web Author.

3.3.4.1: Configuring the License Server Connection

To configure the license server connection for your Oxygen XML Web Author, follow these steps:

Note

This method only applies to the oXygen HTTP Floating License Server .
  1. Go to your Administration Page.
  2. Select License.
  3. Enter the server URL and your authentication credentials for the license server.
  4. Click Submit.

You should see a message that informs you that the license configuration was successfully applied. After it is configured, you can change or manage your server connection by using the Change Server or Manage Server buttons.

3.3.4.2: Adding and Configuring Plugins

Oxygen XML Web Author includes a user-friendly Administration Page that helps you to configure your instance of the Oxygen XML Web Author.

Add a New Plugin

To add a new plugin to the Oxygen XML Web Author, follow these steps:

  1. Go to your Administration Page.
  2. Select Plugins.
  3. Click Upload Plugin and choose a plugin file to upload.
  4. Click OK to upload the file. The plugin should appear in the list on this page.
  5. Once you are finished with all of your changes, restart the server.

Enable or Disable a Plugin

To enable or disable a plugin, follow these steps:

  1. Go to your Administration Page.
  2. Select Plugins.
  3. Click the disabled button to enable the plugin, or the enabled button to disable it.
  4. Once you are finished with all of your changes, restart the server.

Configure a Plugin

If the plugin can be configured, a Configure icon is displayed next to its name in the Administration Page. To configure the plugin, click the icon and follow the instructions.

Delete a Plugin

To delete a plugin from your Oxygen XML Web Author, follow these steps:

  1. Go to your Administration Page.
  2. Select Plugins.
  3. Find the plugin you want to delete and click the Delete the plugin button on the right side of its name.
  4. Restart the server to apply the changes.

3.3.4.2.1: Creating a Plugin Configuration Page

To create a configuration page for a plugin that does not already have the Configure icon displayed in the Administration page, follow these steps:

  1. Register a WebappServlet extension type with a role attribute set to config in your plugin.xml file, as in the following example:
    <extension type="WebappServlet" role="config" class="com.ex.MyPluginConfigExt"/>

    The class attribute value should point to an extension of the PluginConfigExtension class.

  2. When extending the PluginConfigExtension class, consider the following notes:
    • Implement the getOptionsForm method to return an HTML form and make sure that contains inputs with the name attribute the same as the option you want to configure.
    • Implement the getOptionsJson method to return a JSON string that contains the options that you want to make available to the JavaScript code. They will be accessible in your plugin JavaScript code using the sync.options.PluginsOptions.getClientOption(optionName) method.

      Note

      The JSON should only contain key values, where values are of the type string|number|boolean with no arrays or other objects.

      Tip

      You should not include any sensitive information (e.g. OAuth secrets) in the options returned by this method.
    • Implement the getPath method to return a non-empty string that represents the path for which this extension will be served.

      For example: 

       {webapp-context}/plugins-dispatcher/RESULT_OF_GETPATH
    • If you need to override the init method, make sure you call super.init(). Otherwise, options will not be saved to disk and will be lost when you restart the application.
    • If you need to override any of the doPut/doDelete methods, make sure you call the saveOptions method at the end to save the options to disk.
    • If you need to override the doGet method, make sure it responds with the result of getOptionsForm for header Accept=text/html, and with the result of getOptionsJson when called with header Accept=application/json. Use the getOption or getDefaultOptions methods to access the current or default options.

    Tip

    For an implementation example, you can look at com.oxygenxml.sdksamples.github.GithubPluginConfigExtension in the webapp-github-plugin project.
Result: A Configure icon is now displayed next to its name in the Administration page.

Related information:

Adding and Configuring Plugins

3.3.4.3: Adding or Removing a Framework

Add a New Framework

To add a new framework to your Oxygen XML Web Author, follow these steps:

  1. Go to your Administration Page.
  2. Select Frameworks.
  3. Click Upload Framework and choose a framework file to upload.
  4. Click OK to upload the file. The framework should appear in the list on this page.
  5. Once you are finished with all of your changes, restart the server.

Delete a Framework

To delete a framework from your Oxygen XML Web Author, follow these steps:

  1. Go to your Administration Page.
  2. Select Frameworks.
  3. Find the framework you want to delete and click the Schedule for deletion button on the right side of its name.
  4. Restart the server to apply the changes.

3.3.4.4: Configuring Proxy Settings

Configure Proxy Settings for Oxygen XML Web Author

To configure the proxy setting for your Oxygen XML Web Author, follow these steps:

  1. Go to your Administration Page.
  2. Select Connection ⇒ Proxy .
  3. Specify how HTTP(S) connections go through the proxy server. You can choose between the following:
    • Direct connection - HTTP(S) connections will go directly to the target host without going through a proxy server.
    • Use system settings (default setting) - HTTP(S) connections will go through the proxy server set in the operating system.
    • Manual proxy configuration - HTTP(S) connections will go through the proxy server specified in the Web Proxy (HTTP/HTTPS) section.

      Depending on the option you choose, you can configure the following additional options:

      Web Proxy (HTTP/HTTPS) section

      Address
      The address of the proxy server used for manual configurations.
      Port
      The port of the proxy server used for manual configurations.
      No proxy for
      Specifies the hosts that the connections must not go through a proxy server. A host needs to be written as a fully qualified domain name (for example, myhost.example.com) or as a domain name (for example, example.com). Use a comma to separate multiple hosts.
      User
      The user name for authentication with the proxy server.
      Password
      The password for authentication with the proxy server.

      SOCKS Proxy section

      Address
      The address of a SOCKS proxy that all connections will pass through. If this field is empty, the connections do not use a SOCKS proxy.
      Port
      The port of a SOCKS proxy that all connections will pass through.

  4. Click Apply to accept your changes.

3.3.5: Supported Plugin Integrations

By default, the Oxygen XML Web Author comes bundled with the following plugin integrations:

  • Git
  • WebDAV
  • SharePoint

Related information:

Adding and Configuring Plugins

3.3.5.1: Configuring a Git Plugin to Use GitHub Authentication

Oxygen XML Web Author includes a plugin that allows you to edit files stored in a Git repository. The Git Plugin allows you to access repositories simply by using your Git login credentials.

You can also configure your Git plugin to allow OAuth authentication for GitHub integrations to access files stored in a public or private repository. You will then have access to a Login with GitHub button in the Git Login dialog box. You can configure your integration either by using github.com or with a GitHub Enterprise deployment.

Git Login Dialog Box

Configure a Git Integration with github.com

To configure your Git integration using github.com, follow this procedure:

  1. Login to GitHub and register a new developer application at https://github.com/settings/applications/new.
    1. Complete the form.
    2. The Authorization callback URL field should include the following path: [OXYGEN_WEBAUTHOR_INSTALL_DIR] /plugins-dispatcher/github-oauth/callback.
  2. Click on Register application to obtain the Client ID and Client Secret credentials (they are displayed at the top-right section of the resulting page).
  3. Set your Client ID and Client Secret credentials in your plugin configuration by doing the following:
    1. Go to the Administration Page .
    2. In the Plugins section, click on the Configure icon for the GitHub plugin.
    3. Enter the Client ID and Client Secret in the Plugin configuration dialog box.
  4. Restart the Oxygen XML Web Author.

Result: You now have access to the Login with GitHub button in the Git Login dialog box.

Configure a Git Integration with a GitHub Enterprise Deployment

To configure your Git integration using a GitHub Enterprise deployment, follow this procedure:

  1. Login to GitHub Enterprise and register a new developer application. The URL is: [GithubEnterpriseUrl]/settings/applications/new.
    1. Complete the form.
    2. The Authorization callback URL field should include the following path: [OXYGEN_WEBAUTHOR_INSTALL_DIR] /plugins-dispatcher/github-oauth/callback.
  2. Obtain the Client ID and Client Secret credentials at: [GithubEnterpriseUrl]/settings/developers.
  3. Set the Client ID, Client Secret, and the API URL in your plugin configuration by doing the following:
    1. Go to the Administration Page .
    2. In the Plugins section, click on the Configure icon for the GitHub plugin, enable the Use GitHub Enterprise option, and enter the API URL, Client ID, and Client Secret in the Plugin configuration dialog box. The API URL is the URL of your GitHub Enterprise deployment ([GithubEnterpriseUrl]).
  4. Restart the Oxygen XML Web Author.

Result: You now have access to the Login with GitHub button in the Git Login dialog box.

3.3.5.2: Configuring WebDAV Support

The Oxygen XML Web Author includes a plugin that allows you to edit files stored on a WebDAV server.

You can configure your Oxygen XML Web Author instance to access files stored in an existing WebDAV server or use an option to enable a built-in WebDAV server on your local computer.

Configure a WebDAV Plugin Integration

To configure a WebDAV plugin integration, follow this procedure:

  1. Go to your Administration Page.
  2. Select Plugins.
  3. Click the Configure icon next to WebDAV Plugin.

    Step Result: A Plugin configuration dialog box is displayed with the following option:

    • Lock resources on open - Specifies whether or not WebDAV files are automatically locked when they are opened. By default, WebDAV files are automatically locked to prevent anyone using another connection to that WebDAV server from changing the file. To change this behavior, disable this option.

  4. Click Apply to save your changes.

Configure a Built-In WebDAV Server Integration

Oxygen XML Web Author also includes an option to use a built-in WebDAV server that will use a file structure on your local computer. The first time you click the WebDAV icon to open or create a file from your Oxygen XML Web Author Dashboard page, a dialog box will be displayed. This dialog box includes an option to use a built-in WebDAV server that is included with Oxygen XML Web Author. If you use the Use built-in server option, a file structure will be created on your local computer in the following directory: [WEB_AUTHOR_INSTALL_DIR]/tomcat/webapps/oxygen-xml-web-author/webdav-server.

To configure a built-in WebDAV server integration, follow this procedure:

  1. Go to your Administration Page.
  2. Select Plugins.
  3. Click the Configure icon next to WebDAV Server.

    Step Result: A Plugin configuration dialog box is displayed with the following options:

    • Display samples - Specifies whether or not the sample files that are included with Oxygen XML Web Author are displayed in the Samples section on your Oxygen XML Web Author Dashboard page. If you do not want the samples to be available, disable this option. This will remove the Samples section from your Dashboard.
    • Read-only mode - If this option is enabled, the server will be in read-only mode and users can browse the repository and open documents, but they cannot save them to the server. They do have the option to download documents to save them locally.
    • Enforce server - Use this option to add your configuration to the list of enforced servers.

  4. Click Apply to save your changes.

If you use an external WebDAV server, or if you do not use the WebDAV support at all, you can disable the built-in WebDAV server by disabling the WebDAV Server plugin.

3.3.5.3: Configuring a SharePoint Plugin Integration

The Oxygen XML Web Author includes a plugin that allows you to use the Oxygen XML Web Author to edit files stored in a SharePoint repository. You can configure your SharePoint integration to use the OAuth 2.0 authentication flow to access files stored in a public or private repository. You will then have access to some file checking in/out toolbar buttons that are specific to SharePoint.

Configure a SharePoint Integration

To configure your SharePoint integration, follow this procedure:

  1. Register a new application in the Azure Management Portal at: https://manage.windowsazure.com/.

    For details about registering an application in the Azure Management Portal, see the following articles:

  2. During the registration process, Azure will generate a Client ID and Client Secret (app secret), and you can specify a Redirect URL.
  3. Go to the Administration Page , in the Plugins section click on the Configure icon for the SharePoint plugin, and enter the Client ID, Client Secret, and Redirect URL in the Plugin configuration dialog box.
  4. Restart the Oxygen XML Web Author.

Result: After completing the configuration, you will have access to some SharePoint-specific toolbar buttons that allow you to check in/out files. Also, when you check out files from your SharePoint site, the file name will be decorated with a distinctive mark () to indicate that the file is currently checked out.

Related information:

Using a SharePoint Repository

3.3.6: Customizing Options

The Oxygen XML Web Author functionality that is common with the standalone distribution of Oxygen XML Web Author share the same options. This allows you to configure a consistent editing experience for all users.

Oxygen XML Web Author specific options

A small number of options are specific only to the Oxygen XML Web Author and they can be configured in the WEB-INF/web.xml file. Each option is specified as a context-param element.

The following is a list of options and their accepted values:

Option name Value Description
com.oxygenxml.loadBuiltinProtocolHandlers true/false Controls whether or not the built-in handlers for HTTP/HTTPS and FTP/SFTP protocols are installed. Default value is true.
com.oxygenxml.webapp.datastore.docs.memory.size An integer number Indicates the number of editing sessions stored in memory.
com.oxygenxml.webapp.datastore.docs.memory.expire Duration (*) Indicates the delay after which inactive sessions are stored on disk.
com.oxygenxml.webapp.datastore.docs.disk.size An integer number Indicates the number of inactive editing sessions that can be stored on disk.
com.oxygenxml.webapp.datastore.docs.disk.expire Duration (*) Indicates the delay after which inactive sessions are discarded.
com.oxygenxml.validation.threads.no An integer number Configures the number of validation threads.

(*) - Duration is represented by an integer, followed by one of "d", "h", "m", or "s", representing days, hours, minutes, or seconds, respectively.

Here is an example of how to configure a context parameter:

<context-param>
  <param-name>com.oxygenxml.loadBuiltinProtocolHandlers</param-name>
  <param-value>false</param-value>
</context-param>

Related information:

How to Set a System Property

3.3.6.1: How to Set a System Property

A variety of Java system properties can be set to influence the behavior of Oxygen XML Web Author. For example, you can control the amount of memory that is allocated to Oxygen XML Web Author or change the location of the Oxygen Data Directory (oxygen.data.dir).

To set a system property, follow the procedure below for the type of installer you used:

Windows Installer

To set a system property for a Windows installation, follow these steps:

  1. Go to the installation directory of Oxygen XML Web Author.
  2. Launch Manage Web Author.
  3. Go to the Java tab.
  4. In the Java Options section, add the system property using the following pattern: -D[option_name]=[option_value]
  5. Restart the application.

Linux Installer or All Platforms Kit

To set a system property for a for a Linux or All Platforms installation, follow these steps:

  1. Go to the installation directory of Oxygen XML Web Author.
  2. Edit the oXygenXmlWebAuthor.vmoptions file.
  3. Add the system property on a new line, using the following pattern: -D[option_name]=[option_value]
  4. Restart the application.

3.3.7: Adding Custom Dictionaries for the Spell Checker

Oxygen XML Web Author includes an automatic spell checking feature and you can customize the words that are detected by adding custom dictionaries.

To add a custom dictionary, follow these steps:

  1. Download the files needed for your custom dictionary (or create your own). You will need a dictionary file (.dic file extension) and an affix file (.aff file extension). If the dictionary did not include an affix file (.aff), you can create one and leave it empty, but it is needed for the mechanism to work properly.

    Tip

    An example of a website that includes numerous dictionary files is: http://extensions.services.openoffice.org/dictionary.
  2. Copy both files (.dic and .aff) to the dicts folder that is located inside your Oxygen Data Directory (oxygen.data.dir).

    Important

    The name of the dictionary file should begin with a two letter prefix that indicates the language it should be attached to, followed by an underscore or hyphen (for example, en_medical.dic for a medical dictionary in the English language). For a list of language codes, see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.
  3. Restart the server for the spell checker to start using the new dictionary.

3.3.8: Setting up a Load-Balanced Server

To scale a deployment to a larger number of users and to increase the availability, Oxygen XML Web Author can be deployed on a set of load-balanced servers. This topic describes the required setup for such a scenario.

Configure Session Stickyness

Every Oxygen XML Web Author server keeps the state of the edited documents in memory for performance reasons. This implies that every user should connect to the same back-end server for the duration of an editing session. To achieve this result in a load-balanced setting, you should enable session stickyness .

Configure Server Health Checks

To detect unhealthy servers, Oxygen XML Web Author offers a health check REST API. The endpoint has the following interface:

URL
rest-public/status
Response status code
200 for a healthy server and 503 for an unhealthy server.
Response body
For an unhealthy server, the response body contains a text description of the problem.

Configure the License Server

All Oxygen XML Web Author servers can use the same pool of floating licenses. To this end, they all need to be configured to use the same license server.

Share Options Between All Instances

The configuration options are stored in the file system in a directory that can be changed using the oxygen.data.dir system property. In order for all instances to use the same options, oxygen.data.dir should point to the same directory on a shared file system.

3.3.9: Configuring Minimal File Access Permissions

The Oxygen XML Web Author requires access to the following file resources:

  • READ access to the directory where the Oxygen XML Web Author is deployed.
  • READ and WRITE access to the application's working directory.
  • READ and WRITE access to JVM's temporary directory.

It is a good security practice to allow a component to access only the information and resources that are necessary for its purpose. In an environment that uses Apache Tomcat, you can enforce these rules following these steps:

  • Start the Apache Tomcat server using the -security flag.

  • Edit the catalina.policy file and add the following snippet: 

grant codeBase "file:${catalina.base}/webapps/oxygen-webapp/-" {
  // Oxygen uses System properties for various configuration purposes.
  permission java.util.PropertyPermission "*", "read,write";
  // Oxygen custom protocols need access to network.
  permission java.net.NetPermission "*";
  permission java.net.SocketPermission "*", "accept,connect,listen,resolve";
  // The web framework used by Oxygen Webapp uses reflection and classloaders.
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission java.security.SecurityPermission "*";
  permission java.util.logging.LoggingPermission "control";
  permission java.lang.RuntimePermission "*";

  // Oxygen requires these permissions to connect to a URL.
  permission java.net.URLPermission "http:*", "*";
  permission java.net.URLPermission "https:*", "*";
  permission java.net.URLPermission "file:*", "*";

  // Oxygen should be allowed to read JVM jars
  permission java.io.FilePermission "${java.home}/-", "read";
	
  // Oxygen uses the JVM's java.io.tempdir for various file handling tasks.
  permission java.io.FilePermission "${java.io.tmpdir}/-", "read,write,delete";
  permission java.io.FilePermission "${java.io.tmpdir}", "read,write,delete";

  // Folder used by oXygen to deploy the plugins to.
  permission java.io.FilePermission "${oxygen.data.dir}/-", "read,write,delete";
  permission java.io.FilePermission "${oxygen.data.dir}", "read,write,delete";
};
// The jar that contains sandboxing code.
grant codeBase 
  "jar:file:${catalina.base}/oxygen-webapp/WEB-INF/lib/oxygen-sandbox.jar!/-" {
    permission java.security.AllPermission;
};
// Give all permissions to plugins code unless otherwise instructed by vendor.
grant codeBase "file:${oxygen.data.dir}/plugins-v18.1.0/-" {
    permission java.security.AllPermission;
};
// Give all permissions to frameworks code unless otherwise instructed by vendor
grant codeBase "file:${oxygen.data.dir}/frameworks-v18.1.0/-" {
    permission java.security.AllPermission;
};

Note

In the previous example, in the first line, replace oxygen-webapp with the name of your deployment of the Oxygen XML Web Author.

Configuring File Permissions to Custom Locations

There are cases when the Oxygen XML Web Author needs to access files system resources, but due to security reasons, you want to prevent your users from opening them directly in the Oxygen XML Web Author editing page using the file:// protocol.

You can do this by following these steps:

  • Edit the catalina.policy file and add a line such as:
    permission java.io.FilePermission "path/to/yourSecretDir/-", "read,write,delete";
permission java.io.FilePermission "path/to/yourSecretDir", "read,write,delete";
  • Use the following system property when starting the Tomcat server:
    -Dfile.protocol.blacklist=/path/to/yourSecretDir

    Note

    Use the value of path.separator system property to separate more directories. For example, under Linux, the value of path.separator property is a colon punctuation character :.

3.3.10: Sharing a Tomcat Instance

If you want to share a Tomcat instance between Oxygen XML Web Author and another web application, the following issues need to be considered:

  • Oxygen XML Web Author reads and sets system properties, and while we try to namespace those that are specific to Oxygen XML Web Author, there is no guarantee that there will not be any clashes with those set by other applications.
  • You have to adapt the JVM's memory configuration to the scenario where there will be more applications competing for the same pool of memory.
  • The Oxygen XML Web Author currently does not restart (or reload in Apache Tomcat terminology) correctly unless the Servlet Container is also restarted.

3.3.11: Using an IIS Reverse Proxy

If you want to use Oxygen XML Web Author with IIS as a reverse proxy, follow this procedure:

  1. Configure IIS to allow double escaping in URLs. See the following examples:
    • For Microsoft Azure, the applicationHost.xdt file should contain the following:
      <?xml version="1.0" encoding="utf-8"?>
 <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
     <security>
      <requestFiltering allowDoubleEscaping="true" 
xdt:Transform="SetAttributes(allowDoubleEscaping)" />
     </security>
    </system.webServer>
</configuration>
    • For other types, insert the following fragment inside the applicationHost.config file:
      <security>
  <requestFiltering allowDoubleEscaping="true"/>
</security>
  2. Configure Tomcat to allow escaped slashes. Append the following line in the tomcat\conf\catalina.properties file:
    org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
  3. Set an environment variable to instruct Oxygen XML Web Author that the URL path is already decoded. Insert the following line in the [OXYGEN_WEBAUTHOR_INSTALL_DIR] \tomcat\bin\catalina.bat file:
    set "URL_DECODING_PROXY=true"

3.3.12: Locating and Configuring Logs

How to Locate Log Files in the Windows, Linux, and All Platforms Versions

To locate the Log file or Config file that Oxygen XML Web Author uses for logging purposes, go to the Administration Page and in the General tab you can view the location of the logging files.

How to Locate the Logs of the WAR Version

By default, the WAR version of Oxygen XML Web Author sends its logs to standard output. To configure it to send logs to a file, edit the Config file and replace the first line with:

log4j.rootCategory= warn, R2
Also replace the value of the log4j.appender.R2.File property with the path of the file where you want the logs to be saved.

Enabling HTTP Request Logging

To enable a detailed logging of the HTTP requests sent by Oxygen XML Web Author, edit the Config file and add the following lines:

log4j.category.org.apache.http.impl.conn=debug
log4j.category.org.apache.http.impl.client=debug
log4j.category.org.apache.http.client=debug
log4j.category.org.apache.http.wire=debug
log4j.category.org.apache.http=debug

3.3.13: Troubleshooting Oxygen XML Web Author Errors

This topic is intended for system administrators and integration developers that want to troubleshoot deployment or programming errors. If you are not in either of those categories, you should contact your system administrator or use the Report problem action .

Oxygen XML Web Author intentionally does not provide explanatory messages for errors caused by deployment or programming mistakes. If you are trying to troubleshoot such a problem, you can find more information in the browser logs or in the server logs.

Browser logs
To see the browser logs, open the Developer Tools in your browser. This can usually be achieved by pressing F12 .
Server logs
To see the server logs, follow the instructions detailed in the Locating and Configuring Logs topic.

Related information:

Locating and Configuring Logs
How to Set a System Property
Increasing the Memory Allocated to Oxygen XML Web Author

Chapter 4: Form Controls

The form controls that are supported in the Oxygen XML Web Author

Properties supported in the Oxygen XML Web Author
Form control Description
The Text Field form control This form control provides a text field box that is used for entering a single line of text.
The Date Picker form control

Note

Some browsers interpret the HTML5 datePicker as a text-field.
This form control offers a text field that allows the user to choose a date in a specified format. Some browsers include a calendar browsing mechanism along with the text field.
The URL Chooser form control This form control provides a dialog box that allows you to select the location of local or remote resources. The inserted reference is made relative to the URL of the currently opened editor.
The Combo Box form control This form control provides a graphical object that is a drop-down menu of proposed values. It can also be used for a combination of a drop-down menu and an editable single-line text field.
The Checkbox form control This form control offers a single checkbox or multiple check-boxes that can be used to enable or disable an option.
The Button form control This form control provides a button object that is used to invoke a specific action.
The Button Group form control This form control provides a group of button objects that are used to invoke specific actions.
The Pop-up form control This form control offers a contextual menu that provides quick access to various actions. A pop-up form control can display single or multiple selections.
The Text Area form control This form control provides a text box that can be used to enter multiple lines of text.
The HTML Content form control This form control is used for rendering HTML content.

Chapter 5: Oxygen XML Author Options Supported by Oxygen XML Web Author

The oXygen XML Author options that are supported in the Oxygen XML Web Author

Oxygen XML Web Author supports some of the options used by the oXygen XML Author desktop application. The supported options are applied for all Web Author users. The options are stored in an XML file with the following format:

<?xml version="1.0" encoding="UTF-8"?>
<serialized version="18.1" xml:space="preserve">
  <map>   
    <entry>
      <String>author.show.comments</String>
      <Boolean>true</Boolean       
    </entry>
  </map>
</serialized>
For each option, an additional entry should be added in this file.

Oxygen XML Author Options Supported in Oxygen XML Web Author
Key Type Description
dita.ot.directory String The directory path to the default DITA OT installation.
track.changes.initial.state Integer Option for track changes initial state.
  • 0 - Initial state stored in document.
  • 1 - Track changes always on.
  • 2 - Track changes always off.
automatically.accept.certificates boolean Option that controls if oXygen will accept all HTTPS certificates.
additional.frameworks.directories See example entry below

An array of java.lang.String objects representing paths to the additional frameworks folders (may also contain editor variables).

WEBAPP_SHOW_ADMIN_PAGE_LINK boolean "True" to display the admin page link on the dashboard.
author.convert.external.content.on.paste boolean

Option that controls whether or not the content pasted in Author mode should be converted to match the destination styles.

author.convert.external.content.space.preserve boolean

Option that controls whether or not the content pasted in Author mode should be converted to match the destination styles in space preserve elements.

http.read.timeout.seconds Integer An integer number that configures the timeout used when waiting for an HTTP request.
http.proxy.system boolean "True" to detect HTTP proxy from system.
http.proxy.set boolean HTTP proxy uses manual configuration.
http.proxy.port Integer Proxy port.
http.proxy.host String Proxy hostname or IP address.
http.proxy.user String Proxy user.
http.proxy.password String Proxy password.
http.proxy.direct String Comma separated list of hosts for which the proxy is bypassed.
http.max.simultaneous.connections.per.host boolean Limits the number of connections the HTTP client can open to the same server host.
author.show.comments boolean Show the comment nodes in the author page.
author.show.processing.instructions boolean Show the pi nodes in the author page.

Example entry for additional.frameworks.directories option:

<entry>
  <String>
   additional.frameworks.directories
  </String>
  <String-array
    <String>
     /path/to/frameworks
    </String>
  </String-array>
</entry>

Chapter 6: Feature Matrix

Comparison between products of the oXygen family

The Oxygen XML Author Component was designed to provide the functionality of the standard Author mode and can be embedded either in a third-party standalone Java application or customized as a Java Web Applet to provide WYSIWYG-like XML editing directly in your choice of web browsers.

The Oxygen XML Web Author and Oxygen XML Web Author Component are re-implementations of the Oxygen XML Web Author Author mode user interface, based on JavaScript and HTML5. Its purpose is to enable XML editing and reviewing on your mobile devices and desktops, directly in a web browser environment. Since the interface was thinned down as much as possible, the core XML processing was moved into a Java-enabled server.

Feature Matrix Showing Differences Between Web Author, Web Author Component, and Author Component
Feature Oxygen XML Web Author Oxygen XML Web Author Component Oxygen XML Author Component
Intended audience Reviewers and occasional contributors. Reviewers and occasional contributors. Content authors, technical writers.
Mobile device support Specifically designed for mobile devices. Specifically designed for mobile devices. No
Compatibility with the standard version of Oxygen XML Editor Covers only editing and reviewing features. Covers only editing and reviewing features. 100%
Text Mode Yes Yes Yes
Grid Mode No No Yes
Client-side setup Yes, with an Administration page. Yes, with an Administration page. Requires Java to be installed, and Java Applets to be allowed to run.
Server-side setup Simply requires running an installer. Requires a servlet container and performing a Maven build. Requires a web server.
Ability to configure installation bundles No Yes Yes

Copyright

Oxygen XML Web Author User Manual

Syncro Soft SRL.

Copyright © 2002-2016 Syncro Soft SRL. All Rights Reserved.

All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the written permission of the publisher. Products that are referred to in this document may be either trademarks and/or registered trademarks of the respective owners. The publisher and the author make no claim to these trademarks.

Trademarks. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and Syncro Soft SRL was aware of a trademark claim, the designations have been rendered in caps or initial caps.

Notice. While every precaution has been taken in the preparation of this document, the publisher and the author assume no responsibility for errors or omissions, or for damages resulting from the use of information contained in this document or from the use of programs and source code that may accompany it. In no event shall the publisher and the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document.

Link disclaimer. Syncro Soft SRL is not responsible for the contents or reliability of any linked Web sites referenced elsewhere within this documentation, and Syncro Soft SRL does not necessarily endorse the products, services, or information described or offered within them. We cannot guarantee that these links will work all the time and we have no control over the availability of the linked pages.

Warranty. Syncro Soft SRL provides a limited warranty on this product. Refer to your sales agreement to establish the terms of the limited warranty. In addition, Oxygen XML Web Author End User License Agreement, as well as information regarding support for this product, while under warranty, is available through the Oxygen XML Web Author website.

Third-party components. Certain software programs or portions thereof included in the Product may contain software distributed under third party agreements ("Third Party Components"), which may contain terms that expand or limit rights to use certain portions of the Product ("Third Party Terms"). Information identifying Third Party Components and the Third Party Terms that apply to them is available on the Oxygen XML Web Author website.

Downloading documents. For the most current versions of documentation, see the Oxygen XML Web Author website.

Contact Syncro Soft SRL. Syncro Soft SRL provides telephone numbers and e-mail addresses for you to report problems or to ask questions about your product, see the Oxygen XML Web Author website.