Working with Composite Objects

A composite object is a collection of Related Objects that can be processed in a single transaction. When an adding an Order, for example, a program can add OrderItem records, update the ProductInventory, update the Customer address, and add a new Tag, all at the same time, in a single, transaction-safe operation.

About Composite Objects

A simple object corresponds to a single row in a table--like a row in a spreadsheet, it can have multiple fields, but each field contains a single data value. A composite object is one that includes relationships to other tables--so a customer can have multiple orders, for example, and an order can have multiple products.

To put things another way: Fields in a simple object contain data that is essentially "primitive" in nature--strings, numbers, and dates. Those values may reference other objects, but the dependent objects must be handled in a separate transaction. (Transactional safety then becomes an issue if processing is interrupted.)

But in a composite object, fields that reference other objects can be used to manipulate the dependent objects at the same time as the original object. Transactional safety can then be assured, because either the entire transaction succeeds, or (if it fails) the system state is the same as if the transaction never started.

A composite object, then, is any set of objects related by Lookup relationships that are processed in a single transaction. That way, either all attempted operations on the collection of objects succeed, or none of them do--so the database is never left in a "halfway" state.

Learn More: Object Relationships

Managing Composite Objects

Like simple objects, Composite Objects can be added, updated, and deleted programmatically, using a composite request--an API call that operates on a composite object. The process is only slightly more complex, and there are a few things you need to know in advance.

Composite Object APIs and Examples

• The REST composite record Resource provides a full range of composite object manipulations, along with examples.
• The Java Composite Object APIs provide a search and retrieve mechanism for composite objects, along with examples.

Considerations

• All Custom Objects can participate in composite requests.
• Of the Built-in Objects], only the User object can participate in composite requests.
• Composite operations generally take longer than operations on simple objects, and use more memory space.
• Composite reads will generally take significantly more time and memory, especially if the composite relationships include many nested objects.
• Cascade Rules and Aliases need to be specified for each relationship in a composite object.
• With the appropriate Cascade Rules settings:
  • For an N:1 relationship:
    • Updates are allowed.
    • Adds and deletes are not permitted.

• • For a 1:N relationship:
    • Adds, updates, and deletes are allowed.

• • For an M:N relationship:
    • Adds and updates are allowed.
    • Orphan deletes are allowed. (References are removed. If no references remain, the subsidiary object is deleted.)

Composite Object Processing Rules

In the order-processing diagram, Orders are of primary interest. The idea is to add a new (composite) Order object, consisting of a simple Order record and multiple related records. This section describes the operations you can perform on related objects while doing that.

When adding an object that has a 1:N relationship, you can add the records on the "N" side of the relationship at the same time. When adding a new Order for example, you can add new order Items, as well. In that case, you are adding the primary record (Order) and one or more secondary records (Items).

Note: All of the add and update capabilities described are disabled, by default. They can be enabled by setting the Cascade Rules for the object relationships.

You can also add records on the "M" side of an N:M (many-to-many) relationship. So when adding a new Order, you could add a new Tag at the same time.

But when you are adding a object that has an N:1 relationship, you can only update the secondary object, You can't add a new one. So when adding a new Order, you could update the Customer's address and modify the date of their most recent order, but you couldn't create a new customer record. (In general, that behavior is desirable. If a Customer's name or ID# had been entered incorrectly, you want to catch the error--not add a new, empty "customer" record.)

Similarly, when adding a new order Item, you can update an existing Product record, but you can't add a new one. For example, you might update the Product record using a negative number for the quantity, and set up a Data Policy to subtract that value from the quantity currently in inventory.

Note: If you look at the diagram closely, you'll notice that the OrderItem object is very similar to the OrderContact object. Both contain two lookup fields, which allows both of them to serve as junction objects. In reality, the difference lies in the declaration. Declaring that OrderTag is a junction object allows a Tag to be added when adding a Order. By declaring that Orders are in a simple one-to-many relationship with OrderItems, the many-to-One relationship holds when adding an OrderItem as part of an Order. In that relationship, the product record can be updated--for example, to reduce the inventory quantity--but a new product record cannot be added.

Cascade Rules and Aliases

The cascade rules specify which operations are allowed when using the Composite Object APIs. They can also be used to auto-delete detail records in a Master-Detail relationship.

About Cascade Rules and Aliases

• Cascade rules are established by the application designer. They determine which operations are allowed on dependent objects in a relationship.
• The alias gives the relationship a name. In the data stream passed to the composite request handler, the alias is a wrapper for the dependent records in a relationship. The resulting structure looks like this:

<syntaxhighlight lang="xml" enclose="div">

primary record

 |...primary record data...
 |relationship alias for secondary object
 |   secondary record #1  
 |      |...secondary record data...
 |      |relationship alias for tertiary object
 |      |   tertiary record #1
 |      |      |...tertiary record data...
 |      |      |...
 |      |...
 |   secondary record #2  
 |...

</syntaxhighlight>

Notes:

• Relationships can nest to arbitrary depth.
• Relationship aliases will generally have the same name as the dependent object.

Cascade Rules

Cascade rules restrict or allow add, update and delete access to related objects. They determine which operations are allowed on subsidiary objects in a composite relationship.

The choices you can make depend on the type of relationship. The following choices are available:

Relationship Type	Foreign Object Id	Junction Foreign Object Id	Add	Update	Delete	Orphan Delete
One to Many	Other than User	--				--
One To Many	User	--	--		--	--
Many to Many	Any Object	Other than User			--
Many to Many	Any Object	User	--		--	--
Many to One	Any Object	Any Object	--		--	--

Note: The Case Delete Rule has a dual purpose: When the "master" record in a one-to-many relationship is deleted, "detail" records are deleted automatically. Learn more: Master-Detail relationship When the Composite Object APIs are used to update a master record, detail records can be deleted at the same time.

Specifying Aliases and Cascade Rules

Prerequisites:

1. All objects and junction tables have been created.
2. Lookup fields have been defined in the objects to establish the relationships

To specify aliases and cascade rules:

1. > Customization > Objects
2. Select the primary object in the relationship.
   For example, if Order_Items has a Lookup to Orders, then Orders is the primary object, and Order_Items is the dependent object.
3. In the Properties tab, scroll down to Related Information
   A list of dependent objects appears. So if Order_Items has a Lookup to Orders, then Order_Items appears in the list. (The Users object always appears twice: for the creator of the object, and for the most recent person to modify the object.)
4. Select the object relationship you want to specify.
   For example, select the Order_Items object. The Manage Object Relationship window appears.
5. Specify the type of relationship: Either One-to-Many or Junction if this is a junction object for a Many-to-Many relationship.
   If you select many-to-many:
   1. The 'Select Foreign Object field lists the targets of the other Lookup fields in the junction object.
      (Typically there will only be one, but there could be more.)
   2. From that drop down, select the secondary object in the Many-to-Many relationship
      The next drop down is then automatically populated with the lookup field.
6. Specify the name of the relationship alias.
   Typically, that will be a lowercase, plural version of the dependent object's name, but you may need different aliases if the same object is used in multiple dependent relationships. For example, in the Order object, the alias for the Order_Item object might typically be specified as items.
7. Specify the cascade rules. Depending on the type of relationship you have defined, you can enable the capability to:
   1. Add dependent records
   2. Update dependent records
   3. Delete dependent records in a one-to-many relationship
   4. Do an "orphan delete" for a many-to-many relationship
      (Automatically delete the dependent record if no more records point to it.)