association Command

Associations are a collection of groups, roles, or other associations.

For conceptual information on this command, see User Categories.

This page discusses:

User Level

Business Administrator

Syntax

The command uses this syntax. 

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

  • NAME is the name of the association you are creating. All associations must have a named assigned. When you create an association, you should assign a name that has meaning to both you and the user. This name cannot be shared with any other user types (groups, roles, persons, associations). For more information, see About Administrative Object Names.
  • CLAUSE provides additional information about the attribute.

Add Association

Associations are created and defined with the Add Association command. 

add association NAME [ADD_ITEM {ADD_ITEM}];

ADD_ITEM provides more information about the association you are creating. While none of the clauses are required to make the association usable, they are used to define the association’s relationship to existing groups, roles, and associations, as well as provide useful information about the association.

The Add Association clauses are: 

description VALUE
 
icon FILENAME
 
definition DEF_ITEM
 
[!|not]hidden
 
property NAME [to ADMINTYPE NAME] [value STRING]

  • DEF_ITEM must be enclosed within quotes and is: 
    USER_ITEM [{OPERATOR_ITEM USER_ITEM}]
  • USER_ITEM is: 
    [!]GROUP_NAME
    		 
    [!]ROLE_NAME
    		 
    [!]ASSOCIATION_NAME

Definition Clause

This clause defines which groupss, roles, and associations are included in the new association. The definition must be enclosed in quotes. 

definition “USER_ITEM [{OPERATOR_ITEM USER_ITEM}]”

  • USER_ITEM is the previously defined name of a group, role or association. An association definition can consist of all possible combinations of group(s), NOT-group(s), role(s), NOT-role(s), association(s), and NOT- association(s). Any USER_ITEM containing embedded spaces must be enclosed in quotes. Since the entire definition must also be enclosed in quotes, use single quotes for the USER_ITEM components and double quotes for the entire definition, or vice versa.
  • OPERATOR_ITEM can be either && (to represent AND) or || (to represent OR). Checks the association definition before accepting it as a valid definition. AND commands are evaluated before OR commands (that is, AND has a higher order of precedence). This order cannot be changed. The operator OR signifies the end of one expression and the beginning of another.

For example, the following definition: 

Admin and Production or Manager and Services

is evaluated as: 

Admin and Production
 
or
 
Manager and Services

To create a definition using the AND operator, the AND operator requires that the person be defined in each group, role, or association that you include in the AND definition. For example: 

definition “Engineering && Management”
To satisfy this definition, the person must be defined in both the Engineering Group and in the Management Role.

To create a definition using the OR operator, the OR operator allows you to include persons defined in any of the groups, roles, or associations included in the OR definition. For example: 

definition “Engineering || ‘Senior Management’”
To satisfy this definition, the person must be defined in either the Engineering Group or in the Senior Management Role.

Single quotes are used for the two word name “Senior Management,” and there is no space between the name and either single quote. A space between the second single quote and the double quote is optional.

To create a definition using Not Equal to exclude certain roles or groups or associations from the definition, you can use the Not Equal operator in the definition. Place an exclamation point (!) in front of whichever group/role/association you want to exclude. Be sure there is no space between the exclamation point and the name of the group/role/association. For example: 

definition “!Engineering && Management”
To satisfy this definition, the person must be defined in the Management role, but not in the Engineering group.

To create a definition using multiple operators, you can use any combination of roles and groups and associations using AND and OR operators and Equal and Not Equal. You can, for example, create a definition such as “A member of the Products Group AND a member of the Engineering Group OR a member of the Design Group OR a Vice President but NOT a member of the Marketing Group.” For example: 

definition “!Marketing && Products && Engineering || Design ||’Vice President’”

Copy Association

After an association is defined, you can clone the definition with the Copy Association command. This command lets you duplicate defining clauses with the option to change the value of clause arguments. 

copy association SRC_NAME DST_NAME [MOD_ITEM {MOD_ITEM}];

  • SRC_NAME is the name of the association definition (source) to copied.
  • DST_NAME is the name of the new definition (destination).
  • MOD_ITEM is modifications that you can make to the new definition. For more information, see Modify Association.

Modify Association

After an association is defined, you can change the definition with the Modify Association command. This command lets you add or remove defining clauses and change the value of clause arguments. 

modify association NAME [MOD_ITEM {MOD_ITEM}];

  • NAME is the name of the association you want to modify.
  • MOD_ITEM is the type of modification to make. Each is specified in a Modify Association clause, as listed in the following table. You only need to specify fields to be modified.
    Modify Association Clause Specifies 
     name NEW_NAME
    		The current association name is changed to the new name. 
     description VALUE
    		The current description, if any, is changed to the value entered. 
     icon FILENAME
    		The image is changed to the new image in the file specified. 
     definition DEF_ITEM
    		The definition is changed to the new definition specified. 
     hidden
    		The hidden option is changed to specify that the object is hidden. 
     nothidden
    		The hidden option is changed to specify that the object is not hidden. 
     property NAME [to ADMINTYPE NAME] [value STRING]
    		The named property is modified. 
     add property NAME [to ADMINTYPE NAME] [value STRING]
    		The named property is added. 
     remove property NAME [to ADMINTYPE NAME] [value STRING]
    		The named property is removed.

Each modification clause is related to the clauses and arguments that define the association. For example, assume you want to alter the definition for the Drivers First Shift association to reflect the addition of a new group. You might write this command: 

modify association “Drivers First Shift“   
     definition “RR#6 && ‘West Side’ && RR#15”;

This command redefines the groups that are included in the association.

When modifying an association:

  • The roles, groups, or associations that you assign to the association must already be defined within the database. If they are not, an error will display when you try to assign them.
  • Altering the group or role access affects all persons included in the association that contains those groups or roles. If it is a singular case of special access, you can assign that person to the policy directly or define a role that is exclusively used by the person in question.

Delete Association

If an association definition is no longer required, you can delete it with the Delete Association command. 

delete association NAME;
  • NAME is the name of the association to be deleted.

After this command is processed, the 3DSpace searches the list of associations. If the name is not found, an error message is displayed. If the name is found, the association is deleted and any linkages to that association are dissolved.

For example, to delete the association named “Tree Specialists,” enter the following MQL command: 

delete association “Tree Specialists”;

After this command is processed, the association is deleted and you receive an MQL prompt for another command.