Using the Mask Merger

Merger Principles

When upgrading your EV6 installation with a new version, the changes that may have been done to original mask files have to be transferred to the customized ones, according to the following process:

The merger algorithm is based on comparison between 3 sorted tree structures, loaded from previous DEFAULT, current DEFAULT and previous customization mask files.

Thus, file content is automatically sorted when loaded; but node’s weight (it’s line offset v/s its parent node) is kept to sort back the resulting tree according to the weight of added nodes in the sub trees, when it is important:

• list of authorized values (VALUE)
• ordered list of attributes use (FATTR)

Important: merging nodes coming from different trees (NEW or CUSTO) and recombining them according to their weight in these different trees may lead to “bizarre” orders, semantically speaking, although this is a normal behaviour. See example in Limitation 1.

Comparisons are made between nodes of each tree, and an action is deduced according to the result of these comparisons. This is summarized and detailed in the following table.

Actions:

Node origin:

Table:

In some cases, a doubt may exist; an alternate action may be performed. This may be defined through a rule file describing the actions to be taken in such cases (X+4 limitation: only the recommended action is performed, no rule file is considered).

The Next iteration columns define complementary actions that have to be performed:

deep first

If set to yes, the merging process has to be performed on current node’s sub-levels BEFORE the resulting recommended (or alternate) action.

next sibling

It defines in which tree(s) the current node’s cursor has to be moved to the next sibling AFTER the resulting action.

Iteration Example

If we consider 3 mask files whose file structure is as follows, and the current iteration is as indicated by the red cursor box:

Then, based on the table above, the current iteration situation is "Node added in Cus":

The action to be taken is "Add Cus". In such case, it is not necessary to continue merging on sub-levels before performing the "Add Cus" action (this explains why deep first = no).

So, the E2 node (and its sub-tree) is added to the current result:

Then, the current node's cursor in the CUS tree is moved to the next sibling, which results in the following case at the beginning of the next iteration:

Note: The recommended action is performed, no rule file is taken into consideration.

Sample

Suppose we have the following initial file content:

Once loaded, the initial data are as follows (N.B: the authorized value flag property was not listed, to reduce the number of iterations:

Merging iterations start on the 1st child node of each root mask node. Here, it is Entity E1:

The resulting mask file is (N.B: in red is the difference v/s customized mask in version (n):

Mask Merger Syntax

VPLMPosMaskMerger is a server-side batch program (a shell on UNIX), located in:

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

The mask merger merges all mask files listed in the previous customization directory of each specified mask name (<previous_custo_dir>/vplm/mask/<mask_name>).

The merge is based on previous and current DEFAULT version, and of course the previous customization version of each mask file.

Each merged file is generated in a sub-directory of the output directory, depending on the specified mask name (<output_dir>/vplm/mask/<mask_name>). Note that not existing output sub-directories are automatically created, if possible (an error is raised otherwise).

Note: the merger does not use the PLM Dictionary to make additional checks, as the mask compiler does (for instance, checking an entity really exists). It only requires mask files to have a correct mask file syntax.

IMPORTANT: as only mask files (mask sources) are merged – and not SecurityMask files (result) – the administrator has to compile them using the VPLMPosMaskCompiler tool after merge, and redeploy the compiled SecurityMask file in the Web Application Server.

VPLMPosMaskMerger		[-h]
         -m	<mask_name> [<mask_name> ...]
         -p	<previous_DEFAULT_dir> <current_DEFAULT_dir> [<previous_custo_dir>]
         [-d <output_dir>]

The syntax is as follows:

Example

Let’s consider the following filetrees:

         /previousInstallation
         /vplm
		          /mask
               /DEFAULT
				               PLMProductDS.mask
                   …
			            /MYMASK
                   PLMProductDS.mask
         /currentInstallation
         /vplm
		          /mask
			            /DEFAULT
		               	PLMProductDS.mask
                  ...

Executing:

VPLMPosMaskMerger -m MYMASK -p /previousInstallation /currentInstallation

merges all MYMASK customized mask files located in:

/previousInstallation/vplm/mask/MYMASK directory

according to their DEFAULT versions located in:

/previousInstallation/vplm/mask/DEFAULT

and:

/currentInstallation/vplm/mask/DEFAULT

directories (previous and current version, respectively), and generates merged version of mask files in:

./vplm/mask/MYMASK

If we consider there is only one file named PLMProductDS.mask in the /previousInstallation/vplm/mask/MYMASK directory, only one merged file will be generated:

./vplm/mask/MYMASK/PLMProductDS.mask

Limitations

Limitation 1

This limitation concerns node reordering after merging.

Some nodes have to be resorted according to their original appearance order, because this order is important. This is the case for authorized values (VALUE) and attributes use in function (FATTR).

As resulting nodes may from different trees (NEW or CUSTO), their weight in their original tree from may not well coincide in the resulting tree. Recombining them according to this weight (plus the alphabetical order if weights are the same) may lead to "bizarre" orders, semantically speaking, although this is a normal behaviour.

Here is a small example:

Here, the order (One, Many, Two) may seem inappropriate (a logical order would have been : One - Two - Many), but:

• One and Many come from the CUS tree; they kept their respective original order such that Many (weight=1) appears after One (weight=0).
• Two comes from the NEW tree, with the same weight as Many (=1). As Many"" is alphabetically lower than "Two", it appears finally before "Two".

This is because the sort is NOT - of course - a semantic sort.

Limitation 2

Management of alternate actions with an external rules file in ambiguous cases is currently not supported.