Modeling Best Practices

This topic outlines best practices for creating Integration Objects.

When creating an Integration Object:

Select a root item.
Include all attributes, which are unique in the type system for that item type.
Include any optional primitive, enum, or map attributes for the item type.
If the Integration Object is intended for inbound requests, include all non-optional attributes in the item.
If the root item type has a unique attribute that references another item, include the referenced item type and only its key attributes in the Integration Object.
If other non-key reference attributes must be included, then add the referenced item type and only its key attributes to the Integration Object. This Integration Object should not manage other referenced types as there should be other Integration Objects for managing the references. For example, Catalog is referenced from CatalogVersion's key attribute "catalog". Catalog and its key attribute "id" are included so that references to a Catalog in CatalogVersion are updated, but do not include any other Catalog attributes because it's beyond the scope of the example CatalogVersion Integration Object.
Be very careful when adding autoCreate=true to an Integration Object attribute because it means that the Integration Object manages more than one entity. Exceptions can be made, but you should weigh the pros and cons.

An important fact to always keep in mind when creating Integration Objects: The size of an Integration Object = the size of the database transaction. Growth of the database transaction increases chances of a deadlock. For example, a very simple Integration Object that contains only an Order item can't cause a deadlock because even if two concurrent requests are updating the Order record in the database, and each request is a transaction (FYI), the request that commits the changes first wins, and the second request results in StaleDataException. Of course, the exact behavior depends on the isolation level configured for the transaction and locking strategies (row, page, table), so it may succeed too, but it's not important as there will be no deadlock.

If the Integration Object contains two items, for example, Order and OrderEntry. Although this relationship feels safe because it's a partOf relationship and OrderEntries can be bound to only one particular Order, a deadlock is possible. Imagine two concurrent requests updating the same order:

Sample Code

{
  "code": "order1",
  "entries": [
    {
      "seqNumber": 1,
      ...
    },
    {
      "seqNumber": 2,
      ...
    }
  ]
}

and

Sample Code

{
  "code": "order1",
  "entries": [
    {
      "seqNumber": 2,
      ...
    },
    {
      "seqNumber": 1,
      ...
    }
  ]
}

If the two requests are being processed concurrently:

Sample Code

Request/Transaction 1              
Request/Transaction 2  
places lock on the entry 1         
places lock on entry 2
waits to get a lock on entry 2     
waits to get a lock on entry 1

That is a deadlock. If the Integration Object contains references to CatalogVersions, Catalog, Product, Unit, Currency, Customer, etc. types, each of those references can be locked on to, which increases the chances for a deadlock.