What's New in DITA CMS 4.2

Transcription

1 What's New in DITA CMS / DITACMS v. 4.2 / Copyright 2015 IXIASOFT Technologies. All rights reserved. Last revised: October 22, 2015

2

3 Table of contents 3 Table of contents Chapter 1: New DITA CMS 4.2 features Improved performance 8 Creating and generating reports 8 Understanding reports 8 Create viewpoints 9 Create a TEXTML Server query 13 About reports 15 Generate a report manually 23 Generate reports using the Scheduler 24 Improvements in DITA CMS document assignments 24 Add comments to DITA CMS assignments 25 Import a taxonomy from a TSV text file 27 Delete a taxonomy from the Taxonomy Terms view 28 Miscellaneous improvements to the DITA CMS 29 Availability of the DITA CMS in Japanese 29 Setting the image description when importing images 30 Chapter 2: New DITA CMS 4.2 Administration features Simplifying the interface of the DITA CMS Eclipse Client 32 About the simplified user interface feature 32

4 4 What's New in DITA CMS 4.2 Simplifying the user interface 33 Enable the trace log 47 Obtain the list of IDs in a trace log for a perspective 48 Simplify a perspective 50 Location-based groups 51 Create location-based groups from the TEXTML Administration view 51 Create location-based groups by editing groups.xml 52 Scheduler improvements 53 Schedule user-defined reports created with the DITA CMS 53 DITA-OT Chapter 3: New Web Author 4.2 features Configuring the Web Author startup page 58 Configure the Web Author startup page in the web.author.welcome.xml file58 Insert images in Web Author 58 Enable the Insert image option in the web.author.roles.xml file 58 Insert images in Web Author 59 Specify the editing context 65 Chapter 4: New DRM 4.2 features Snapshots 68 Understanding the Snapshots feature 68 Create a snapshot 69

5 Table of contents 5 Generate the output of a snapshot 70 View the contents of a snapshot 71 Version tags 72 Understanding the Version tag feature 72 Create a version tag 72 Search version tags 73 Create a new version from a version tag 73 Synchronization 75 Understanding the synchronization feature 75 Synchronize two versions 82

6 6 What's New in DITA CMS 4.2

7 1New DITA CMS 4.2 features New DITA CMS 4.2 features Topics: Improved performance Creating and generating reports Improvements in DITA CMS document assignments Import a taxonomy from a TSV text file Delete a taxonomy from the Taxonomy Terms view Miscellaneous improvements to the DITA CMS Availability of the DITA CMS in Japanese Setting the image description when importing images This section describes the new features introduced in this release of the DITA CMS.

8 8 What's New in DITA CMS 4.2 Improved performance Operation speed has been greatly improved on most actions, including: Search, Lock, Release, Replace with Server Revision, Open Map, and Display Dependency View. Creating and generating reports You can create and generate reports using the DITA CMS. Understanding reports This section provides an overview of reports and describes how to generate them using the DITA CMS. What are reports? A report contains all the information generated from a saved TEXTML search query in DITA CMS. The search results are presented according to a defined viewpoint, which arranges the search results into groups and displays them using a defined set of columns. The report is generated as an HTML output using an XSL transformation template.the following diagram shows a sample report: Generating reports There are two ways to generate search reports:

9 New DITA CMS 4.2 features 9 Manually from the DITA CMS: In this scenario, a report is generated directly from the search query panel (Search > Queries > Reports). Automatically using the Scheduler: In this scenario, a report is scheduled at a specific time interval and the report is generated as a Scheduler job. The Scheduler reviews the Content Store for any scheduled reports. If there are reports scheduled, the Scheduler retrieves all the relevant information (for example: query name, viewpoint, etc.) about each report and processes the reports according to their scheduled entries. The Scheduler service must be configured and running for the report to be generated. The report is sent as an to a specified list of recipients. To generate a report you: 1. Create a viewpoint. 2. Create a TEXTML Server query. 3. Create a report. 4. Generate the report manually or automatically (using the Scheduler). This section shows how to generate a sample report using the Topics in Authoring:work search criteria. Create viewpoints To create a report you have to create a viewpoint. A viewpoint is a combination of grouping fields and display columns that allows you to organize search results. They are useful when you are performing broad searches that produce a large number of search results. When a viewpoint is selected, the search results are automatically arranged into fields and displayed according to specific columns. To create viewpoints: 1. In the DITA CMS, click the Search Results tab to display the view. 2. In the Search Results view, click the Manage Viewpoint button ( ). The Manage Viewpoints window appears. For example:

10 10 What's New in DITA CMS Click Create Viewpoint ( ). The Viewpoint Name window appears. 4. Enter a name to identify the viewpoint, then click OK. For example: The new name appears in the Viewpoints list and the Available Fields list is populated with all the available fields to create groupings.

11 New DITA CMS 4.2 features 11 Figure 1: Manage Viewpoints window 5. Select the Grouping Columns tab to add your columns. 6. From the Available Fields panel, select a field, then click the Add button ( ). Your selection moves to the right-hand pane. You can make multiple selections by holding the Shift or Ctrl keys and clicking a field.

12 12 What's New in DITA CMS Use the Move Up ( ) or Move Down ( ) button to organize the desired grouping order. 8. Select the Display Columns to add display columns. 9. From the Available Fields panel, select a display column, then click the Add button ( ). Your selection moves into the right-hand pane. You can make multiple selections by holding the Shift or Ctrl keys and clicking a column. 10. Use the Move Up ( ) or Move Down ( ) button to organize the desired display order. 11. Click OK. Your new viewpoint is now available in the Search View Results. Use viewpoints in search results To use viewpoints in search results: 1. Open the DITA perspective.

13 New DITA CMS 4.2 features Perform a search. Your search results are displayed in the Search Results view. An example of the search results without viewpoint is displayed. 3. In the Search Results view, click Select viewpoint from the drop-down list and select a viewpoint. The search results are organized into folders and display columns according to the viewpoint selected. The example below shows the viewpoint display of the Maps in Authoring:work search results grouped by the following fields: title, status, and last mod by. The results are also displayed in columns according to the selected columns. Click a folder to display the documents within it. 4. To exit the viewpoint mode, click the Select viewpoint drop-down list and select None. Create a TEXTML Server query To create a report you need a TEXTML Server query. A TEXTML Server query retrieves documents from the Content Store that correspond to a specified set of search criteria.you save a TEXTML Server query to store search parameters that you use frequently so you can re-use them. To create a TEXTML Server query: 1. Set up a search in the Search view. For example, the following diagram shows the search criteria for Topics in Authoring:work.

14 14 What's New in DITA CMS To save the criteria as a TEXTML query, click the Save TEXTML Query button ( ) and enter a descriptive name. Note: (Optional) If a viewpoint is already selected in the viewpoint drop-down list, the Save viewpoint with query option is available. Click this option to save the TEXTML query with the currently selected viewpoint. For example: 3. Click OK. The query is saved under Personal Textml in the Queries panel.

15 New DITA CMS 4.2 features 15 About reports This feature allows users to generate reports based on queries that they have created. The report contains all the required information to generate reports from the saved TEXTML Server query in the DITA CMS. Reports are created with the Create report editor as shown below: Figure 2: Create report editor The Create report editor has the following tabs: Report: Specifies all the information required to create a report. XML: Provides the XML view of the report. You cannot modify the XML source. A Report contains four sections: 1. General Information: Select the query, viewpoint, and XSL transformation template used to convert the report to an HTML output, as follows: Field Report name State Description Name given to the report. Select one of the following: To generate the report, select Enabled.

16 16 What's New in DITA CMS 4.2 Field Description Otherwise, select Disabled. This is useful when you are working on a report and do not want to generate it right away. Query Viewpoint Shows all the saved TEXTML search queries. Choose the search query of your choice. Shows all the available viewpoints. Choose the viewpoint of your choice. Note: The color of the Viewpoint field indicates its status, as follows: Red: No viewpoint is selected. The report cannot be Enabled without a viewpoint. Purple: A valid viewpoint is selected, but it is different from the one saved with the TEXTML Server query. Black: The viewpoint selected matched the one in the TEXTML Server query. XSL template Shows all the available templates used to convert the report to HTML. By default, only the report2html.xsl XSL template is available, but additional templates may have been added for your deployment by your CMS System Administrator. Select the template to use for this report. Note to CMS System Administrators: XSL templates are stored in the Content Store's Repository at the following location: /system/xsl/report.you can customize the existing template or create multiple ones as appropriate for your deployment. When you add templates to the location above, they are listed in the XSL template field. Attach Dataset Select this option to receive the report.xml, xsltemplate.xsl, textmlquery.tql, Output.xml, and Output.tsv files as attachments along with the report sent as HTML in the notification. 2. Notify: You can enter a list of all s that should receive the generated report.

17 New DITA CMS 4.2 features 17 Field Type Description address of the person to notify when the report is completed. This does not have to be a DITA CMS user. You can enter multiple addresses. The can be sent directly, as a carbon copy (cc), or as a blind carbon copy (bcc). 3. Parameters: You can define the value of parameters used for the report. These parameters are contained in the selected XSL template. Field Key Value Description Parameter name. Value of the parameter. 4. Schedule: The Schedule allows you to specify the interval at which the report will run. It is a combination of minutes, hours, days, months, and weekdays. Note: This section is only applicable to scheduled reports and requires that the Scheduler be installed and running. Field Value Description Description Enter the exact time to schedule the report. Note: The scheduled value converts to a cron job: <schedule>minute hour day month weekday</schedule> Choose the time interval: minutes, hours, days, months, or days of week. The table below describes various available options for the Value field in the Schedule section. Examples for scheduling in minutes is shown, along with their respective Cron jobs. The scheduling can be extended to hours, days, months, and weekdays.

18 18 What's New in DITA CMS 4.2 Table 1: Schedule values, value description, example for scheduling in minutes, and the respective Cron job Value Description Example - Schedule in minutes Cron job Any Runs every minute Every minute <schedule>* * * * * </schedule> Fixed Runs at a fixed time At 2 minutes past the hour <schedule>2 * * * * </schedule> Range Runs within a certain time range Between 0 through 5 minutes past the hour <schedule>0-5 * * * * </schedule> List Runs at all the listed times At 1,3,5,7,and 9 minutes past the hour <schedule>1,3,5,7,9 * * * * </schedule> Repeated Job repeats itself Every 2 minutes <schedule>*/2 * * * * </schedule> Note: For more information about all available Cron options, see the following URL: Create a report The following procedure describes how to create a report. Before creating a report: Create a viewpoint. Create a TEXTML query. 1. In the Queries panel, right-click the Reports folder. The Create report option appears.

19 New DITA CMS 4.2 features Click Create report. The Create report dialog appears. 3. Enter a Report name, select Open report in default editor, and click OK. For example: The report is created and opened in the DITA CMS, as shown below. The report name is displayed: Note: The created report can also be viewed in the Queries panel.

20 20 What's New in DITA CMS Enter the required information in the report. 5. In the General Information panel: You first have to choose a Query and a Viewpoint before enabling the report. a) Choose the relevant Query from the drop-down list. b) Choose the relevant Viewpoint from the drop-down list. c) In the State field, select ENABLED to receive a report. d) In the XSL template field, select the template. e) To receive the dataset in the , select Attach Dataset. For example: 6. In the Notify panel, enter the list of all s that should receive the generated report. To add recipients: a) Right-click to add, delete, and modify details. For example: b) Choose Add to add a new to the list. A Notify window opens. For example: c) Enter the and choose the type from the drop-down list. d) Click OK.

21 New DITA CMS 4.2 features 21 For example: 7. In the Parameters panel, enter the parameters that are required for the report. Note: Both the Key and Value are configurable from the report2html.xsl template. However, from the Parameters panel only the Value is modifiable. To modify the Value: a) Right-click Value. b) Click Modify to modify the Value. The Report parameters window opens. c) Enter the Value. For example: d) Click OK. For example : 8. In the Schedule panel, specify the time interval at which the report will run. To specify the values:

22 22 What's New in DITA CMS 4.2 a) Double-click the Value field on the line that you want to configure. For example, to set the minutes for the job double-click Value on the Minutes line. The following dialog appears: b) Choose the preferred time from the available options. c) Repeat these steps to set the Hours, Days, Months, and Days of week for the report to be sent. In the following example the report is scheduled for 8:00 AM every day. 9. Save and close the report. An example of the final report is displayed below:

23 New DITA CMS 4.2 features 23 Generate a report manually Generating a report manually is very useful to test that the report includes the correct information. To manually run a report: 1. Select and right-click the report you want to run from the search query panel (Search > Queries > Report > ) folder. 2. Choose Run now from the selection. Once generated, the report is opened using the default HTML browser of your operating system. For example:

24 24 What's New in DITA CMS 4.2 Generate reports using the Scheduler Reports can be generated automatically by setting the Schedule information when creating a report. The Scheduler must be running for this feature to work. Contact your CMS System Administration to confirm that a Scheduler is running and configured to generate reports. Improvements in DITA CMS document assignments Multiple improvements were made to the document assignments. Assignments dialog updated - The Assignments dialog consists of two panes: The left pane displays all the roles that are configured for the types of documents you selected. The right pane displays your selected documents, grouped under the user roles that are responsible for them. The right pane also includes Set Due Date and Edit Comment options that allow you to easily add comments and set due dates to each document according to the user role. For example:

25 New DITA CMS 4.2 features 25 Additional options to view your documents in the Todo list - You now have additional options to group your documents in the Todo List. The new options are: Status - lets you group documents according to the status of the document, such as Authoring:work or Authoring:review. Object type - lets you group documents according to their type, for example, concept, topic, task, and so on. Add comments to DITA CMS assignments This topic describes how to add comments while assigning documents to the users. User roles must already have been configured for each type of document. To add comments in assignments: 1. Right-click the required documents. You can select multiple documents using Ctrl-click or Shift-click. 2. Select Assign to... from the menu. The Assignments dialog appears. 3. Go to the right pane. The right pane displays the selected documents, grouped under the user roles that are responsible for them. For example:

26 26 What's New in DITA CMS Right-click a document and then select Edit Comment. You can select multiple documents under each role using Ctrl-click or Shift-click. A Comment window appears. For example: 5. Enter a comment and click OK. The comment appears in the Comment column. 6. (Optional) If you need to clear the comment from a document, right-click and then select Clear Comment from the menu. 7. Repeat for each document, as required. 8. Click OK in the Assignments dialog when you're finished. To view the comments, go to Todo list/jobs and then right-click RoleComments. The documents and their comments will be displayed in the Todo list. Note: The RoleComments displays all the comments assigned to a document, irrespective of the configured roles. For example, if a document is assigned (with comments) to a writer/author, and the same document is assigned (with different comments) to a reviewer, the RoleComments will display both comments made on the document.

27 New DITA CMS 4.2 features 27 Import a taxonomy from a TSV text file The import taxonomy wizard lets you add one or more taxonomy files prepared outside DITA CMS to the repository. The taxonomy must be specified in a TSV (tab-separated values) text file that reflects the structure of the taxonomy. For example: Figure 3: Sample taxonomy structure (from the Google product taxonomy) To import a taxonomy from a TSV text file: 1. Select File > Import... The Import dialog appears. 2. Open the DITA CMS folder and select Import Taxonomy From TSV Text File. 3. Click Next. The Import Taxonomy From TSV File dialog appears.

28 28 What's New in DITA CMS Click Browse. The Open dialog appears. 5. Navigate to the TSV file, select the desired file, and click Open. The selected TSV file appears in the Taxonomy Title. 6. Click Finish. The taxonomy pane displays the imported taxonomy and is available for you to use. Delete a taxonomy from the Taxonomy Terms view You can now delete a taxonomy from the Taxonomy Terms view. To delete a taxonomy from the Taxonomy Terms view: 1. In the Taxonomy Terms view, right-click the root node of the taxonomy. Note: The taxonomy must not be in editing mode. 2. Select Delete Taxonomy. The Delete Taxonomy dialog opens. For example: 3. Click OK. The taxonomy is removed from the list of taxonomies.

29 New DITA CMS 4.2 features 29 Miscellaneous improvements to the DITA CMS The DITA CMS 4.2 includes miscellaneous improvements. Autorefresh in map view - Selecting a map from the history list now automatically opens the map in the DITA Map Editor. Partial synchronization is now always enabled - Partial synchronization is now always enabled to improve the performance of the DITA CMS. As such, the synchronization page has been removed from the DITA CMS preferences. Options that were on the synchronization page were moved to other pages: To clear information from the cache, select DITA CMS > General Behavior and click Clear Memory Cache. To clear files from your hard drive, select DITA CMS > General Behavior and click Clear Workspace. To synchronize the image thumbnails, select DITA CMS > General Behavior and click Synchronize Image Thumbnails. Export search results - You can export search results and save them in a file outside the repository in three different formats: Tab Separated Value (TSV). Extensible Markup Language (XML). Spreadsheet (XLS) These formats can be imported into other programs such as spreadsheet applications. The Connection Information tooltip for the connection status icon in the toolbar now shows both the roles and groups to which the user belongs. Availability of the DITA CMS in Japanese The DITA CMS is now available in Japanese. The user interface was localized and can be displayed in Japanese, as shown below:

30 30 What's New in DITA CMS 4.2 The user documentation is also available in Japanese. Setting the image description when importing images When importing images, the DITA CMS now uses information from the source topic to set the image description that is saved in the DITA CMS. The Image description is determined as follows: 1. Use the <title> element of the figure. 2. If the <title> element is not available, use: a. the content of the <alt> element, or b. the value of the alt attribute 3. If neither of these are available, the Image description field remains empty. Note: As before, the image filename is always used as the image title.

31 New DITA CMS 4.2 Administration 2features New DITA CMS 4.2 Administration features Topics: Simplifying the interface of the DITA CMS Eclipse Client Location-based groups Scheduler improvements DITA-OT 2.1 This section describes the new features for CMS Administrators.

32 32 What's New in DITA CMS 4.2 Simplifying the interface of the DITA CMS Eclipse Client The simplified user interface (UI) feature allows you to customize the interface of the DITA CMS Eclipse Client according to your preferences. About the simplified user interface feature This section describes the simplified UI feature introduced in DITA CMS 4.2. The purpose of this feature is to simplify the user interface by customizing the layout both when the DITA CMS starts up and in the various DITA CMS perspectives, allowing you to hide the menus, options, and other interface items that users do not need. For example, the following diagram shows the default Import dialog that is displayed when users select File > Import: Since users will only need the import options for the DITA CMS, you can remove the other folders so that users only see these options, as shown below:

33 New DITA CMS 4.2 Administration features 33 You can customize the following aspects of the DITA CMS: DITA CMS startup elements: You can control the elements displayed when users first start up the DITA CMS. This includes items such as the Import menu, the Preferences menu, as well as the perspectives that are opened at startup. The startup configuration is loaded only once, when the DITA CMS starts up. DITA CMS Perspectives: You can customize any DITA CMS perspective according to your preferences. For each perspective, you can customize the following interface elements: menus, submenus, oxygen pop ups and action bar, panels, views, buttons, etc. Note: Not all features are modifiable. The following sections describe how to customize the DITA CMS startup elements and perspectives. Simplifying the user interface Each item in the interface has an ID. To simplify the interface, you add the IDs of the items to remove in the eclipseui.xml configuration file. To obtain the list of IDs, you use the trace log provided by IXIASOFT. The following sections describe the eclipseui.xml and trace log files in details.

34 34 What's New in DITA CMS 4.2 Understanding the eclipseui.xml file The DITA CMS user interface (UI) is customized in the eclipseui.xml configuration file. To remove an item from the interface, you add the item's ID to the eclipseui.xml file. For example, to remove the Edit menu from the Eclipse main menu when the DITA perspective is open, you add the following line: <perspective id="com.ixiasoft.dita.eclipse.gui.perspective.ditaperspective"> <section id="menu"> <removeditem id="edit"/> </section> </perspective> The eclipseui.xml file has the following structure: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE eclipseui PUBLIC "-//ixiasoft.com//cms//config//eclipseui" "eclipseui.dtd"> <eclipseui> <perspective id="perspective_id"> <section id="section_id">...items to remove... <removeditem id="item_id"/>...or items to close/minimize... <item id="item_id" state="minimized"/> </section> </perspective> </eclipseui> There are three main elements in this file: <perspective> <section> <removeditem> or <item> Perspectives The interface is configurable by perspective, so the first sub-element is the <perspective> element, as shown above. There are two types of perspectives: The startup perspective: This is not an Eclipse perspective per se. It's the configuration that is executed when the DITA CMS starts up. This configuration lets you customize the File > Import and Window > Preferences menus as well as the perspectives that are shown to users when they start the DITA CMS. The ID of the startup perspective is ixiasoft.eclipse.startup. Regular perspectives such as the DITA perspective, the Information Architect perspective, the RelTable Editing perspective, etc.: For each perspective, you can customize the menus, submenus, oxygen pop ups and action bar, panels, views, buttons, and so on.

35 New DITA CMS 4.2 Administration features 35 The IDs for the main DITA perspectives are: DITA: com.ixiasoft.dita.eclipse.gui.perspective.ditaperspective Information Architect: com.ixiasoft.dita.eclipse.gui.perspective.leadperspective You can use the trace log to identify the ID of the other perspectives. Sections Each perspective has sections that can be customized. The startup perspective has 3 specific sections: Table 2: Sections of the startup perspective Section ID import preferences perspective Description Removes items from the File > Import menu. Removes items from the Window > Preferences menu. Configures the perspectives that are closed when the DITA CMS starts. For example, the Java perspective is opened by default when customers run the DITA CMS Eclipse Client for the first time. By customizing the perspective section you can now close the Java perspective when the DITA CMS first starts. There are 12 sections supported in a regular perspective: Table 3: Sections of the regular perspectives Section ID menu submenu oxygenpopup Description Removes items from the main Eclipse menu bar (for example, the Project menu). Removes options (submenus) from the main Eclipse menus (for example, the Print option from the File menu). Removes options from the oxygen right-click menu (for example, Edit Attributes).

36 36 What's New in DITA CMS 4.2 Section ID oxygenactionbar panels views com.ixiasoft.dita. eclipse.gui.views. map.mapview com.ixiasoft.dita. eclipse.gui.views. sidebar.searchgui MiniBar com.ixiasoft.dita. eclipse.gui.views. sidebar.sidebar com.ixiasoft.dita. eclipse.gui.views. sidebar.sidebarresults com.ixiasoft.dita. eclipse.gui.views. job.jobview toolbar Description Removes options/buttons from the XML main menu, the oxygen toolbar on the top-level toolbar, and the oxygen toolbar in the oxygen editor (for example, Validate). Removes panels from the Search view (for example, the Advanced Search panel). Closes or minimizes views (for example, the DITA Map view). Removes buttons from the Map View (for example, the Set Conditions button). Removes the menu bar (i.e., the 4 buttons) from the Cycles, Document Types, Limit to, and Languages panels in the Search view. Removes the New Query, Save Query, Save XML Query, and Show/Hide Panels buttons from the Search view. Removes the Clear Results List, Export Results List, Search and Replace, Manage Groupings, and Turn On/Off Thumbnail Display buttons from the Search Results view. Removes the Refresh Todo List, Export Todo List, Show Statistics, Select Groupings, and Turn On/Off Thumbnail Display buttons from the Todo List view. Removes buttons from the toolbar at the top of the DITA CMS. Items to remove, close, or minimize There are two different elements used to customize each interface items: <removeditem>: Applies to items that can either be removed or displayed (such as a menu option). <item>: Applies to items that can be removed, displayed, or minimized (such as views).

37 New DITA CMS 4.2 Administration features 37 The element and attributes that must be specified depend on the section ID. For example, to remove the File menu completely, you only need to specify the menu ID, as shown below: <removeditem id="file"/> But to remove an option from the File menu (for example, Print), you need to specify the ID of the option and the ID of its parent menu, for example: <removeditem id="print" menupath="file"/> The following tables summarize the elements and attributes required per section for each type of perspective. Note: The IDs specified in italics in the tables are obtained from the trace log. Table 4: Section elements and attributes for the Startup perspective Section ID Element/Attributes required import For top menus: <removeditem id="item_id"/> For menu options or submenus: <removeditem id="item_id" menupath="parent_menu_id"/> preferences perspective <removeditem id="item_id"/> <item id="item_id" state="closed"/> Table 5: Section elements and attributes for the Regular perspectives Section ID menu submenu oxygenpopup Element/Attributes required <removeditem id="item_id"/> <removeditem id="item_id" menupath="parent_menu_id"/> <removeditem id="item_id" type="type_id"/> or <removeditem id="item_id" type="type_id" menupath="parent_menu_id"/>

38 38 What's New in DITA CMS 4.2 Section ID oxygenactionbar Element/Attributes required <removeditem id="item_id" type="type"/> Where type is one of the following: menu toolbar button panels views <removeditem id="item_id"/> <item id="item_id" state="state"/>where state is one of the following: closed minimized open com.ixiasoft.dita. eclipse.gui.views. map.mapview com.ixiasoft.dita. eclipse.gui.views. sidebar. SearchGuiMiniBar com.ixiasoft.dita. eclipse.gui.views. sidebar.sidebar com.ixiasoft.dita. eclipse.gui.views. sidebar. SideBarResults com.ixiasoft.dita. eclipse.gui.views. job.jobview <removeditem id="item_id" type="org.eclipse.swt.widgets.label"/> <removeditem id="item_id" type="org.eclipse.swt.widgets.button"/> <removeditem id="item_id" type="org.eclipse.swt.widgets.button"/> <removeditem id="item_id" type="org.eclipse.swt.widgets.button"/> <removeditem id="item_id" type="org.eclipse.swt.widgets.button"/>

39 New DITA CMS 4.2 Administration features 39 Section ID toolbar Element/Attributes required <item id="item_id"/> Getting IDs from the trace log IXIASOFT provides a trace log to determine the IDs of the items in the interface. The trace log contains the IDs of the interface items in the currently opened perspective. As you interact with items in the interface for example, open a dialog box or select a menu option they get added to the trace log, allowing you to easily identify the IDs of elements you want to remove. The trace log first provides an overview of the currently opened perspectives with their section IDs and the number of items and removeditems that are configured for each section. For example, the following trace shows that in addition to the startup perspective, the Information Architect (i.e., the LeadPerspective ID) and the DITA (i.e., the DitaPerspective) perspectives are open and that some items have been removed from the interface: eclipseui Perspective id: [ixiasoft.eclipse.startup] has 3 section(s) Section id: [import] has 0 item(s) and 18 removeditem(s) Section id: [preferences] has 0 item(s) and 0 removeditem(s) Section id: [perspective] has 0 item(s) and 0 removeditem(s) Perspective id: [com.ixiasoft.dita.eclipse.gui.perspective.leadperspective] has 2 section(s) Section id: [views] has 0 item(s) and 0 removeditem(s) Section id: [panels] has 0 item(s) and 0 removeditem(s) Perspective id: [com.ixiasoft.dita.eclipse.gui.perspective.ditaperspective] has 12 section(s) Section id: [menu] has 0 item(s) and 5 removeditem(s) Section id: [submenu] has 0 item(s) and 51 removeditem(s) Section id: [oxygenpopup] has 0 item(s) and 6 removeditem(s) Section id: [oxygenactionbar] has 0 item(s) and 27 removeditem(s) Section id: [panels] has 0 item(s) and 1 removeditem(s) Section id: [views] has 15 item(s) and 0 removeditem(s) Section id: [com.ixiasoft.dita.eclipse.gui.views.map.mapview] has 0 item(s) and 10 removeditem(s) Section id: [com.ixiasoft.dita.eclipse.gui.views.sidebar.searchguiminibar] has 0 item(s) and 1 removeditem(s) Section id: [com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebar] has 0 item(s) and 0 removeditem(s) Section id: [com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarresults] has 0 item(s) and 2 removeditem(s) Section id: [com.ixiasoft.dita.eclipse.gui.views.job.jobview] has 0 item(s) and 4 removeditem(s) Section id: [toolbar] has 0 item(s) and 13 removeditem(s) The log then lists each section of the perspectives and, for each section, the log provides the ID of each item with a status indicating whether the item is currently removed. No status indicates that the item is displayed in the UI.

40 40 What's New in DITA CMS 4.2 IDs for the Import menu IDs for the options in the Import menu are listed in the Processing [import] from [ixiasoft.eclipse.startup] section of the log. For example: Processing [import] from [ixiasoft.eclipse.startup] com.ixiasoft.dita.eclipse.wizard.category com.ixiasoft.dita.eclipse.wizard.import.map...: com.ixiasoft.dita.eclipse.wizard.import.topic...: com.ixiasoft.dita.eclipse.wizard.import.taxonomy...: com.oxygenxml.editor...: org.eclipse.debug.ui...: To remove a top menu, enter its ID in a <removeditem> element. For example, to remove the oxygen XML option from the Import menu, enter its ID in the eclipseui.xml file as follows: <perspective id="ixiasoft.eclipse.startup"> <section id="import"> <removeditem id="com.oxygenxml.editor"/>... To remove a menu option or submenu, enter its ID in a <removeditem> element and specify its parent ID is a menupath attribute. For example, to remove the Import Taxonomy from the DITA CMS option, enter its ID and the ID of its parent in the eclipseui.xml file as follows: <section id="oxygenactionbar"> <removeditem id="com.ixiasoft.dita.eclipse.wizard.import.taxonomy" menupath="com.ixiasoft.dita.eclipse.wizard.category"/>... IDs for the Preferences menu IDs for the options in the Preferences menu are listed in the Processing [preferences] from [ixiasoft.eclipse.startup] section of the log. For example: Processing [preferences] from [ixiasoft.eclipse.startup] com.ixiasoft.dita.eclipse.gui.preferences.ditapreferencespage...: com.ixiasoft.dita.eclipse.gui.preferences.synchronizationpreferencespage..: com.ixiasoft.dita.eclipse.gui.preferences.behaviorpage...: com.ixiasoft.dita.eclipse.gui.preferences.importexport...: org.eclipse.ant.ui.antpreferencepage...: org.eclipse.ant.ui.antruntimepreferencepage...: org.eclipse.ant.ui.anteditorpreferencepage...:

41 New DITA CMS 4.2 Administration features 41 To remove an option from the Preferences menu, enter its ID in a <removeditem> element. For example, to remove the Ant section from the Preferences dialog, enter its ID in the eclipseui.xml file as follows: <section id="preferences"> <removeditem id="org.eclipse.ant.ui.antpreferencepage"/> IDs for the perspectives at startup IDs for the perspectives are listed in the Processing [perspective] from [ixiasoft.eclipse.startup] section of the log. For example: Processing [perspective] from [ixiasoft.eclipse.startup] org.eclipse.jdt.ui.javaperspective...: closed org.eclipse.debug.ui.debugperspective...: closed org.eclipse.jdt.ui.javabrowsingperspective...: closed org.eclipse.ui.resourceperspective...: closed com.ixiasoft.dita.eclipse.gui.perspective.ditarelationshipperspective..: closed com.ixiasoft.dita.eclipse.gui.perspective.offlineperspective...: closed com.ixiasoft.dita.eclipse.gui.perspective.projectperspective...: closed com.ixiasoft.dita.eclipse.gui.perspective.smeperspective...: closed To configure a perspective so that it's closed when the DITA CMS starts, enter its ID in a <removeditem> element and set its state to closed. For example, to close the Information Architect perspective, enter its ID in the eclipseui.xml file as follows: <section id="perspective"> <item id="com.ixiasoft.dita.eclipse.gui.perspective.leadperspective" state="closed"/>... IDs for the Eclipse main menus IDs for the Eclipse main menus are listed in the Processing [menu] section of the log. For example: Processing [menu] file...: edit...: navigate...: To remove a menu item, enter its ID in a <removeditem> element. For example, to remove the edit menu, enter its ID in the eclipseui.xml file as follows: <section id="menu"> <removeditem id="edit"/>...

42 42 What's New in DITA CMS 4.2 IDs for the menu options (submenus) in the Eclipse main menu IDs for the Eclipse menu options are listed in the Processing [submenu] section of the log. For example: Processing [submenu] file new...: removed new.ext...: removed To remove a menu option, enter its ID in a <removeditem> element and specify its parent menu using the menupath attribute. For example, to remove the File > New option, enter its ID and its parent menu ID in the eclipseui.xml file as follows: <section id="submenu"> <removeditem id="new" menupath="file"/>... IDs for the oxygen right-click menu options IDs for the oxygen right-click menu are listed in the Processing [oxygenpopup] section of the log. For example: Processing [oxygenpopup] &Paste special [type: org.eclipse.jface.action.menumanager]...: &Table [type: org.eclipse.jface.action.menumanager]...: The log also contains the type of the menu option. To remove a menu option, enter its ID in a <removeditem> element and specify its type in the type attribute. For example, to remove the Paste special right-click option, enter its ID and type in the eclipseui.xml file as follows: <section id="oxygenpopup"> <removeditem id="&paste special" type="org.eclipse.jface.action.menumanager"/>... To remove a submenu option, enter its ID in a <removeditem> element, specify its type in the type attribute, and specify its parent menu using the menupath attribute. For example, to remove the Insert > Image option, enter its ID and its parent menu ID in the eclipseui.xml file as follows: <section id="oxygenpopup"> <removeditem id="author/insert.image" type="org.eclipse.jface.action.menumanager" menupath="&insert" />...

43 New DITA CMS 4.2 Administration features 43 IDs for the XML main menu and the oxygen toolbars IDs for the items in the XML main menu, the oxygen toolbar on the top-level toolbar, and the oxygen toolbar in the oxygen editor are listed in the Processing [oxygenactionbar] section of the log. For example: Processing [oxygenactionbar] com.oxygenxml.editor.validate...: To remove a top menu, enter its ID in a <removeditem> element and enter its type in the type attribute. Valid type values are: menu: XML main menu toolbar: Buttons for the Oxygen editor on the top-level toolbar button: Buttons inside the Oxygen editor For example, to remove the Validate command from the XML menu, enter its ID in the eclipseui.xml file as follows: <section id="oxygenactionbar"> <removeditem id="com.oxygenxml.editor.validate" type="menu" />... IDs for the Search view panels IDs for the Search view panels are listed in the Processing [panels] PanelManager() section of the log. For example: Processing [panels] PanelManager() com.ixiasoft.dita.eclipse.gui.views.sidebar.search.composite.searchcyclesection...: com.ixiasoft.dita.eclipse.gui.views.sidebar.search.composite.sidebardategui...: com.ixiasoft.dita.eclipse.gui.views.sidebar.search.composite.advancedsearchsection.: To remove a panel, enter its ID in a <removeditem> element. For example, to remove the Advanced Search panel, enter its ID in the eclipseui.xml file as follows: <section id="panels"> <removeditem id="com.ixiasoft.dita.eclipse.gui.views.sidebar.search.composite.advancedsearchsection"/>... Note: You cannot remove the Search for panel, even if you specify its ID in the eclipseui.xml file.

44 44 What's New in DITA CMS 4.2 IDs for views IDs for views are listed in the Processing [views) section of the log. For example: Processing [views] com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarview...: com.ixiasoft.dita.eclipse.gui.views.documents.documentsview...: com.ixiasoft.dita.eclipse.gui.views.map.mapview...: While most interface items can either be hidden or displayed, views can be hidden, displayed, or minimized. To remove or minimize a view, you specify its ID in an <item> element and specify its state as closed or minimized in a state attribute. For example, to minimize the DITA Map view, enter its ID in the eclipseui.xml file as follows: <section id="views"> <item id="com.ixiasoft.dita.eclipse.gui.views.map.mapview" state="minimized"/>... IDs for the DITA Map view IDs for items in the DITA Map view are listed in the Processing [com.ixiasoft.dita.eclipse.gui.views.map.mapview] section of the log. For example: Processing [com.ixiasoft.dita.eclipse.gui.views.map.mapview] type=org.eclipse.swt.widgets.label com.ixiasoft.dita.eclipse.actions.map.setconditions...: com.ixiasoft.dita.eclipse.actions.map.selectconditions...: The log also contains the type for all the items in the Map View. To remove an item from the DITA Map view, enter its ID in a <removeditem> element and specify its type in the type attribute. For example, to remove the Set Conditions button from the DITA Map view, enter its ID in the eclipseui.xml file as follows: <section id="com.ixiasoft.dita.eclipse.gui.views.map.mapview"> <removeditem id="com.ixiasoft.dita.eclipse.actions.map.setconditions" type="org.eclipse.swt.widgets.label"/>...

45 New DITA CMS 4.2 Administration features 45 IDs for the button bar in the Search view panels IDs for the button bar in the Search view panels are listed in the Processing [panels] PanelManager() section of the log and contain the SearchGuiMiniBar string. For example: Processing [panels] PanelManager() com.ixiasoft.dita.eclipse.gui.views.sidebar.searchguiminibarcycles...: com.ixiasoft.dita.eclipse.gui.views.sidebar.search.composite.searchcyclesection...: com.ixiasoft.dita.eclipse.gui.views.sidebar.searchguiminibarfilters...: com.ixiasoft.dita.eclipse.gui.views.sidebar.search.composite.searchdocumenttypesection.: To remove the button bar from a panel in the Search view, enter its ID in a <removeditem> element and specify its type as org.eclipse.swt.widgets.button. For example, to remove the button bar from the Cycles panel, enter the following code in the eclipseui.xml file as follows: <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.searchguiminibar"> <removeditem id="com.ixiasoft.dita.eclipse.gui.views.sidebar.searchguiminibarcycles" type="org.eclipse.swt.widgets.button"/>... IDs for the buttons in the Search view IDs for the New Query, Save Query, Save XML Query, and Show/Hide Panels buttons in the Search view are listed in the Processing [com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebar] section of the log. For example: Processing [com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebar] com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.newquery...: com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.savequery...: com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.savexmlquery...: com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarguishowhideaction...: To remove a button from the Search view, enter its ID in a <removeditem> element and specify its type as org.eclipse.swt.widgets.button. For example, to remove the New Query button, enter the following code in the eclipseui.xml file: <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebar"> <removeditem id="com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.newquery" type="org.eclipse.swt.widgets.button"/>...

46 46 What's New in DITA CMS 4.2 IDs for the buttons in the Search Results view IDs for Clear Results List, Export Results List, Search and Replace, Manage Groupings, and Turn On/Off Thumbnail Display buttons in the Search Results view are listed in the Processing [com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarresults] section of the log. For example: Processing [com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarresults] com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.clearresultslist...: com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.exportresultslist...: com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.searchreplace...: com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.viewpointbybutton...: com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.showthumbnails...: To remove a button from the Search Results view, enter its ID in a <removeditem> element and specify its type as org.eclipse.swt.widgets.button. For example, to remove the Export Results List button, enter the following code in the eclipseui.xml file: <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarresults"> <removeditem id="com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.exportresultslist" type="org.eclipse.swt.widgets.button"/>... IDs for the buttons in the Todo List view IDs for Refresh Todo List, Export Todo List, Show Statistics, Select Groupings, and Turn On/Off Thumbnail Display buttons in the Todo List view are listed in the Processing [com.ixiasoft.dita.eclipse.gui.views.job.jobview] section of the log. For example: Processing [com.ixiasoft.dita.eclipse.gui.views.job.jobview] com.ixiasoft.dita.eclipse.gui.views.job.actions.refreshjoblistaction.: com.ixiasoft.dita.eclipse.gui.views.job.actions.exporttodolist...: com.ixiasoft.dita.eclipse.gui.views.job.actions.showjobviewstatisticsaction.: com.ixiasoft.dita.eclipse.gui.views.job.jobviewgroupbycombo...: com.ixiasoft.dita.eclipse.gui.views.sidebar.actions.showthumbnails...: To remove a button from the Todo List view, enter its ID in a <removeditem> element and specify its type as org.eclipse.swt.widgets.button. For example, to remove the Show Statistics button, enter the following code in the eclipseui.xml file: <section id="com.ixiasoft.dita.eclipse.gui.views.job.jobview"> <removeditem id="com.ixiasoft.dita.eclipse.gui.views.job.actions.exporttodolist"

47 New DITA CMS 4.2 Administration features type="org.eclipse.swt.widgets.button"/> IDs for the buttons on the toolbar IDs for the buttons on the top toolbar are listed in the Processing [toolbar] section of the log. For example: Processing [toolbar] org.eclipse.ui.workbench.file new.group...: newwizarddropdown...: new.ext...: save.group...: save...: saveall...: To remove a button, enter its ID in a <removeditem> element. For example, to remove the save buttons from the toolbar, enter the following code in the eclipseui.xml file: <section id="toolbar"> <removeditem id="save"/> <removeditem id="saveall"/> Enable the trace log IXIASOFT provides a trace log that lists the IDs for the different interface items in a perspective. When you enable the trace log, you get IDs for the following perspectives: Startup DITA Information Architect Note: To get the IDs of other perspectives, see Obtain the list of IDs in a trace log for a perspective on page 48. When you enable the trace log, the UITrace.log file records the ID of the current perspective. As you open the different menus in the DITA CMS, the trace log file records the IDs of the different interface items you are interacting with. When you open another perspective, the trace log is cleared before it records the IDs for this perspective. To enable the trace log: 1. Open the %eclipse%/eclipse.ini file (for example, C:\eclipses\cms41_x64\eclipse.ini). 2. Add the -Duitracefilename=<%file_location%>UITrace.log option to the file.

48 48 What's New in DITA CMS 4.2 Where %file_location% specifies where to create the trace log file. For example, if you specify the following: -Duitracefilename=c:\logs\UITrace.log The file will be created in the c:\logs\ directory. To create the UITrace.log file in the same location as the eclipse.ini file, enter: -Duitracefilename=UITrace.log 3. Save and close the file. 4. Restart the DITA CMS. The UITrace.log file is created and contains the IDs of the perspective that is currently open.you may need to open dialogs and menus to get the IDs of these items.when you switch perspective, the UITrace.log file is overwritten with the IDs of the currently open perspective. Obtain the list of IDs in a trace log for a perspective By default, when you enable the trace log, you get IDs for the Startup, DITA, and Information Architect perspectives. To get the IDs for another perspective, you must add it to the eclipseui.xml configuration file. The default eclipseui.xml configuration file contains a template that you can use to enable the trace for a perspective. To enable the trace log for a perspective: 1. Open the TEXTML Server Java Console or the TEXTML Server Administration perspective in the DITA CMS. 2. Connect to the server and the Content Store that you want to manage. 3. Expand the Content Store's Repository node and browse to /system/conf to locate the eclipseui.xml file. 4. Right-click eclipseui.xml and select Check Out. 5. Open the file in an XML editor. 6. For the perspective that you want to customize, add the following code: <perspective id="perspective_id"> <section id="menu"> </section> <section id="submenu"> </section> <section id="oxygenpopup"> </section> <section id="oxygenactionbar">

49 New DITA CMS 4.2 Administration features 49 </section> <section id="panels"> </section> <section id="views"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.map.mapview"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.searchguiminibar"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebar"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarresults"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.job.jobview"> </section> <section id="toolbar"> </section> </perspective> Where perspective_id is the ID of the perspective. If you do not know what the ID of the perspective is, run the DITA CMS with the trace log enabled and open the perspective. The log will display the ID of the perspective. For example, to get the IDs for the RelTable Editing perspective, enter: <perspective id="com.ixiasoft.dita.eclipse.gui.perspective.ditarelationshipperspective"> <section id="menu"> </section> <section id="submenu"> </section> <section id="oxygenpopup"> </section> <section id="oxygenactionbar"> </section> <section id="panels"> </section> <section id="views"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.map.mapview"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.searchguiminibar"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebar"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.sidebar.sidebarresults"> </section> <section id="com.ixiasoft.dita.eclipse.gui.views.job.jobview"> </section> <section id="toolbar"> </section> </perspective> 7. Save and check in the file. 8. Restart the DITA CMS.

50 50 What's New in DITA CMS 4.2 Simplify a perspective This section provides the procedure for simplifying a perspective. Note: This procedure assumes that you have the IDs for the elements that you want to hide and that you have added the perspective ID to the eclipse.xml file. See Obtain the list of IDs in a trace log for a perspective on page 48 for the procedure. To simplify a perspective: 1. Open the TEXTML Server Java Console or the TEXTML Server Administration perspective in the DITA CMS. 2. Connect to the server and the Content Store that you want to manage. 3. Expand the Content Store's Repository node and browse to /system/conf to locate the eclipseui.xml file. 4. Right-click eclipseui.xml and select Check Out. 5. Open the file in an XML editor. 6. Look for the perspective that you want to simplify. 7. Inside the perspective, look for the section that you want to simplify. 8. Add the items that you want to hide, close, or minimize in a <removeditem> or <item> element, as appropriate. Most interface items are already defined but commented out for the startup and DITA perspectives. You can simply uncomment the items as appropriate. For the list of valid elements and attributes per section, see Understanding the eclipseui.xml file on page 34. To determine the ID of the element items to configure, see Getting IDs from the trace log on page Save, close, and Check In the eclipseui.xml file. 10. To apply the changes restart the DITA CMS Eclipse Client.

51 New DITA CMS 4.2 Administration features 51 Location-based groups The location-based groups is a grouping capability with a provision to define locations within the groups. Adding locations to the groups allows users to gain access to various DITA CMS features according to their location. For example, user-a from ACME-London has access to both the content reviewer and system administrator groups. In ACME-Montreal, all the users have access to the localization functionality. When user-a switches office from ACME-London to ACME-Montreal, user-a's DITA CMS profile should reflect the new location. Thanks to the location-based groups feature, user-a at the ACME-Montreal location now gains additional access to the localization functionality without you having to change the access rights. User-A will still have access to the content reviewer and system administrator groups. Note: You may want to automate updating users' locations in the DITA CMS, for example based on the LDAP information. This is outside the scope of this document. Create location-based groups from the TEXTML Administration view To configure the location-based groups from the TEXTML Administration view: 1. Open the Group Manager window. 2. Click the Lock button ( ). 3. In the Groups panel, select the group where you want to add the new location. 4. Right-click in the Locations panel and select Add Location. Add Location dialog opens. 5. Enter the Location. For example:

52 52 What's New in DITA CMS 4.2 Note: Be sure to use consistent location naming and character case in order to avoid creating multiple versions of a location. The new location is displayed in the Locations panel. 6. Repeat from Step 5 to add additional locations. 7. Save your changes locally (Ctrl-s). 8. Click CheckIn Document ( ). Your changes are updated in the repository. Create location-based groups by editing groups.xml To support location-based groups, a new optional element <locations> should be added as a child to the <group> element in the groups.xml file. The <locations> element contains the list of locations that are mapped to a group. To create location-based groups through the groups.xml file: 1. Open the TEXTML Server Java Console or the TEXTML Server Administration perspective in the DITA CMS. 2. Connect to the server and the Content Store that you want to manage. 3. Expand the Content Store's Repository node and browse to /system/conf/ to locate the groups.xml file. 4. Right-click groups.xml and select Check Out. 5. Open the file in an XML editor. 6. Under <groups>, enter the <locations> element, along with a list of location names to any group of your preference. For example: <groups> <group name="system Administrators"/> <group name="guests"/> <group name="everyone"/> <group name="content Reviewers"/> <locations> <location name="ixiasoft Montreal"> <location name="ixiasoft Toronto"> </locations> </group> </groups> The above example shows that all users in Ixiasoft Montreal and Ixiasoft Toronto have access to the role of Content Reviewers. 7. Save, close, and check in the groups.xml file.

53 New DITA CMS 4.2 Administration features 53 Scheduler improvements This section lists the improvements and changes made to the Scheduler in DITA CMS 4.2. You can now easily disable a job using the new enable attribute. A new job is now available ReportScheduler, allowing you to schedule and generate user reports. Note: This job does not create any reports. To create reports, see Creating and generating reports on page 8 The Scheduler templates are now installed in the Content Store, in the following directory: Repository\system\scheduler The connection to the Content Store for all the Scheduler jobs is now defined by the global configuration element as shown below: <!-- This section is required to synchronize CMS configuration locally --> <configuration> <dita.cms url="hostname" port="2500" docbase="docbase" secure="false"> <user domain="ixiasoft" username="testuser" password="password" synchdir="c:/temp/scheduler/"/> </dita.cms> <!-- TextMl, dita.out and smtp If none are specified in job they fall back to this global TextMl connection --> <textml url="hostname" version="4" port="2500" docbase="docbase" secure="false"> <user domain="ixiasoft" username="testuser" password="password"/> </textml> <dita.out url="localhost" port="1501" secure="false"/> <smtp url="smtp.ixiasoft.local" port="25" ="scheduler-noreply@ixiasoft.com" /> <dumpqueue filename="schedulerqueue.txt" /> </configuration> You can now define a second Content Store other than the one defined in the configuration element. The second Content Store is configured within a specific Scheduler job. This provision can be useful if you want to run a Scheduler job from a Content Store other than the one defined in the configuration element. For more information, see the Scheduler Installation Guide. Schedule user-defined reports created with the DITA CMS This section describes how to configure the Scheduler to generate user reports created with the DITA CMS. Note that this job does not create the report. The reports are created and scheduled in the DITA CMS, using the Report feature. The job configures at which times the Scheduler reviews the Content Store for any scheduled reports. If there are reports scheduled, the Scheduler retrieves

54 54 What's New in DITA CMS 4.2 all the relevant information about each report and processes the reports according to their scheduled entries. See the DITA CMS User Guide for more information about the reports feature. Configure the job in the schedule.xml file To configure the Reports notifications, configure the job in the schedule.xml file. The ReportScheduler class is the Scheduler job used to generate reports. When the Scheduler runs, it retrieves all the relevant information about the scheduled reports and processes them according to their scheduled entries. Consider an example where the Scheduler job ReportScheduler is configured to run at 6 a.m. every day. Report A and Report B are scheduled to run at 7 a.m. and 10 a.m. respectively. When the Scheduler runs at 6 a.m., it checks for any scheduled reports, retrieving all the required information from the Content Store. It then creates jobs according to the reports' scheduled times. Report A will be generated at 7 a.m. and Report B at 10 a.m. Both outputs will be sent by to all the configured recipients. Any changes made to the report after the Scheduler job runs for example, changes made to Report A at 6:30 a.m. are not applied to the reports. You have two options to configure the connection to the Content Store: Use the default connection settings configured in the <configuration> element. Configure a Content Store that is specific to a Scheduler job. This option is recommended only if you want to run a Scheduler job using a Content Store other than the one defined in the <configuration> element. If the Content Store is the same you do not need to additionally configure the connection to the Content Store within a specific Scheduler job. The configuration will fall back to the default Content Store connection. To configure the ReportsScheduler job: 1. Open the %SchedulerDir%/conf/schedule.xml file. 2. Look for the Report Scheduler default job; it looks as follows: <!-- The following take in charge the scheduling of user reports as schedule independant items --> <job useclass="com.ixiasoft.cms.postman.reportsscheduler" enable="true"> <-- <textml id="docbase" url="hostname" version="4" port="2500" docbase="hostname" secure="false"> <user domain="ixiasoft" username="testuser" password="password"/> </textml> --> <-- <smtp url="smtp.ixiasoft.local" port="25" ="scheduler-noreply@ixiasoft.com" /> --> <schedule> <when>* * * * *</when> </schedule> </job>

55 New DITA CMS 4.2 Administration features Change the value of enable to true. Note: The Scheduler job will not run if the enable value is set to false. 4. (Optional) Uncomment and enter the appropriate information in the textml, user, and smtp elements to configure the connection to a specific Content Store. If you do not specify this information, the default values set in the <configuration> element will be used. 5. Edit the <when> element to configure when the job will run. Use a crontab-like pattern, as shown below: <when>minute hour day month weekday<when> Where: minute specifies the minutes (0-59) of the hour that the job will run; a value of * indicates that the job will run every minute hour specifies the hours (0-23, 0=midnight) of the day that the job will run; a value of * indicates that the job will run every hour day specifies the days (1-31) of the month that the job will run; a value of * indicates that the job will run every day month specifies the months (1-12) of the year that the job will run; a value of * indicates that the job will run every month weekday specifies the days (0-6, 0 = Sunday) of the week that the job will run; a value of * indicates that the job will run every day For example, to indicate that a job should run at midnight every day, enter the following: <when>0 0 * * *<when> To indicate that a job should run at 6:15 every day, enter the following: <when>15 6 * * *<when> There are other options that you can use. For example, to indicate that a job should run every 15 minutes, enter the following: <when>*/15 * * * *<when> For more information about all available Cron options, see the following URL:

56 56 What's New in DITA CMS When you are done, save and close the schedule.xml file. 7. Stop and start the Scheduler service. For example: net stop Scheduler net start Scheduler DITA-OT 2.1 The Output Generator now supports version of the DITA-OT. To upgrade your Output Generator installation and use this version of the DITA-OT, see the Output Generator Installation Guide.

57 3New Web Author 4.2 features New Web Author 4.2 features Topics: Configuring the Web Author startup page Insert images in Web Author Specify the editing context This section describes the new Web Author features.

58 58 What's New in DITA CMS 4.2 Configuring the Web Author startup page The Web Author startup page can be customized to fit the needs of your deployment. For example, you can provide instructions that are specific to your deployment or additional contact information for users. Configure the Web Author startup page in the web.author.welcome.xml file To customize the Web Author startup page, you modify the web.author.welcome.xml file. 1. Open the TEXTML Server Java Console or the TEXTML Server Administration perspective in the DITA CMS. 2. Connect to the server and the Content Store that you want to manage. 3. Expand the Content Store's Repository node and browse to /system/cms.webauthor/configuration to locate the web.author.welcome.xml file. 4. Right-click web.author.welcome.xml and select Check Out. 5. Open the file with a text or xml editor. 6. Edit the topic according to your preference. For example, add deployment-specific instructions or other information required for your Web Author users. 7. Save, close, and Check In the file. 8. To apply the changes restart the CMS Application Server (Glassfish) and Web Author Application (Tomcat) services. Insert images in Web Author You can now insert images in a document from the Web Author Application. Enable the Insert image option in the web.author.roles.xml file Before using the insert image feature of the Web Author Application, you first have to configure the web.author.roles.xml file. To configure the web.author.roles.xml file:

59 New Web Author 4.2 features Open the TEXTML Server Java Console or the TEXTML Server Administration perspective in the DITA CMS. 2. Connect to the server and the Content Store that you want to manage. 3. Expand the Content Store's Repository node and browse to /system/cms.webauthor/configuration to locate the web.author.roles.xml file. 4. Right-click web.author.roles.xml and select Check Out. 5. Open the file in an XML editor. 6. Look for the code <actionset label="insert" id="context.insert.actions" dropdown="true">, which defines the insert actions. It looks as follows: <actionset label="insert" id="context.insert.actions" dropdown="true"> <action id="insert Paragraph"/> <action id="insert Section"/> <action id="insert Concept" visible="false"/> <action id="insert Task" visible="false"/> <action id="insert Topic" visible="false"/> <action id="insert Reference" visible="false"/> <action id="insert Image" visible="false"/> <action id="insert Equation" visible="false"/> </actionset> 7. Set the value of the visible property to true in the action id Insert Image. For example: <action id="insert Image" visible="true"/> When the value is set to true, you enable the insert image feature in the Web Author Application. When the value is set to false, you will not be able to insert images. The default value is false. 8. Save, close, and Check In the file. 9. To apply the changes restart the CMS Application Server (Glassfish) and Web Author Application (Tomcat) services. Insert images in Web Author This procedure describes how to insert images in the Web Author Application. To insert images from the Web Author Application, you have the following two options: 1. Select an existing image from the Content Store. 2. Add a new image directly from the Web Author Application. Note: All the images added from the Web Author Application are automatically added to the Content Store.

60 60 What's New in DITA CMS 4.2 The Web Author supports files of type *.png, *.jpg, *.gif, and *.svg. Insert an existing image from the DITA CMS image library You can add an existing image from the Content Store using the Web Author Application and then include it in a topic. To insert an image from the Image Library of the Content Store: 1. Click the document in the Assignments pane. The document is displayed in the Editing and Reviewing pane.you will see Edit Document, if the document is not locked. If the document is already locked for editing, the Edit Document button is replaced by the Submit and Cancel buttons. 2. Do one of the following depending on the status of the document: a) If the document is not locked, click Edit Document to start editing the document. The Editor toolbar appears above the document. b) If the document is already locked, you can start editing the document. Note: The buttons displayed depend on your role and the configuration for your deployment. For example, you will only be able to insert an image if you are editing the document using a role that allows the document content be to modified (for example, Author, as opposed to Reviewer). 3. To insert an image, place the cursor at the desired location. Note: You must place your cursor within an element that allows images. 4. Right-click and select Insert > Insert Image from the menu. By default this takes you to the Image Library pane, where the images from the Content Store are available. 5. Search for the desired image by either browsing through the image library pages or by searching for the image in the search section available at the bottom of the page. For example:

61 New Web Author 4.2 features Select the image to insert and click Insert. The image is inserted at the desired location. Add a new image to the Content Store You can add a new image to the Content Store using the Web Author Application and then include it in a topic. Adding images in DRM: When you add an image while using the DRM module, the image is added to the same container as the topic to which the image is being added. To add a new image to the Content Store: 1. Click the document in the Assignments pane. The document is displayed in the Editing and Reviewing pane. 2. Click Edit Document. The oxygen toolbar appears above the document. The buttons displayed depend on your role and the configuration for your deployment. 3. To add and insert an image, place the cursor at the desired location. Note: You must place your cursor within an element that allows images. 4. Right-click and select Insert > Insert Image from the menu.

62 62 What's New in DITA CMS 4.2 By default this takes you to the Image Library pane, where the images from the Content Store are available. 5. Select the Add New Image pane. The following page is displayed: 6. To add an image, do one of the following: Drag and drop the desired image in the Drop An Image Here pane. Click Browse and select the desired image from your local computer. Note: All the images added from the Web Author Application are automatically added to the Content Store. 7. Enter an image Title and Description. 8. Select an Image Type from the options. 9. Click Insert. The image is inserted at the desired location.

63 New Web Author 4.2 features 63 Troubleshooting: Inserting images in Web Author The following section describes the typical problems encountered while inserting images in Web Author. You cannot see the insert image option If you do not see the insert image option even after configuring the web.author.roles.xml file, you have to clear the Java cache on your local machine or system. To clear the Java cache (for Windows): 1. Go to Start > Control Panel. 2. Click Java. The Java Control Panel window appears: 3. In the General section, click Settings in the Temporary Internet Files area. The Temporary Files Settings window appears:

64 64 What's New in DITA CMS Click Delete Files. The Delete Files and Applications window appears: Make sure that the Trace and Log files and Cached Applications and Applets options are selected. 5. Click OK. The cache is cleared and the Temporary Files Settings dialog is displayed. 6. Click OK. 7. In the Java Control Panel window, click Apply and OK. 8. Start the Web Author application again. You should see the Insert Image option.

65 New Web Author 4.2 features 65 Specify the editing context To resolve the keys in a document, the Web Author must know which key definition to use. You can now specify the editing context for a document, which lets you specify which map to use to resolve the keys in a document. This is mostly useful with the DRM module, which uses keys for all its references. For example, consider a topic (Topic A) that includes a screen shot of the user interface. The topic is used in two different product versions: and In 4.1.2, the user interface is updated and a new version of the screen capture is created in When Topic A is opened in the Web Author, to determine how to resolve the key reference to the image, you specify its editing context. The editing context is the containing map for the document. All the maps to which the document belongs are listed in the Editing Context area of the Web Author, as shown below: To resolve the key, you select the appropriate map. The Web Author then displays the document with the keys resolved according to the map selected. If there is more than one editing context for a topic, the Web Author behaves as follows: The Web Author automatically selects the first editing context to resolve the keys. When you select an editing context for a topic, the Web Author remembers this context. If you switch back to the topic later, it will automatically use that editing context. If you open a topic and the currently selected editing context appears in the new topic's list of contexts, the Web Author keeps the currently selected editing context for the new topic. This

66 66 What's New in DITA CMS 4.2 ensures that if you are working on many topics from the same map, you don't have to keep selecting that map for each topic. To specify an editing context for a document: 1. Click the document in the Assignments pane. The document is displayed in the Editing and Reviewing pane and the maps to which the document belongs are listed in the Editing Context area. 2. To specify the editing context for the document, click the + sign in the Editing Context area and select the context. The document is updated according to the context specified. 3. Click the - sign to close the Editing Context area.

67 4New DRM 4.2 features New DRM 4.2 features Topics: Snapshots Version tags Synchronization This section describes the new DRM features introduced in this release of the DITA CMS.

68 68 What's New in DITA CMS 4.2 Snapshots You can create snapshots of your working maps. Understanding the Snapshots feature A snapshot is a DITA CMS object that captures a map at a particular point in time. You can use this snapshot to rebuild the map and the objects that it contains container, container parts, topics, images, referable content, sub-maps, and so on exactly as they were when the snapshot was created. When you create a snapshot for a map, the DITA CMS creates an.xml file that contains the list of all the objects in the map (and sub-maps, if any) along with their current version numbers. For example, consider the following map, which contains a topic and a sub-map: <!DOCTYPE bookmap PUBLIC "-//IXIA//DTD DITA Map for Release Management//EN" "IxiaMap-releasemanagement.dtd"> <bookmap id="ddp " xml:lang="en-us"> <title>sample map</title> <containerref href="kiy ditamap"/> <chapter keyref="bhi "/> <chapter format="ditamap" keyref="dsi "/> </bookmap> The following code shows the contents of the snapshot file for this map. The snapshot includes the objects referenced in the topic (in this case, an image and referable content) as well as the objects in the sub-map (in this case, a task that also includes an image). For each object in the map that is, the map itself as well as all the objects that it contains: container, container parts, topics, images, referable content, sub-maps (and their contents), etc. the following information is kept: Status of the object Link to the object in the DITA CMS Navtitle Revision number Object type This information allows the DITA CMS to recreate the map exactly as it was when the snapshot was created. As with any DITA CMS object, you can search for a snapshot in the Content Store. You can also output a snapshot. Important note

69 New DRM 4.2 features 69 To create the snapshot, the DITA CMS uses the latest released revisions of the objects in the map. Therefore, if you have locked documents in your map, the snapshot will not include these locked revisions but rather the latest released revisions of these objects. Why use snapshots? Creating a snapshot does not create copies of the map and its objects. It's simply a text file that lists the map's contents at a specific point in time, so creating a snapshot has virtually no impact on the Content Store. Another advantage of snapshots is that you can create a snapshot from a map that is in any state, as long as the map is not locked. When using snapshots, you can: Generate the output of a snapshot: At any time you can see the content of a snapshot by generating its output. When you generate the output of a snapshot, the Output Generator retrieves from the Content Store the versions of the map and its objects as specified by the snapshot. New files are not created. Keep a historical record of all your documentation releases: Every time that you release your documentation or at important milestones, you can make a snapshot of your map. This ensures that you can see the content of a specific release at any time by generating its output. Note: You cannot localize a snapshot. Create a snapshot When you create a snapshot, the DITA CMS creates an.xml file that contains the list of all the objects in the map along with their version numbers. Requirements The map must not be locked, but the objects in the maps may be locked. When you create a snapshot, the map and its objects can be in any state. Important note To create the snapshot, the DITA CMS uses the latest released revisions of the objects in the map. Therefore, if you have locked documents in your map, the snapshot will not include these locked revisions but rather the latest released revisions of these objects. In the default configuration, when you create a snapshot, the snapshot object is in the Authoring:review status (or the equivalent in your deployment).

70 70 What's New in DITA CMS 4.2 You can create a snapshot from any view that lists the map (Search Results, DITA Map, Dependencies, etc.). To create a snapshot of a map: 1. In a view that lists the map, right-click the map and select Create snapshot. The Create Snapshot window appears: By default, the title of the map is used as the title of the snapshot. 2. If desired, modify the snapshot title in the Title field. This might be useful to differentiate the snapshots for a map. For example, to indicate that a snapshot identifies the version of the Web Author Installation Guide that was sent for technical review, you could enter "Web Author Installation Guide - Tech Review". 3. In the Version field, specify the version for this snapshot. Important: The snapshot will automatically be created in the same product version as the map. The Version field is used to specify a label for this snapshot. Note: The version specified is the version of the snapshot and is not related to the product version. 4. Click OK. The snapshot is created. As with any DITA CMS object, you can search for a snapshot in the Content Store. You can also output a snapshot or preview it. Generate the output of a snapshot Just as with maps, you can output a snapshot using the Generate Output command. When you generate the output of a snapshot, the Output Generator retrieves from the Content Store the revisions of the map and its objects as specified by the snapshot. You can generate the output of your snapshot in any format supported by the Output Generator.

71 New DRM 4.2 features 71 To generate the output of a snapshot: 1. Use Search to find the snapshot you want to output. 2. Right-click the snapshot and select Generate Output. 3. Select the Output Format, specify required conditions and user fields (if any), and click Create. The Output Generator outputs the snapshot. Note: The Output Generator does not create copies of the snapshot objects. Instead, it simply retrieves the objects from the Content Store to create the output. View the contents of a snapshot You can view the contents of a snapshot using the Show Preview command. When you use the Show Preview command, the DITA CMS lists the objects in the snapshot, as shown below: To view the contents of a snapshot:

72 72 What's New in DITA CMS Use Search to find the snapshot to preview. 2. Right-click the snapshot and select Show Preview. The preview of the snapshot is displayed. Version tags This section describes the version tag feature. Understanding the Version tag feature A version tag is a DITA CMS object that captures the contents of a product version or library version at a particular point in time. It contains a list of all the objects that were in the version. You can then use this tag to rebuild the version and the objects that it contained container, container parts, topics, images, referable content, sub-maps, etc. exactly as they were when the tag was created. You can rebuild this version in any release inside the same product or library. Note: Creating a version tag on a product will not tag its underlying libraries. Only the direct content of the product will be tagged. If you need to tag a library, you must create the tag on a library version. Create a version tag A version tag is a DITA CMS object that captures the contents of a product or library version at a particular point in time. It contains the list of all the objects that were in a version. You can then use this tag to create a new version. Note: Creating a version tag on a product will not tag its underlying libraries. Only the direct content of the product will be tagged. If you need to tag a library, you must create the tag on a library version. To create a version tag: 1. From the Dynamic Release Management window, right-click the version to tag and select Tag. The Create Tag window is displayed. By default, the name of the tag is tag_<version>_<date><hour>. 2. In the Name field, keep the suggested name or enter a new one.

73 New DRM 4.2 features Enter a Description. 4. Click OK. The tag is created.you can search for the tag by selecting Others > Version tag in the Document Types panel of the Search view. Search version tags Version tags are categorized as "other" document types in the DITA CMS Search view. To list the existing version tags: 1. In the Cycles panel of the Search view, select Authoring. 2. In the Document Types panel, select Others. 3. Click the drop-down arrow to the right of Others. 4. Select version-tag. 5. Click the Search button. Create a new version from a version tag You can create a new product or library version from a version tag by using the New version option. Note: Version tags can be used within the same product or library that they were created. For example, if you create a version tag for a version in Product A, you cannot use this version tag in Product B or Library C. If you need to reuse a version in a different product, use the Clone version feature instead. Create a new version A version contains the actual documentation objects. When users add a new object, they must add it to a version. A version must therefore exist before content can be added to it, and the same content object can be used in more than one version. You have three options for creating a new version: Creating a completely new, empty version. Creating a version based on an existing version. All the objects in the existing version are added to the new version. This option is displayed only if versions are available for the product or library.

74 74 What's New in DITA CMS 4.2 Creating a new version based on a version tag. All the objects in the version tag are added to the new version. This option is displayed only if tags are available for the product or library. Versions have the file extension.version but they are XML files and so they can be most easily edited in your preferred XML editor.you should add a default editor to.version files in your Eclipse preferences so that the versions that you want to edit are opened automatically in your preferred editor. To create a new version: 1. In the Dynamic Release Management view, right-click the release to which you want to add a version and select New Version. The Create Version dialog box is displayed: 2. Give the version name and a description. 3. Specify the language for the version in the Language field. 4. If another version or a version tag exists for this product/library, the Based On field is displayed. Select one of the following: Option Description NEW Version Version Creates a new, empty version. When you select Version in the Based On field, all the available versions for the product/library are listed. Select the version that you want to copy. All the objects in the existing version are added to the new version. This option is displayed only if versions are available for the product/library.

75 New DRM 4.2 features 75 Option Tag Description When you select Tag in the Based On field, all the available tags for the product/library are listed. Select the version tag that you want to copy. All the objects in the version tag are added to the new version. This option is displayed only if tags are available for the product/library. 5. (Optional) Click the Save Settings button to save the Language setting for the next time that you create a version tag. 6. Click OK. The version is created and displayed in the Dynamic Release Management view under the appropriate release. Synchronization This section describes the synchronization feature. Understanding the synchronization feature The synchronization feature compares the contents of two product or library versions and returns the objects that have changed. Users can open the objects in a compare editor to see the differences between the two versions. They can also merge the changes so that both objects are identical. Synchronization: From source to target The synchronization feature works by comparing a source version with a target version and returning the changes made in the source version that can be applied to the target version. For example, consider Version 4.1.1, which contains 3 objects: a map, Product A User Guide, and 2 topics. The User Guide is cloned in Version and two new topics are added to Version 4.1.2, as shown below:

76 76 What's New in DITA CMS 4.2 When version (source) is synchronized with version (target), the DITA CMS does not report any difference between the versions. This is because there are no changes in that could be merged or added to The Synchronize feature allows you to: Add maps, topics, and images from the source version to the target version Merge the entire content and structure of objects from the source version to the target version Selectively merge changes in maps and topics in the source version to the target version Revert to their source version objects that were modified in the target version but not in the source version Note: Objects that are removed from a DRM version are not shown as deleted when you synchronize that version with another. For example, if Topic2 had been removed from version 4.1.1, it would not show as a deleted topic when you synchronize with To identify the topics that were deleted between versions, you need to compare the maps to see the topics that were removed from the map. When you synchronize versions, the results of the comparison are provided in the DRM Synchronization perspective. Using the example above, the DITA CMS would return the following results in the DRM Synchronization perspective:

77 New DRM 4.2 features 77 As shown in the example above, the Synchronization Tree lists three changes in the source version that could be applied to the target version: Topic 3 and Topic 4 were added to Version 4.1.2, as shown by the plus sign icon ( ). The content of the User Guide map was modified, as shown by the star icon ( ). Some changes, such as the ones above, are simple changes that can be easily merged automatically by the DITA CMS Synchronization feature. For example, new paragraphs added to a topic in the source version can easily be merged automatically to the target version. However, sometimes the changes are not as obvious; in such cases, the object appears in the Conflict folder and the user must review the changes and manually accept or reject them, as appropriate. For example, consider the following situation: Topic 1 in Version is branched in Version In Version 4.1.1, the topic is modified and its title changed to "Topic 1: New title in 4.1.1". In Version 4.1.2, the topic is modified and its title is changed to "Topic 1: New title in 4.1.2", as shown in the following diagram:

78 78 What's New in DITA CMS 4.2 When Version is synchronized with Version 4.1.2, this topic is determined to be in conflict because the Synchronization tool cannot determine how to handle this change: Which title should be used? Should the change made to the title be applied to version 4.1.2, or should the title remain as is? In this case, the user must open the topic in the compare editor to review the changes and determine what to do. For example, opening Topic 1 in the compare editor would appear as follows: The user has the option to keep the title of the version or to merge the title from To synchronize versions, you use the Synchronization perspective and a compare editor.

79 New DRM 4.2 features 79 The DRM Synchronization perspective To view the results of the synchronization and to merge changes, you use the DRM Synchronization perspective. The DRM Synchronization perspective has three main areas. DRM Synchronization area The DRM Synchronization area has two sections: The Synchronization section lists the product or library name as well as the source and target versions. The Synchronization Tree lists the results of the synchronization, as shown below: Results are displayed in the following folders: The Changes in source folder lists the objects that were added in the source version as well as objects that were modified and for which the changes can be applied automatically by the DITA CMS. When a user approves the changes for the objects, the DITA CMS makes the changes to the target version and removes the objects from the Changes in source folder.

80 80 What's New in DITA CMS 4.2 The Conflict folder lists the objects for which there are changes that cannot be merged automatically. Users must open each object in a compare editor and manually accept or reject the changes. The user then marks the object as merged, and the DITA CMS removes the object from the Conflict folder and moves it to the Merged folder. The Merged folder lists the objects that were reviewed and merged by the user but that haven't been released yet. To finalize the process, the user commits the objects, which releases them to the Content Store and moves the objects to the Commit folder. The Synchronization tree can also display the following folders (not shown in the sample dialog above): Note: By default, the following folders are hidden. To display them, click the folder icon at the top of the Synchronization Tree and select the folders that you want to display. The Changes in target folder lists the objects that were added in the target version as well as objects that were modified in the target version but not in the source version. Users can revert a modified object to its source version. When a user reverts an object to its source revision, the DITA CMS removes the object from the Changes in target folder. Note: Objects that were added in the target version cannot be added to the source version using the Synchronize tree. The Committed folder lists the objects that were merged and released. The No Change folder contains: Objects that were branched in the target version but that have not been modified in the source version or target version. Objects that were merged in a previous synchronization and that have not been modified since. The Reused folder lists the objects that are reused in the source and target versions. Information view The Information view provides information about the selected object, including the versions in which the objects is used in the Release Management section. If an object is used in multiple versions, its primary version is provided in bold. Graph Clone Tree The Graph Clone Tree shows how an object was cloned and modified. This can be useful to see the clone history of the object as well as the relationship between its revisions. For example, the following diagram shows that the map was cloned in and 4.1.3, and that is was modified in 4.1.1:

81 New DRM 4.2 features 81 Working with a compare tool To see the differences between two objects, you use a compare tool. The DITA CMS provides access to two compare tools: Compare Editor: By default, the Compare Editor is a text compare tool provided with the Eclipse SDK. It displays the source object and the target object and allows you to see the differences between the two versions, do 2-way and 3-way comparisons between the objects, and apply or reject changes from the source version to the target version. The following diagram shows the Compare Editor: This document provides some information about using the Text Compare tool. For the Eclipse documentation on this tool, see the Eclipse help. Note: You can also configure the DITA CMS to use a different compare tool for the synchronization. This is done by opening the Window > Preferences > DITA CMS >

82 82 What's New in DITA CMS 4.2 > General Behavior panel and specifying a compare tool. See the DITA CMS User Guide for more information. Default Editor: The Default Editor is the oxygen track changes editor (if the oxygen XML editor is installed). It shows the changes in a single document (the target object) using the oxygen track changes markup. For example: For more information about this editor, see Note: oxygen is the only supported editor at this point. You can use the tool of your choice but you cannot use both compare tools in the same revision, otherwise you will get unexpected results. Synchronize two versions When you synchronize two versions, you compare a source version with a target version to identify the changes made in the source version that could be applied to the target version. To synchronize two versions:

83 New DRM 4.2 features In the Dynamic Release Management window, right-click the source version and select Synchronize With.... The Select Target Version dialog is displayed, listing the versions that you can synchronize with. 2. In the Select Target Version dialog, select the target version and click OK. Note: Optional: A message may be displayed asking if you want to open the Synchronization perspective. Click OK. The DRM Synchronization perspective is displayed, showing the changes in the source version that could be added to the target version. For example: The next steps depend on the types of changes identified during the merge: New objects added to a version: All objects that were added to a source version and are not in the target version are listed with the plus sign icon ( ) in the Changes in source section of the Synchronization Tree. To add the object to the target version, see Add objects to a version on page 84. Modified source objects that can be automatically merged: All objects that were modified and for which the changes can be merged automatically are displayed in the Changes in source folder with the ( ) icon. To automatically merge these objects, see Automatically merge modifications on page 84.

84 84 What's New in DITA CMS 4.2 Conflicts: Objects for which there are changes that cannot be merged automatically are listed in the Conflicts folder. These objects must be opened in a compare editor and each change must be manually accepted or rejected.to manage conflicting objects, see Manage conflict on page 85. Modified target objects that can be reverted: All objects that were modified in the target version but not in the source version and that can be reverted to the source version are displayed in the Changes in target folder with the ( ) icon. To revert these objects, see Revert an object to the source version on page 88. Add objects to a version New objects that can be added to a target version are identified with the + icon ( Changes in source section. ) in the To add objects to a target version: In the Synchronization Tree, right-click the file and select Accept. The object is added to the target version. It is also removed from the Changes in source folder. Automatically merge modifications All objects that were modified and for which the changes can be merged automatically are displayed in the Changes in source section with the ( ) icon. It's always a good practice to first look at the changes to make sure that you do want to approve them. This is done by opening the object in a compare editor. For example, consider a map that includes two new chapters. Opening the map in a compare editor would display the following changes:

85 New DRM 4.2 features 85 The compare editor shows that two chapter references were added to the map. Note: When you first open the object in a compare editor, the object is locked and the content in the source is inserted into the target object. For example, if you had added a new paragraph in the source topic, the Compare Editor would automatically add it to the target topic. To automatically apply modifications: 1. In the Synchronization Tree, right-click the object and select either Merge in > Compare Editor or Merge in > Default Editor depending on which editor you prefer. The object is locked and opened in the editor. 2. Review the changes to confirm that you agree with them. 3. In the Synchronization Tree, right-click the object and select Replace with Server Revision. 4. In the Synchronization Tree, right-click the object and select Accept. The object is added to the target version. It is also removed from the Changes in source folder and moved to the Reused folder. You can branch it again later on if you need to use it in another version. Manage conflict When an object is in conflict, it is displayed with a red conflict icon in the Conflict folder. To manage objects in conflict, you open them in the compare or default editor, according to your preference. The DITA CMS locks the document, opens the document in the editor, and shows the differences between the topics. You can look at the changes and accept or reject them as appropriate. Note: You can merge two tables if the content of the table has changed but the structure has not changed (no row added/deleted, no column added/deleted). If the structure changed, the editor will display the table in the source version as deleted and the table in the target version as added content. Some tips when resolving conflicts: In the Eclipse Text Compare tool, select the Ignore White Space Where Applicable button ( ) in the top menu bar (you can also right-click anywhere in the document and select Ignore White Space). This will improve the clarity of the document.

86 86 What's New in DITA CMS 4.2 For more difficult changes, use the 3-way compare of Eclipse Text Compare tool. For more information, see Understanding the 2-way and 3-way compare modes on page 86. Opening the Graph Clone Tree can also help you see the relationship between the cloned versions and the different revisions of an object. For more information, see Display the Graph Clone Tree for an object on page 86. To manage conflicts in the Synchronization Tree: 1. Right-click the object that is in the Conflict folder and select either Merge in > Compare Editor or Merge in > Default Editor depending on which editor you prefer. A message may be displayed indicating that the document must be locked. To stop displaying this message, select Don't ask again. Click Yes to lock and open the document. The editor opens and show the differences between the two documents. 2. Accept or reject the differences, as appropriate. 3. Save the document. 4. In the Synchronization Tree, right-click the object and select Mark as Merged. The topic moves to the Merged folder. 5. Right-click the topic in the Merged folder and select Commit. The Release dialog is displayed. 6. Enter a comment, if required, and click OK. The document is released and is removed from the Merged folder. Display the Graph Clone Tree for an object The Graph Clone Tree shows how an object was cloned and modified. This can be useful to see the relationship between the revision of the object. To open the Graph Clone Tree for an object, right-click the object in the Synchronization Tree and select Show Clone Tree. Understanding the 2-way and 3-way compare modes Two-way compare You can turn on two-way compare by selecting the Two-Way Compare (Ignore Ancestor) button in the Text Compare toolbar. In a two-way comparison, the comparison is only between the two latest revisions of the branched object in the two DRM versions. In a two-way comparison, all changes are in gray. Changes in gray are applied automatically upon selection of the Copy

87 New DRM 4.2 features 87 Current Change from Left to Right. That is to say, changes in the left pane will be used to replace content in the right pane. Three-way compare This feature is most useful when merging objects that have conflicting changes (the object is listed in the Conflict folder of the DRM Synchronization view). If a common ancestor of a branched object is available, the Text Compare view allows for a three-way comparison. You can display the common ancestor in a three-way compare by selecting the Show Ancestor Pane button in the toolbar of the Text Compare view. Three-way comparisons show the differences between three different revisions of a branched object: The common ancestor revision of the branched object. The revision of the object in the source DRM version. The branched or cloned object in the target DRM version. The relationship between the three revisions of the object can be seen using the DRM Graph Clone Tree view, as shown in the following diagram: The diagram shows the Text Compare view and DRM Graph Clone Tree view. The views are opened for a three-way comparison of a branched topic, Shoveling Snow. In the top pane of the Text Compare is the common ancestor revision, revision 1. This same revision is shown in the yellow box in the DRM Graph Clone Tree view. Revision 1 is the common ancestor of revision 2 of the same branch, DRM version 1.0, as well as revision 4 of the branch in DRM version 1.1. In a three-way compare the Text Compare view shows you: