Edit online

Integrating Oxygen Feedback with Oxygen XML Editor/Author

It is possible to integrate Oxygen Feedback with Oxygen XML Editor/Author so that your documentation team can see all the comments added in your WebHelp output. This means they can react to user feedback by making corrections and updating the source content without leaving the application. This is made possible by an add-on that when installed in Oxygen XML Editor/Author, a Feedback Comments Manager view becomes available.

Attention: The Feedback Comments Manager view only functions in Oxygen XML Editor or Oxygen XML Author. It does not work in the Oxygen XML Developer edition.

To see a demonstration of Oxygen Feedback being integrated with Oxygen XML Editor/Author, watch our Webinar: DITA Publishing and Feedback with Oxygen Tools.

Quick Installation

You can drag the following Install button and drop it into the main editor in Oxygen to quickly initiate the installation process:

Install

Manual Installation

To manually install this add-on in Oxygen XML Editor/Author, follow this procedure:

Go to Help > Install new add-ons to open an add-on selection dialog box.
Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.
Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file.
Select Oxygen Feedback Connector add-on and click Next.
Select the I accept all terms of the end user license agreement option and click Finish.
Restart the application.

Result: The Feedback Comments Manager view is now available. By default, it is displayed to the right of the main editing panel. If the view is not displayed, it can be opened by selecting it from the Window > Show View menu. You can also use the Show Feedback Comments Manager from the contextual menu in the DITA Maps Manager.

Connecting the Feedback Comments Manager View

If this is your first time using it, you need to configure a mapping between Oxygen XML Editor/Author and your Feedback site configuration(s). If you have already configured a mapping, you just need to connect the Feedback Comments Manager to your Feedback account.

To connect, follow this procedure:

Select Connect from the user drop-down menu at the top-right corner of the Feedback Comments Manager.
Step Result: You are directed to the administration login page in your default browser.
Log in with your credentials, click Authorize in the resulting page, and go back to Oxygen XML Editor/Author.
If this is your first time using the Feedback Comments Manager, you need to configure a mapping:
1. Select Preferences from the user drop-down menu at the top-right corner of the Feedback Comments Manager.
  Step Result: You are directed to the Oxygen Feedback Connector preferences page (you can also reach this page by going to Options > Preferences > Plugins > Oxygen Feedback Connector).
2. Click the New button at the bottom of the mappings table.
  Step Result: This opens the New Oxygen Feedback Mapping dialog box where you can configure the mapping.
3. In the Context DITA map location field, click the browsing button and specify the URL of your context DITA map. This is the path to the root DITA map used to publish your output.
4. For the Published site base URL field, Oxygen XML Editor/Author automatically detects all the base URLs for the site configurations that you have the role of Moderator, Admin, or Owner. You can type the base URL or select it from the drop-down menu.
5. Click OK in both dialog boxes.

Result: The comments that exist in the published WebHelp output for the site configurations attached to the current user's organization (based on the configured mapping) will be loaded in the Feedback Comments Manager view.

Using the Feedback Comments Manager View

If the view is not already open in Oxygen XML Editor/Author, go to Window > Show View > Feedback Comments Manager. You can also use the Show Feedback Comments Manager from the contextual menu in the DITA Maps Manager.

Figure 1. Feedback Comments Manager View

The Feedback Comments Manager view contains the following actions and components:

Home button

Use this button to open the Oxygen Feedback administration interface in your default browser.

User Name drop-down menu

Once connected and authorized, your user name will appear in the upper right corner of the view. The drop-down menu offers the following actions:

Refresh: Forces a refresh to synchronize the information in the view and reloads the first 20 items.
Preferences: Opens the Oxygen Feedback Connector preferences page where you can configure a mapping between Oxygen XML Editor/Author and your Feedback site configuration(s).
Help: Opens the Oxygen Feedback user guide in your default browser.
Connect/Disconnect: Signs you in or out of your Oxygen Feedback account.

Feedback for

You can choose which display mode to use for retrieving comments. The options are:

Context DITA map - If there are base URLs mapped to the current context map, comments from all versions defined by the given base URLs will be loaded.
Current editor - Only comments added in the output for the current topic will be loaded. This mode will retrieve comments from web pages generated from any DITA source file (.dita file extension) as well as any source file with a file extension of xml, html, or md.

Filters

You can apply filters for Site, Version, and Status:

Site

You can choose to show All site configurations that you are assigned as Moderator, Admin, or Owner or you can choose a specific site configuration.

Version

You can choose show All versions for the site configurations that you are assigned as Moderator, Admin, or Owner or you can choose a specific version for the specified site configuration. If the Site filter is set to All, this drop-down includes the name for all the versions available for the currently detected sites. If there are multiple versions with the same name, the name will be shown only once, but the filtering will detect all the versions with the selected name.

Status

You can choose between:

Not resolved (Pending, Open, Reopened) - Displays comments that are in a state of Pending, Open, or Reopened.
Pending - Only displays comments that are in a Pending state.
Open - Only displays comments that are in an Open state.
Reopened - Only displays comments that are in an Reopened state.
Resolved - Only displays comments that are in a Resolved state.
All - Displays all comments.

Note: The filters are persistent between sessions. If the comments are retrieved for the Context DITA map, they are saved in options associated with the context map. Otherwise, they are associated to a ditamap that is determined from the one that is set in the mapping preferences.

Comments Area

Note: Comments are only retrieved for site configurations that you have the role of Moderator, Admin, or Owner.

In the comments area, each comment is displayed as its own box and they are grouped by the topic title or path of the web page where the comments were added and then sorted by date (most recent first). If a DITA topic from context map (or the current topic) can be computed from the web page where a comment is added, you can double-click anywhere in the comment box to open the topic in the main editor. You can also click the group name (the topic title or path) to open the particular topic in the WebHelp output, in your default browser.

At the bottom-right corner of the comment box for each first-level comment (a comment that is not a reply), there is a link to Resolve or Reopen the comment. The Resolve action is only available for first-level comments (not replies) and it marks the comment as Resolved. The Reopen action is only available for resolved comments and it marks the comment as Reopened.

Note: If a new reply is added to a thread that is marked as Resolved, the thread is automatically marked as Reopened.

Each comment box also includes the commenter's name and avatar, the time the comment was added, the state of the comment (e.g. Open, Rejected, Deleted, Resolved, Reopened), the initials of the site configuration, the version number, a link to open the WebHelp topic in your browser (the most specific URL for a version is used), and the content of the comment (up to 4 lines). If you hover over a status badge for comments whose status is Rejected, Deleted, or Resolved, you can see the user name who changed the status and the time it was changed.

If there are more than 20 top-level comments, the comments are retrieved in chunks of 20 (replies are not limited) and there is a Load more comments button at the bottom that will retrieve the next chunk of top-level comments.

Contextual Menu

If you right-click anywhere in a comment box, the contextual menu offers the following actions:

Open topic: If the Feedback for option is set to Context DITA Map and a parent file (from the current DITA map hierarchy) could be determined, selecting this option opens the parent document in the main editor. If the Open topic action is executed on a block-level comment, the parent document is opened and the element that the block-level comment is attached to is highlighted in Author mode (or the cursor is placed at the beginning of the element in Text mode).
Copy content (Ctrl + C): Copies the content of the comment to the system clipboard.
Show comment: Opens a dialog box with the entire comment displayed. You can copy selected content from the comment to the system clipboard by clicking the Copy button at the bottom of the dialog box. If not content is selected, it copies the entire content of the comment.