The 'Query Template Builder' is a way to create a business function that returns a query result. Users can create a search query business function without knowing JavaScript.
For example, in Web UI, a reference target search benefits from a query by restricting the reference type options available to only those that are appropriate for the use case. The Query Template Builder supports combining criteria to declare precisely which targets should be available for a given reference. For configuration steps, refer to the Custom Reference Target Search topic in the Web User Interfaces documentation.
Sample uses for the Query Template Builder include limiting reference type search results to targets, such as:
-
below a specified hierarchy node to limit reference targets to only products under a specified classification.
-
of a certain object type, like only contact person.
-
with a reference of a certain type, and/or points to the same node as the reference on the current object, like limiting the supplier location selection to only locations belonging to an already selected supplier.
-
with an attribute value that matches the attribute value on the current object or data container, like selecting only remote controls that supports the protocol of the current TV object.
-
where the entity owned by the data container already has at least one of the specific type of data container being referenced.
Refer to the Use Cases section at the end of this topic for other common scenarios and setup.
To add the query to this operation, click the Edit Business Function link.
For more information on editing a business function, refer to the Editing a Business Rule or Function topic in the Business Rules documentation.
Configuration Example
The example in this section configures a Business Function so the reference target options are limited to:
-
products where the attribute (WallMountType) matches the setting on the current node (via the 'getWallMountType' business function provided by the Query Variable)
-
AND that are below the identified classification hierarchy (I-WebLevel2-25)
-
AND where the specified search string text matches the name, ID, or the value found in the specified attribute.
Note: When using variables, if the variable cannot be resolved, the Query Template Builder search ignores the criteria to build the search. Continuing with the example above, if after creating the search, you delete the getWallMountType business function, then the top-most Attribute value criteria cannot be evaluated and as a result, the Query Template Builder returns any product linked under the 'TV Stands, Mounts & Storage' hierarchy, where either product name, product ID or the ApplianceType attribute matches the search string the user entered in the typeahead.
-
Input Parameter - define the parameters that can be passed to the function from the outside. STEP and Java types are available. For the business function to be used in Web UI for Custom Reference Target Search, in input parameters must be of type Node and String.
Note: Use caution when changing an input parameter type for an active business rule. Business rules that call the modified function may also need to be updated.
-
Query Variables - define business function(s) to be used within the search query. Click the Add Query Variable link, click the Business Function option, and add a Variable Name. Click the ellipsis button (
) to choose the desired business function and make it available for selection in the Search flipper Variables dropdowns. Query Variables allow the user to retrieve values to be used in the search criteria from the current object. For example, to search wall mounts that match the current node can be a business function that get a current node object type or the parent of the current node. -
Search - use the available search operations to build a query. Only objects that are true for the entire criteria in the search are included in the result set. At least one criteria must exist and the Hierarchy Criteria is displayed by default. Click the dropdown to change the first criteria if necessary since it cannot be deleted.
-
Hierarchy Criteria - defines the location in the hierarchy to search below. Select either Variables or Node from the dropdown and select the Query Variable or click the ellipsis button (
) to select the node. -
Object Type Criteria - defines the object type to search for. Select either Variables or Node from the dropdown and select the Query Variable or click the ellipsis button (
) to select the node. -
ID Criteria - uses an Equals, Does Not Equal, or Like (preferred) operator as a search criteria. Select either Variables or Node from the dropdown and select the Query Variable or click the ellipsis button (
) to select the node. Using the 'Like' operator allows searching on parts of the ID. 'Like' is necessary in custom reference target search to match the user's partially written search string towards the STEP ID. -
Name Criteria - uses an Equals, Does Not Equal, or Like (preferred) operator to define the name of the target. Select either Variables or Node from the dropdown and select the Query Variable or click the ellipsis button (
) to select the node. Using the 'Like' operator allows searching on parts of the name. 'Like' is necessary in custom reference target search to match the user's partially written search string towards the STEP name. -
Attribute Criteria - search a specific attribute. Both the value and the attribute can be defined by variables or input parameters. Select either Variables or Node from the dropdown and select the Query Variable or click the ellipsis button (
) to select the node. -
Reference Type Criteria - search nodes containing a specific reference type. Defines the reference type allowed for the target. Select either Variables or Node from the dropdown and select the Query Variable or click the ellipsis button (
) to select the node. -
Criteria Group - defines how multiple criteria combine. One criteria group combines the included criteria using a selectable operator. As defined in the next section, some criteria options have limits: AND and OR allow more criteria; while EXCLUSIVE OR and EXCEPT allow only two criteria.
Click the Add Criteria link to display the operator types and choose one when adding a new criteria.
-
And - All criteria must be true for the whole Criteria Group is considered true.
-
Or - If at least one criteria is true, the whole Criteria Group is considered true.
-
Exclusive OR - combines only two criteria; when one is true and the other is false, the whole Criteria Group is considered true. For example, to query for packages that are either large and light or small and heavy, create the criteria as: <package_size larger than XL> EXCLUSIVE OR <package_weight larger than Heavy>.
-
Except - combines only two criteria; when the first is true and the second is false, the whole Criteria Group is considered true.
To remove criteria, on a single criteria, click the delete button (
); on a multi-criteria item, click the delete button (
) to remove only a part of the criteria. Click the Or link (
) or the And link (
) to create a relationship between criteria. -
Use Cases
The image above shows a use case mapping applicable wall mounts for televisions where the appliance type of the target of the reference must match the wall mount type on the current object.
A use case in customer data is when selecting a 'ship to' location for a sales area. The user is allowed to select a 'ship to' location and the options will include the customer itself (to indicate direct shipments). Additionally, 'ship to' locations must belong to the 'ship to' account group and match the search characters the user entered. In the image below, the 'ship to' customer itself continues to be available regardless of the search characters entered by the user.
While yet another customer data use case is onboarding a contact person, where a contact-to-organization reference is mandatory. The reference target search finds organizations based on the entered string compared to Legal Name or STEP name and also filters out deactivated organization records.
