Skip to main content

Standard Batch APIs: Details

Emily Yeomans

Each Batch API targets a specific functional area within the product. Some examples include: 

  • committee (to load/update Committees)
  • doctoral-researcher (to load/update GEM research projects)
  • historical-suspensions (to migrate GEM suspension history)

Let’s use the doctoral-researcher Batch API as an example since this is typically used in integrations to regularly (e.g. daily or hourly) update student projects.

Example: Doctoral Researcher

On page “Standard Batch APIs”, select doctoral-researcher and you will see:

  • A New import button which allows you to import project data (as JSON) via the UI
    • For one-off imports it can be useful to just load them in the UI
    • For regular imports (e.g. daily delta updates) we strongly recommend using the API
  • The control file 
    • This is what dictates internal mapping for the fields you submit
    • You can ignore this, Cayuse will provide you with the JSON template for all Batch APIs

  • A View mappings button

    • Here, you can edit the mappings to suit your needs
    • For example, if you want the data file (JSON) value for the Project Mode “Full Time” to be “FT” and “Part Time” to be “PT”, you would set the mapping as below:

In the remaining sections on this page you will find details about each Standard Batch API.

COMMITTEES

  • Kind: committees
  • Purpose: Supplementary feed for creating & updating Committee records and setting key committee roles.
  • Notes: Can be used by both GEM and Ethics Monitor.

Note: If only a small number of committees are required, it would be quicker to set these up manually.

EXAMPLE DATA FILE:

[{
   "CommitteeCode": "Must be unique for future updates. E.g. MED-RDC.",
   "CommitteeTitle": "Free text",
   "CommitteeUnitPrimaryCodes": ["Primary code set in Cayuse Admin"],
   "CommitteeType": "As per committee mappings table",
   "CommitteeRepresentatives": [
       { "username": "Username in Cayuse Admin" }
   ],
   "CommitteeChairs": [
       { "username": "Username in Cayuse Admin" }
   ],
   "CommitteeDeputyChairs": [
    { "username": "Username in Cayuse Admin" }
   ],
   "CommitteeMembers": [
       { "username": "Username in Cayuse Admin" },
       { "username": "Username in Cayuse Admin" }
   ]
}]

FIELDS:

  • CommitteeCode - used to uniquely identify committee records - if not found the committee record will be created; if found, the existing record will be updated. That means the data file can be rerun with additional committee members, updated title etc. if required.
  • CommitteeRepresentatives and other user roles should be provided as a list of records with usernames.
  • CommitteeUnitPrimaryCode should be the Primary Org Codes for the relevant unit as set in Admin (or alternatively: a list of CommitteeUnitPrimaryCodes: ["847","891"] if a single committee covers multiple departments - note the 's' if providing a list. You can send a list with one entry, so possibly easier to just use CommitteeUnitPrimaryCodes across the board).
  • CommitteeType type mappings are set up in-system - the type used for each record should match how the approvers for the relevant workflows have been configured. Current committee types available:
    • Research Degrees Committee (catch-all - all types, all processes)
    • Doctoral Sub-Committee (Doctoral types, all processes)
    • Prof Doc Sub-Committee (Prof Doc types, all processes)
    • Master’s Sub-Committee (Masters types, all processes)
    • Academic Progress Committee (all types, AP)
    • Candidature Management Committee (all types, CM)
    • Examinations Committee (all types, Exams)
    • (if Ethics installed: Ethics Committee, Ethics Animal Committee, Ethics Human Tissue Committee)

NOTES:

  • To create a record, minimum required fields:
    • CommitteeCode, CommitteeTitle, CommitteeType
    • To make the record usable in workflows, at least one CommitteeUnitPrimaryCode and at least one username in CommitteeRepresentatives should also be provided.
  • To update a record, minimum required fields:
    • CommitteeCode to find the record, then the field(s) to update (field will be overwritten with provided value(s), all other fields will be unchanged).

PROJECT AND MILESTONE END DATES

  • Kind: project-end-dates
  • Purpose: One-off feed for importing historic project date deadlines and completion dates.

EXAMPLE DATA FILE:

[{
   "Username": "Username in Cayuse Admin",
   "MilestoneName": "As per project-end-dates mappings table",
   "Deadline": "YYYY-MM-DD",
   "Actual": "YYYY-MM-DD"
}]

FIELDS:

  • Username - used to locate the relevant student’s project.
  • MilestoneName selects the project date to update. Mappings are set up in-system - the identifier for each imported milestone should be added to the mappings table.
  • Deadline sets the deadline for the selected project date - as a fixed deadline, it will no longer automatically recalculate.
  • Actual sets the completion date for the selected project date.

NOTES:

  • Although the API description is ‘project-end-dates’, this can be used for importing deadlines/completion dates for all project dates.
  • Username and MilestoneName are required for each record, then the value to set - Deadline, Actual or both.
  • NB! This API doesn’t support previous completion dates (e.g. importing all the previous completions for a recurring AP deadline).
  • This feed can be re-run - new values will overwrite previously imported values. Imported values can’t be removed through the API, only overwritten.

HISTORICAL EXTENSIONS

  • Kind: historical-extensions
  • Purpose: One-off feed for importing historical extensions.

EXAMPLE DATA FILE:

[{
   "Username": "Username in Cayuse Admin",
   "StartDate": "YYYY-MM-DD",
   "EndDate": "YYYY-MM-DD"
}]

FIELDS:

  • Username - used to locate the relevant student’s project.
  • StartDate sets the extension start date.
  • EndDate sets the extension end date.

NOTES:

  • All fields are required for each record.
  • StartDate should match the previous project end date to be included in date calculations.
  • Each extension can only be imported once! Re-running the file will duplicate the extension in the project history rather than updating the previously imported extension.

HISTORICAL SUSPENSIONS

  • Kind: historical-suspensions
  • Purpose: One-off feed for importing historical suspensions.

EXAMPLE DATA FILE:

[{
   "Username": "Username in Cayuse Admin",
   "StartDate": "YYYY-MM-DD",
   "EndDate": "YYYY-MM-DD"
}]

FIELDS:

  • Username - used to locate the relevant student’s project.
  • StartDate sets the suspension start date.
  • EndDate sets the suspension end date.

NOTES:

  • All fields are required for each record.
  • Each suspension can only be imported once! Re-running the file will duplicate the suspension in the project history rather than updating the previously imported suspension. 

HISTORICAL CHANGES OF MODE

  • Kind: historical-changes-of-mode
  • Purpose: One-off feed for importing historical changes of mode (e.g. FT, PT).

EXAMPLE DATA FILE:

[{
   "Username": "Username in Cayuse Admin",
   "DateOfChange": "YYYY-MM-DD",
   "PreviousMode": "As per historical-changes-of-mode mappings table”,
   "NewMode": "As per historical-changes-of-mode mappings table"
}]

FIELDS:

  • Username - used to locate the relevant student’s project.
  • DateOfChange sets the date the change takes effect.
  • PreviousMode records the mode before the change.
  • NewMode records the mode after the change.

NOTES:

  • All fields are required for each record.
  • PreviousMode / NewMode mappings are set up in-system - the identifier for each should be added to the mappings table.
  • Each mode change can only be imported once! Re-running the file will duplicate the mode change in the project history rather than updating the previously imported mode change.

SUPERVISORS

  • Kind: supervisors
  • Purpose: Feed for importing supervisor registration status for staff.

EXAMPLE DATA FILE:

[{
   "Username": "Username in Cayuse Admin",
   "SupervisionStatus": "As per supervisors mappings table",
   "SupervisionCategory": "As per supervisors mappings table",
   "SupervisorTraining": "YYYY-MM-DD",
   "ChairTraining": "YYYY-MM-DD"
}]

FIELDS:

  • Username - used to locate the relevant supervisor record
  • SupervisionStatus mappings are set up in-system - the identifier for each status (Registered, Not Registered, etc.) should be added to the mappings table.
  • SupervisionCategory mappings are set up in-system - the identifier for each category (Junior, Senior, etc.) should be added to the mappings table.
  • SupervisorTraining sets the date of the training.
  • ChairTraining sets the date of the training.

NOTES:

  • Username and SupervisionStatus are required for each record.
  • SupervisionCategory, SupervisorTraining and ChairTraining only relevant if set up in-system for customer (as per customer’s requirement).

DOCTORAL RESEARCHERS

  • Kind: doctoral-researcher
  • Purpose: Main GEM supplementary feed for migrating, creating and updating project information. The structure/content of this file will vary between customers, as well as between the very first load (think: migration/seeding the database) and subsequent regular syncs. 
    • Regular syncs support deltas (i.e. only POST projects with changes) and can be run at any time (e.g. near real-time) or nightly.

EXAMPLE DATA FILE:

[{
   "username": "Username in Cayuse Admin",
   "projectTitle": "Title to be confirmed",
   "projectMode": "As per doctoral-researcher mappings table",
   "projectType": "As per doctoral-researcher mappings table",
   "projectStage": "As per doctoral-researcher mappings table",
   "projectStatus": "As per doctoral-researcher mappings table",
   "projectFeeStatus": "As per doctoral-researcher mappings table",
   "projectVisaType": "As per doctoral-researcher mappings table",
   "projectVisaEndDate": "YYYY-MM-DD",
   "projectStartDate": "YYYY-MM-DD",
   "projectStudyLocation": "As per doctoral-researcher mappings table",
   "projectCourseTitle": "Free text",
   "projectCourseCode": "Free text",
   "projectAdvisor": "Username in Cayuse Admin",
   "projectMentor": "Username in Cayuse Admin",
   "projectSupervisors": [
       {
           "username":"Username in Cayuse Admin",
           "role": "As per doctoral-researcher mappings table"
       }
   ],
   "courses": [
       {
           "courseName":"Free text",
           "courseCode": "Free text",
           "courseStatus": "Free text",
           "courseOutcome": "Free text",
           "courseCredits": "Free text",
           "additionalFields": "Free text"
       }
   ],
   "scholarships": [
       {
           "scholarshipName":"Free text",
           "scholarshipStartDate": "YYYY-MM-DD",
           "scholarshipEndDate": "YYYY-MM-DD",
           "scholarshipType": "Free text",
           "additionalFields": "Free text"
       }
   ]
}]

NOTES:

  • To create a project, minimum required fields:
    • username, projectTitle, projectMode, projectType, projectStartDate, projectSupervisors
    • Preferably the initial load should also provide the initial values for fields such as projectStage, projectStatus, etc. that will be controlled inside GEM after the data load
  • To update a project, minimum required fields:
    • username to find the record, then the field(s) to update (field will be overwritten with provided value(s), all other fields will be unchanged)
  • courses - list of individual course objects. Each course should include:
    • courseName
    • courseCode
    • courseStatus
    • courseOutcome
    • courseCredit
    • additionalFields
  • scholarships - list of individual scholarship objects. Each scholarship should include:
    • scholarshipName
    • scholarshipStartDate
    • scholarshipEndDate
    • scholarshipType
    • additionalFields
  • Usage:
    • The current default is that the feed should include all records, and if records are omitted then that’s taken as the signal to mark the project ‘Past’.
    • Alternatively, disable default by enabling delta updates so only new projects/projects to be updated need to be included - with this enabled, projects become Past when the user account is disabled (so student inactive in Admin → student profile inactive in GEM → student project inactive in GEM).

Related to

Related articles