Configuring Effectivity Resolution

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 29 – Query Builder Guide. For additional information about Tree Grid View, refer to the Aras Innovator 29 – 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.

Figure 8.

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.

   

   

Figure 9.

5. 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.

   

   

6. Figure 10.

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

   

   

Figure 11.

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

Figure 12.

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.

   

   

Figure 13. 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).

Figure 14.

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.

Figure 15.

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.

Figure 16.

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.

Figure 17.

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.

Figure 18.

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

Figure 19.

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 TOC -> Administration -> 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.

   

   

Figure 20.

5. Click the Show Editor button on the sidebar.

   

   

Figure 21.

6. 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.

   

   

Figure 22.

7. 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.

   

   

Figure 23.

8. 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.

Figure 24.

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

   

   

Figure 25.

10. Change the new column label to State.

    

    

Figure 26.

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

    

    

Figure 27.

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

    

    

Figure 28.

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

    

    

Figure 29.

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

    

    

Figure 30.

15. Click Save to save your changes.

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

   

   

Figure 31.

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

   

   

Figure 32.

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.

   

   

Figure 33.

1. Specify the relationship name and label.

   

   

2. Figure 34.

3. 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.

   

   

   Figure 35.

4. Click Next. The following dialog box appears:

   

   

   Figure 36.

5. Click Generate 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.

Figure 37.

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.

Figure 38.

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

Figure 39.

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.

Figure 40.

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.

1. Open the “MP2940” Part item which is present in the Part Structure Tree Grid View.
2. Click Edit so that the Part BOM relationships can be edited too.
3. Right click on the “MP0370-004” Part row and click Open to open the Part BOM relationship item.

Figure 41.

4. 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.

Figure 42.

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

Figure 43.

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

Figure 44.

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

Figure 45.

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

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

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

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

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

Figure 50. 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.

Figure 51. 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.

Figure 52. 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.

Figure 53. 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.

Figure 54. 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.

Figure 55.