Import and configure system files

This procedure describes the system files to import and configure for DITA CMS.

The configuration changes below are required to support the new 4.3 features and updates, such as:
  • Subject schemes
  • Incremental localization
  • Pivot language localization
  • Modifications to the linguisticReview.xml DTD

For more information about these new features, see the What's New in DITA CMS 4.4 document.

To upgrade your Content Store:

  1. Open a TEXTML Server Console Java.
  2. Connect to the server and Content Store to upgrade.
  3. Make a backup of the linguisticReview.xml file:
    1. Expand the Content Store's Repository node and browse to the /system/conf folder.
    2. Right-click the linguisticReview.xml file and select Rename.
    3. In the New Document Name box, enter linguisticReview.cms42.xml.
    4. Click OK.
  4. If you customized your Preview view, make a backup of your html folder and some files in the resource folder. The Preview view is now based on the xhtml plugin of the DITA OT 2.3.1.
    1. Expand the Repository node and browse to /system/xsl/html.
    2. Right-click the html folder and click Rename.
    3. In the New Collection Name box, type a new name for the folder so it will not be overwritten when you import the new files. For example, html_backup.
    4. Click OK.
    5. Browse to the /system/xsl/resource folder.
    6. Right-click the commonltr.css file and click Rename.
    7. In the New Document Name box, type a new name for the file so it will not be overwritten when you import the new files. For example, commonltr.backup.css.
    8. Click OK.
    9. Repeat the previous steps to rename the commonrtl.css and messages.xml files.
  5. Insert system files:
    1. Right-click the Repository node and select Insert Documents.
      The Insert Documents Dialog window appears.
    2. Click Add Folder and browse to the base-upgrade\system folder in the upgrade package directory (for example, C:\ixiasoft\DITA_CMS_4.3_upgrade_package\base-upgrade\system).
    3. Select the system folder and click OK.
      The system folder is listed in the Insert Documents Dialog window.
    4. Select the Add and Replace options in the Set Options panel and leave Indexable unchecked.
      For example:
      Set options
    5. Click OK to import the system files.
  6. If you are using the linguistic review feature, add the classes of the elements you do not want translated in the updated linguisticReview.xml file:
    1. Expand the Content Store's Repository node and browse to the /system/conf folder.
    2. Open the linguisticReview.cms42.xml file in an XML editor.
    3. Right-click the linguisticReview.xml file and select Check Out.
    4. Open the linguisticReview.xml file in an XML editor.
    5. Add the name attribute values from linguisticReview.cms42.xml to the linguisticReview.xml file.
      Note: The element name was renamed from <className> to <class>, so be careful when copying and pasting the name attribute values between the two files.
    6. Save and check in the linguisticReview.xml file.
  7. Add new icons to the equivalence.xml file:
    1. In the /system/conf folder, right-click the equivalence.xml file and select Check Out.
    2. Open the file.
    3. In the map type, look for the <object type="subjectScheme"/> element:
      For example:
      <equivalence type="map" standardSearch="true" groupName="Maps">
      		<object type="map"/>
      		<object type="bookmap" icon="/system/conf/icons/bookmap-icon.png"/>
      		<object type="subjectScheme"/>
      
      </equivalence>
    4. Add the icon attribute as follows:
      <equivalence type="map" standardSearch="true" groupName="Maps">
      	<object type="map"/>
      	<object type="bookmap" icon="/system/conf/icons/bookmap-icon.png"/>
      	<object type="subjectScheme" icon="/system/conf/icons/subjscheme.png"/>
      </equivalence>
    5. In the topic type, look for the <object type="glossentry"/> element:
      For example:
      <equivalence type="topic" standardSearch="true" groupName="Topics">
         <object type="topic"/>
         ...
         <object type="glossentry"/>
         ...
      </equivalence> 
    6. Add the icon attribute as follows:
      <equivalence type="topic" standardSearch="true" groupName="Topics">
         <object type="topic"/>
         ...
         <object type="glossentry" icon="/system/conf/icons/glossentry.png"/>
         ...
      </equivalence>
    7. Save and check in the file.
  8. Integrate the Subject Scheme DTD into the IxiaMap.dtd:
    1. In the /system/plugins/com.ixiasoft.dita.dtd/dtd folder, right-click the IxiaMap.dtd file and select Check Out.
    2. Open the file.
    3. Look for the MAP ENTITY DECLARATIONS section.
      For example:
      <!-- ============================================================= -->
      <!--                    MAP ENTITY DECLARATIONS                    -->
      <!-- ============================================================= -->
      
      <!ENTITY % bookmap-dec 
        PUBLIC "-//OASIS//ENTITIES DITA 1.2 BookMap//EN" 
               "../../../dtd/bookmap/dtd/bookmap.ent"
      >%bookmap-dec;
    4. At the end of this section, add the following code:
      <!ENTITY % subjectScheme-dec 
        PUBLIC "-//OASIS//ENTITIES DITA 1.2 Subject Scheme Map//EN" 
               "../../../dtd/subjectScheme/dtd/subjectScheme.ent"
      >%subjectScheme-dec;
    5. Look for the DOMAINS ATTRIBUTE OVERRIDE section.
      For example (the actual code may vary):
      <!-- ============================================================= -->
      <!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
      <!-- ============================================================= -->
      <!--                    Must be declared ahead of the DTDs, which
                              puts @domains first in order               -->
      <!ENTITY included-domains 
                              "&bookmap-att;
                               &delay-d-att;
                               &mapgroup-d-att;
                               ...
    6. After the &mapgroup-d-att; code, add the following code:
       &subjectScheme-att;
      For example:
      <!-- ============================================================= -->
      <!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
      <!-- ============================================================= -->
      <!--                    Must be declared ahead of the DTDs, which
                              puts @domains first in order               -->
      <!ENTITY included-domains 
                              "&bookmap-att;
                               &delay-d-att;
                               &mapgroup-d-att;
                               &subjectScheme-att;
                              ...
    7. Look for the MAP ELEMENT INTEGRATION section.
      For example:
      <!-- ============================================================= -->
      <!--                    MAP ELEMENT INTEGRATION                    -->
      <!-- ============================================================= -->
      
      <!ENTITY % map-type 
        PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Map//EN" 
               "../../../dtd/base/dtd/map.mod"
      >%map-type;
      
      <!ENTITY % bookmap-type 
        PUBLIC "-//OASIS//ELEMENTS DITA 1.2 BookMap//EN" 
               "../../../dtd/bookmap/dtd/bookmap.mod"
      >%bookmap-type;
    8. At the end of this section, add the following code:
      <!ENTITY % subjectScheme-type 
        PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Subject Scheme Map//EN" 
               "../../../dtd/subjectScheme/dtd/subjectScheme.mod"
      >%subjectScheme-type;
    9. Save and check in the file.
  9. Integrate the Subject Scheme DTD into the IxiaMap-releasemanagement.dtd:
    Note: Perform this step even if you are not using DRM.
    1. In the /system/plugins/com.ixiasoft.dita.dtd/dtd folder, right-click the IxiaMap-releasemanagement.dtd file and select Check Out.
    2. Open the file.
    3. Look for the MAP ENTITY DECLARATIONS section.
      For example:
      <!-- ============================================================= -->
      <!--                    MAP ENTITY DECLARATIONS                    -->
      <!-- ============================================================= -->
      
      <!ENTITY % bookmap-dec 
        PUBLIC "-//OASIS//ENTITIES DITA 1.2 BookMap//EN" 
               "../../../dtd/bookmap/dtd/bookmap.ent"
      >%bookmap-dec;
    4. At the end of this section, add the following code:
      <!ENTITY % subjectScheme-dec 
        PUBLIC "-//OASIS//ENTITIES DITA Subject Scheme Map//EN" 
               "../../../dtd/subjectScheme/dtd/subjectScheme.ent"
      >%subjectScheme-dec;
    5. Look for the DOMAINS ATTRIBUTE OVERRIDE section.
      For example (the actual code may vary):
      <!-- ============================================================= -->
      <!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
      <!-- ============================================================= -->
      <!--                    Must be declared ahead of the DTDs, which
                              puts @domains first in order               -->
      <!ENTITY included-domains 
                              "&bookmap-att;
                               &delay-d-att;
                               &mapgroup-d-att;
                               ...
    6. After the &mapgroup-d-att; code, add the following code:
       &subjectScheme-att;
      For example:
      <!-- ============================================================= -->
      <!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
      <!-- ============================================================= -->
      <!--                    Must be declared ahead of the DTDs, which
                              puts @domains first in order               -->
      <!ENTITY included-domains 
                              "&bookmap-att;
                               &delay-d-att;
                               &mapgroup-d-att;
                               &subjectScheme-att;
                              ...
    7. Look for the MAP ELEMENT INTEGRATION section.
      For example:
      <!-- ============================================================= -->
      <!--                    MAP ELEMENT INTEGRATION                    -->
      <!-- ============================================================= -->
      
      <!ENTITY % map-type 
        PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Map//EN" 
               "../../../dtd/base/dtd/map.mod"
      >%map-type;
      
      <!ENTITY % bookmap-type 
        PUBLIC "-//OASIS//ELEMENTS DITA 1.2 BookMap//EN" 
               "../../../dtd/bookmap/dtd/bookmap.mod"
      >%bookmap-type;
    8. At the end of this section, add the following code:
      <!ENTITY % subjectScheme-type 
        PUBLIC "-//OASIS//ELEMENTS DITA 1.3 Subject Scheme Map//EN" 
               "../../../dtd/subjectScheme/dtd/subjectScheme.mod"
      >%subjectScheme-type;
    9. Save and check in the file.
  10. In your own shell DTDs, perform the previous steps on your map DTDs to integrate the SubjectScheme DTD.
    This step is essential, otherwise you will not be able to use subject schemes in your specialized maps.
    Note: Contact IXIASOFT Support if you need help with this step.
  11. Remove the old system ID for the SubjectScheme DTD:
    1. Browse to the /system/conf folder.
    2. Right-click the systemid.xml file and select Check Out.
    3. Open the systemid.xml file.
    4. Look for the Subject Scheme reference:
      <reference public="-//OASIS//DTD DITA Subject Scheme Map//EN" system="subjectScheme.dtd"/>
    5. Remove this line from the file.
    6. Save and check in the systemid.xml file.
  12. If you had not customized the eclipseui.xml file for your deployment, use the new version provided in DITA CMS 4.3:
    The default file was updated so that the initial UI is simplified. If you already customized your eclipseui.xml file, you can skip this step.
    1. Expand the Content Store's Repository node and browse to the /system/conf folder.
    2. Right-click the eclipseui.xml file and select Rename.
    3. In the New Document Name box, enter eclipseui.cms42.xml.
    4. Click OK.
    5. Right-click the eclipseui.new_cms43_version.xml file and select Rename.
    6. In the New Document Name box, enter eclipseui.xml.
    7. Click OK.
  13. Replace the type name="*" elements with specific object types in the accessrights.xml file for all front-end methods:
    These changes are required to fix errors that occur when an object does not have one of the cycles specified and users select the method in the interface. For example, consider the following code for the "Assign to" method:
    <method name="Assign to" type="front-end" hide-when-disabled="true">
    		<!-- determines if a notification email should be sent when this action is taken -->
    		<notify enabled="false"/>
    		<!-- To be enabled or runnable the condition set must return true -->
    		<!-- possible operator are any (One of the condition must match)-->
    		<conditionset operator="any">
    			...
    			<condition>
    				<!-- Object on which action is taken -->
    				<current>
    					<type name="*">
    						<statuses>
    							<status>Localization:*</status>
    						</statuses>
    					</type>
    				</current>
    This code indicates that the Assign to method can be applied to all the object types in the Localization cycle. However, the Localization cycle does not exist for objects of type build-manifest or snapshot, so the code above will create errors when users try to run the "Assign to" command in the user interface.
    Note: This step applies only for front-end methods, that is, methods with the type="front-end" attribute; for example:
    <method name="Assign to" type="front-end" hide-when-disabled="true">
    		<!-- determines if a notification email should be sent when this action is taken -->
    		<notify enabled="false"/>

    To prevent these issues:

    1. Expand the Content Store's Repository node and browse to /system/conf folder.
    2. Right-click the accessrights.xml file and select Check Out.
    3. Open the accessrights.xml file in an XML editor.
    4. Locate the first <type name="*"> element.
      For example:
      <method name="Assign to" type="front-end" hide-when-disabled="true">
      		<!-- determines if a notification email should be sent when this action is taken -->
      		<notify enabled="false"/>
      		<!-- To be enabled or runnable the condition set must return true -->
      		<!-- possible operator are any (One of the condition must match)-->
      		<conditionset operator="any">
      			...
      			<condition>
      				<!-- Object on which action is taken -->
      				<current>
      					<type name="*">
      						<statuses>
      							<status>Localization:*</status>
      						</statuses>
      					</type>
      				</current>
    5. If the method is of type="front-end" (as shown above in bold), duplicate the <type name="*"> element for each object type to which this action applies and replace the "*" value with the object type.
      For example, if the action applies to maps, topics, images, and resources, replace the <condition> code above with the following:
      <condition>
         <!-- Object on which action is taken -->
         <current>
            <type name="map">
               <statuses>
                 <status>Localization:*</status>
               </statuses>
            </type>
            <type name="topic">
               <statuses>
                  <status>Localization:*</status>
               </statuses>
            </type>
            <type name="image">
               <statuses>
                  <status>Localization:*</status>
               </statuses>
            </type>
            <type name="resource">
               <statuses>
                 <status>Localization:*</status>
               </statuses>
            </type>
         </current>
         <!-- Action user must be in this list -->
         <users>
         ...
      </condition>
    6. Repeat for all <type name="*"> elements of front-end methods in the file.
    7. Save the accessrights.xml file.
  14. Update the access rights for the Edit Variables method to ensure it is available to the appropriate users at the appropriate status only:
    1. In the accessrights.xml file, look for the Edit Variables method.
      It should look as follows (the actual code may differ according to your deployment):
      <method name="Edit Variables" type="front-end" hide-when-disabled="true">
      	<!-- determines if a notification email should be sent when this action is taken -->
      	<notify enabled="false"/>
      	<!-- To be enabled or runnable the condition set must return true -->
      	<!-- possible operator are any (One of the condition must match)-->
      	<conditionset operator="any">
      		<condition>
      			<current>
      				<type name="map">
      					<statuses>
      						<status>Authoring:*</status>
      					</statuses>
      				</type>
      			</current>
      			<!-- Action user must be in this list -->
      			<users>
      				<groups>
      					<group name="System Administrators"/>
      					<group name="Everyone"/>
      				</groups>
      				<roles/>
      			</users>
      		</condition>
      	</conditionset>
      </method>
    2. Change the <status> element to Authoring:work (or the equivalent for your deployment).
      For example:
      <type name="map">
         <statuses>
            <status>Authoring:work</status>
         </statuses>
      </type>
    3. Set the <users> element to the groups and roles that can run this command.
      For example:
      <users>
         <roles>
            <role name="Information Architect"/>
            <role name="Writer"/>
         </roles>
         <groups>
            <group name="System Administrators"/>
         </groups>
      </users>
    4. Save the accessrights.xml file.
  15. Update the access rights for the Insert Variables method to ensure it is available to the appropriate users at the appropriate status only:
    1. In the accessrights.xml file, look for the Insert Variables method.
      It should look as follows (the actual code may differ according to your deployment):
      <method name="Insert Variables" type="front-end" hide-when-disabled="true">
      	<!-- determines if a notification email should be sent when this action is taken -->
      	<notify enabled="false"/>
      	<!-- To be enabled or runnable the condition set must return true -->
      	<!-- possible operator are any (One of the condition must match)-->
      	<conditionset operator="any">
      		<condition>
      			<current>
      				<type name="map">
      					<statuses>
      						<status>Authoring:*</status>
      					</statuses>
      				</type>
      			</current>
      			<!-- Action user must be in this list -->
      			<users>
      				<groups>
      					<group name="System Administrators"/>
      					<group name="Everyone"/>
      				</groups>
      				<roles/>
      			</users>
      		</condition>
      	</conditionset>
      </method>
    2. Change the <status> element to Authoring:work (or the equivalent for your deployment).
      For example:
      <type name="map">
         <statuses>
            <status>Authoring:work</status>
         </statuses>
      </type>
    3. Set the <users> element to the groups and roles that can run this command.
      For example:
      <users>
         <roles>
            <role name="Information Architect"/>
            <role name="Writer"/>
         </roles>
         <groups>
            <group name="System Administrators"/>
         </groups>
      </users>
    4. Save and check in the accessrights.xml file.
  16. Add the Assignments Comments column to the display.xml file:
    1. In the /system/conf folder, right-click the display.xml file and select Check Out.
    2. Open the file.
    3. Add the following <key> element to the file, in a <columns> element:
      Note: Add the key in alphabetical order of label.
      <key halign="LEFT" label="Assignment Comments" name="assignment_comment" sortOrder="ASC" sortType="ALPHA" type="Index" visibility="255" width="30"/>
      
    4. Save and check in the file.
  17. Edit the resources.xml file to add a type for non-DITA files and remove an unknown type, if present:
    1. Right-click the /system/conf/resources.xml file and click Check Out.
    2. Double-click the file to open it in the XML editor area.
    3. Add the following lines to the file:
      <!-- Default type used by the import process -->
      <type description="">unknown</type>

      For example, the file should look as follows:

      <resource>
      	<resourcetypes>
      		<type description="">pdf-graphics</type>
      		<type description="">pdf-legal</type>
      		<type description="">css</type>
      		<type description="">html</type>
      		<!-- Default type used by the import process -->
      		<type description="">unknown</type>
      	</resourcetypes>
      </resource>
    4. If the <type description="">ditaval-file</type> line is present, remove it from the file.
    5. Save and check in the file.
  18. Edit the users.dtd file to prevent text from being added in the <role> and <group> elements.
    1. Browse to /system/conf/ to locate the users.dtd file.
    2. Right-click the file and click Check Out.
    3. Double-click the file to open it in the XML editor area.
    4. Locate the element <!ELEMENT role (#PCDATA) and replace (#PCDATA) with EMPTY.
      For example: <!ELEMENT role EMPTY
    5. Locate the element <!ELEMENT group (#PCDATA) and replace (#PCDATA) with EMPTY.
      For example: <!ELEMENT group EMPTY
    6. Save, close, and check in the file.
  19. Update the DITA CMS version in the configuration:
    1. Right-click the /system/conf/textmlservercfg.properties file and select Check out.
    2. Open the file.
    3. Set the value of ixia.cms.version to the build of the DITA CMS that you are installing.
      For example:
      ixia.cms.version=1.2.3
    4. Save and check in textmlservercfg.properties.
  20. If you had customized your Preview view, use your backup copy to re-implement your changes to the Preview view.