CMS 10.6 Installing Oxygen Web Service


  • 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_[version-number].zip compatible with your CMS 10.6 version. Contact Ingeniux Support to obtain the .zip file. See CMS Statistics to check the version.
    • CMS 10.6.492 requires OxygenWebService_1.6.9.zip.
    • CMS 10.6.378 requires OxygenWebService_1.6.6.zip.
    • CMS 10.6.342 requires OxygenWebService_1.6.5.zip.
    • CMS 10.6.308 requires OxygenWebService_1.5.68.zip.
  • Administrators with DITA configuration permissions must set up the DITA publishing pipeline. See Initial DITA Configuration for details.
    Note
    Configure the DITA Root Folder and DTD Folder within Administration > DITA.
  • System administrators must create a Templates folder in the CMS Assets Manager to enable template access for users. Define the folder ID in the plugin's Web.config file.

    Create the folder directly under the DITA Root folder in the Assets Tree. Upload custom template resources to this folder as needed.

Install the Oxygen Web Service in the CMS site instance file directory to enable the Oxygen Desktop Plugin for DITA authoring.

To install the OxygenWebService.zip package for CMS 10.6:
  1. Stop the CMS instance application pool:
    1. Open Internet Information Services Manager (IIS) and navigate to the CMS instance application pool.
    2. Right-click the application pool and select Stop.
      The CMS instance stops running.
  2. Access the CMS 10.6 OxygenWebService_[version-number].zip package on your file system.
  3. Extract the OxygenWebService_[version-number].zip contents to the OxygenWebService folder in [Drive:]\[path-to-cms-site-instance]\App_Data\xml\Custom\.
  4. Configure the Web.config file:
    Important
    Skip this step if you plan to configure Web Launcher. Configure Web.config only if you need customized Oxygen Desktop Plugin settings or plan to manually set up the CMS connection.
    1. Open Web.config in a text editor from the the OxygenWebService folder.
    2. Configure settings as needed for these keys:
      Oxygen Web Service Web.config settings
      <!-- ... -->
          <add key="user" value="admin" />
          <!-- this setting only kicks in when cms doesn't have dita root configured -->
          <!-- <add key="rootFolderId" value="af/50" /> -->
          <add key="ditaSchema" value="DITA Content" />
          <!-- <add key="templatesFolderId" value="af/56" /> -->
          <!-- this setting only kicks in when cms doesn't have DTD root configured -->
          <!-- <add key="dtdRootId" value="af/51" /> -->
          <add key="defaultTemplateDescription" value="Default Template" />
          <add key="treeChildrenPageSize" value="40" />
          <add key="allowDelete" value="true" />
          <add key="contentTitleXpath" value="" />
          <add key="customTemplatesOnly" value="false" />
          <add key="prodModeErrorReport" value="false" />
      <!-- ... -->
      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. The default is admin. 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 asset (a/ID) of the CMS root folder containing your DITA assets.

      Configure the DITA Root Folder within Administration > DITA instead of using this setting (see prerequisite).

      Web Launcher automatically retrieves folder information from the CMS UI.

      Note
      This Web.config setting serves as a fallback. If configured in the CMS UI and Web.config file, the system uses the Administration > DITA setting.
      ditaSchemaName of the asset schema (DITA Content) associated with DITA asset items in the CMS. Leave this value as is.
      templatesFolderId

      Enter the asset folder ID (af/ID) of the CMS root folder containing your custom template assets (see prerequisite).

      dtdRootId

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

      Configure the DTD Folder within Administration > DITA instead of using this setting (see prerequisite).

      Web Launcher automatically retrieves folder information from the CMS UI.

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

      Enter a brief text description for your default templates. The default value is Default Template.

      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 (default value), users can directly delete DITA assets via the Oxygen Desktop Plugin.

      If set to false, 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 (default), 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:
    1. Open Internet Information Services Manager (IIS) and navigate to the CMS instance's application pool.
    2. Right-click the application pool and select Start.
      The CMS instance starts running.

Next Steps:

Note
For subsequent CMS 10.6 Oxygen Web Service updates, see Updating Oxygen Web Service for update procedures.

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