API Overview

Ad Astra provides an API for customers and third-parties to interface with the Astra Schedule products. The API uses open standards and can be accessed by any toolset or language (.NET, Java, Python/Ruby, etc.).

The API is fairly small but powerful.  The two primary API calls are the Entity and Query API.  With those two API calls, you can get to just about any data you want in the system.  The API can query all entities and relationships in the Ad Astra Database and perform complex searches. Further, there is a transaction API for updating data in the Ad Astra Database.

The Ad Astra API is best described as a RESTful web service1, using standard HTTP2 or HTTPS3. What this means in practice is that data contained in the Ad Astra Database can be queried using simple web requests. For example, http://schedule.xyz.edu/~api/entities/event/byid/... would request data for an event given its unique ID. This concept extends to data relationships as well as searches. Further, searches can be filtered using arbitrary expressions against any number of fields, sorted by multiple fields, and broken into conveniently sized pages.

For efficiency and convenience for Web 2.0 applications, the data returned by the Ad Astra API is encoded using the JSON4 data format (described by RFC 46275). The http://json.org web site has links to dozens of open source and free libraries that can be used to easily decode JSON data in almost any language.

SAML Entity Metadata

An “entity” in the Ad Astra Database is basically a row in a table, though not all tables are entity tables. All entities have certain fields in common:

• Id: unique identifier of the entity (a GUID6).
• CreateDate: datetime stamp set when the entity (row) was created.
• CreateBy: Id of the User that created the entity.
• ModifiedDate: datetime stamp of the last modification of the entity.
• ModifiedBy: Id of the User that last modified the entity.
• RowVersion: internal number used for transaction management.

Beyond these fields, many entities have a Name, but the other fields vary by table. The most concise, programmatic description available to describe an entity in Ad Astra is found in JavaScript format in the web application. These files are used by the Web UI to properly decode, validate, format, and parse data for an entity. The location (relative to the virtual directory) for these files is:

/javascript/astra/entities

For example, the /javascript/astra/entities/Section.js file contains a description of the Section entity.

The data comes into play when accessing the Ad Astra API via the Query and Entity API’s.

Fields

The most primitive information is the field description object. This information is equivalent to the table columns (more or less) found in the Ad Astra Database. For example, the Section entity contains these fields:

fields:

{

    Id: { type:'string' },

    TermId: { type:'string' },

    CampusId: { type:'string' },

    CourseDeliveryMethodId: { type:'string' },

    SectionTitle: { type:'string' },

    SectionCode: { type:'string' },

    DoNotOptimize: { type:'boolean' },

    DoNotOptimizeInstructor: { type:'boolean' },

    DoNotOptimizeTime: { type:'boolean' },

    CourseTitleId: { type:'string' },

    IsCanceled: { type:'boolean' },

    SISEnrollment: { type:'int' },

    SISMaxEnrollment: { type:'int' },

    AdjustedMaxEnrollment: { type:'int' },

    CalculatedSeats: { type:'int' },

    EstimatedEnrollment: { type:'int' },

    CensusEnrollment: { type:'int' },

    CensusEnrollmentDate: { type:'date' },

    CensusEnrollment2: { type:'int' },

    CensusEnrollmentDate2: { type:'date' },

    IsPreReq: { type:'boolean' },

    IsGradeable: { type:'boolean' },

    EnrollmentWaiting: { type:'int' },

    WaitingAvailCount: { type:'int' },

    WaitingCapacity: { type:'int' },

    IsLinkParent: { type:'boolean' },

    IgnoreInAnalysis: { type:'boolean' },

    ContainsCrossList: { type:'boolean' },

    SISCrossEnrlError: { type:'boolean' },

    LinkedSectionId: { type:'string' },

    SisKey: { type:'string' },

    LastSisUpdateDate: { type:'date' },

    LastImportedDate: { type:'date' },

    LastExportedDate: { type:'date' },

    RequiresAttention: { type:'boolean' },

    RequiresAttentionReason: { type:'string' },

    IsActive: { type:'boolean' },

    CreatedDate: { type:'date' },

    CreatedBy: { type:'string' },

    ModifiedDate: { type:'date' },

    ModifiedBy: { type:'string' },

    RowVersion: { type:'int' }

}, 

Associations (joins)

Beyond simple fields, the Ad Astra Database defines associations between entities and describes these associations in the same file. These are contained in a “join” portion of the metadata. For example, a Room has some of each kind of association:

join :
{
 // one-to-one association (set)
 Building : { field:"BuildingId", type:"Building" },
 HvacZone : { field:"HvacZoneId", type:"HvacZone" },
 RoomType : { field:"RoomTypeId", type:"RoomType" },
 WorkflowDefinition : { field:"WorkflowDefinitionId",
type:"WorkflowDefinition" },
 // one-to-many association (edit)
 OptimizerSctMtgSuitRms : { type: "OptimizerSctMtgSuitRm",
isOwner: false, fkField: "RoomId", fkNullable: false},
 PrefRuleRoomItems : { type: "PrefRuleRoomItem",
isOwner: true, fkField: "RoomId", fkNullable: false},
 RoomConfigurations : { type: "RoomConfiguration",
isOwner: true, fkField: "RoomId", fkNullable: false},
 RoomConflictsByConflictRoomId : { type: "RoomConflict",
isOwner: true, fkField: "ConflictRoomId", fkNullable: false},
 RoomConflicts : { type: "RoomConflict", isOwner: true,
fkField: "RoomId", fkNullable: false},
 RoomFeatureQuantities : { type: "RoomFeatureQuantity",
isOwner: true, fkField: "RoomId", fkNullable: false},
 NotesByRecordId : { type: "Note", isOwner: true,
fkField: "RecordId", fkNullable: false,
fkTypeField: "NoteTypeId",
fkTypeValue: "ad950a8d-046b-4d25-b079-5845a0f5530a"},
 RoomPartitionsByPartitionRoomId : { type: "RoomPartition",
isOwner: true, fkField: "PartitionRoomId",
fkNullable: false},
 RoomPartitions : { type: "RoomPartition", isOwner: true,
fkField: "RoomId", fkNullable: false},
 ProfileItemsByDataValueId : { type: "ProfileItem", isOwner: true,
fkField: "DataValueId", fkNullable: false,
fkTypeField: "ValueDataTypeId",
fkTypeValue: "759385fd-0d7c-4f3f-95d2-2f6757cb5606"},
 TimetableSctMtgSuitRms : { type: "TimetableSctMtgSuitRm",
isOwner: false, fkField: "RoomId", fkNullable: false},
 // many-to-many association (add/remove)
 Regions : { relation: "RoomRegion", role: "RoomId",
type:"Region" },
 AdHocRequestSettings : { relation: "AdHocRequestSttngRoom",
role: "AdHocRequestSettingId", type:"AdHocRequestSetting" }
}

One-to-One

The simplest form of association is an entity that contains the ID of another. The properties for this type of association are as follows:

• Field: name of the field that contains the ID value.
• Type: type of entity to which this ID refers.

One-to-Many

These entries describe other entities that contain an ID value related to this type.

• Type: type of the entity that contains an ID relating to this type.
• isOwner: true if this entity owns the entities that contain its ID. Such entities are deleted when the owning entity is deleted.
• fkField: field in the related entity that contains the ID.
• fkNullable: true if the fkField in the related entity should be set to null when the related entity is deleted.
• fkTypeField: If present, this is the name of a field in the relating entity that contains a discriminating value that specifies the type to which it is related. For example, a Note can reference many different entity types. Which type a particular Note reference is stored in its NoteTypeId field, so this property would contain “NoteTypeId” to describe this.
• fkTypeValue: this goes along with fkTypeField and is the value used to specify this type of entity. For example, the GUID “ad950a8d-046b-4d25-b079-5845a0f5530a” is stored in the NoteTypeId field of a Note to indicate that a Note references a Room.

Many-to-Many

To describe entities that relate in a many-to-many arrangement, the descriptor contains the following properties:

• Type: type of entity related to this type.
• Relation: name of the many-to-many association.
• Role: field name of this entity type in the association.

This type of association is often called a matrix association and the table containing the ID pairs is called a matrix table.

Ad Astra API Terms of Service Agreement