Navigating Association Links to find Related Case Objects

From within a script, each case reference provides a set of attributes and methods that you can use to navigate association links from the referenced case object to find related case objects.

Note: You can only use these methods and attributes to navigate existing association links. If you try to navigate using a link that either has not been created yet or has been deleted, execution of the script will fail.

The exact set of attributes and methods available depends upon the number of association links that exist from the referenced case class, and upon the multiplicity of those association links.

Zero-to-One Association Relationships

For each class that is related to this class by a 0-to-1 association relationship, the following attributes and methods are available.

Attribute Description
associationNameRef Returns the case reference object that is linked to this case reference object by the associationName relationship.
Method Description
navigateByCriteriaToassociationNameRef(criteriaObject) Returns the case reference object that is linked to this case reference object by the associationName relationship, and that matches the criteria specified in the criteriaObject.
navigateByCriteriaToassociationNameRef(DQLString) Returns the case reference object that is linked to this case reference object by the associationName relationship, and that matches the criteria specified in the DQLString.

Zero-to-Many Association Relationships

For each class that is related to this class by a 0-to-many association relationship, the following attributes and methods are available.

Attribute Description
associationNameRefs Returns a list of all case reference objects that are linked to this case reference object by the associationName relationship.
Method Description
getassociationNameRefs(index,pageSize) Returns a paginated list of case reference objects that are linked to this case reference object by the associationName relationship.
navigateByCriteriaToassociationNameRefs(criteriaObject) Returns a paginated list of case reference objects that are linked to this case reference object by the associationName relationship, and that match the criteria specified in the criteriaObject.
navigateByCriteriaToassociationNameRefs(DQLString) Returns a list of case reference objects that are linked to this case reference object by the associationName relationship, and that match the criteria specified in the DQLString.
navigateByCriteriaToassociationNameRefs(DQLString,index,pageSize) Returns a paginated list of case reference objects that are linked to this case reference object by the associationName relationship, and that match the criteria specified in the DQLString.

index is the (zero-based) number of the first record to return.

pageSize is the number of records to return in each page of a paginated list. A value of -1 means return all records.

Examples

The following examples are based on the following fragment of a case data model.

In the following screenshot the content assistance shows the methods and attributes available on an orderRef object.

This example demonstrates the use of the direct navigation methods and attributes. It shows how , given an order ID, to find the associated customer and the employee(s) who took the order. 

	// Find order number "123"
	var orderRef = cac_com_example_ordermodel_Order.findByOrderId("123");

	//Navigating a 0-to-1 relationship:
	// Find the customer associated with this order
	var customerRef = orderRef.customerRef;

	//Navigating a 0-to-many relationship:
	// Find the employees who took this order, either in a single list...
	var employeeRefList = orderRef.orderTakersRefs;

	// ...or, in a paginated list
	var	employeeRefList = orderRef.getOrderTakersRefs(0,5);
This example demonstrates the use of the navigateByCriteria methods. It shows how to navigate from a customer case reference object, returning orders with an orderLine quantity greater than 100.
Note: The orderLines.quantity attribute path in the DQL criteria string is relative to the target class (Order) and not the source class (Customer). 
	orderRefList = customerRef.navigateByCriteriaToOrdersRefs("orderLines.quantity > 100");

This example demonstrates how to do the same thing using a criteria object. In this case, the createCriteria method for the target case access class - cac_com_example_ordermodel_Order - is used. 

	var criteria = cac_com_example_ordermodel_Order.createCriteria("orderLines.quantity>100");
	orderRefList = customerRef.navigateByCriteriaToOrdersRefs(criteria);