16 Roles

This chapter explains how to use Agile PLM's preconfigured roles and how to create new ones.

16.1 Overview of Roles and Privileges in Agile PLM

Roles and privileges govern a user's access to Agile PLM business objects and functionality.

For a PLM user to be able to perform tasks, users must be assigned to at least one role. Each user (or user group) can be assigned to multiple roles, depending on which actions they need to perform.

Agile PLM includes a wide-ranging set of preconfigured roles and base privileges. While you can always modify roles and tailor privileges as needed, you are encouraged to become familiar with the default roles in Agile PLM before constructing your own; the default roles are listed in a few pages.

16.1.1 What is a Privilege Mask?

This chapter examines PLM roles—both default and customized—and the next chapter takes up privileges and privilege masks. However, it is important to understand from the start what these elements are. ("Getting Familiar with Roles" describes the process to view the default roles in the Roles node; the Privileges node can be expanded in the "node tree" to see a list of the default privileges.)

The following table defines privilege, privilege mask, and role.

Table 16-1 Definitions of Privilege, Privilege Mask, and Role

Term	Definition	Examples
Privilege	The action users are allowed to take. A privilege is only a "building block": to be assigned to users, it must be combined with other components, like Criteria and a target object.	Administrator (privilege) Create Read Modify
Privilege mask	A set of criteria statements that define under what specific conditions an action can be taken on a named business object. Each role requires at least one privilege mask.	Administrator (privilege mask) Create Designs; Create Items Read Designs; Read Items Modify Designs; Modify Items
Role	A common set of privileges that can be assigned to one or more users who perform the same functions in the change control process. A role is a tailored assembly of privilege masks. A user can be assigned to more than one role. The default roles are set up for immediate use.	Administrator (role) Change Analyst Compliance Manager Component Engineer Each role comprises several-to-many privilege masks.

From the definitions in this table, these summary statements apply:

• The actions that users can perform in Agile PLM—such as creating, sending, or canceling—are based on privileges. But privileges do not function "by themselves".

• Privilege masks are combinations of: privileges, reusable criteria (introduced in earlier chapter), and target object (which can be as granular as required). A privilege mask is a functional unit that acts as a filter to manage user actions. Privilege masks can be added to roles (default or custom) or can be assigned to users without being part of a role.

• Roles are groupings or assemblies of several-to-many privilege masks. (A role like "Enforce Field-Level Read" has but 2 or 3 privilege masks, while "Change Analysts" has dozens.)

  Roles provide a way to allocate a common set of privileges to a group of users who have common functions in the change control process.

  When you assign a role or a privilege mask to a user, it takes effect only after the user has logged out and logged back into an Agile PLM client.

This introduction to "roles and privileges" in Agile PLM now turns to Roles; the following chapter goes into detail about privileges.

16.2 Getting Familiar with Roles

You can modify the default PLM Roles in the following ways:

• Change the name of an existing role.

  Exceptions are the (Restricted) roles, and the Administrator, My User Profile, and View Historical Report roles, whose names cannot be changed.

• Exceptions are the (Restricted) roles, and the Administrator, My User Profile, and View Historical Report roles, which cannot be disabled.

  Enable or disable a role on its General Information tab.

• Assign a user to a role or remove a user assignment from a role on the Users tab.

  Exceptions are the (Restricted) roles, and the My User Profile and View Historical Report roles, which do not allow you to modify user assignments.

• Add or remove privilege masks for the role by using the Privileges tab.

  Exceptions are the (Restricted) roles, and the My User Profile and View Historical Report roles, which do not allow you to add or remove privilege masks.

• On the Privileges tab, double-click the name of a privilege mask to display the privilege mask's tabbed object window. When a privilege mask's tabbed window is displayed, you can modify that privilege mask.

You cannot do the following from the Roles window:

• Change the object type of a privilege mask.

• Modify any of the Example Roles (or its privilege masks) or the Example Privileges. These are found in Examples > Example Roles and Example Privileges.

16.2.1 Viewing the Roles Window

To view the Roles window:

1. Under User Settings, double-click Roles. The Roles window appears

2. You can filter roles records to narrow your search.

   For example, set Filter By to Description, Match If to Contains, and Value to Change, then click Apply to find all the roles pertaining to "change" objects. (See "Filtering Data in Java Client.")

   To see all roles currently in PLM, set Match If to Show All and click Apply.

   The list of roles is displayed in the table. The Roles table shows the name, description and enabled status for each role.

The buttons on the Roles window allow you to perform various role management tasks.

Table 16-2 Role Management Tasks

Button	Action
New	Create a new role. See "Creating a New Role."
Delete	Deletes the selected roles. A role cannot be deleted if it is already in use.
Enable	Enables the selected roles.
Disable	Disables the selected roles.
Import	Import a text file to create a new role. See "Object History and Administrative Object History."
Export	Exports role data for the selected role. See "Object History and Administrative Object History."
Refresh	Refreshes the table with the latest information about the list of roles.

16.2.2 Viewing a Role

To view a specific role:

1. In the Roles window, double-click the role you want.

   The tabbed window for that role appears. The buttons that appear at the top of the window of each role are Save As, Delete, and Export.

2. The role's basic properties are displayed on the General Information tab. These include Name, API Name, Description, and Enabled.

3. The privilege masks that are assembled in the role are displayed on the Privileges tab.

   You can double-click any row to open that privilege-mask object; on its General Information tab, the field Privilege (which is grayed-out because it cannot be changed) shows the basic privilege that drives that privilege mask.

4. The Users tab lists users who have been assigned to this role. The User Groups tab lists user groups that have been assigned to this role.

   On both these tabs, you can add or remove users or user groups, respectively. Note that when you "delete" a user or user group from one of these tabs, you are only removing the role assignment (the role you are "in") from that "user object."

5. The History tab displays the history of actions taken on this role object.

16.2.3 Guidelines for Working with Roles

Follow these steps when working with roles:

1. Print a Roles and Privileges Summary report and a Privilege Mask Detail report to see the definitions currently active in your Agile PLM system. See "Administrator Reports."

   
   

   Note: The Privilege Mask Detail report can be extremely long. You may want to generate and view the report before printing it.

   
   

2. Read and follow the security recommendations in "Securing and Maintaining Roles and Privilege Masks."

3. If necessary, modify and create roles, as described later in this chapter.

4. Assign users to appropriate roles. See "Modifying a Role."

16.3 Default Agile PLM Roles

When you double-click the Roles node, you see a list of your currently configured roles. The table below lists the ready-to-use roles and briefly describes what each role permits the user to do.

You can assign a user as many or as few roles as he needs to perform his duties. You can use the roles provided as they are, or you can copy a provided role (using Save As) and modify the copy to create a new role, or you can create a new role from scratch.

Caution: As much as possible, copy (using Save As) and adapt the roles and privilege masks provided with your Agile PLM installation rather than create new ones. This is especially true for roles, since the nature of their privilege mask combinations is not immediately obvious.

16.3.1 Administrator roles

These roles apply only to users who work in the Administrator modules in Java Client (Admin tab) and in Web Client (Tools and Settings > Administration).

An important part of tailoring the Administrator roles is the AppliedTo property in the Administrator privilege; see "Administrator Privilege and the AppliedTo Capability."

Table 16-3 Administrator Roles

Role	Applies to these base classes (or other PLM utility)	Description
Administrator	All Classes	Perform all administrative tasks. The other, specialized Administrator roles (including Discussion, Folder, Price, Program, Quality, Resource Pool, Sourcing, and User administrators) all have less capability than this role.
User Administrator	Users, User Groups	Perform administrative tasks (create, modify, delete) as defined by the Agile administrator

16.3.2 General-function Agile PLM roles

These roles apply to users who work across all Agile PLM solutions.

Table 16-4 General-function Agile PLM roles

Role	Applies to these base classes (or other PLM utility)	Description
Acknowledge	Changes, MCOs	Acknowledge routable objects through workflows.
Approval Matrix Manager	Functional Teams	Manage functional team objects. Approval Matrix Manager would add and delete members of functional teams, and edit functional team job functions to keep the functional teams current.
Approve/Reject	Changes, Packages, QCRs, PSRs, ATOs, and Projects	Approve or reject routable objects through workflows, and read items and changes
Creator can read and discover object he or she created	All objects	The creator of a business object can always read and discover that object. This role is enabled and part of every new user's profile, by default. There is no change in behavior with existing users (that is, "legacy" users for upgrading customers). Removing this role from a user Read or Discovery of objects they create.
Discussion Administrator	Discussions	Create and manage discussion objects. Discussions are used primarily in Agile PPM and PCM solutions, but it is possible to use that class in other solutions.
Discussion Participant (Restricted) Discussion Participant	Discussions	Manage portions of discussions; the (Restricted) Discussion Partner would generally be someone who works outside the enterprise.
Enforce Field-Level Read	(Works in conjunction with other roles)	This role (contains only Enforce Field-level Read privilege mask) is used in conjunction with other roles: it enforces the AppliedTo fields under Read privileges in all roles assigned to the user, which reduces the user's capabilities.
Export	(Allows access to Export utility.)	Allows user to export objects for which they have Discover and Read privileges. (Contains only Export privilege mask.)
Folder Administrator	File Folders	Create and manage file folders. For additional information, see "Attachment Privileges."
Folder Manager	File Folders	Create and manage file folders. For additional information, see "Attachment Privileges."
Java Client Access	(Allows access to Java Client)	Allows the user to log in to Agile PLM Java Client. A user who does not have this role cannot log in to Java Client. For more information, see "Client Access." Any user assigned an Administrator privilege mask always has access to Java Client by default.
Markup for All	File Folders (Affected Item Attachments)	Modify the redline Markups or other users for File Folders or for the Affected Item attachments of change orders. User must have Read privileges for the file folder objects or change order objects. For additional information, see "Redline Markup Default Roles and Privileges."
Markup for Self	File Folders (Affected Item Attachments)	Create and modify the user's own redline Markups for File Folders or for the Affected Item attachments of change orders. User must have Read privileges for the file folder objects or change order objects. For additional information, see "Redline Markup Default Roles and Privileges."
My File Folder	File Folders	Permits reading file folders created by the assignee.
My User Profile (Restricted) My User Profile	Users	View and modify his own user profile properties under My Settings, and create and modify personal user groups. Assigned to every user, and is required to use the Agile PLM system. Note The Discover Users privilege is not part of the My User Profile role by default.
(Restricted) Grant	All objects	Grant roles to users in a controlled, finite way, using Access Control List (ACL) capability.

16.3.3 Engineering Collaboration role

This role applies to users who work in the Agile EC solution.

Table 16-5 Engineering Collaboration role

Role	Applies to these base classes (or other PLM utility)	Description
Design Engineer	File Folders (Designs class objects)	Create and manage Designs class objects and Design Model structures.

16.3.4 Product Collaboration roles

These roles apply to users who work in the Agile PC solution.

Table 16-6 Product Collaboration roles

Role	Applies to these base classes (or other PLM utility)	Description
Change Analyst	Changes, Items, Manufacturers, Mfr. Parts, File Folders	Create items and changes, and manage the routing and release process of changes through workflows. Also create BOMs, MPNs, AMLs, and to manage file folder references
Component Engineer	Items, Manufacturers, Mfr. Parts, Mfr. Orders (MCOs)	Create manufacturer change objects and manage the routing and release process of MCOs
Incorporator	Changes, Items, Mfr Parts, Manufacturers, Prices,	Incorporate items and numerous functions with the listed base classes (this role is similar to Change Analyst, but with fewer capabilities).
Item Content Manager	Changes, Items	Create items, and create and submit changes
Manufacturer Content Manager	Items, Manufacturers, Mfr. Parts, Mfr. Orders (MCOs)	Create items, manufacturers, and manufacturer parts, and create and submit MCOs
Modify Item Released	Items	Change the Description of an item that has been released (contains only one privilege mask for this).
Partner	Packages	Create and submit package objects
Product Content Read Only	Changes, Items, Manufacturers, Manufacturer Parts	Discover, read, comment, get, print, send, and view items, changes, manufacturers, and manufacturer parts

16.3.5 Product Quality Management roles

These roles apply to users who work in the Agile PQM solution.

Table 16-7 Product Quality Management roles

Role	Applies to these base classes (or other PLM utility)	Description
Organization Manager	Suppliers, Customers	Manage suppliers and customers (also applies to PCM solution)
Quality Administrator	Quality Change Requests	Manage the corrective and preventive action and audit processes
Quality Analyst	Product Service Requests	Submit quality incidents and manage their resolution
Quality Analytics User	(Quality Analytics application)	Permits PQM user to access (Run, Discover, Read) the Quality Analytics application.

16.3.6 Product Cost Management roles

These roles apply to users who work in the Agile PCM solution.

Table 16-8 Product Cost Management roles

Role	Applies to these base classes (or other PLM utility)	Description
Organization Manager	Suppliers, Customers	Create and manage suppliers and customers (also applies to PQM solution)
Price Administrator	Prices, Price Change Orders	Control price management activities, including PCOs
Price Manager	Prices, Price Change Orders	Manage pricing information through creation of price objects and PCOs
(Restricted) Price Collaborator	Prices, Price Change Orders	Manage pricing information through creation of price objects and PCOs, but more limited than price manager role; typically provided to supplier users
RFQ Manager	RFQs, RFQ Responses	Create RFQs and manage the RFQ process
(Restricted) RFQ Responder	RFQ Responses	Respond to RFQs; this role is generally provided to supplier users
Sourcing Administrator	Sourcing Projects, RFQs	Control sourcing activities, including the ability to view and modify all sourcing projects and RFQs
Sourcing Project Manager	Sourcing Projects	Create and manage sourcing projects
(Restricted) Supplier Manager	Suppliers	Manage supplier information, limited to suppliers' own organizations, including the ability to create users in the supplier organization

16.3.7 Product Portfolio Management roles

These roles apply to users who work in the Agile PPM solution. (Note: The base class Programs is changed to Projects as of Rel. 9.3.0; the PPM roles and privilege masks may still use the term "Program".)

Table 16-9 Product Portfolio Management roles

Role	Applies to these base classes (or other PLM utility)	Description
Executive	Projects	Global read access to all projects that have matching categories; for example, if a project is associated with the North American region, and a user has an Executive privilege for all North American, then he can read them
Portfolio Analytics User	(Portfolio Analytics applications)	Permits PPM user to access (Run, Discover, Read) the Portfolio Analytics application.
Program Administrator	Projects	Create and manage complete projects
Program Manager	Projects	Create and manage routing and release process for projects
Program Team Member	Projects	Manage portions of projects
Resource Pool Administrator	Projects	Create and manage resource pools
Resource Pool Owner	Projects	Manage resource pools
Timesheet Administrator	Projects	Perform administrative tasks on all timesheets that are created in the system

16.3.8 Reports roles

These roles apply to users who work with Reports.

Table 16-10 Reports roles

Role	Applies to these base classes (or other PLM utility)	Description
Report Manager	Reports	Access and manage all reports, even those they did not create
Report User	Reports	Create new custom reports and manage reports they created
View Historical Report	Reports, Historical Report File Folders	View specific instances of previously executed reports; this is a non-editable role and is automatically assigned whenever a report instance is shared with a user

16.3.9 Agile Content Services role

This role applies to users who work in the ACS solution.

Table 16-11 Agile Content Services role

Role	Applies to these base classes (or other PLM utility)	Description
Content Manager	Transfer Orders, Packages	Create, modify, route, release and implement CTO and ATO objects, and package objects

16.3.10 Product Governance & Compliance roles

These roles apply to users who work in the Agile PG&C solution.

Table 16-12 Product Governance & Compliance roles

Role	Applies to these base classes (or other PLM utility)	Description
Compliance Manager	Declarations, Commodities, Specifications, Substances	Create and manage PG&C objects, run PG&C reports, and route material declarations to suppliers
(Restricted) Material Provider	Declarations	Create, modify, and complete material declarations; this role is generally provided to supplier users

16.3.11 Agile Configuration Propagation roles

These roles apply to users who work in the ACP solution. For more information see the current Agile PLM Configuration Propagation Guide.

Table 16-13 Agile Configuration Propagation roles

Role	Applies to these base classes (or other PLM utility)	Description
(Propagation) Administrator	All Classes	Perform propagation tasks.
(Propagation) User Administrator	Users, User Groups	Perform propagation tasks that are limited to users and user groups.

16.3.12 Example Roles

Your Agile PLM installation includes both a read/write version and a read-only example or reference copy of the roles. double-click the Example Roles node under the Example node folder to see the reference copy, which is provided so that you always have default copies of the roles as they were installed. To restore the default version of any role, you can just make a copy (using Save As) of its Example role.

For example, the following are the two versions of the Change Analyst role provided at installation:

• Change Analyst – This is a modifiable (Read/Write) role that you can assign to users.

• Example - Change Analyst – This is an uneditable (Read-Only) reference copy of the Change Analyst role.

Note: If Agile PLM users are unable to move a routable object from one status to another, for example from Hold to CCB, often they do not have appropriate privileges to make these status changes. In such cases, check the roles they are assigned and the privilege masks included in those roles.

More information about example roles is in "Using the Example Roles."

16.3.13 Restricted Roles

Some roles are restricted in the extent to which they can operate on their specified objects; these role names are preceded by the word Restricted in parentheses. Their purpose is the same as the like-named role that is not preceded by "(Restricted)". They are generally assigned to members of supplier organizations, that is, Agile PLM users who work outside the enterprise.

16.3.14 Role-based Enhancements

User Administrator Enhancement

The PLM role User Administrator has a privilege mask called "Admin Access for User Admin"; its AppliedTo property dictates which User-related Administrator nodes can be accessed (Users, User Groups, and so forth). The User Administrator can also access the User-specific functions in Web Client (accessed through Tools and Settings > Address Book).

The User Administrator role also has a privilege (and privilege mask) called "User Administrator". The AppliedTo property of the User Administrator privilege mask is populated with PLM Roles. This means that a user administrator can be configured so that he can only assign specified roles to PLM users.

This is more fully described in"Options for Building Administrator Assistants," which is part of the important topic "AppliedTo Property in Select Privileges."

Advanced Search Security

Two restrictions have been added to Advanced Search utility.

The first restriction applies to the "Search for" field when a user creates any type of search (Quick, Advanced, Parametric search). Now he will see (in the drop-down list of classes) only those classes for which he has been assigned the Discovery privilege.

Similarly, "Field" criteria condition (drop-down list) will not display fields if user does not have a Read privilege (or Enforce Field-level Read privilege) to them. To ensure restricted field-level read, the user's Read privilege mask must include in its AppliedTo property only the fields you want the user to read. In addition, the user must also be assigned an Enforce Field Level Read privilege mask, for example, by assigning the Enforce Field Level Read role.

For a user to be able to view Workflow Routings folder under Search tab (on the Navigation pane), in the user's profile > Searches field, "Workflow Routings" must be moved from Choices to Selected table.

Read and Discover Object I Created Role

This new role simply enforces access to an object to be strictly based on assigned roles and privileges.

It has always been possible for the creator of a business object to subsequently access the object even if he did not have specific Read or Discover privileges for the object. While this is usually not a serious problem, it could pose problems to a company when users change departments or other assignment.

Now a new user is created with two default roles: besides My User Profile, each user is assigned Read and Discover Objects I Created. This role can be removed from any user at any time.

Note: Upgrade customers will not see a change in behavior with existing users; that is, upgrading users can still see objects they created.

16.4 Securing and Maintaining Roles and Privilege Masks

Important: This section is intended to both warn you of potential risks if you do not have a "security and maintenance plan" and provide some steps for simple troubleshooting if you do encounter a problem in PLM. Discuss this matter with your Oracle Consulting - Agile Practice representative, or call Agile Support.

By following the recommended plan described in this section, you will help prevent security violations, interruptions in your change control process, and confusion if you need to restore the system to a previous security configuration.

Caution: Failure to follow the recommendations in this section could have serious consequences: without your knowledge, users may unexpectedly be able to perform actions they had been prohibited from performing; also, users could suddenly lose their ability to carry out required actions.

When corruption or unplanned alteration to your Agile PLM system occurs, you will have to interrupt regular system management just to restore essential permissions, which itself could result in additional violations.

16.4.1 Using Agile Configuration Propagation to Restore Admin Settings

You have access to Agile Configuration Propagation (ACP), which lets you propagate the configuration of one Agile instance to another instance of the same version. ("The configuration" is a general term that refers to "all settings content of all Java Client Administrator nodes in one Agile instance".) Any single propagation may consist of the complete Administrator data for an instance, or it may consist of a selected subset of Administration data for an instance.

The subsections that follow, regarding Admin Export and running Administrator Reports, offer some steps to troubleshoot or to diagnose a problem you may suspect exists. By these means, if you detect a problem with a role or some roles or privileges in your production instance of PLM, you may be able to resolve it from within the Administrator module itself.

However, if you determine that your production instance has a serious and widespread problem in Roles and Privileges (or, indeed, with other parts of the PLM application), you may need to do a propagation using ACP to restore correct (and validated) settings. In this case, see Agile PLM Configuration Propagation Guide for this release.

16.4.2 Recommended Security and Maintenance Plan

You should take great care when making changes to the powerful Agile PLM roles. Follow these configuration and maintenance recommendations:

• It is strongly recommended that one person be assigned responsibility for configuring roles and privileges. If a change in ownership is to occur, the current administrator should explain to the new owner:

  • The roles and privileges configuration

  • Any changes that have been made

  • The system of tracking changes to roles and privileges

• Perform a roles export (in the Roles window, select all roles, and click Export) and run the Roles and Privileges Summary report and the Privilege Mask Detail report before you change or create roles or privilege masks. Save the results for later comparison in case you need to determine what changes caused particular effects. Keep a log of changes to the privileges configuration. For more information about exporting, see "Object History and Administrative Object History." For more information about reports see "Administrator Reports."

• Use the supplied roles and privileges and make only required alterations.

• Follow the Action-Criteria-Object Type privilege mask naming convention (described in "About Privileges and Privilege Masks") to avoid confusion and potential security breaches. Include at least these three recommended basic identifying parts, and maintain consistent word order. Use the names of the privilege masks provided at installation as your guide.

• Avoid changing role and privilege assignments after their initial assignment. For example, if a change originator or CCB member has the Discovery privilege removed after an ECO has been routed, the originator or CCB member still receives notifications but cannot view the change.

• Avoid changing role and privilege assignments while users are working on the system. If such changes are made, users must log out and restart Agile PLM clients again for some changes to take full effect.

16.4.3 Database Backup Procedures

Before you make any changes, it is a good idea to back up the entire Agile PLM database, and run Administrator reports. You can use the database backup to rebuild the previous database. You can compare "before-and-after" reports and use them to diagnose the cause of changes to Agile PLM security.

16.4.3.1 Exporting Agile PLM Administrative Settings

Follow the instructions in "Object History and Administrative Object History." When you have finished backing up current role and privilege settings, run your reports.

Note: If you are importing these settings, be certain you are importing to the same database or the Agile PLM administrative data will not match.

16.4.3.2 Running Reports

When you run an Administrator report, include the report date and time in the file name, such as Roles_072601_3pm.csv. If you keep these report files, you can compare them later to track changes.

Note: Be aware that the Privilege Masks Details report can be quite long (hundreds of pages), depending on the number of users on the system.

To run the Roles and Privileges Summary report:

1. Select the Analytics and Reports tab in the navigation pane. The Analytics and Reports folders appear.

2. Expand the Standard Reports > Administrator Reports folder.

3. Double-click (Java Client) or click (Web Client) the Roles and Privileges Summary report. The Roles and Privileges Summary Report page appears.

4. Click Execute. The Get Attachment window appears.

5. Click Continue. This accepts the displayed default encoding type (Western European (ISO)). If you need to use a different encoding type, select it in the drop-down list and click Continue.

6. Follow the directions in the File Download and Save As dialog boxes to save the file to disk and specify a location to save it.

7. Modify the file name to include the report date and time. For example, Roles072602_3pm.csv

8. When the download is complete, click OK in the Get Attachment dialog box.

To run the Privilege Mask Detail report:

1. Select the Analytics and Reports tab in the navigation pane. The Analytics and Reports folders appear.

2. Expand the Standard Reports > Administrator Reports folder.

3. Double-click (Java Client) or click (Web Client) the Privilege Mask Detail report. The Privilege Mask Detail Report page appears.

4. Click Execute. The Get Attachment window appears.

5. Click Continue. This accepts the displayed default encoding type (Western European (ISO)). If you need to use a different encoding type, select it in the drop-down list and click Continue.

6. Follow the directions in the File Download and Save As dialog boxes to save the file to disk and specify a location to save it.

7. Modify the file name to include the report date and time. For example, Privmask072602_3pm.csv

8. When the download is complete, click OK in the Get Attachment dialog box.

Note: Be aware that the Privilege Masks Details report can be quite long (hundreds of pages), depending on the number of users on the system.

By running the Roles and Privileges Summary report and the Privilege Mask Detail report, you create a record of the current roles and privileges configuration. These reports are ASCII text files in .CSV format (comma separated values) that can be opened with an analysis application, such as Microsoft Excel.

You can also use a word processing program to compare two versions of the same report. If the changes you make to the security configuration produce unexpected results, you can run these reports again, and compare them in the word processing program to see the changes that you made.

16.5 Working with Roles

You can modify existing roles and create new ones. Once a role exists, you can assign it to users. This section describes the following role-management tasks:

• Modifying a Role

• Creating a New Role

• Deleting a Role

16.5.1 Modifying a Role

When you open a role, you can change its name, description, whether it's enabled or disabled, its list of privilege masks, and the users assigned to it. You cannot modify the properties for the Example-Read-Only roles.

To change the name or description of a role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Use the filter bar to display the role you want to modify.

3. Double-click a role to open it.

4. In the Name field, type a unique name (up to 255 characters).

   
   

   Note: You cannot rename the Administrator, My User Profile, or View Historical Report roles, or any of the Restricted roles.

   
   

5. In the Description field, type a short description (up to 510 characters).

6. Click Save.

To disable a role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Use the filter bar to display the role you want to modify.

3. Click the Disable button.

Note: You can also disable a role by opening it and changing its Enabled property. You cannot disable the Administrator, My User Profile, or View Historical Report roles, or any of the Restricted roles.

To remove privileges from a role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Use the filter bar to display the role you want to modify.

3. Double-click a role to open it.

4. Click the Privileges tab.

5. Select the privilege you want to remove.

6. Click Remove to delete the selected privilege from the role.

7. Click Yes on the Delete dialog.

To add privileges to a role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Use the filter bar to display the role you want to modify.

3. Double-click a role to open it.

4. Click the Privileges tab.

5. Click Add Privileges to open the Select Privileges dialog box.

6. Select privilege masks in the Choices list and use the right arrow to move privilege masks to the Selected list.

7. When you are finished, click OK.

To remove a user from a role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Use the filter bar to display the role you want to modify.

3. Double-click a role to open it.

4. Click the Users tab.

5. Select the user you want to remove.

6. Click Remove to delete the selected user from the list of assigned users.

7. Click Yes on the Delete dialog.

To add users to a role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Use the filter bar to display the role you want to modify.

3. Double-click a role to open it.

4. Click the Users tab.

5. Click Add Users to open the Select Users dialog box.

6. Select and use the arrows to move users from the Names list to the Recipients list.

7. When you are finished, click OK.

16.5.2 Building and Testing Attributes, Read/Modify Privileges, and Roles

Agile's privilege model is powerful and flexible, but it is also complex. The following task is a simple procedure for you to check that attributes (both pre-defined and user-defined attributes), privilege masks, and roles all work together as you customize them for your users' work.

To test that an attribute works with Read or Modify privilege masks and roles:

1. In a class, for example, Parts class, create a new, simple Page Two attribute. In this example, you are creating Parts.PageTwo.Test01. (See "About Attributes, Flex Fields, and Read-Through Fields.")

2. Create test privilege masks called Read Parts and Modify Parts. Apply them to the Test01 attribute. (See "AppliedTo Property in Select Privileges." You may want to examine "Discovery and Read Privileges.")

3. Assign the Read Parts and Modify Parts privilege masks to the Content Manager role. (See "Adding a Privilege Mask to a Role.")

4. Assign the Content Manager role to a user, perhaps a test user you create for the purpose. (That task precedes this section.)

5. Log out of your client, log in as that user, and check to see that you can both read and modify the Test01 field.

Note: This procedure is an overview of building and testing attributes, privileges, and roles. The task of setting up Agile PLM for your company is quite large, and you might consider enlisting the services of an Oracle Consulting - Agile Practice consultant for this important task.

16.5.3 Creating a New Role

Before creating a new role, you should review the roles you currently have. Run the Roles and Privileges Summary report to see a listing of current roles and their privilege masks. (See "Running Reports.")

The recommended method for creating a new role is to copy an existing role, and then make any necessary changes to the copy; see "Creating a New Role Using Save As." You can also create a new role from scratch; see "Creating a New Role from Scratch."

Note: If you delete a role, you can reuse the name of the deleted role when you create a new role or rename an existing role.

16.5.3.1 Before You Begin

Before creating a new role, answer the following questions:

• What will you name the new role?

• Which users will be assigned to the new role?

• What do you want the users assigned to this role to be able to do in Agile PLM?

• What do you want users assigned to this role to be prevented from doing in Agile PLM?

• Can you modify one or more existing roles to achieve the results you want?

• Is there an existing role that you can copy and modify to avoid having to create the role from scratch?

16.5.3.2 Creating a New Role Using Save As

You might find it easier to duplicate an existing role under a new name.

Creating a new role by duplicating one of the Example roles is a different process and produces different results. Review both processes to determine which one meets your needs. See "Using the Example Roles."

To create a new role from an existing role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Use the filter bar to display the role you want to modify.

3. Double-click the role you want. The tabbed window for that role appears.

4. Click the Save As button. The Save As dialog box appears.

5. Enter a new name and API name for the role.

6. Click OK.

   The new role is created with the new name, and its tabbed window appears. The new role has the same description as the one you copied. You can modify the description now, if you want. See "Modifying a Role."

   The list of privilege masks assigned to the original role is also assigned to the new role. However, no users have been assigned to the new role.

   For example, if the original role included the Modify Item privilege mask, the new role also includes the Modify Item privilege mask.

   
   

   Note: A read-only example role has read-only example privileges. When you use Save As to create a copy of an example role, the way the privilege masks are copied from the example role is different from what is described above. For details, see "Using the Example Roles."

   
   

7. Do one or more of the following:

   • On the Privileges tab, remove the privilege masks you do not want in the role.

   • On the Privileges tab, add the privilege masks you want to include in the role.

8. To assign the new role to specific users, see "Modifying a Role."

16.5.3.3 Creating a New Role from Scratch

You may decide to create a role or roles from scratch.

To create a new role from scratch:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Click the New button. The Create Role dialog box appears.

3. Type the name, API name and description of the new role.

4. To enable or disable the role, select Yes or No in the Enabled drop-down list. It is suggested that you disable the role while you develop it; select No.

5. Do one of the following:

   • To finish creating the role without assigning privilege masks or users (you can assign privilege masks and users later), click Finish.

   • To assign privilege masks to the role, click the icon next to the Privilege field. The Select Privileges dialog box opens. Continue with step 6.

6. Select privilege masks in the Choices list and use the right arrow to move privilege masks to the Selected list.

7. When you are finished, click OK.

   
   

   Note: You can also click New in the dialog box to create a new privilege mask. The Create Privilege dialog box opens. See "Creating a New Privilege Mask from Scratch." (Start with step 3.) The new privilege mask will be added to the role, and the privilege mask will appear in the list of available privilege masks in the Privileges node.

   
   

8. Do one of the following:

   • To finish creating the role without assigning users, click Finish. You might want to do this while developing the role and its privilege masks.

   • To assign specific users to the new role, click next to the Users field. The address book opens. Continue with step 9.

9. Select users from the Names tab—and groups from the Groups tab—and use the right arrow to move them to the Recipients list.

10. When you are finished, click OK.

11. When you are finished defining the new role, click Finish.

    The new role name appears in the Roles table. (Click Refresh if you do not see the role in the table.) Add privileges and users as needed. If you disabled the role in step 4, the Enabled field says No. You must enable the role for its assignment to users to go into effect.

16.5.4 Using the Example Roles

Agile PLM includes a number of example roles that you can use as references or as a starting point for your own roles. They are stored under the Example node folder in the Example Roles node. Example roles are read-only and cannot be modified. However, you can use Save As to make a copy of an example role and modify the copy.

Each example role corresponds to one of the preconfigured roles provided when Agile PLM is first installed. If you have modified the preconfigured roles and privileges, you can view the example roles to compare your modifications to the original construction of the preconfigured roles and privileges.

16.5.4.1 Example Privilege Masks in Example Roles

Example roles include example privilege masks. Example privilege masks are also read-only and cannot be modified. When you use Save As to create a copy of an example role, the system populates the new role with copies of the read-only example privileges.

For example, the Example – Creator role includes an example privilege mask named Example - CS - Submit ChgOrder. If you use Save As to make a copy of the Example - Creator role, the new role will include a privilege named Copy of Example - CS - Submit ChgOrder. This privilege mask copy is a new privilege mask that did not exist in the database before you copied the example role. All the privilege masks in the new role are copied in the same manner.

16.5.4.2 Creating a New Role from an Example Role Using Save As

To create a new role from an example role:

1. Under Examples, double-click Example Roles. The Example Roles page appears.

2. You can filter roles records to narrow your search. (See "Filtering Data in Java Client.")

3. In the Example Roles window, double-click the example role you want. The tabbed window for that example role appears.

4. Click the Save As button. The Save As dialog box appears.

5. Enter a new name and API name for the role.

6. Click OK.

   The new role is created with the new name, and its tabbed window appears. The new role has the same description as the example role you copied. You can modify the description now, if you want. See see "Modifying a Role."

   The privilege masks in the new role are copies of the example privilege masks in the example role. For more information, see "Example Privilege Masks in Example Roles" above.

7. Do one or more of the following:

   • On the Privileges tab, remove the privilege masks you do not want in the role.

   • On the Privileges tab, add the privilege masks you want to include in the role.

   For instructions on how to add or remove privilege masks and how you assign the new role to specific users, see "Modifying a Role."

   You can also change the names of the privilege masks or change the criteria or applied to properties of the privilege masks.

   On the Privileges tab, double-click a privilege mask to display its tabbed object page. Once you have displayed the privilege mask window, you can:

   • Change the name or description.

   • Modify the privilege mask criteria. See "Modifying Privilege Masks."

   • Modify the privilege mask applied to property. See "Modifying the AppliedTo Property."

8. For information about how to assign the new role to specific users, see "Modifying a Role."

16.5.5 Deleting a Role

If a role is no longer needed and no users have been assigned it, you can delete it.

To delete a role:

1. Under User Settings, double-click Roles. The Roles window appears.

2. Click the role you want to delete. The tabbed window for that role appears.

3. Click the Users tab to bring it forward.

   
   

   Note: You cannot delete a role if it has been assigned to any users or user groups. Before you can delete the role, you must remove all of its users and user groups. Remember that it is always possible to disable a role if you are not ready to delete it but want to block its effect on assigned users and user groups.

   
   

4. If there are any users listed on the Users tab, select all the users on the table.

5. Click Remove to clear the Users tab.

6. Repeat steps 3, 4, and 5 for the User Groups tab.

7. Click the Delete button.