Reference editors in Web UI determine which target objects the user is allowed to select based on the object type validity configured on the reference type. In many cases, a meaningful reference target includes far fewer options than would be included in a list based solely on the object type.
A custom reference target search presents the user with only those targets that are relevant for selection.
For illustrations, refer to the Query Template Builder Example section which shows the recommended method for creating a query or the Query API JavaScript Example section for an alternate method below.
Note: To enable a more focused search for reference target objects, a custom reference target search can be configured and applied to each reference editor in the Web UI. For more information, refer to the Custom Reference Target Search Configuration section of the Web User Interfaces documentation here.
By default, the standard query search in some Web UI components provides additional filtering, for example:
-
For performance, a dropdown may only show the first 10 results and a search list may only show the first 100 results.
-
For validity, a query search that would otherwise return 100 results, only shows 40 choices in the list because the other 60 are invalid as determined by the component.
Configuration
Customizing the reference component target search involves creating a business function in the workbench and assigning it for a reference target search in the Web UI. General information on business functions is in the Business Functions topic of the Business Rules documentation here.
Configuration is required in both workbench and Web UI as follows:
-
In workbench, create a business function using the steps included in the Creating a Business Rule, Function, or Library topic here.
-
On the Business Function editor, click the Edit Business Function link and click the edit button (
) for the Function. 
-
From the dropdown, select a method to configure a business function that returns a 'Query Specification':
-
Use the recommended Query Template Builder operation to create a Web UI search query, as described in the Query Template Builder Operation topic here. Refer to also the Query Template Builder Example section below.
-
Use the JavaScript Function operation and the Query API, as described in the JavaScript Function Operation topic here. Refer to also the Query API JavaScript Example section below.
-
Note: The business function will be completely responsible for the search. There is no further object type validity or similar performed on top of the search. It is recommended to include an object type criteria or similar in the business function's conditions.
-
Click the Save button on each of the dialogs to close and save the business function.
-
In Web UI, configure the Reference Target Search feature in the desired Web UI References components, as defined in the Custom Reference Target Search Configuration section of the Web User Interfaces documentation here.
Query Template Builder Example
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.
Query API JavaScript Example
This JavaScript use case is of a ship-to reference search, only allowing the user to select ship-to targets that are actual ship-to accounts and part of the same organization hierarchy as the currently selected node.
The following are examples of Query API JavaScript to be used with business functions that power the Custom Reference Target Search functionality.
Search Attribute in Data Container
The query below finds all entities where the Main Address data container has a zip equal to the zip variable.
var querySpecification = queryHome.queryFor(com.stibo.core.domain.entity.Entity).where(
queryConditions.hasDataContainer(mainAddressDcType).where(
queryConditions.valueOf(zipAttr).eq(zip)
)
); Nesting AND and OR
The query below finds valid ship-to targets for a reference.
A textual statement of the below query could be: The ship-to target of supermarket must either be a warehouse in the supermarket chain, or the supermarket itself.
We could also state this as:
- Either
- Entity is of the Ship-to account group type
- AND the owner is the same as the current object
- AND name OR id match the search string
- OR
- entity is the Current Object
Important: The sequence in which the logical operator methods are executed determines the logic, not the standard Java logical operator precedence. Following this, the condition X.or(Y).and(Z) will match objects for which X or Y is true and for which Z is also true.
var refHome = manager.getReferenceTypeHome();
var queryHome = manager.getHome(com.stibo.query.home.QueryHome);
var queryConditions = com.stibo.query.condition.Conditions;
var customerAccountGroupRefType = refHome.getReferenceTypeByID("SAPCustomerAccountGroup");
var ownershipRefType = refHome.getReferenceTypeByID("OrgOwnedByOrg"); //"Subsidiary of"
var ownerRef = currentNode.getReferences(ownershipRefType);
var hq = ownerRef.get(0).getTarget();
var querySpecification = queryHome.queryFor(com.stibo.core.domain.entity.Entity).where(
queryConditions.name().like(searchString) // And name is somewhat like the search string
.or(
queryConditions.id().like(searchString)
).and(
queryConditions.hasReference(customerAccountGroupRefType).where( // Is a shipto target
queryConditions.targetMatches(
queryConditions.id().like("SAP-Cust0002") //The ship-to account group
)
)
).and(
queryConditions.hasReference(ownershipRefType).where( // Is part of the same ultimate organisation
queryConditions.targetMatches(
queryConditions.id().like(hq.getID())
)
)
).or(
queryConditions.id().like(currentNode.getID())
)
);
return querySpecification;