Configuring Effectivity Management

Effectivity Management of Part BOM structures is available in the Product Engineering (PE) application. This enables expressing Effectivity conditions of Parts within the BOM and resolving BOM structures against these conditions. As an Administrator, you can configure and customize some aspects of Effectivity Management in the PE application, such as:

• Creating additional Effectivity Variables and Effectivity Scopes.
• Customizing the Effectivity Scope Builder Method for custom business logic.
• Configuring Query Definitions for structure resolution logic.
• Configuring Tree Grid Views to display Item and Relationship properties.
• Configuring Permissions that determine who can manage Effectivity information.

This section provides a high-level overview of the Effectivity Services based data model concept as implemented in the PE application. For more information on Effectivity Services, refer to the Aras Innovator – Effectivity Services Programmer’s Guide.

An Effectivity Scope defines a context for Resolution through Effectivity Criteria, which should be applied to particular effective items. An Effectivity Scope consists of the following items:

• Effectivity Variables, which are variables influencing Effectivity decisions.
• Effectivity Scope ItemType, which determines Items to be resolved by Effectivity.

A Builder Method uses Effectivity Variables to construct a Scope object in the runtime, used by the Effectivity Resolution Engine to perform Resolution of effective items.

The user interacts with the Tree Grid View (TGV) to provide the Effectivity Criteria for structure resolution.

TGV requests necessary data from the associated Query Definition (QD). The Effectivity Criteria is passed to this QD via QD parameters.

QD requests Effectivity Expression items with provided Effectivity Criteria.

The Effectivity Resolution Engine resolves Effectivity Expression items against provided Effectivity Criteria and returns the result.

The results are displayed to the user using the TGV.

Many variables influence Effectivity decisions. They depend on the industry, product, and business processes among others. They are used in:

• Effectivity Expressions to set Effectivity conditions within a structure.
• Effectivity Criteria for structure resolution.

Some of the most commonly used Effectivity Variables are provided out of the box:

• Model
• Unit
• Date

The Aras Part BOM Scope Effectivity Scope uses these Effectivity Variables.

Based on business needs, additional Effectivity Variables can be defined, as described in the following section.

To access the Effectivity Variables, select Administration Effectivity Services Effectivity Variables from the TOC.

Use the standard Item creation procedure to create a new Effectivity Variable. The following fields are required:

• Name
• Type: The out-of-the-box Builder Method supports the following Effectivity Variable types:
• Date
• Integer
• Item
• List
• String
• If the specified Type is List or Item, provide an accompanying value in the List or ItemType field.

Use the standard Item editing procedure to edit an Effectivity Variable.

Use the following procedure to delete an Effectivity Variable:

Remove it from its associated Effectivity Scopes.

Use the standard Item deletion procedure to delete the Effectivity Variable.

The Model Effectivity Variable uses Items of the Model (effs_model) ItemType. There are no Model Items out of the box. If your business uses the Model as an Effectivity Variable, you need to create Model Items.

To access the Model Items, go to Administration Effectivity Services Models in the TOC.

Use the standard Item creation procedure to create a new Model Item. The Name field is required and unique.

Use the standard Item editing procedure to edit a Model Item.

Use the standard Item deleting procedure to delete a Model Item.

An Effectivity Scope is an Item of the effs_scope ItemType that defines the context for setting Effectivity conditions and resolving structures against given Effectivity Criteria.

To access the Effectivity Scopes, select Administration Effectivity Services Effectivity Scope from the TOC.

The PE application provides the Aras Part BOM Scope Effectivity Scope. The effs_scopeObjectBuilderMethod Builder Method constructs an object of this Scope.

The Aras Part BOM Scope Effectivity Scope uses the Part BOM ItemType and the Model, Unit, and Date Effectivity Variables. You can either update this Scope or create a new one to specify a set of Effectivity Variables that are relevant to your business.

A Builder Method is an Item of the Method ItemType, which constructs the Scope object using business data and logic.

In the PE application, effs_scopeObjectBuilderMethod is the default Builder Method that works with the Effectivity Scope ItemType and Effectivity Variables.

There are no restrictions on the number or types of Effectivity Variables in an Effectivity Scope. You can either update the Aras Part BOM Scope Effectivity Scope or create a new Effectivity Scope to specify a set of Effectivity Variables that are relevant to your business.

Use the standard procedure for attaching Items on the Effectivity Variables accordion tab of an existing Effectivity Scope Item view.

Use the standard procedure for removing attached Items on the Effectivity Variables accordion tab of an Effectivity Scope Item view.

Use the standard Item creation procedure to create a new Effectivity Scope. The following fields are required:

• Name
• Builder Method -- Use the effs_scopeObjectBuilderMethodmethod unless you have implemented a different Method that uses custom business logic.

Specify Effectivity Scope ItemTypes and Effectivity Variables on the corresponding accordion tabs.

To find out where an Effectivity Scope is used, you can use the Where Used browser.

This section provides an overview of the Query Definitions (QD) configuration for resolving the BOM structures against Effectivity Criteria.

• Definition of a QD containing Effectivity filtering logic.
• Merging this QD into another QD to create a single executable QD for a related Tree Grid View.

In the Product Engineering (PE) application, Part BOM Relationships are resolved against Effectivity Criteria on the BOM Structure tab of a Part Item. The resolution uses Effectivity Scope and Effectivity Variable values set in the Effectivity Criteria Filter dialog. The resolved structure is displayed using the PE_BomStructure Tree Grid View (TGV) configuration.

You can configure the PE_BomStructure TGV to add, remove, or reorder columns to display Part and Part BOM properties. Adding or removing columns requires changing the QD configuration to return the given properties. You can use the standard TGV and QD procedures for this configuration.

The QD containing Effectivity filtering logic is effs_effectivityResolutionOnPartBom. It retrieves assigned Effectivity Expressions and evaluates them against the given Effectivity Criteria in the Resolution Engine. The QD filters out Items that are evaluated as not valid for the given Effectivity Criteria.



The effs_effectivityResolutionOnPartBom QD passes data to the Effectivity Resolution Engine using the following Query Parameters:

• EffectivityScopeId—the ID of the Effectivity Scope.
• EffectivityCriteriaDefinition—the Effectivity Criteria Definition.

The Query Structure of the effs_effectivityResolutionOnPartBom QD is as follows:

• Part BOM is the Effective ItemType of the PE application Effectivity Scopes.
• Where Condition:

(Count(effs_Part_BOM_expr_no_resolve) = 0) OR (Count(effs_Part_BOM_expression) > 0)

Note
You can change the Where Condition to use AND logic instead of OR. The logic to use depends on how multiple Effectivity Expressions on a given single Part BOM Item should be evaluated. For details, refer to section 7.9 Configuring Logic to Evaluate Effectivity Expressions for Effectivity Resolution.



Note
It is recommended to use only the “Count()” aggregate function for Effectivity relationships to prevent performance degradation.
• effs_Part_BOM_expression is a RelationshipType with the source Part BOM ItemType.
• Where Condition:

(Scope = $EffectivityScopeId) AND (Definition = '<expression>$EffectivityCriteriaDefinition</expression>')

The Effectivity Scope ID value is set from the Scope cell, and the Effectivity Criteria Definition value is set from the Variables and Values cells of the Effectivity Criteria Filter dialog.

• Join Condition:

[Part BOM].id = effs_Part_BOM_expression.source_id



• effs_Part_BOM_expr_no_resolveis used tocheck if the Part BOM item has any effectivity relationship items for the specified scope.
• Where Condition:

Scope = $EffectivityScopeId

The Effectivity Scope ID value is set from the Scope cell.

• Join Condition:

[Part BOM].id = effs_Part_BOM_expr_no_resolve.source_id



The effs_effectivityResolutionOnPartBom QD is merged into the PE_BomStructure QD to produce a single executable QD, as described later in this section.



The PE_BomStructure QD has the following Query Parameters:

• EffectivityResolutionMode — structure resolution mode. Aras.Resolution.EntryPoint;Default is the default value.
• EffectivityResolutionConfigurationQueryDefinitionId — ID of the QD containing Effectivity filtering logic to enable Effectivity resolution.
• EffectivityScopeId — ID of the Effectivity Scope Item passed to the Effectivity Resolution Engine.
• EffectivityCriteriaDefinition — the Effectivity Criteria Definition passed to the Effectivity Resolution Engine.

When Effectivity Resolution is triggered from the Effectivity Criteria Filter dialog (see section 6.7 Understanding TGV Definition for Effectivity Resolution), the EffectivityResolutionConfigurationQueryDefinitionId parameter value is retrieved from the effs_getResolutionCfgQdIdByTgvId Method.



The method defines 1-to-1 associations between Tree Grid Views and Query Definitions containing Effectivity Resolution logic to be merged for Effectivity Resolution, when triggered from the Effectivity Criteria Filter dialog. The Query structure of the PE_BomStructure QD is recursive:

• Part BOM is the root ItemType of the BOM Structure accordion tab.
• Order:

1. Sequence (Ascending)

• Where Condition:

$EffectivityResolutionConfigurationQueryDefinitionId = $EffectivityResolutionConfigurationQueryDefinitionId

Note
This condition is used as an anchor to detect the place in the QD where the effectivityResolutionOnPartBomQD is merged. This condition should not be removed otherwise Effectivity Resolution will not work.
• Properties:

Quantity, Sequence, Reference Designator, Expression, id



• Part
• Join Condition:

'$StructureResolutionMode;parent.related_id’ = Part.id

• Properties:

Part Number, Revision, State, locked_by_id, Name, id



Part BOM is extracted recursively – all its values are the same as for the top Part BOM, and the following Join Condition is added:

Part.id = [Part BOM].source_id

To merge the QD for Effectivity Resolution, the PE_BomStructure QD has the OnBeforeExecute event set for the effs_mergeQueryDefinition Method.

By default, the QD Item view does not display tabs. To view and to add events to QDs, make tabs visible by setting the Default Structure View property of the qry_QueryDefinition ItemType to Tabs On.

This section provides an overview of how Tree Grid View (TGV) is configured to work with a corresponding Query Definition (QD) to display the resolved structure for user-provided Effectivity Criteria. In the Product Engineering (PE) application, the Part BOM Relationships are resolved against Effectivity Criteria on the BOM Structure tab of a Part Item. This tab uses a TGV to display data retrieved from a QD as a tree grid. You can configure the PE_BomStructure TGV to add, remove, or reorder columns to display Part and Part BOM properties. Adding or removing columns requires changing the QD configuration to return the given properties. You can use the standard TGV and QD procedures for this configuration. The PE_BomStructure TGV configuration has the following UI elements: the Set Effectivity Criteria button, the View Effectivity context menu item, and the Manage Effectivity Expressions split pane.

You can configure the PE_BomStructure TGV to add, remove, or reorder columns to display Part and Part BOM properties. Adding or removing columns requires changing the QD configuration to return the given properties. Use the standard TGV and QD configuration procedures.

The TGV configuration uses the PE_BomStructure Presentation Configuration, which adjusts the toolbar and context menu with two new command bar sections: effs_tgvToolbarCustomization and effs_tgvContextMenuCustomization.

The effs_tgvToolbarCustomization command bar section adds the new button to the default TGV toolbar. This button is effs_tgvToolbarSetEffectivityCriteriaButton labeled as Set Effectivity Criteria.

Set Effectivity Criteria triggers the effs_setEffectivityCriteriaHandl Method to show the Effectivity Criteria Filter dialog for setting the Effectivity Criteria, for which a BOM structure will be resolved.

The effs_tgvContextMenuCustomization command bar section adds a new menu item to the default TGV context menu. This menu item is effs_tgvContextMenuViewEffectivityItem labeled as View Effectivity.

View Effectivity triggers the effs_bomStructureViewEffCtxHandl Method to display the Manage Effectivity Expressions split pane with Effectivity Expressions set for the given Part BOM.

In Aras Innovator, Effectivity Management on Part BOM structures is available out of the box. If your business is not going to use this feature, you can hide its associated UI elements. This section explains how to hide and redisplay the discussed UI elements. These elements are as follows:

• The Effectivity Services subcategory under Administration in Contents:
• Effectivity Scope
• Effectivity Variables
• Models
• The Effectivity tab in the Part BOM Relationship Item view.
• The BOM Structure tab in the Part Item view:
• The Set Effectivity Criteria button in the BOM Structure toolbar
• The View Effectivity menu item in the context menu of a Part
• The Effectivity column

The Effectivity Services subcategory of the Administration category in the Table of Contents (TOC) contains the following ItemTypes:

• effs_scope (Effectivity Scope)
• effs_variable (Effectivity Variable)
• effs_model (Model)

The visibility of the Effectivity Services category depends on the visibility of its contained ItemTypes:

• Visible when at least one of the ItemTypes is visible.
• Hidden when all the ItemTypes are hidden.

You can hide and redisplay the Effectivity Services ItemTypes in any sequence. Use the standard TOC configuration. When redisplaying an Effectivity Services ItemType, use the Effectivity Management Identity and Effectivity Services Category.

By default, the Part BOM Relationship Item view includes the Effectivity accordion tab.

The visibility of the Effectivity accordion tab is controlled by the Hide In All check box in the Source group of the effs_Part_BOM_expression RelationshipType Item view.

To hide this tab, select the Hide In All check box. To display this tab, clear the check box.

By default, the BOM Structure accordion tab of the Part Item view has the following Effectivity Management UI elements:

• The Set Effectivity Criteria button in the BOM Structure toolbar.
• The View Effectivity menu item in the context menu of a Part.
• The Effectivity column.

This section describes configuration specifications for the PE_BomStructure QD and TGV, which shows these UI elements as well as calls Effectivity filtering. If you need to hide the discussed elements, remove the described configuration from the TGV and then from the QD. If you need to redisplay the discussed elements after you have removed them, configure the QD and then the TGV according to the given specifications. Relog into Aras Innovator to confirm the change.

To show the Effectivity-related UI elements on the BOM Structure accordion tab of the Part Item view, the PE_BomStructure TGV is configured as specified in this section. The PE_BomStructure TGV uses the PE_BomStructure Presentation Configuration.

The PE_BomStructure Presentation Configuration is configured to show the Set Effectivity Criteria toolbar button and the View Effectivity context menu item to the World Identity:

• effs_tgvToolbarCustomization located on TGV_Toolbar with sort order 128.
• effs_tgvContextMenuCustomization located on TGV_ContextMenu with sort order 256.

To display the Effectivity column on the BOM Structure accordion tab of the Part Item View, the PE_BomStructure TGV has the Effectivity column between the Name and Reference Designator columns specified to show data of the Text type according to the {Part BOM.eff_expression_string_notation} text template.

To hide the Effectivity-related UI elements on the BOM Structure tab of the Part Item View, remove effs_tgvToolbarCustomization and effs_tgvContextMenuCustomization from the PE_BomStructure Presentation Configuration as well as the Effectivity column in the TGV editor, and then reconfigure the PE_BomStructure QD. To redisplay these elements after they were hidden, reconfigure the PE_BomStructure QD, and then add the command bar sections and Effectivity column as specified.

To show the Effectivity-related UI elements on the BOM Structure accordion tab of the Part Item view, the PE_BomStructure QD is configured as follows:

• The qry_QueryDefinitionEvent relationship tab has an OnBeforeExecute event using the effs_mergeQueryDefinition Method.
Note
For more information about this Method and how to display and hide tabs in the QD Item view, refer to section 7.6 Understanding Query Definitions for Effectivity Resolution.



• The top Part BOM item in the QD editor has the Expression and id properties.

When hiding the Effectivity-related UI elements on the BOM Structure tab of the Part Item View, remove the effs_mergeQueryDefinition Method and the Expression and id properties after reconfiguring the PE_BomStructure TGV. When redisplaying these elements after they were hidden, add these Method and properties back before reconfiguring the PE_BomStructure TGV.

A Part BOM Item can have several Effectivity Expressions.

By default, multiple Effectivity Expressions on a Part BOM Relationship Item are evaluated using the OR conditional operator for the Effectivity Resolution: A given Part BOM is effective against Effectivity Criteria if at least one of its Effectivity Expressions evaluates to true for the selected Effectivity Scope. It is possible to change the evaluation logic to use the AND conditional operator: A given Part BOM is effective against Effectivity Criteria if all of its Effectivity Expressions evaluate to true for the selected Effectivity Scope. The evaluation logic is configured in the Where Condition of the top Part BOM item in the effs_effectivityResolutionOnPartBom QD. This section describes the configuration specifications of this Query Definition for both evaluation logic.

For the AND evaluation logic, the Where Condition of the top Part BOM item of the effs_effectivityResolutionOnPartBom Query Definition is configured as follows:

Count(effs_Part_BOM_expression) = Count(effs_Part_BOM_expr_no_resolve)

For the OR (default) evaluation logic, the Where Condition of the top Part BOM item of the effs_effectivityResolutionOnPartBom Query Definition is configured as follows:

(Count(effs_Part_BOM_expr_no_resolve) = 0) OR (Count(effs_Part_BOM_expression) > 0)

While an Effectivity Expression is saved as XML, a user-friendly Notation of this Expression is displayed to users. It is possible to change the construction of this Notation. This section describes how the Notation can be customized. Effectivity on a Part BOM Relationship is managed using its related effs_Part_BOM_expression Items. A Part BOM Relationship can have zero, one, or more Effectivities. The string_notation text property on the effs_Part_BOM_expression ItemType stores the user-friendly Notation for a single Effectivity Expression. The eff_expression_string_notation federated property on the Part BOM ItemType dynamically constructs the Effectivity text from its related Effectivities. The string_notation property from the effs_Part_BOM_expression ItemType appears in:

• The Manage Effectivity Expressions split pane on the BOM Structure tab of the Part Item view when the View Effectivity context menu item is accessed.
• The Effectivity tab of the Part BOM Relationship Item view.

The eff_expression_string_notation property on the Part BOM ItemType is displayed in:

• The BOM Structure tab of the Part Item view in the Effectivity column.

Upon its creation and update, an Effectivity Expression gets a new Effectivity String Notation. This behavior is the job of the effs_expStringNotationConversion server-side Method executed on the onBeforeAdd and onBeforeUpdate events of the effs_Part_BOM_expression Items. This Method converts an Effectivity Condition to an Effectivity String Notation and stores the output to the string_notation Item property. Customization of the Effectivity String Notations requires modification of the discussed Method as follows:

1. Define a new class to represent a new Effectivity String Notation converter and to provide a String Notation value for a given Effectivity Expression object representation. This class should get objects of Effectivity Variables and Effectivity Expression, convert them into Effectivity String Notation, and return this Notation. The class must implement the Aras.Server.Core.Configurator.IStringNotationConverterinterface, as included in the Appendix.
Note
A new class for a custom Effectivity String Notation converter is required because the Aras.Server.Core.Configurator.ExpressionToStringNotationConverter class with the default Effectivity String Notation converter is compiled. A customization example is provided in the Appendix.
2. In theCreateNewStringNotationConverter local method definition, replace the Aras.Server.Core.Configurator.ExpressionToStringNotationConverter class with your custom class in the return statement. Do not change the variableContainer argument.

internal virtual Aras.Server.Core.Configurator.IStringNotationConverter CreateNewStringNotationConverter(IEnumerable<Aras.Server.Core.Configurator.Variable> variableContainer) { return new Aras.Server.Core.Configurator.ExpressionToStringNotationConverter( variableContainer); }

The Part BOM ItemType is the Effectivity Scope ItemType of the Aras Part BOM Scope. An ItemType used as the Effectivity Scope ItemType can have a unified Effectivity String Notation joined from its related single Effectivity Expressions. To provide this feature, the Part BOM ItemType uses the:

• eff_expression_string_notation federated property.
• effs_getExpressionStringNotation server-side Method executed on the onAfterGet event.

Customization of the unified Effectivity String Notations requires modification of this Method, where the JoinExpressionStringNotation local method definition is changed according to the desired uniting template.

Note
A customization example is provided in the Appendix.

The local method produces a single value for the eff_expression_string_notation property. It combines related Effectivity Expressions using a conjunction. The following is the default implementation of JoinExpressionStringNotation where parentheses enclose individual Effectivity String Notations and commas join these Notations.

internal virtual string JoinExpressionStringNotation(IEnumerable<string> expressionStringNotations)

{

if (!string.IsNullOrEmpty(expressionStringNotations.ElementAtOrDefault(1)))

{

expressionStringNotations = expressionStringNotations.Select(

expressionStringNotation => "(" + expressionStringNotation + ")”);

}

return string.Join(", ", expressionStringNotations);

}