Calendar API
When querying data via the Calendar API, custom fields can be accessed through their entity associations. However, the values will be returned as a separate element for each custom field value that is associated to the parent entity.
Examples
Location.Room.UserFieldValuesByRecordId.UserFieldDefinition.Name
Location.Room.UserFieldValuesByRecordId.Value
These will return all of the room custom field names and values associated with the activity. If there is more than a single custom field, the activity will be returned for each of them with all data repeated other than the custom field information. This is due to the one-to-many nature of the association and is the same as with multiple resources returned via the Calendar API.
Example of full call:
https://www.aaiscloud.com/<INSTANCENAME>/~api/calendar/calendarList?&fields=Location.Room.UserFieldValuesByRecordId.UserFieldDefinition.Name%2CActivityName%2CParentActivityName%2CMeetingType%2CDescription%2CStartDate%2CEndDate%2CStartMinute%2CEndMinute%2CActivityTypeCode%2CCampusName%2CBuildingCode%2CRoomNumber%2CRoomName%2CLocationName%2CStartDateTime%2CEndDateTime%2CInstitutionId%2CSectionId%2CSectionPk%2CIsExam%2CIsPrivate%2CEventId%2CEventPk%2CCurrentState%2CLocation.RoomId&limit=10&_s=1 &filter=Location.Room.EffectiveParentId%20in%20(%22<ROOMID>%22)&sortOrder=%2BStartDate%2C%2BStartMinute&view=XML
Query API
The Query API is often the cleanest way to get the custom field information in bulk. When searching for the List Values or the list of custom field names associated to a specific entity, the Query API will return them in a clean list.
If using the Query API to directly call an activity and making the associations, the results will return multiple elements with the non-custom field data being repeated (as with the Calendar API). Again, this is due to the one-to-many nature of these associations.
Examples of these calls via a debugger tool can be captured by going to the Settings > Custom Fields page. When the page drop-down is selected, the query call to the UserFieldDefinition can be seen:
/~api/query/UserFieldDefinition?&start=0&limit=500&fields=Id%2CName%2COwnerId%2CFieldNumber%2CFieldPriority%2CFormAreaId%2CDisplayLabel%2CFieldTypeCode%2CControlTypeCode%2CIsRequired%2CIsReadOnly%2CControlWidth%2CControlHeight%2CCreatedDate%2CCreatedBy%2CModifiedDate%2CModifiedBy%2CRowVersion&entityProps=&_s=1&filter=(OwnerId%3D%3D%2223788ab6-b520-48c4-8132-c0f31d2d5c11%22)&page=1
Entity API
When the custom field information of a single item is needed, the Entity API can be used to pull the custom field data for that specific item. A single event meeting, event, or section can be returned this way:
~api/entity/EventMeetingUserFields/byid/{eventMeetingId}
~api/entity/EventUserFields/byid/{eventId}
~api/entity/SectionUserFields/byid/{sectionId}
This will return both the title and the value associated for the specific item referenced in the call. When the value returned is a GUID, this means that the UserFieldListValues must be checked to return the name of the value selected.
Data model
The custom field data model can be challenging. There are multiple entities that tie together and may be used to get the association to the parent entity to the value that is displayed. The model representation below is the basic structure of the associations.
Custom Field Entities:
UserFieldOwner - Indicates the element with which the custom field is associated (Room, Building, Section, Event, etc.)
Fields: Id, TableName, DisplayName
UserFieldDefinition – The parent custom field information. Link between the owner and the value.
Fields: Id, Name, OwnerId, DisplayLabel, FieldTypeCode, ControlTypeCode, IsReqired, IsReadOnly
Common Filter: OwnerId.
UserFieldValue – The actual value saved into the custom field.
Fields: Id, RecordId, TableName, Value
Common Filter: UserFieldDefinitionId
UserFieldListValue – Values that can be found in the drop-down list custom fields. Must be pulled separately and used via lookup. ID in UserFieldValue is ID of the ListValue, but there is no direct entity association.
Fields: Id, UserFieldDefinitionId, Name, Value
Common Filter: ID
Connection Hierarchy
Comments
Please sign in to leave a comment.