Assign Roles to Modules, Sections, or Topics

Once you have created roles using role lists, you can assign the roles to one or more modules, sections, or topics. This step is necessary to allow both role-selective publishing in the Developer and role-based filtering in the Player.

You can assign roles while working in the Library or Outline Editor, using the Properties toolpane. Roles can be assigned to module, section, or topic documents, and all of the documents selected for role assignment at one time must be of the same language.

Tip: You can select multiple documents using the standard Windows selection keys (CTRL+click and SHIFT+click). However, you must select only modules, sections or topics, as no other document types support roles. If a multi-document selection in the Library includes a document type that does not support roles, such as a package, the Role property does not appear in the Properties toolpane.

When you select documents for role assignment, the Developer determines the language of the selected document(s) and displays a list of all roles in the master role list for that language. If any additional roles are in use in the selected documents but are not on the role list, they are also shown. Note that inclusion of these additional roles depends on the specific document(s) selected for role assignment, rather than just language. Consequently, such roles are available for role assignment only if the document(s) to which they are assigned are included in the selection. It is therefore recommended that you always update the master role list to include these additional roles whenever they exist.

If no role list exists for the language of the selected document(s), role assignment is not enabled.

Warning! Do not delete the role list for any language. Doing so will disable role assignment for that language.

To assign a role to a document, you simply select the checkbox next to the desired role in the Assign Roles dialog box. To remove the role from the document, clear the checkbox. Note, however, that, if you remove a document from all roles, the document will appear in the Player only if role-selective filtering is turned off.

If you select multiple documents for property assignment, the checkboxes for the property values can have any of three initial states:

• Unselected (clear) - The value is not assigned to any of the selected documents.
• Selected (checked) - The value is assigned to all of the selected documents.
• Partially selected (gray with gray checkmark) - The value is assigned to some, but not all, of the selected documents.

You can check or clear any checkbox, regardless of its initial state, to assign the value to or remove it from ALL of the selected documents. If you do not change the state of a partially selected checkbox, the assignment of the corresponding value remains unchanged (assigned to some, but not all, of the selected documents). However, once you click a partially selected checkbox, you cannot restore it to its initial state. Therefore, when assigning property values to documents, you should select only those documents to/from which you want to add/remove the same value(s).

Once you assign one or more roles to a topic, the role assignment is saved as a property of the topic document. If you later make changes to these roles in a master role list, the topic assignment must also be updated. It is recommended that you update role assignments automatically when prompted to do so after saving changes to the master role list. If the role assignment for a topic cannot be updated automatically at that time, for example, if the topic is open in the Topic Editor, or if you choose not to update role assignments automatically, you must manually update each topic to which obsolete roles are assigned to reflect the changes in the master role list. Therefore, it is recommended that you define and finalize your role lists before assigning roles to topics.

Tip: You can use find and replace to update role assignments.

Multi-user Considerations

Before you can perform this action, you must check out the document. After you save any changes, you should check in the document to make it available to other authors and add the changes to the Developer's version control system. If you are assigning roles to multiple documents at the same time, all selected documents must be checked out. The Roles property is not available for editing if one or more documents in a multi-document selection are not checked out.

You do not need to check out the role document, only the document(s) to which roles are being assigned. In addition, you can assign roles even if the appropriate master role list is checked out to another user, although only the roles in the latest checked in version of the role list will be available for assignment.

To assign roles while working offline, you should ensure that you have the latest version of the appropriate master role list(s) available in your local cache. To do this, you can either check out or get the role list, depending on whether you plan to edit it or to have access to a read-only copy. If you go offline and do not have a current copy of a role list in your local cache, some of the roles on the role list might be unavailable to you as you work offline. To remedy this, you need to go back online and get the documents that you need.

To assign roles to one or more documents:

1. Display the Properties toolpane.
2. From the Library or Outline Editor, select the document(s) to which you want to assign roles.

   You can select multiple documents using the standard Windows selection keys (CTRL+click and SHIFT+click). However, all documents included in your selection must have the same language.

3. In the General category, click in the Roles cell.
4. In the Assign Roles dialog box, select the role(s) to which you want to assign the selected document(s).

   To include a role, click the checkbox next to its name. To remove a role, clear the checkbox next to its name.

   You can also use the Select All button to include all roles or the Clear All button to remove all roles from the selection. These buttons apply to all roles listed in the Assign Roles dialog box, whether they are included in the master role list or are available as additional roles for the selected documents.

5. Click OK or press ENTER.