Custom Reference Target Search

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, meaningful reference targets are far fewer than what the object type would suggest.

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 Web UI. A custom reference target search presents the user with only those targets that are relevant for selection.

Note: A custom reference target search can be configured and applied to each reference editor in the Web UI. For more information, see the Custom Reference Target Search Configuration section of the Web User Interfaces / Web UI Setup and User Guide documentation here.

Customizing the reference component target search involves creating a business function that returns a 'Query Specification' in the workbench and assigns the business function for a reference target search in the References component in Web UI.

Setting up a Reference Target Search

A Reference Target Search requires configuration in both workbench and Web UI as defined in the following sections.

Workbench Configuration

Create a reference target search as a business function in JavaScript using the Query API to provide the user with only the reference targets that are valid on the reference. In workbench, create a business function as defined below. General instructions for creating business functions can be found in the Business Functions section of the Business Rules documentation here.

  1. On the System Setup tab, select a node that is valid for business functions, right-click and choose the New Business Function option.

  2. On the Create Business Function dialog, type an ID and Name and click the Create button.

  3. On the Business Function editor, click the Edit Business Function link and click the edit button () for the JavaScript Function.

  1. For Input Parameters, consider that the Web UI will attempt to populate these input parameters for a custom reference target search (as illustrated in the example below):

  • String: Populated with the search string the user has entered. Most cases require a String input.
  • Node: Populated with any node selected. When creating a reference, this will be the source node of the reference. Most cases require a Node input.
  • Data Container Object: If the user is within a data container editor, the source of the reference will be a data container instance, and this source will be available to the business function as a Data Container Object.

  1. For Return Type, as shown below, the business function must return a 'Query Specification.' Otherwise, the business function cannot be selected in the Web UI for Target Search Function in the Search Table Tab Properties (for the References component Node Picker Dialog) as described later in this topic.

  1. For JavaScript, the search code must properly handle null situations for Data Container Object if you use the same function both in Data Container reference editors and in editors on Node Details. See the last section of this topic for more Query API JavaScript examples.

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. A good suggestion is to include an object type criteria or similar in the business function's conditions.

  1. Click the Save button on each of the dialogs to close and save the business function.

The following is an example 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.

Web UI Configuration

The Reference Target Search feature is available for configuration in several Web UI components.

For more information on where and how this can be configured, see the Custom Reference Target Search Configuration section of the Web User Interfaces / Web UI Setup and User Guide documentation here.

Query API JavaScript Examples

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.

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

Copy 
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;