Metadata API - quandis/qbo3-Documentation GitHub Wiki

QBO supports several technique for tracking metadata associated with relational tables.

Labels

Labels allow users to add zero or more labels to any QBO object.

Labels grew out of need to categorize Organization records as client, vendor, title company, insurance provider, etc., and realizing that frequently organizations fit multiple categories.

All QBO modules support labels, which is the ability to tag or categorize records with an unlimited number of attributes.

Labels examples include:

Title Companies: a group of Organizations that perform title work
Foreclosure Attorneys: a group of Organizations that manage foreclosures
Team: a group of users representing a team
High Risk Loans: a group of loans that are considered high risk
Preferred Brokers: a group of real estate brokers that are preferred by a client

Most classes include a Type property (e.g. Loan.LoanType, Organization.OrganizationType, Contact.ContactType), any given record may have only one type defined. However, any record may have an unlimited number of tags applied to it. When a search is performed, the following will produce a list of Field Services companies:

Organization.ashx/Search?Tag=Field Services

Standard search panels support the ability to select multiple records and 'tag' them with an existing or new tag. This action creates a Collection (if the label is new), and a CollectionMember row for each selected item mapping it to a Collection.

Labels comprises the following classes:

Class	Description
Collection	A 'label' or 'tag' representing some sort of collection of items.
CollectionMember	Maps an object to a Collection (this is the 'label').
CollectionTemplate	Defines the characteristics of a `Collection`.

Search Indexes: Key-value Pairs

The SearchIndex table is used to store string-based key-value pair

To add metadata leveraging the SearchIndex table:

// Pattern
{ClassName}/Save?{Parameters}&SearchIndexes_{Key}={Value}
// Associate a name with an Attachment
Attachment/Save?ID=1&SearchIndexes_FirstName=John&SearchIndexes_LastName=Doe
// Associate a lockbox code with a Property
Property/Save?ID=1&SearchIndex_LockBoxCode=12345

Given know SearchIndex keys, one can quickly query them:

Attachment/Search?SearchIndex=LastName&Value=Doe
Property/Search?SearchIndex=LockBoxCode&Value=12345

Lastly, the standard Select and Summary operations will include SearchIndexes in the XML or JSON results:

{
  "PropertyID": 1,
  ...
  "SearchIndexes": [{
    "SearchIndexID": 1,
    "Attribute": "LockboxCode",
    "Value": "12345",
    "Object": "Property",
    "ObjectID": 1
    ...
  }]
}

ObjectLink

The ObjectLink module enables defining relationships between homogeneous or heterogeneous objects. The object being linked from is referred to as the PrimaryObject, and the object being linked to is the LinkedObject.

Use cases include:

Linking all documents added to a zip file document.
Linking all templates that comprise a release.
Linking which states a document template is usable in.

The ObjectLink module comprises:

Property	Description
ObjectLink	Label for the link.
Status	Status of the relationship.
ObjectLinkType	Type of the relationship.
PrimaryObject	Name of the object to link from.
PrimaryObjectID	Identity of the object to link from.
LinkedObject	Name of the object to link to.
LinkedObjectID	Identity of the object to link to.
Master	Identifies the 'primary' relationship when multiple links exist between a primary and linked object.

Link Filters

The following generic filters can be used when search any QBO module:

Filter	Description
LinkedFrom	Records must exist in the `ObjectLink` table as `LinkedObject/ID`.
LinkedTo	Records must exist in the `ObjectLink` table as `PrimaryObject/ID`.
NotLinkedFrom	Records must not exist in the `ObjectLink` table as `LinkedObject/ID`.
NotLinkedTo	Records must not exist in the `ObjectLink` table as `PrimaryObject/ID`.

Examples:

Show document templates that are linked where the name of the link is 'State Approved':

/AttachmentTemplate/Search?LinkedFrom=State Approved

Show process templates that are not linked where the name of the link is 'Release v1.0.0':

/ProcessTemplate/Search?NotLinkedFrom=Release v1.0.0

AbstractObject Support for ObjectLink

The AbstractObject class includes support for ObjectLink:

Method	Description
`LinkFrom(AbstractObject linkedObject)`	`this` is the `PrimaryObject`, and `linkedObject` is the `LinkedObject`.
`LinkTo(AbstractObject primaryObject)`	`this` is the `LinkedObject`, and `sourceObject` is the `PrimaryObject`.

ObjectLink vs. Labels

Labels must be homogeneous; if a label applies to Contact, only Contact records may have that label applied. ObjectLink may be homogeneous, but they are more useful if they are heterogeneous.

Use by Plugins

Plugins may optionally leverage ObjectLink to define relationships that are not otherwise formally defined in QBO. For example, the ZipGenerator plugin creates, er, zip files, saving the zip file as a document. It is useful to know what Attachment records were used when creating the zip document.

Create a Zip file from a list of AttachmentIDs:

Attachment/Generate?Template=Zip Template&ID=1,3,5,9,12&Link=Added to Zip File

The plugin pseudo-code looks like:

foreach (var attachment in attachments) {
  source.add(attachment);
  if (!string.IsNullOrEmpty(link))
    source.LinkFrom(attachment, link);
}