Mask Syntax

Syntax

Keyword	Description	Example
`MASK <id>`	Starts a mask definition for all following entities (only ONE per mask file is allowed) `<id>` is the identifier of the mask `<id>.SecurityMask` will be the name of the file resulting from the compilation of every specified mask files containing the line: `MASK <id>`	`MASK DEFAULT`
`ENTITY <entity_ name>`	Starts the access control information about this `<entity_name>` for the current mask. `<entity_name>` is the value of the attribute “Name” of the tag “Class” or “Extension” in the metadata file.	`ENTITY PLMProductDS`
`ATTR <attribute> ;< mandatory>;< authorized_ required>;< default value>`	Defines the static access control information about an `<attribute>` belonging to the current entity. `<attribute>` is the value of the attribute "Name" of the tag "Simple" in the .metadata file. Rule: only simple attributes are currently supported in masks: aggregates and relationships are excluded.	`ATTR PLM_ExternalID;Y;N;$`
`mandatory`	Specifies if the attribute is required or not. Legal values are: Y and N. `Y`if the attribute is required (this forces the end user to enter a value in the field in the GUI) `N` otherwise Rule: if the attribute is already set as mandatory in `.metadata`, then it must also be set as mandatory in mask.
`authorized_ required`	Specifies a constraint on the values of this attribute. Legal values are Y and N. `Y` values are the only authorized values (the end user must select one of the values from a combo list in the GUI) `N` values (see VALUE) are help values, i.e. a value not in the list can be used to set the attribute value
`default_value`	Used to preset this attribute's value at creation time. Any value, or $ if value is null. Rule 1: `<default_value>` cannot be equal to $ if `<authorized required>` == Y. Rule 2: If authorized values are defined in the mask, the `<default_value>` MUST BELONG to this list.
`VALUE <value>`	Sets an authorized value for the current attribute. Add one value to help/authorized values of attribute. Rule: if a list of enumerated values exist in `.metadata`, the `<value>` must belong to it.	`VALUE Supplier A`
`FUNC <operation>`	Starts the access control information about a pre-defined `<operation>` for the current entity. Valid operations are: Create, Write, Read, EZQuery (simple query), Query (extended query), Tree (Tree node id), List.	`FUNC Create`
`FATTR <attribute>`	References the `<attribute>` that is visible in the current operation's view. Rule: `<attribute>` must have been previously declared using the keyword ATTR. `<editable>` specifies if this attribute is modifiable or not. Legal values are Y and N: `Y` attribute can be modified in this operation `N` not modifiable. Note: this property is meaningful mainly for the Write operation: is the end-user allowed to modify or not the corresponding field in the properties editor? However, this property is mandatory for any `FATTR` declarations under any `FUNC` declarations. This property should be set to: `Y` for Create, Write, Query and Ezquery `N` for Read, Tree and List. The order of the `FATTR` declarations in the `FUNC` section specifies the order in which the referenced attributes appear in the current operation's view.	`FATTR PLMExternalID;Y`

Rules about IP Protection (defined in metadata files)

Not all attribute combinations are authorized in a security mask: this depends on their IP Protection declaration in the .metadata file.

These rules are enforced by the VPLMPosMaskGenerator tools and any errors reported by the VPLMPosMaskCompiler tool (however, these are not fatal errors for the compilation process, only syntax errors are fatal):

ATTR

An attribute is authorized in a security mask if its Protection attribute equals ExternalRO, External, Free, or User.
<mandatory> MUST BE == Y if this attribute has Mandatory=Yes in the .metadata file.

FATTR

If Protection equals External or ExternalRO, then this attribute SHOULD NOT be visible in:

SHOULD NOT be visible in FUNC Create
SHOULD NOT be modifiable in FUNC Write

You could have either:

no corresponding FATTR command
the following: FATTR <attribute>;N.

If Protection equals Free or User and <mandatory> is Y, then this attribute MUST be visible in FUNC Create

The only valid case is: FATTR < attribute >;Y.

Summary

<Simple>		ATTR <mandatory>	FUNC Create		FUNC Create
Protection	Mandatory		V	`<editable>`	V	`<editable>`
External	Yes	Y	O		*	N
External	No	Y/N	O		*	N
Free, User	Yes	Y	X	Y	*	Y/N
Free, User	No	Y	X	Y	*	Y/N
Free, User	No	Y	X	Y	*	Y/N

V indicates the visibility:

x = visible (listed via an FATTR command)
o = not visible
* = indicates any possibilities.

Mask Concatenation

Mask concatenation mechanism is finally a mask override mechanism.

When a user logs on, only one mask is chosen (and loaded) according to the first mask found granted on (in this order):

the person
the current security context
the current security context's project
the current security context's role
the current security context's organization.

If none is found, the DEFAULT mask is applied.

Notes:

there is no search of granted mask in the hierarchy of the current context's project, role or organization. So, even if one (or several) was granted in higher levels in hierarchy, IT WILL NOT BE TAKEN INTO ACCOUNT.
if MORE THAN ONE mask is granted to the same component, the first mask found in the list of available mask commands is taken. You can know this order in using the MQL command:
list mask::*

The recommendation is to grant only ONE mask to a given P&O object to avoid such side effects. All entities declared in the chosen mask are RESTRICTED: they are subject to access control.

When an entity is RESTRICTED by a mask, ALL its attributes must be EXPLICITLY DECLARED to be accessible. Otherwise, attributes of a restricted entity are considered as NOT ACCESSIBLE. The entities not referenced by a mask have NO RESTRICTION: no access control is applied.

PLMProductDS Sample

The examples below show the effects of security masks as far as the Product dialog boxes are concerned (Product is the alias for the customized PLMProductDS entity, in this example).

If you are using a context with no mask other than the default mask, the Product dialog boxes will look like below.

PLMProductDS Mask Definition

The mask definition of the PLMProductDS entity corresponding to these views is contained in the PLMProductDS.mask file. We show the related part of this file along with the panels. The syntax used to define the security mask is explained in this document.

The mask definition begins with the entity and its attribute definitions:

ENTITY PLMProductDS
ATTR PLM_ExternalID;Y;N;$
ATTR V_version;N;N;$
ATTR V_description;N;N;$
ATTR C_created;N;N;$
ATTR C_modified;N;N;$
ATTR V_maturity;N;N;$
ATTR LOCKUSER;N;N;$
ATTR V_discipline;N;N;$
ATTR V_usage;N;N;$
ATTR V_project;N;N;$
ATTR V_user;Y;N;$
ATTR V_organization;Y;N;$
ATTR V_IndustryCode;N;N;$
ATTR V_StdNumber;N;N;$
ATTR V_BOM;N;Y;Yes
VALUE Yes
VALUE No
ATTR V_Supplier;N;Y;TRUE
VALUE TRUE
VALUE FALSE
ATTR V_SupplierName;N;N;$
VALUE Supplier A
VALUE Supplier B
VALUE Supplier C

Next is the mask for the Create operation. Create controls the creation time attribute list:

GUI interaction: PLM Access->New…

Result:

//-------------------------------
FUNC Create
//-------------------------------
FATTR V_description;Y
FATTR PLM_ExternalID;Y
FATTR V_description;Y
FATTR V_IndustryCode;Y
FATTR V_StdNumber;Y
FATTR V_BOM;Y
FATTR V_Supplier;Y
FATTR V_SupplierName;Y

Next are the masks for EZQuery and Query operations. Query controls the list of attributes available for queries. EZQuery is the same as Query except that the EZQuery mask is used to define the "Easy" panel (the most-used list of attributes for query) whereas the Query mask is used for the "Extended" and "Expert" panels (all queryable attributes):

GUI interaction: PLM Access -> Advanced Search:

Result:

Easy query:


// -----------------------------
FUNC EZQuery
// -----------------------------
FATTR PLM_ExternalID;Y
FATTR V_version;Y
FATTR C_created;Y
FATTR C_modified;Y
FATTR V_maturity;Y
FATTR LOCKUSER;Y

Normal query (“extended”):

// -----------------------------------
FUNC Query
// -----------------------------------
FATTR PLM_ExternalID;Y
FATTR V_version;Y
FATTR V_description;Y
FATTR C_created;Y
FATTR C_modified;Y
FATTR V_maturity;Y
FATTR LOCKUSER;Y
FATTR V_discipline;Y
FATTR V_usage;Y
FATTR V_project;Y
FATTR V_user;Y
FATTR V_organization;Y
FATTR V_IndustryCode;Y
FATTR V_StdNumber;Y
FATTR V_BOM;Y
FATTR V_Supplier;Y
FATTR V_SupplierName;Y

Result (not all attributes are visible as a whole):

Next is the mask for Read operation. Read controls the displayable attribute list for presenting the results of a search:

This mask applies in Search dialog boxes:

// ---------------------------------------
FUNC Read
// -----------------------------------
FATTR PLM_ExternalID;N
FATTR V_version;N
FATTR V_description;N
FATTR C_created;N
FATTR C_modified;N
FATTR V_maturity;N
FATTR LOCKUSER;N
FATTR V_discipline;N
FATTR V_usage;N
FATTR V_project;N
FATTR V_user;N
FATTR V_organization;N
FATTR V_IndustryCode;N
FATTR V_StdNumber;N
FATTR V_BOM;N
FATTR V_Supplier;N
FATTR V_SupplierName;N

Result (not all attributes are visible as a whole):

Finally, here is the mask for the Write operation. Write controls the modifiable attribute list:

GUI interaction: Explore in PPR -> Properties

Result:

// -----------------------------------
FUNC Write
// -----------------------------------
FATTR PLM_ExternalID;Y
FATTR V_version;N
FATTR V_description;Y
FATTR C_created;N
FATTR C_modified;N
FATTR V_maturity;N
FATTR LOCKUSER;N
FATTR V_discipline;N
FATTR V_usage;N
FATTR V_project;N
FATTR V_user;N
FATTR V_organization;N
FATTR V_IndustryCode;Y
FATTR V_StdNumber;N
FATTR V_BOM;Y
FATTR V_Supplier;Y
FATTR V_SupplierName;Y

PLMProductDS.CATNls File

You may have noticed the difference between the attribute names contained in the .mask file and the attribute names displayed in the panels which are all NLS enabled aliases. The attribute aliases are not contained in the mask definition any more like in ENOVIA V5 releases, but are contained in CATNls files (on the CATIA client in the directory:

<os>/resources/msgcatalog

that must be provided along with the metadata and mask files to complete the picture for the entities and their attributes. The aliases should conform to the following format:

Modeller: <modeller name> = "<modeller alias>" = ;

Entities: <modeller name>.<PLM core type> = "<entity alias>"; Attributes: <modeller name>.<PLM core type>.<attribute name> = "<attribute alias>";

Where <PLM core type> is one of the possible core types: PLMCoreReference, PLMCoreInstance, PLMCoreRepReference, PLMCoreRepInstance, PLMPort, PLMConnection. Example: an extract from file PLMProductDS.CATNls: PRODUCT="Product Structure Default Customization"; PRODUCT.PLMCoreReference="Product"; PRODUCT.PLMCoreReference.V_hasConfigContext="Is Configurable"; PRODUCT.PLMCoreReference.V_maturity="Maturity"; PRODUCT.PLMCoreReference.V_ApplicabilityDate="Applicability date"; PRODUCT.PLMCoreReference.V_version="Version"; PRODUCT.PLMCoreReference.C_created="Creation date"; PRODUCT.PLMCoreReference.C_modified="Last modification"; PRODUCT.PLMCoreReference.V_user="Responsible"; PRODUCT.PLMCoreReference.V_organization="Organization"; PRODUCT.PLMCoreReference.V_project="Project"; PRODUCT.PLMCoreReference.V_description="Description"; PRODUCT.PLMCoreReference.V_discipline="Discipline"; PRODUCT.PLMCoreReference.V_usage="Usage"; PRODUCT.PLMCoreReference.V_nature="Nature"; PRODUCT.PLMCoreReference.V_isUptodate="Is Uptodate"; PRODUCT.PLMCoreReference.LOCKSTATUS="Is Locked"; PRODUCT.PLMCoreReference.LOCKUSER="Lock Owner"; PRODUCT.PLMCoreReference.V_IndustryCode="Industry code"; PRODUCT.PLMCoreReference.V_StdNumber="Standard Number"; PRODUCT.PLMCoreReference.V_BOM="BOM"; PRODUCT.PLMCoreReference.V_Supplier="Sub-contracted"; PRODUCT.PLMCoreReference.V_SupplierName="Supplier Name"; PRODUCT.PLMCoreReference.PLM_ExternalID="Part Number";