Customizing the B.I. Essentials

Introduction

Conceptual Model

The B.I. Essentials concept is to allow dynamic identification of elements of any PLM structure, which will help the user to orient himself and look for information in a structured way.

The classifications are listed in the B.I. Essentials menu as shown below:

This documentation concerns the customizing of the B.I. Essentials.

Capability Summary

This article describes the capability to customize the B.I. Essentials.

For each type of editor, it will be possible to register a set of customizations.

Each customization will manage:

• The caption display in order to explain what is the nature and meaning of the information that is shown.
• The PLM Shading (color in the 3D view) of the B.I. Essentials and the background color of texts displayed in the spec tree.
  • RGB color and transparency coefficient, homogenous for both items: 3D representation and background color of texts.
• The labels of the B.I. Essentials.
  • Icons and texts of each row of the labels.

Each customization will rely on properties stored locally on each node of the tree. A mechanism of rule scripts is proposed for evaluating properties.

Therefore when a customer extends the PLM Data model, and adds new PLM attributes to objects, it will be possible to enhance the B.I. Essentials to have it taking into account the "customer specific" information.

External View/Behavior

For information, the B.I. Essentials presented to the end-user will be the one delivered by Dassault Systèmes, It is our STANDARD.

This Standard will be activated each time a user launches a new session.

• When selecting B.I. Essentials, a drop down list shows the list of available customizations plus the standard B.I. Essentials behavior. The user selects one item to see the associated rendering.
• The B.I. Essentials Checker(explained later) appears in the drop down list as the last entry.
• If the customization files are modified during the Session, these modifications can be reloaded using BI Essentials Checker(explained later).
• When one classification rule of the B.I. Essentials is in use, the shading color is consistent between the tree (text background color) and the 3D representations.
• Whenever a customization is selected, a set of rules are executed to provide information about:
  • The color codes and associated legends of the caption area.
  • Texts and icons which are shown in the labels.
  • The color code to be applied for each node and associated 3D representation.
• If the tree is already customized, the B.I. Essentials customization will overload his customization during its use.

User Interface

The standard user interface of the B.I. Essentials(old Name Compass) is modified.

In addition, a new list of choices are available to choose one customization from the list. The list also contains the default behaviors supplied by Dassault-Systèmes, all ordered alphabetically.

Customization

Customization Principle

The default behavior - reminder:

The selected classifying rule from B.I. Essentials, compute and display information about PLM Objects STATE relying on predefined PLM Attributes. These attributes belong to the basic PLM types.

For example: the LOCK status rule displays for each object a STATE relying on the V_LockOwner and V_Owner attributes.

These attributes are available on any Reference object (Part, Representation from any customization).

The customized behavior:

Let's suppose a customer deploy a customization of the PLM model this way:

Hence there will be a need for displaying two new STATES of PLM objects relying on Reviewer and Quality_Resp attributes (added by customization). This will lead to two customizations in B.I. Essentials : "Review" and "Quality".

Parts created in the customer database will be either of type PartRef_Custo1 or PartRef_Custo2. In one 3DLive window a mix of these objects might be displayed at the same time.

So any customization has to declare the way an object STATE is computed on a per type basis. This means a customization is made of a set of script rules; each rule is associated to one type. When executing a customization, for each PLM object of the current window a rule is searched based on the object type. If one is found it is executed, otherwise a rule is searched based on the object father type. The searching process stops when reaching the PLMCore type level.

As a summary:

• A customization is listed in B.I. Essentials.
• A customization is made of one or several rules; each of them is linked to a specific type.

Without any Customization

The shading today defined by using the B.I. Essentials will be applied to:

• The 3D representations as usual

Customization definition

Resource file and referenced script files:

To define the customization we need a description for:

• The list of PLM attributes that the user wants to use for its customizations.
  • All these PLM Attributes must exist in the CATPLMMaskTree
    • Customization Name
    • Custo
    • modeler
    • type
    • list of PLM Attributes
• The colors and associated legend of the B.I. Essentials for each customization.
  • For the 3D representations and background color of the tree's texts
    • Customization Name
    • The Color description i.e. that signifies what is defined by the Color.
    • Text of the legend
    • Name of the script use to get the color characteristics.
    • The RGBA, alpha description of the color.
• The description of the labels for each customization.
  • Customization Name
  • For each Row of the label:
    • Icon name
    • Customized text (in front of the value of the attribute).
    • Attribute name to do the query or the name of the script to get the attribute value, depending of what technology will be used to get the PLM information.

All this information will be stored in different .CATRsc files :

• BICusto.CATRsc :- Name of file should not change .The BI-ID and the Scope of the BI is defined here.
• CATRsc which defines the Colors to be used RGBT values.
• Each BI should be defined in separate CATRsc file.

The script files contain the rule to get Colors value for a given customization (for a unique defined type based on these three characteristics: customization , modeler, PLMCoretype) . The rule in the script computes Color, alpha value getting the value of the PLM Attributes. This rule has been coded by the user.

The Colors above are defined in a CATRsc file which maps the RGBT values to a color name.

The BINames are defined in the BICusto.CATRsc File.

Principles:

The files defined in the previous paragraph are used to set up the customization.

Here are the main steps of the process (shading and background color of the text of the specs tree):

• The list of available customizations is built from the resources files.
• The user click down one customization from the B.I. Essentials
• The information for the current customization is obtained from the resources files.
  • Definition of the color, text, name of script files
  • Definition for the labels.
  • All required PLM Attributes used by the customization.
• Set the caption area information
• For all objects involved by the customization (which have a 3D representation or a 2D representation or in the specs tree) do a query for all PLM Attributes.
  • => One query for all PLM Objects / all PLM attributes.
• Set the value of these attributes in the local buffer of the application(VPM Nav) for each object of the tree.
• For each object call to the script in order to have the RGB, alpha value
  • The scripts now get the information from the local buffer of the window.
• Set the PLM Shading on the 3D representations and the Tree NOdes by using the RGB, alpha value.
• Set the background color of the text of the 2D representations (specs tree) with the same information.

Here are the main steps of the process (labels of the B.I. Essentials):

• The user click down one customization of the B.I. Essentials and objects are selected or customization of the B.I. Essentials is in use and the user selects some objects in the 3D view or in the tree of specs.
• The information for the current selected customization of the B.I. Essentials is get from the resources files.
  • Definition of the color, text, name of script files.
  • Definition for the labels.
  • All required PLM Attributes used by the customization.
• For all objects involved by the customization (which are selected) do a query for all PLM Attributes.
  • => One query for all PLM Objects / all PLM attributes.
• Set the value of theses attributes in the local buffer of the application (VPM Nav) for each selected object of the tree.
• For each object call to the script in order to have the information displayed in the labels.
  • The scripts get now the information from the local buffer of the window.
• Creates the labels of the B.I. Essentials.

Note: The modification of script files in Session is taken into account when you use the Reload Custo Definition button in the BI Essentials Checker. But sometimes the Reload button might not work in that case the session should be restarted.

Sample of customization

File BICusto.CATRsc

	TST1_Description.Scope="ALL"; //It should be <BIID>Scope as key  

Please Note: Filename below is the BIID mentioned in the BICusto.CATRSc file. So you should have one file for each BI displayed.

File TST1_Description.CATRsc

	LegendNlsFile = "MyBICustoNLSFile";   //The NLSName of the BI is mentioned here
	ColorRscFile = "MyBICustoColorFile";   // The Color IDs are defined here.Only One file can be mentioned
	TypeRuleDefinitionFile = "TST1_Attribute_OnRef_RuleTypeAssociation";  //CATRule and Type Association for both Color and Label
	Version = "3"; // to activate the occurrences mode     
	NumberOfColors = "3";
	LegendId1 = "REFERENCE_INSTANCE_WITH_DESC";  //LegendId in the LegendNLS File
	ColorId1  = "Color_Green";  //ID mentioned in the ColorRscFile
	LegendId2 = "REFERENCE_INSTANCE_WITH_NO_DESC";
	ColorId2  = "Color_Blue";
	LegendId3 = "PROBLEM";
	ColorId3  = "Color_PROBLEM";
    

File MyBICustoNLSFile.CATNls in <os>\resources\msgcatalog directory

	TST1_Description="Rules_On_Instances";    //"
	REFERENCE_INSTANCE_WITH_DESC="Instance Validating Rule";      //Name as shown in the Screenshot Below
	REFERENCE_INSTANCE_WITH_NO_DESC="Instance Not Validating Rule";
	PROBLEM="Not An Instance";
	

File MyBICustoColorFile.CATRsc

	Color_Green.RGBA="0|255|0|0";
	Color_Blue.RGBA="0|0|255|0";
	Color_PROBLEM.RGBA="255|0|0|0";
	

File TST1_Attribute_OnRef_RuleTypeAssociation.CATRsc

	Color.Rule.VPMReference = "Test1_Reference";
	Label.Rule.VPMReference = "Test1_Reference";
	Color.Rule.VPMRepReference = "Test1_Reference";
	Label.Rule.VPMRepReference = "Test1_Reference";

Note: The Attributes can also be mentioned in this file instead of Attributes_For_Rules.CATRsc file for some Workshops. For now only UNIWorkshop.

File Test1_Reference.CATRule in <os>\resources\knowledge\scripts directory.

	Let sObjectDescription(String)
	Let thisReference(PLMCoreReference)
	Let thisOccurrence(ProductOccurrence)
	Let repReference(VPMRepReference)
	Let repInstance(VPMRepInstance)
	Let sColor(String)
	Let sLabel(String)
	Let bVDescExist(Boolean)
	
	sColor="PROBLEM"
	sLabel = ToString(rIndex) + "|TEST1: Attributes on Current Reference|I_NoIcon"
	bVDescExist=false
	Set thisOccurrence=ThisObject

	if (NULL<>thisOccurrence) {
		Set thisReference=thisOccurrence.Reference
		if (NULL<>thisReference) {
			sObjectDescription = thisReference->V_description
		}
	}
	else {
		Set repInstance=ThisObject
		if (NULL<>repInstance) {
			Set repReference=repInstance.Reference
		}
		else {
			Set repReference=ThisObject
		}
		if (NULL<>repReference) {
			sObjectDescription = repReference->V_description
		}
	}
	if(NULL <> sObjectDescription) {
		bVDescExist=true
	}
	if (bVDescExist==true) {
		sLabel = sLabel + "|" + ToString(rIndex) + "|STEP 1 - Description=" + sObjectDescription + "|I_NoIcon"
		sColor="REFERENCE_INSTANCE_WITH_DESC"
		sLabel = sLabel + "|" + ToString(rIndex) + "|STEP 2 - Has description in the Object|I_Green"
	}	
	else {
		sColor="REFERENCE_INSTANCE_WITH_NO_DESC"                   //Color can be Legend ID now
		sLabel = sLabel + "|" + ToString(rIndex) + "|STEP 2 - Has No Description Attribute Loaded|I_Blue"
	}

	Parameters->SetAttributeString("MyColorForPLMCompass",sColor)

	Parameters->SetAttributeString("MyLabelForPLMCompass",sLabel)
	

Things to Note In the above Script(Test1_Reference.CATRule):

• Here we used the same CATRule to describe the Color and the Label.
• We have used the LegendID but not the ColorID to Assign the Color in the Rule. Its more logical to use the LegendId than the ColorId or the RGBA value.

File Attributes_For_Rules.CATRsc in <os>\resources\msgcatalog directory.

Attributes.VPMReference = "PLM_ExternalID|organization|current|owner|reservedby|V_description";
Attributes.VPMRepReference = "organization|current|owner|reservedby|V_description";

Capability to define rules based on instances is also provided. Here is a sample script for customizing a shading:

The ThisObject is now an OccurrenceObject so you can use the knowledge methods to get the instance and Reference. We illustrate the way to do for instances.

To work with instance: Let InstanceObject(VPMInstance)

To check if the is an instance: if(NULL <> ThisOccurrence.Instance)

To get the instance: ThisOccurrence.Instance()

Note:If you try to access an Instance which is not defined on the object, the whole rule will fail. So, we strongly advice to check its availability with: if ( bAllowComputingRuleWithInstanceObject == TRUE )

	let InstanceObject(VPMInstance)
	let ThisOccurrence(ProductOccurrence)
	let bAllowComputingRuleWithInstanceObject(boolean)
  
	Set ThisOccurrence = ThisObject
	if(NULL <> ThisOccurrence)
	{
		Set InstanceObject = ThisOccurrence.Instance;
		if( NULL <> InstanceObject )
			bAllowComputingRuleWithInstanceObject = TRUE
	} 
	if ( bAllowComputingRuleWithInstanceObject == TRUE )
	{
		if (InstanceObject.PLM_ExternalID =="Rim.1")
			Parameters->SetAttributeString("MyColorForPLMCompass","255|0|0|80")
		else
			Parameters->SetAttributeString("MyColorForPLMCompass","0|0|255|80")
	}
	else
	{
		Parameters->SetAttributeString("MyColorForPLMCompass","0|255|0|80")
	}

For defining rules on objects, there is a dedicated Resource file by which we can declare Attributes which can be used in rules

For defining rules on objects, there is a dedicated Resource file named

Attributes_For_Rules.CATRsc

Put in <os>\resources\msgcatalog directory.

Note: this file have been put in the directory msgcatalog, because the attributes defined may be used for other customizations (tree / icons etc…)

Here is its syntax:

Attributes.<Object_type>=”Attribute_1|Attribute_2|……|Attribute_n”;

Where attributes separated by a | are retrieved from DataBase.

Example of file Attributes_For_Rules.CATRsc :

Attributes.VPMReference = "PLM_ExternalID|V_description|organization";

Attributes.VPMRepReference = "V_discipline|V_nature";

So there will be the possibility to define rules based on following attributes for the VPMReference real type:

PLM_ExternalID V_description organization

And these ones on VPMRepReference real type :

V_discipline V_nature

Capability to define rules based on extensions is also provided. Here is a sample script for customizing a shading for the extension V_Elec_NumberOfPins:

 if (ThisObject.GetAttributeInteger("V_Elec_NumberOfPins")== 3)
   Parameters->SetAttributeString("MyColorForPLMCompass","255|0|0|80")
 else
  Parameters->SetAttributeString("MyColorForPLMCompass","0|0|255|80")

File Attributes_For_Rules.CATRsc for extensions support is in <os>\resources\msgcatalog directory.

	Attributes.VPMReference = "PLM_ExternalID|organization|current|owner|reservedby|V_description";
	Attributes.VPMRepeReference = "organization|current|owner|reservedby|V_description";

	Extension.VPMReference="PLMEleRefEquipment|PLMEleRefSplice";
	Attributes.VPMReference.PLMEleRefEquipment="V_Elec_NumberOfPins|V_Elec_SubType";
	Attributes.VPMReference.PLMEleRefSplice ="V_Elec_Length";

Syntax and integrity management

In a customization, if a color is not correctly defined:

• Values not included between 0 and 255 (Because the R value corresponds to Red color which should be between 0 and 255; the G value corresponds to Green color which should be between 0 and 255;the B value corresponds to Blue color which should be between 0 and 255, the alpha value corresponds to transparency which index should be between 0 and 255). Example shown in CATPLMCompassCustomizationOfQuadrants.CATRsc file chapter sample of customization
• A color value is missing.
• etc.

In a customization, if no color is correctly defined, the entire customization will not be proposed. In such case use the BI Essentials checker to correct the problem

Integrity Check :

If the end user defines many times the same set of custom attributes, only the first one will be taken into account.

If a color resulting from rule doesn't belong to the scope of defined colors, the customization will not be applied.

Customization Files localization

For *.CATRules files they have to be defined in the directory <os>\resources\knowledge\scripts\

For the unique Resource file named : BICusto.CATRsc and the supporting CATRsc files like e.g. TST1_Description.CATRsc,MyBICustoColorFile.CATRsc,TST1_Attribute_OnRef_RuleTypeAssociation.CATRsc it has to be defined in a directory Provider and role-dependant under <os>\resources\compass\directory

If the file is defined directly under the plmcompass directory , it will be the one used , if no provider is defined (or if there is an invalid definition of the current provider). In case of VPM its different the File is taken from VPM Folder only if not found then the Loading of CATRsc file fails.

Under the plmcompass directory , there can be defined folders corresponding to a different provider. Under each provider directory , there can be defined folders corresponding to different roles.

If a BICusto.CATRsc is directly defined under a provider directory , it will be the one used if the role with which the user has connected is not found in the compass hierarchy (see image above).

Here is the list of allowed providers :

ENOVIA VPM : VPM1
3DXML : DXP
ENOVIA SmarTeam : SMT
ENOVIA V6 – Collaborative Business Process & Design data Management : MX1
ENOVIA V6 : PLM1
ENOVIA VPM V5 : EV5

Finally it will be the a BICusto.CATRsc file and the <BIID>.CATRsc,<ColorRscFile>.<TypeRuleDefinition>.CATRsc file which is under the current connected role which will be used by the B.I. Essentials if everything is all right.

compass
  |- CATPLMCompassCustomizationOfQuadrants.CATRsc 
  |-Provider1
      |- CATPLMCompassCustomizationOfQuadrants.CATRsc 
      |- Role1.1
            |- CATPLMCompassCustomizationOfQuadrants.CATRsc 
      |- Role1.2
            |- CATPLMCompassCustomizationOfQuadrants.CATRsc 
...
  |-Provider n
      |- CATPLMCompassCustomizationOfQuadrants.CATRsc 
      |- Rolen.1
            |- CATPLMCompassCustomizationOfQuadrants.CATRsc 
      |- Rolen.2
            |- CATPLMCompassCustomizationOfQuadrants.CATRsc

With the new Customization the user or administrator cannot change the behavior of BI depending on the workshop involved. To do this the user has to do the customziation in the Old way of Customization. Please refer the old Customization Documentation for this:

These CATRsc files will be located in a directory like :

<os>\resources\plmcompass\PROVIDER\ROLE

BI Essentials Checker:

There is a tool in the user interface enabling you to understand syntax errors in your customization files, this is the B.I. Essentials Checker. The new BI Essentials Checker has more new features and improved now.

In the drop down list of B.I. Essentials, select Check BI Essentials Customization present in separate section as shown below.

Intially the BI Essentials Checker shows the below Report giving the generic information of the Customization done on the BI.

When clicking on Check an item type the user have to select the geometry or on Tree he wants to customize with the B.I. Essentials. The BI Essentials Checker returns the character string of the of the type of the object. The user have to insert this string in the <TypeRuleDefinition> .CATRsc file. This displays a report related to the Node and the CATRule when applied on it.

With the new BI Essentials Version the user can Reload the customization if you have made some changes to the customization during the Session.

NOTE: Sometimes the Reload does not work due to wrong CATRsc Files in that case a new session may be required

A drop down comes when you click on the Drop Down Button which is named Select BI To Analyse

To check the CATRule definition use the Check CATRule Definition Button in the Checker. It shall generate a report just as below.

The Check CATRule Button

The Check CATRule Definition Report

Limitations

Limitation #1:
The customization of the B.I. Essentials works only in VPM Navigator, Search and Physical Editor workshop

Limitation #2:
If no customization of the B.I. Essentials is defined, in its default working behavior, the background color of the tree won't change.

Limitation #3: 
The customization of the B.I. Essentials is based on attributes of the tree mask defined in the rules, or on the attributes defined in the 
Attributes_For_Rules.CATRsc file.

Limitation #4:
Update of information in the case of labels.
The displayed information in the label for selected objects are always refreshed from DataBase.
These information (as in the default behavior of the compass today defined) may be "fresher" 
than the information relative to the 3D shading  and the Tree  Background color.

Limitation #5:
It is  not possible , in a CATRule to compare a character string with a space inside It or with special characters (as # ! etc...)
    example which doesn't work: 
        if (ThisObject.reservedby=="MY NAME") 
        Parameters->SetAttributeString("MyColor","0|255|0")

Limitation #6:
The character comparison is Case Sensitive, so it is required to take into account the case.

Limitation #7:
The B.I. Essentials Checker Tool won't check the content of Attributes_For_Rules.CATRsc.

Limitation #8:
There is a limitation due to the transparency algorithm implementation.
As far as the polygons are concerned, the results might not be as expected,
when the triangles are blended with the rest of the scene.
As it is too costly and may adversely affect performance, polygons are not drawn using a Z order(ie: depth order).
Therefore it is not possible to be sure that when transparent polygon is blended, all the scene is drawn behind.
Transparent polygons are drawn at the end of the draw phase by they are not depth-stored,

Suggestion:
Paint objects without transparency or paint objects with a strong transparency.

Limitation #9:
Only PLM attributes and objects are taken in account (not features).

Limitation #10:
the BI canot be cusomized to specific Workshops. Please follow old way of customization for the same.

In Short

The following CATRsc file to write: BICusto .CATRsc ,<BIID>.CATRsc, <ColorID>.CATRsc,<TypeRuleDefinitionFile>.CATRsc, and Attributes_For_Rules.CATRsc. All CATRule file which is described in <TypeRuleDefinitionFile>.CATRsc to write.

History