1. Install Oxygen XML Web Author
2. Install REST Plugin
3. Configure REST Plugin
4. Optional: Configure Security
5. Install Custom App
6. Configure CMS local-appsettings.config
7. Configure Custom App Web.config
8. Create Custom Tab
9. Test Oxygen XML Web Author

After completing installation, you can update Oxygen XML Web Author when new versions become available. See the Upgrade section for update steps.

1. Download Oxygen XML Web Author version 25 or 24 from the Oxygen XML website.
   Important

   • Oxygen XML Web Author version 26 is incompatible with Ingeniux CMS. Use version 24 or 25 only.
   • This proprietary authoring tool requires a license purchase. Contact Ingeniux Support for licensing information.
2. Run oxygenxml-web-author-64bit.exe and follow the setup wizard steps.
   Important

   • Install on the same server as your CMS for optimal performance unless otherwise directed. Once security credentials are in place, the CMS connects to Oxygen XML Web Author from any accessible web server.
   • Remember the Server Port number you use during the installation—you'll need this number for subsequent configuration steps.

   The installation opens the Oxygen XML Web Author License Configuration page in your web browser. The URL format depends on your server and port configuration.

   For example:

   http://localhost:8080/config/

3. Select your preferred licensing option and follow the on-screen Oxygen XML Web Author application instructions to activate your license.

   For detailed licensing steps, see Oxygen XML Web Author Installation.

4. Keep the Oxygen XML Web Author application open after license activation and navigate to the Dashboard to prepare for REST plugin installation.

1. Open the Oxygen XML Web Author application in your web browser.
   Tip

   The URL format depends on your server and port configuration. For example:

   http://localhost:8080/oxygen-xml-web-author/app/oxygen.html

2. Click Administration Page in the top-right application corner.
3. Navigate to Settings > Plugins.
4. Click the Upload Plugin button.
5. Browse to and select the REST plugin from Ingeniux Support in File Explorer.
   The REST Connector - Ingeniux OAuth plugin displays highlighted at the top of the plugin list and is automatically enabled.
6. Restart Oxygen XML Web Author to activate the plugin:
   1. Navigate to the Oxygen XML Web Author installation directory on your server.
   2. Run the Manage Web Author application.
   3. Select the General tab.
   4. Click Stop, then click Start.
      This restarts the application.
   5. Click OK.
7. Refresh the Oxygen XML Web Author application in your web browser.
   The REST plugin is active and ready for configuration.

1. Navigate to Settings > Plugins in the Oxygen XML Web Author Administration Page.
2. Locate the REST Connector - Ingeniux OAuth, and click Configure...
3. Complete the following fields in the Plugin configuration dialog:

   Field	Description
   REST Server URL	Enter your CMS URL followed by /automated/OxygenApi/. Example format: http://[cms-site-name]/automated/OxygenApi/
   REST Client ID	Enter the Client ID from your OAuth identity, per prerequisites.
   REST Client_Sec	Enter the Client Secret value from your OAuth identity, per prerequisites.
   use_invisible_login checkbox	Select the use_invisible_login checkbox.

4. Click Apply.
5. Restart the Oxygen XML Web Author to apply the plugin configuration changes.

1. Open to the Oxygen XML Web Author application in your web browser.
   Tip

   The URL format depends on your server and port configuration. For example:

   http://localhost:8080/oxygen-xml-web-author/app/oxygen.html

2. Click Administration Page in the top-right application corner.
3. Navigate to Settings > Security.
4. Select the Only allow connections to these trusted hosts option in the Firewall section.
5. Enter your CMS base URL or domain in the provided field. Use separate lines for multiple hosts.

   For example:

   mydomain

   mycms.ingeniux.com

   Note

   Alternatively, select the Allow All Connections option to permit all connections without specifying trusted hosts. Select the Log Each Connection checkbox to log all outgoing connections.
6. Click Apply.

   Oxygen Web Author restricts connections to the specified trusted hosts only.

1. Locate the OxygenWebAuthorApp.zip file from Ingeniux Support.
2. Extract OxygenWebAuthorApp.zip contents to the OxygenWebAuthorApp folder in [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom\.

1. Navigate to [Drive:]\[path-to-cms-site-instance] and open local-appsettings.config in a text editor.
2. Copy and paste the AntiForgery:AllowedPaths setting to <appSettings>:

   local-appsettings.config AntiForgery:AllowedPaths setting

   <add key="AntiForgery:AllowedPaths" value="/automated/OxygenApi/**" />

   This setting allows the CMS to bypass anti-forgery token validation for Oxygen API calls.

3. Save and close local-appsettings.config.

1. Navigate to [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom\OxygenWebAuthorApp and open Web.config in a text editor.
2. Update the <add> element with @key="OxygenAuthorBaseURL". The @value depends on your CMS version.
   CMS 10.6.492

   Set the @value attribute to your Oxygen XML Web Author URL and append ?author={0}&url=rest%3A%2F%2Fcms%2F{1} to the end of the URL.

   Example URL configuration:

   CMS 10.6.492 OxygenAuthorBaseUrl setting

   <add key="OxygenAuthorBaseUrl" value="http://localhost:8080/oxygen-xml-web-author/app/oxygen.html?author={0}&amp;url=rest%3A%2F%2Fcms%2F{1}" />

   CMS 10.6.308–10.6.378

   Set the @value attribute to your Oxygen XML Web Author URL and append ?author={0}&url=rest%3A%2F%2F{1} to the end of the URL.

   Example URL configuration:

   CMS 10.6.308–10.6.378 OxygenAuthorBaseUrl setting

   <add key="OxygenAuthorBaseUrl" value="http://localhost:8089/oxygen-xml-web-author/app/oxygen.html?author={0}&amp;url=rest%3A%2F%2F{1}" />

   Note

   The URL parameters {0} and {1} are placeholders that the CMS will replace with actual values during runtime.
3. Update the <add> element with @key="OxygenRootFolder". Set the @value attribute to the asset ID of the DITA root folder.Example configuration:

   OxygenRootFolder setting

   <add key="OxygenRootFolder" value="af/7"/>

4. Save and close Web.config.
5. Recycle the CMS instance application pool to apply your configuration changes:
   1. Open Internet Information Services Manager (IIS) and locate the CMS application pool.
   2. Right-click the application pool and click Recycle.

1. Navigate to Administration > System Options > CMS > Custom Tabs > Management.
2. Click Add to create the custom tab.
3. Enter a Name for the new custom tab (e.g., Oxygen XML Web Author).
4. Enter the following URL:

   Oxygen Web Author URL

   
                   Apps/OxygenWebAuthorApp/OxygenRedir
                 

5. Select the Attach to Assets checkbox and clear the Global App checkbox in the Scope section.
6. Click Save in the top-left corner of Custom Tabs Management Configuration.
   The custom tab is now available for DITA asset editing

   

1. Access your CMS with the configured Oxygen XML Web Author integration.
2. Navigate to Assets > Asset Tree.
3. Check out a DITA asset and select the Oxygen XML Web Author custom tab.
4. Verify the checked-out DITA asset loads and can be edited within the custom tab.
   Troubleshooting

   If the custom tab fails to load, review all installation steps for completeness. For persistent issues, contact Ingeniux Support.

   

Oxygen XML Web Author is now successfully integrated with your CMS.

Next Steps:

• System administrators can configure additional customization settings in the Oxygen Web Author installation options.xml file. See Oxygen XML Web Author 25.1: Configuring Options for details.
• Edit DITA content using the integrated tools within Oxygen XML Web Author. See Oxygen XML Web Author 25.1 Reviewing and Editing Documents for details.

1. Stop the CMS application pool:
   1. Open Internet Information Services Manager (IIS) and locate your the CMS instance application pool.
   2. Right-click the application pool and select Stop.
      The CMS instance stops running.
2. Back up your existing Web.config file from [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom\OxygenWebAuthorApp\ to preserve your current settings.
   Note

   You will merge your existing settings with the updated Web.config file in a later step.
3. Delete all contents from the existing [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom\OxygenWebAuthorApp\ folder.
   Important

   Remove all files and subfolders from the OxygenWebAuthorApp directory before extracting the new package contents.
4. Extract all contents from the target OxygenWebAuthorApp.zip package version to the [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom\OxygenWebAuthorApp\ folder.
   The updated files populate the OxygenWebAuthorApp folder, including a new Web.config file.
5. Merge your backed-up Web.config settings with the new Web.config file to preserve your existing configuration:
   Tip

   Compare the backed-up file with the new file to identify which settings need to be transferred. Key settings typically include OxygenAuthorBaseUrl, OxygenRootFolder, and custom values.
   1. Open both the backed-up Web.config and the new Web.config in a text editor.
   2. Compare and copy your custom settings from the backed-up file to the corresponding locations in the new file.
   3. Save the updated Web.config file.
6. Start the CMS application pool:
   1. Open Internet Information Services Manager (IIS) and locate your CMS application pool.
   2. Right-click the application pool and select Start.
      The CMS starts running.