Nested Data Structures

Top-level schema types in Luminate Online Web Services are all derived from the Record type. The primary top-level type is the Constituent record. Top-level Record types such as Constituent, Donation or TeamRaiserGift directly support various operations. Sub-types such as Name, Address, or AnnualTransactionSummaryare only accessible through their parent type; they do not directly support operations.

Luminate Online Web Services types are hierarchical, and in code, access to sub-elements is specified using dot notation. For example, Constituent.Name contains the fields Constituent.Name.FirstName and Constituent.Name.LastName. Likewise the Patricipant field of a TeamRaiserRegistration type record is a Constituent type; specify the participant's surname as: TeamRaiserRegistration.Participant.Name.LastName.

Configurable Constituent Fields

Like snowflakes, no two Constituent record structures are exactly alike. The fields of a Consituent record can be customized for individual clients, so some fields listed in the documentation may not be present in a specific client implementation, and custom fields may be included which are not necessarily documented. If you are unsure about the meaning or use of specific custom fields, you should contact the Client system administrator or Luminate Online support for assistance.

Using the DescribeRecordType Operation

The DescribeRecordType operation allows you to inspect any CWS type in the WSDL to determine the properties of that type. This operation returns the list of the operations that the type supports and the list of fields in the type. Field properties include:

• Name - the name of the field
• Writable - whether or not the field may be modified on Create or Update operations
• Custom - whether or not the field name is an alias for a custom field in the Luminate Online database
• Nillable - whether or not the field value may be Null
• Multiple - whether or not the field may return multiple instances
• Type - the field's data type (may be either a simple type or another CWS schema type)
• MaxLength - the maximum number of characters supported for text fields (longer values will be truncated)
• IsCriterion - Not used (Deprecated)
• IsWildcard - whether or not the field is returned to a query that does not specifically request it when the parent type is requested
• Option - a list of valid values for an enumeration

Wildcard and Nillable Fields

The number of fields in Constituent records can be quite large. Therefore, by default, CWS returns only a commonly-requested subset of fields by default if their parent type is requested in an operation. These fields are designated as "wildcard" fields, indicated by theIsWildcard property of each Field entry in the DescribeRecordType response for any given type. To return non-wildcard field values, simply specify the field in the request.

Likewise to optimize performance of Update operations, only those fields which contain values, or which specify the attribute xsi:nil="true" are updated. Some middleware frameworks may include empty field elements in a request if values are not specified for those fields. To guard against accidental data loss, CWS requires that you explicitly set a field to null to clear it on Update.

Attempting to set the value of a non-writable field, or clear a non-nillable field, will result in an error.

Bi-directional Synchronization, One-way Synchronization, and Query

The Constituent record is currently the only object in CWS that supports bi-directional synchronization (i.e. it supports Create, Update and Delete operations into the Luminate Online database); other top-level schema types that expose transactions (e.g. Donations) support only one-way (download) synchronization. These support the synchronization operations GetIncrementalInserts, GetIncrementalUpdates, GetIncrementalDeletes, but not Create, Update and Delete. Other top-level types that provide metadata, summary information, or additional data about a Constituent or other synchronized type (e.g. TeamRaiserParticipationType) are accessed through Query operations. Such objects are not directly associated with events in time (i.e. a registration or donation) and so do not support the synchronization operations.