Configuring Effectivity Services

This section provides a brief description of what needs to be configured in Effectivity Services to use it with Query Builder and Tree Grid View. A more detailed description can be found in subsequent sections.

Administrators are responsible for the following tasks:

• Define Custom Data Model – Define business item types to be used to build the Effectivity Scope. These can be item types for effectivity variables, relationships where effectivity information is managed.
• Implement builder method - Implement the server method that builds the Scope object from custom Data.
• Create Scope – Add effs_scope Item, specify Name and builder method. Link custom Data to Scope if needed.
• Link Scope with Relationship – Add the effs_scope_itemtype Item. Link Scope and Relationship ItemType that need to be managed by effectivity.

This section describes how to configure Effectivity Scope to manage Effectivity on selected Relationship ItemTypes.

1. Create an Effectivity Scope item to define a context. Select Administration → Effectivity Services → Effectivity Scope in the TOC.
2. Select the Builder Method. Method effs_scopeObjectBuilderMethod is provided out of the box and is used to construct a Scope object based on related Effectivity Variables.
3. Select Effectivity Scope ItemTypes where effectivity will be managed.
4. Select Effectivity Variables for the Scope by creating or using existing Effectivity Variables.
5. Save the Effectivity Scope.



The new “Effectivity” (effs_EffectivityScopeItemType_expression) “No Related” relationship ItemType is created automatically. With this configuration, an “Effectivity” tab appears on the EffectivityScopeItemType form.

Note
You can have any number of different Relationships in the same Effectivity Scope.If the automatically generated RelationshipType name (“effs_%ITEMTYPE%_expression”) is longer than 30 characters, you will not be able to create the relationship in the relationship grid. In this case, you can either manually enter the name on the Effectivity Scope ItemType form (by selecting Effectivity Scope ItemType, RMB→Open) or send an AML request with the explicitly specified property “name” to create the RelationshipType. The length of the property “name” value should not exceed 13 characters.
6. Log out of Aras Innovator and login again as new relationship ItemTypes are created automatically unless they already exist.

Both Administrators and Users can perform the following actions:

• Set Effectivity Expressions – Create the effs_#ItemType#_expression Item with an Effectivity Expression for a selected Relationship Item.
• Configure Query Definition to work with Effectivity Criteria – Create a Query Definition that selects your data using the specified criteria expression.
• Configure Tree Grid View to display returned data – Create a Tree Grid View configuration that shows the data returned from executing the Query Definition.

Using Query Builder with Effectivity Services, resolved item structures can be presented in a Tree Grid View. For additional information about Query Builder, refer to the Aras Innovator 30 – Query Builder Guide. For additional information about Tree Grid View, refer to the Aras Innovator 30 – Tree Grid View Administrator Guide.

This section describes the following use cases using Effectivity Services combined with Query Builder and Tree Grid View:

• Resolving a Part BOM structure for the given effectivity criteria.
• Viewing all parts in a Part BOM structure that are a) effective for the criteria contained in the specified Effectivity Scope and b) have no Effectivity Expressions in the specified Effectivity Scope.

Before you can configure a Query Definition and a Tree Grid View, you need to:

• Define the business data that will be converted to Variables and Named Constants by the Builder Method.
• Implement the Builder Method.
• Create the Effectivity Scope.
• Relate a Relationship ItemType to the Effectivity Scope instance.

To follow the example in this section the Administrator has already defined the following structural elements:

• The Effectivity Scope item “3D Printer”. The Effectivity Scope item has the Relationship ItemType “Part BOM” as the Effectivity Scope ItemType.
• The Effectivity Variables associated with the Effectivity Scope item:
• Model – is an Item Variable with effs_model ItemType. “Replicator” and “Replicator 2” items were created in the Administration → Effectivity Services → Models TOC category which means this Effectivity Variable has only two possible Named Constants (“Replicator” and “Replicator 2”), which can be assigned to it.
• Unit – is an Integer Variable. That means any appropriate integer value can be assigned to this Effectivity Variable.
• Production Date – is a Date Variable. That means any appropriate date value can be assigned to this Effectivity Variable.

A Query Definition is a fundamental element to retrieve data from the server.

In this section we use the Part → Part BOM structure to show how Effectivity Services can be used.

1. Select Administration→Configuration→Query Definitions in the TOC.
2. Click Create New Query Definition.
3. Enter a value in the Name field.
4. Click on the ellipses in the Context ItemType dialog to search for a Context Item Type. Once you select the ItemType and save the form, the selected ItemType appears as a link as shown here.

Click the Show Editor button on the left sidebar to switch to Query-Editing Mode. Build a recursive Part structure using the Part BOM relationship.

Select the properties that you want the query to return. Let’s select the following properties for Part:

To define effectivity criteria, add the corresponding “Effectivity” relationship (effs_Part_BOM_expression), where Effectivity Conditions are saved.

1. Add the Effectivity relationship twice with different aliases as shown in Figure 13.
2. Use the Relationship with the effs_Part_BOM_expression alias for structure resolution by effectivity.
3. Use the Relationship with the effs_Part_BOM_expr_no_resolve alias to check if the Part BOM item has any “Effectivity” relationship Items for the specified Scope.



These two aliases will be used in the where condition on the Part BOM query item.

4. Add a where condition to the “Part BOM” query item. The “(Count(effs_Part_BOM_expr_no_resolve) = 0) OR (Count(effs_Part_BOM_expression) > 0)” condition allows us to get the related part in case the Part BOM item does not have any effectivity relationships (Count(effs_Part_BOM_expr_no_resolve) = 0), or it has at least one effectivity expression resolved to true for the given effectivity resolution criteria/condition (Count(effs_Part_BOM_expression) > 0).
Note
It is recommended to use only the “Count” aggregate function for effectivity relationships to prevent performance degradation.



5. Add a where condition “Scope = $EffectivityScopeId” on the “effs_Part_BOM_expr_no_resolve” query item filtering by the “Scope” property.

The “Scope” value must match the ID of the scope which is provided via $EffectivityScopeId Query Parameter created for this Query Definition. Query parameters allow us to execute the same query using different parameter values.



Note
Default Value can be provided for the $EffectivityScopeId Query Parameter.The Parameter name should be exactly “EffectivityScopeId” to be compatible with Effectivity Resolution via Effectivity Criteria Filter dialog.

This condition gives us Part BOMs that have no configured Effectivity Expression in the current Scope.



6. Add a where condition “(Scope = $EffectivityScopeId) AND (Definition = '<expression>$EffectivityCriteriaDefinition</expression>')” on the “effs_Part_BOM_expression” query item filtering by the “Scope” and “definition” properties.

The “Scope” value must match the ID of the scope which is provided via $EffectivityScopeId Query Parameter created for this Query Definition. The Definition property value must contain an effectivity expression with Effectivity Criteria which is provided via $EffectivityCriteriaDefinition Query Parameter created for this Query Definition.



Note
The Parameter name should be exactly “EffectivityCriteriaDefinition” in order to be compatible with Effectivity Resolution via the Effectivity Criteria Filter dialog.

This condition gives us Part BOMs that have a configured Effectivity Expression in the current Scope. The configured Effectivity Expression corresponds to the Effectivity Criteria from the “definition” property of the Query Item.



7. Confirm that all conditions are set correctly. The final version of the effectivity query definition is as follows:

Tree Grid View is standard functionality for Aras Innovator. It offers a visual layout of the data as a Relationship tab in an item view. In this example Tree Grid View uses the Query Definition created in the previous section to resolve the Part BOM structure and display the result in the grid.

1. Go to TOCAdministration → Configuration → Tree Grid Views.
2. Click Create New Tree Grid View.
3. Enter a value in the Name field.
4. Specify the query definition in the Query Definition field.



Click the Show Editor button on the sidebar.



Select the “Part”, “Part BOM” and nested “Part” rows, right-click and select Map Element from the context menu to include these elements in the tree grid view.



Select Part BOM and nested Part elements, right click on them and choose Combine from the context menu to combine them into one element for better structure visualization in the Tree Grid View.



Select the row with combined Part BOM and Part elements, right click on it and choose Change icon from the context menu to change the standard icon for the combined row.



Right click on the Part Structure column header and select Add New Column.



Change the new column label to State.



Select the State cell in the Part row, right click on it and choose Cell Display Settings from the context menu.



5. Select the {Part.state} option in the Helper listbox to set it as the text template for this cell.



6. Set {Part.state} as the text template for the “State” cell in the “Part BOM --- Part” row.



7. Add the Part Number column and setup display settings as shown here:

Click Save to save your changes.

1. From the Tree Grid View, click the Actions menu and select Set Tree Grid View Usage.



2. Choose the Relationship Tab option as the target usage in the Set Tree Grid View Usage dialog box.



3. Click Next to proceed to the next dialog box. Click the ellipses in the Used On field and select the ItemType to add to the new relationship. Click Next.



4. Specify the relationship name and label.



5. Define the starting condition for query definition execution. The Starting condition is applied once to the root item of the query definition. It allows to get the resolved part structure for one part item.



6. Click Next. The following dialog box appears:



7. ClickGenerate to create the relationship with the Tree Grid View.

1. Create a Presentation Configuration Item and specify a name for it.
2. In the Command Bar Section relationships tab, select the effs_tgvToolbarCustomization Command Bar Section item. The effs_tgvToolbarCustomization Command Bar Section is provided out of the box and contains the “Set Effectivity Criteria” toolbar button which will be added to the Tree Grid View toolbar in the next steps.
3. Specify a value for the “For Identity” cell and save the Presentation Configuration item.



Note
If the Presentation Configurations category is not displayed in the TOC, you will need to expose the category by opening the Presentation Configuration ItemType and adding TOC Access for the current user.
4. Open the Tree Grid View item where the “Set Effectivity Criteria” button will be added and specify the just created Presentation Configuration in the Linked Toolbar/Context Menu field.



5. Click Save to add the “Set Effectivity Criteria” button to all Tree Grid View toolbars which use this Tree Grid View definition.

The resolved part structure for the current part item is displayed in the Tree Grid View. Figure 40 shows the related parts. The Effectivity Expressions have not been added yet.

In this example, Part “MP2940” has related Parts as shown in Figure 41. Effectivity Expressions will be added to the Part BOM relationships with the “MP0370-004” and “MP0370-006” related Part items. Open the “MP2940” Part item which is present in the Part Structure Tree Grid View. Click Edit so that the Part BOM relationships can be edited too. Right click on the “MP0370-004” Part row and click Open to open the Part BOM relationship item.

Go to the “Effectivity” relationship tab and add a new Effectivity Expression. Set “3D Printer” Effectivity Scope in the Scope cell. Right click on the Effectivity Expression row and select Open to open the expression item.

Fill the Effectivity Expression field with the expression: “Model = Replicator and Unit >= 100”.

Save, unlock, and close the Effectivity Expression item. Save and close the Part BOM item

Repeat steps 3-7 for the related Part “MP0370-006” and add two Effectivity Expressions: “Model = [Replicator 2]”, “[Production Date] >= [7/1/2021]”.

The Effectivity Criteria Filter dialog can be opened via the “Set Effectivity Criteria” button of the Tree Grid View toolbar.

The Effectivity Scope can be selected in the “Scope” field to populate the grid with Effectivity Variables which are present in the selected Scope.

For Integer and String Effectivity Variables, users can enter a variable value manually into the input field.

For Date Effectivity Variables, users can enter values manually or via the Date Picker.

For List and Item Effectivity Variables, users can enter values manually or via the dropdown list.

The Apply button converts the entered Effectivity Variable values into Effectivity Criteria in the free-form Boolean expression format and refreshes the Tree Grid View with the item structure resolved according to the provided Effectivity Criteria.

For example, a user enters and applies the following Effectivity Criteria: Unit = 112, Production Date = 3/1/2021, Model = Replicator.

In this case Part “MP0370-006” is no longer displayed in the Tree Grid View because its Effectivity Expressions “Model = [Replicator 2]”, “[Production Date] >= [7/1/2021]” conflict with the provided Effectivity Criteria.

If Effectivity Criteria is changed to Unit = 112, Production Date = 3/1/2021, Model = [Replicator 2] then Part “MP0370-004” is not displayed because its Effectivity Expression “Model = Replicator and Unit >= 100” conflicts with provided Effectivity Criteria.

If the Effectivity Criteria is changed to Unit = 7, Production Date = 3/1/2021, Model = Replicator then both “MP0370-004” and “MP0370-006” Parts are not displayed because their Effectivity Expressions conflict with the provided Effectivity Criteria.

When the user clicks the “Set Effectivity Criteria” button again, the previously applied Effectivity Criteria will be displayed in the Effectivity Criteria Filter dialog. Each Effectivity Variable value can be cleared separately by removing the cell value. Alternatively, the Clear button can be used to clear all Effectivity Variable values and the selected Scope.

After the Effectivity Criteria is cleared and Apply is clicked, an unfiltered BOM is displayed including both Parts.