Mask Generation and Compilation Tools

The VPLMPosMaskGenerator and VPLMPosMaskCompiler server-side batch tools generate and compile masks. These tools do not work with CAS authentication. These tools must be run on the server host, and the -connect argument should specify the localhost URL.

This page discusses:

Tool Locations

The VPLMPosMaskGenerator and VPLMPosMaskCompiler batch (Windows) or shell (UNIX) commands are located in:

  • INSTALL_PATH\server\win_b64\code\command (Windows)
  • INSTALL_PATH/server/scripts (UNIX)

The tools use the runtime view located in: <ENOVIAPlatformServer_WEB-INF>

VPLMPosMaskGenerator

The VPLMPosMaskGenerator generates the mask file associated to a modeler. The attributes of a modeler's entity are retrieved as follows:

If a mask was associated to the parent modeler:

  • The mask definition of inherited attributes (from the parent entity in the parent modeler) is retrieved as is
  • A mask definition is computed based on attributes local to the modeler's entity.

Otherwise, the mask definition of each modeler's entity is computed on all attributes (inherited or local).

After the mask is generated, it can be edited to match your business requirements. For example, you can:

  • Add authorized values / set a default value
  • Change mandatory property (from N to Y)
  • Change editable property of attribute usage in the WRITE function
  • Change attribute order in a given function

You need to copy generated mask files in the <ENOVIAPlatformServer_WEB-INF>/classes/vplm/mask/<mask_name> directory before compilation. Example:

VPLMPosMaskGenerator -d /tmp PLMProductDS

This command generates a file named PLMProductDS.mask in directory/tmp taking into account any existing mask definition for inherited attributes (defined in the PRODUCTCFG.mask file) plus the attributes local to the PLMProductDS.metadata.

VPLMPosMaskGenerator Syntax

The syntax is as follows: 

VPLMPosMaskGenerator [-h]
	[-connect	 <URL>]
	[-m	       <mask_name>]
	[-addpath 	<additional_mask_file_directory>]
	[-connect	 <URL>]
	[-d 	      <output_directory>]	
	<modeler>  <modeler> ...]
Keyword Description
-h Prints help.
-connect <URL> The command must be run on the server host, so the URL value should be the localhost URL. For example:

-connect http://localhost:8080/3DSpace

The value must be an http: server; https: is not supported.
-m <mask_name> The name of the mask to generate (default is "DEFAULT").
-addpath <additional_mask_file_directory>] The absolute path to an additional directory. The tool searches for inherited mask files in this directory, and then in standard resources path if not found. Mask files must be located in a vplm/mask/<mask_name> subdirectory of <additional_mask_file_directory>.
-d <output_directory> The output location of generate.log and the generated .mask file. One mask file is generated per specified modeler ( a .metadata file). If this option is not specified, the current path is used as output.
<modeler> [<modeler> ...] Modeler.

VPLMPosMaskCompiler

VPLMPosMaskCompiler compiles all <mask_name> mask files located in <ENOVIAPlatformServer_WEB-INF>/classes/vplm/mask/<mask_name> and generates a single <mask_name>.SecurityMask file.

The compilation result log is <output_directory>/result.log and contains:

  • Tree of modelers hierarchy, with the associated mask file
  • Summary of errors (sorted by modeler)
  • Summary of errors (sorted by category)

If a fatal error occurs, the .SecurityMask file cannot be used.

HTML files are generated in the <html_directory> (if the -html option is used). The _index.html file lists all processed modelers, alphabetically sorted, with the number of fatal errors, errors, and warnings. The file includes a link to the mask for any modeler with a mask.

The Modeler Overview shows:

  • The package hierarchy
  • The index of entities
  • An index table of errors, if some errors were encountered, with a link to the highlighted source
  • Per entity and function, the html-simulated rendering

The tool does not account for attribute aliases.

This table lists detected errors, their severity level, and possible cause:

Severity Message Comment and Action Resolution
Warning Unknown command [%0] Command is ignored. Check for spelling errors.
Warning This Custo Package has no associated mask Any CUSTO-type modeler must have a mask file. Generate a mask file.
FATAL Expected mask name %0, not %1 Command should have been: MASK %0 Edit the file.
FATAL Entity %0 does not belong to package %1 ENTITY command is ignored; consequently, all related commands (ATTR, etc.) will fail. Check for a spelling error or validate against the metadata entity.
Error Entity %0: attribute %1 was not predefined by ATTR command Attribute referenced by a FATTR command must be declared first by an ATTR command. Add the required ATTR command.
FATAL Entity %0 has no %1 attribute ATTR command is ignored. Check for a spelling error or validate against the metadata entity.
Error Entity %0, attribute %1: mandatory property cannot be N while it is Y in metadata Command should have been: ATTR %1;Y;… Edit the file.
FATAL Entity %0, attribute %1 : cannot use %2 value as an authorized value An enumerated set of values is defined on attribute %1 in metadata; value %2 must be chosen in this set. Either remove this VALUE command, or modify the enumerated set of values in metadata.
Error Unexpected %0 function FUNC command is ignored. Check for a spelling error.
FATAL Entity %0: external-type %1 attribute is not allowed in %2 function IP Protection : external-type attributes cannot be set/modified in generic UI interfaces(CREATE or WRITE functions)

Some exceptions to this rule show as warnings instead of fatal errors.

 Remove the corresponding FATTR command.
Error Entity %0: MANDATORY %1 attribute cannot be set to NOT EDITABLE in CREATE function Command should have been : FATTR %1;Y Edit the file.
Error Entity %0: attribute %1 whose protection is Read-only cannot be modified in WRITE function IP Protection: external-type attribute cannot be modified in generic UI interfaces

Command should have been : FATTR %1;N

 Edit the file.
FATAL Unexpected boolean value %0 \: expected Y'or N Use either N either Y character, respectively for NO and YES Edit the file.
Error Entity %0: cannot use attribute %1 in mask, as its protection flag (%2) denies it IP Protection: access to internal attributes is forbidden. Remove the ATTR command (and all related FATTR commands).

VPLMPosMaskCompiler Syntax

The syntax is as follows: 

VPLMPosMaskCompiler [-h]
	[-connect	 <URL>]
	[-m	       <mask_name>]
	[-addpath 	<additional_mask_file_directory>]
	[-connect	 <URL>]
	[-d 	      <output_directory>]
	[-html     <html_directory>]

Keyword Description
-h Prints help.
-connect <URL> The URL of a 3DEXPERIENCE server.
-m <mask_name> The name of the mask to generate (default is "DEFAULT").
-addpath <additional_mask_file_directory>] The absolute path to an additional directory. The tool searches for inherited mask files in this directory, and then in standard resources path if not found. Mask files must be located in a vplm/mask/<mask_name> subdirectory of <additional_mask_file_directory>.
-connect <url> The command must be run on the server host, so the URL value should be the localhost URL. For example:

-connect http://localhost:8080/3DSpace

-d <output_directory> The output location of result.log and the generated .SecurityMask files. If this option is not specified, the current path is used as output.
-html <html_directory> The directory for the compilation report and GUI rendering HTML files. If this option is not specified, no HTML files are generated.

The compilation report (result.log) lists the mask instructions that do not comply with the metadata file, in particular when the IP protection rules are not observed.

Message Type Description
Fatal An unrecoverable error occurred. The mask file was either not generated, either partially generated (and unusable).
Error The compiler either automatically fixed or ignored the error. The mask file could be generated.
Warning A minor error occurred.