CMS 10.6 Installing Oxygen Web Service


Prerequisites:
  • System administrators must install Ingeniux CMS 10.6 and have access to the CMS site instance file system. See Installation and Upgrades for details about CMS installations.
  • System administrators must have access to the OxygenWebService.zip compatible with CMS 10.6. Contact Ingeniux Support to obtain the .zip file.
  • Users with DITA configuration permissions must set up the DITA publishing pipeline. See Initial DITA Configuration for details.
    Note
    CMS 10.6 users configure the DITA Root Folder and DTD Folder within Administration > DITA.
  • For users to access templates, CMS administrators must create a folder called Templates in the CMS Assets Manager, and then define the folder ID in the plugin's Web.config.

    Create the folder directly under the Assets root node in the Assets Tree, or create the folder under the DITA root folder to display template resources directly in the Oxygen Desktop Plugin's Ingeniux CMS Browser tab. If you have custom template resources, upload them to this folder.


The Oxygen Desktop Plugin requires Ingeniux CMS 10.6 system administrators to install the Oxygen Web Service in the CMS site instance file directory.
To install the OxygenWebService.zip package for CMS 10.6:
  1. Stop the CMS instance application pool by completing the following steps.
    1. Open Internet Information Services Manager (IIS), and navigate to the CMS instance application pool.
    2. Right-click the application pool, and click Stop.
      The CMS instance stops running.
  2. Access the CMS 10.6 OxygenWebService.zip package on your file system.
  3. Extract OxygenWebSevice.zip to the Custom folder within your Ingeniux CMS installation (e.g., [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom\OxygenWebService\).
  4. Configure Web.config via the following steps.
    Important
    If you plan to configure Web Launcher, you can skip configuring Web.config. However, if you plan to use customized Oxygen Desktop Plugin settings and or plan to manually set up the CMS connection for the plugin, then modify the applicable keys.
    1. In the OxygenWebService folder, open Web.config in a text editor.
    2. Provide the appropriate values for the following keys:
      <?xml version="1.0" encoding="utf-8"?>
      <configuration>
        <appSettings>
          <add key="webpages:Version" value="3.0.0.0" />
          <add key="webpages:Enabled" value="false" />
          <add key="ClientValidationEnabled" value="true" />
          <add key="UnobtrusiveJavaScriptEnabled" value="true" />
          <add key="key" value="ingeniux" />
          <add key="user" value="admin" />
          <add key="lockdown" value="false"/>
          <add key="rootFolderId" value="af/3" />
          <add key="ditaSchema" value="DITA Content" />
          <add key="templatesFolderId" value="af/4" />
          <add key="dtdRootId" value="af/5" />
          <add key="defaultTemplateDescription" value="Custom Template" />
          <add key="javaBinPath" value="C:\Program Files\Java\jdk-12.0.1\bin" />
          <add key="treeChildrenPageSize" value="40"/>
          <add key="allowDelete" value="false"/>
          <add key="contentTitleXpath" value=""/>
          <add key="pluginsFolderId" value="" />
          <add key="customTemplatesOnly" value="true|false"/>
          <add key="prodModeErrorReport" value="false"/>
        </appSettings>
        ... 
                        
      </configuration>
      Key NameDescription
      user

      For implementations with Web Launcher: Skip this key. Web Launcher automatically retrieves the user information from the CMS.

      For implementations without Web Launcher:

      Enter a username value. Provide a valid user that exists in the CMS instance that you will access.

      Note

      The user defined for this key will be a fallback account for operations related to the web service.

      rootFolderId

      The a/ID of the CMS root folder where your DITA assets reside.

      Instead of configuring this value here, configure the DITA Root Folder within Administration > DITA (see prerequisite).

      If you plan to configure Web Launcher, keep in mind that Web Launcher automatically retrieves the folder information from the CMS UI.

      Note
      This Web.config setting serves as a fallback configuration. If the setting is configured in both places, the system references the Administration > DITA setting.
      templatesFolderId

      Enter the af/ID value. Provide the ID of the CMS root folder where your custom template assets reside (see prerequisite).

      dtdRootId

      The a/ID of the DTD folder where your docyment type definitions (DTDs) will reside.

      Instead of configuring this value here, configure the DTD Folder within Administration > DITA (see prerequisite).

      If you plan to configure Web Launcher, keep in mind that Web Launcher automatically retrieves the folder information from the CMS UI.

      Note
      This Web.config setting serves as a fallback configuration. If the setting is configured in both places, the system references the Administration > DITA setting.
      defaultTemplateDescription

      Enter a brief text description for your custom templates.

      javaBinPathIf this filepath doesn't exist on your machine, then change the value to the appropriate filepath (e.g., C:\Program Files\Oxygen XML Editor 25\jre\bin).
      treeChildrenPageSize

      Keep the 40 value as is or enter a new number value.

      This key sets the maximum number of assets to display for any expanded node in the Ingeniux CMS Browser tab and Search Result tab of the Oxygen Desktop Plugin. If a node contains more assets than the maximum defined value, the system doesn't load the extra assets until the user clicks More... in the tree structure.

      allowDelete

      Enter true or false.

      If set to true, users can directly delete DITA assets via the Oxygen Desktop Plugin.

      If set to false (default value), users can only delete DITA assets via the CMS Assets Manager UI.

      contentTitleXpath

      Keep this setting as is or enter the following XPath expression: /*/title.

      If set to /*/title, each DITA asset's title element value displays as the DITA asset's name in the Ingeniux CMS Browser tab tree structure.

      Tip
      To view the DITA asset's file name, content contributors can hover over the DITA asset in the Ingeniux CMS Browser tab. The asset's tooltip displays the file name.

      If set to no value (default), the DITA asset's file name displays in the Ingeniux CMS Browser tab tree structure.

      customTemplatesOnly

      Enter true or false.

      If set to true, users can only select custom templates when creating new document assets.

      If set to false, users can select preconfigured Oxygen XML Editor templates or custom templates when creating new documents.

      prodModeErrorReport

      Enter true or false.

      If set to true, the system removes the stack trace from the CMS instance error report.

      If set to false (default), the system keeps the stack trace in the CMS instance error report.

    3. Save and close Web.config.
  5. Start the CMS instance application pool by completing the following steps.
    1. Open Internet Information Services Manager (IIS), and navigate to the CMS instance's application pool.
    2. Right-click the application pool, and click Start.
      The CMS instance starts running.

Next Steps:

Note
When subsequent CMS 10.6 Oxygen Web Service updates become available, see Updating Oxygen Web Service for details to apply them.

Install the CMS 10.6 Connector in your Oxygen XML Editor authoring client.