role Command

[add|copy|modify|delete|list|print] role NAME {CLAUSE};

• NAME is the name you assign to the role. This name must be unique and cannot be shared with any other type of user (groups, roles, persons, associations). Assign a name that has meaning to both you and users. For more information, see About Administrative Object Names.

  In addition to the character restrictions for administrative object names, these characters are also forbidden for role names: \ " * ' $ ? ' , . ; \n \r .

• CLAUSEs provide additional information about the role.

Syntax

Roles are created and defined with the following command:

add role NAME [ADD_ITEM {ADD_ITEM}];

• ADD_ITEM is a clause that provides more information about the role you are creating. While none of the clauses are required to create the role, they are used to assign specific users and groups to the role. Roles can also be defined as either a project or organization. The ADD_ITEM clauses are:

  assign person PERSON_NAME [group GROUP_NAME]

  assign role ROLE_NAME

  child ROLE_NAME {,ROLE_NAME}

  description VALUE

  icon FILENAME

  maturity[none | public | protected | private]

  parent ROLE_NAME

  site SITE_NAME

  [!|not] hidden

  AS_KIND_OF

  property NAME [to ADMINTYPE NAME] [value STRING]

  history STRING

  • AS_KIND_OF is one of these values: | asaproject | asanorg | asarole | asaprojectgroup |

Maturity Clause

The maturity of a project determines the access to objects in that project. The maturity attribute is intended primarily for roles that represent projects, but is not limited to that category. The maturity attribute on roles can be set to public, protected, private, or none.

For more information, see Collaboration and Approvals Administration Guide: About Project-Based Access.

Parent and Child Clauses

These clauses define the relationship of the new role to other defined roles. This hierarchy allows one role to share access privileges with another, saving time when defining access privileges when a policy is defined. You can have any number of child roles and any number of parent roles.

For example:

add role “Engineer” child “Principal Engineer”;

add role “Engineering Manager” parent Manager,Employee;

Of course, the role named as the parent or child must be previously defined. For more information, see Collaboration and Approvals Administration Guide: User Categories.

Assign Person Clause

The Assign Person clause assigns specific users to the role. A role can have no users, or they could have many. Roles with no users can be defined to show a hierarchical relationship between roles. In that case, the defined role acts as a parent for other roles.

Do not modify the persons creator or guest. Modifying these objects could cause triggers, programs or other application functions not to work.

assign person PERSON_NAME [role ROLE_NAME]

• PERSON_NAME is the previously defined name of a person.
• ROLE_NAME is the previously defined role.

If these names are not previously defined, an error message is displayed.

You can assign users roles in two ways, depending on how you are building your database:

• With the Assign Person clause in the add Role command, as described here.
• In the Person command. For more information, see Add Person.

Since previously defined names are required to make the Assign Person clause valid, it is not uncommon to wait before assigning persons to a role definition. When building the database, you might want to define only the roles and then handle the assignment of users in the person definitions. But, if you choose to define the persons first, or if you are adding a role to an existing database, you can assign users to the role with the assign person clause. Regardless of where you define it, an assignment made to a role becomes visible from all applicable definitions. This means that the link between the role and the person will appear when you later view either the role definition or the person definition.

Assign Role Clause

You can use the Assign Role clause to add a user group to the role. In effect, this adds all the people in that user group to the role instead of needing to add them individually. A user group is a role defined as a project group. For more information, see As a Project Group Clause.

This user group is different from the group used in the assign person PERSON_NAME [group GROUP_NAME] clause. For more information on that type of group, see group Command.

Site Clause

A site is a set of locations. It is used in a distributed environment to indicate the file store locations that are closest to the role. The Site clause specifies a default site for the role you are defining. Consult your System Administrator for more information.

To write a Site clause, you use the name of an existing site. If you are unsure of the site name or want to see a listing of the available sites, use the list site command. This command produces a list of available sites from which you can select. For more information, see Locations and Sites.

Sites can be set on persons, groups and roles, as well as on the Server (with MX_SITE_PREFERENCE). The system looks for and uses the settings in the following order:

• If using a Collaboration Server, the MX_SITE_PREFERENCE is used.
• If not using a Collaboration Server, or the MX_SITE_PREFERENCE is not set on the server, if there is a site associated with the person directly, it is used.
• If no site is found on the person, it looks at all groups to which the user belongs. If any of those groups have a site associated with it, the first one found is used.
• If no sites are found on the person or their groups, it looks at all roles the person is assigned. If any of those roles have a site associated with it, the first one found is used.

Add the MX_SITE_PREFERENCE variable to the 3DSpace Service initialization file (enovia.ini). This adjustment overrides the setting in the person, group, or role definition for the site preference, and should be set to the site that is local to the server. This ensures optimum performance of file chicken and checkout for Web clients.

As a Project Clause

A project is created by defining a role as a project with the asaproject clause. Roles are often hierarchical and you will not be able to define a role as a project if the parent of that role is not defined as a project.

add role “my project” asaproject;

In the example above, the project, “my project,” is created. The name of a project must be unique and cannot be used by another role or user category. Projects are still of the type role user category and have the same parameters as roles. The type shown for a project will be a role. The selectable list for a project is the same as for a role.

As an Organization Clause

An organization is created by defining a role as an organization with the asanorg clause. Roles are often hierarchical and you will not be able to define a role as an organization if the parent of that role is not defined as an organization.

add role “my organization” asanorg;

In the example above, the organization, “my organization,” is created. The name of an organization must be unique and cannot be used by another role or user category. Organizations are still of the type role user category and have the same parameters as roles. The type shown for an organization will be a role. The selectable list for an organization is the same as for a role.

As a Role Clause

The asarole clause is used to modify a role defined as a project or organization back into a role. Use this clause with the Modify Role command.

mod role "my project" asarole;

In the example above, the role previously defined as the project, “my project,” is turned back into a role.

As a Project Group Clause

The asaprojectgroup clause defines the role as a user group. User groups can be assigned to collaborative spaces or folders (or other business objects) or security contexts, to collectively assign the people in that user group to that object. After that, adding or removing people from the user group manages the access to the business object. You do not have to add or remove the people individually. For example:

add role "DesignGroup" asaprojectgroup;

This user group is different from the group used in the assign person PERSON_NAME [group GROUP_NAME] clause. For more information on that type of group, see group Command.

Ancestor Selectable on Role

The select keyword “ancestor” returns the entire upward hierarchy of parents, as well as the user against which it is executed. For example:

project.ancestor match context.user.assignment.parent

This evaluates to true for data allowed for a user’s project.

History Clause

The history keyword adds a history record marked “custom” to the role that is being added. The STRING argument is a free-text string that allows you to enter some information describing the nature of the addition. For more information, see Adding History to Administrative Objects.

copy role SRC_NAME DST_NAME [MOD_ITEM {MOD_ITEM}];

• SRC_NAME is the name of the role that you want to copy.
• DST_NAME is the name of the new role.
• MOD_ITEM is the list of clauses that define the changes to make to the new copy. For more information, see the clauses listed in the next section.

Syntax

modify role NAME [MOD_ITEM {MOD_ITEM}]

After you establish a role definition, you can add or remove defining values. When modifying a role, it is important to consider how accesses are shared between parent and children. If you do not want a child to assume the same accesses to business objects as the parent, you will have to modify the policy so the privileges for the child role are specified. If a role is not specifically referenced in a policy, 3DSpace looks for access hierarchically. For example, if the role has a parent and the parent is named in the policy, the child shares the parent’s privileges.

The MOD_ITEM clauses for a role are:

[add] assign person PERSON_NAME [group GROUP_NAME]

[add] assign role ROLE_NAME

name NEW_NAME

description VALUE

parent ROLE_NAME

child ROLE_NAME {,ROLE_NAME}

maturity [none | public | protected | private]

remove assign | person PERSON_NAME [group GROUP_NAME] | 
              | role ROLE_NAME                        |             
              | all                                   |

remove child  | ROLE_NAME {,ROLE_NAME} |
              | all                    |

remove parent

site SITE_NAME

[!|not] hidden

add property NAME [to ADMIN] [value STRING]

remove property NAME [to ADMIN]

property NAME [to ADMIN] [value STRING]

If you remove a parent or child, you might inadvertently remove access privileges from the children. Make sure that you consult the policies you have created when you alter the hierarchy of defined roles.

History Clause

The history keyword adds a history record marked “custom” to the role that is being modified. The STRING argument is a free-text string that allows you to enter some information describing the nature of the modification. For more information, see Adding History to Administrative Objects.

To determine the projects and organizations that reference a role, you can execute these MQL commands:

temp query bus * * * where project==<rolename>
temp query bus * * * where organization==<rolename>
query connection type * where project==<rolename> select id
query connection type * where organization==<rolename> select id

where <rolename> is the name of the role you plan to delete.

If you still want to delete the role, use the results of the above queries to change the referenced role for each object. You can only delete the role if ALL of the references have been removed.

When deleting a role, the elimination of linkages can affect another role’s access to business objects. For example, suppose you have these two roles: Assembly Manager and Component Assembler. Assembly Manager is the parent of Component Assembler.

According to the policy governing the Assembly Manager role, the Assembly Manager role has read access to all business objects of type Assembly. Since a child role inherits the access abilities of its parent role (unless specified otherwise), the Component Assembler role also has read access.

If the Assembly Manager role is deleted, the linkages disappear between Assembly Manager and Component Assembler. Component Assembler becomes a stand-alone role and loses the read access inherited from the Assembly Manager role. If this access was critical, you can modify the role definition for Component Assembler with read access.