© 2018 Capita Business Services Ltd. All rights reserved.

Capita Education Software Solutions is a trading name of Capita Business Services Ltd. Our Registered office is 30 Berners Street, London, W1T 3LR and our registered number is 02299747. Further information about Capita plc can be found in our legal statement.

SIMS Primary Enhanced API - Attendance Record

This API is obsolete

Please use the V3 Attendance APIs

We are delighted to provide the following update to partners with regard to SIMS Primary APIs for session attendance.

Access to these APIs for development purposes are subject to the terms and conditions of use .

Availability

Access to the APIs are only available for partners who have their own dedicated copies of SIMS Primary and the APIs described below can both read and write from/to the dedicated copy of SIMS.

Typically dedicated copies of SIMS Primary are provided under contract to SIMS Partners.

Enhanced APIs

Some of the enhanced APIs are designed for larger volumes of data, these include the attendance marks APIs. These enable the batching of ‘marks’ to be achieved so that one call saves say 30 marks for a class.

The read elements of these APIs are managed to return up to 1000 records at a time with a continuation link. In addition:

· Attendance is date limited so that ‘get marks’ will allow a maximum time span of 90 days.

Partners will need to make their algorithms speed sensitive. For example, asking for 90,000 attendance marks in one call would generate a need for 90 calls. (1000 at a time). Asking for all 90,000 at once may well be slower than asking for say 30,000 at a time (shorter date range) and may still require ~ 90 calls. It would also be worth asking the question ‘do you really need to download 90,000 marks?

Attendance Records Enhanced APIs’

The new APIs allow partners to read and write bulk data. They also implement a continuation facility within the request returning the first 1000 records and a URL for the next 1000. Bulk reads should use these services.

These are standard OData model calls.

 

 

Attendance Model Guidance

Please note that unlike SIMS 7, attendance marks are only recorded for ‘real attendances and real absences’, so for example:

· No marks are stored for holidays and weekends unless learners are required to attend.

· Leavers will not have any marks stored after they leave.

Partners may need to use the attendance definition calls in the sample API call document to obtain information about whether a Learner is expected to attend.

The example below shows the idea behind a report of attendance for a term might be generated.

It first considers how to establish that the school is open and students required to attend. This covers the pattern for attendance and then shows how an example student’s on roll’ness’ is overlaid. The example shows a sport’s academy where Wednesday afternoon lessons are replaced with lessons on Saturday morning.

Guest students are potentially edge cases and hence sessions where the school was open and a guest attenable sessions are shown as an exclamation mark. Product owners would need to specify what they want to show for guest attendance. Answers may vary depending on the purpose of the report.

Part-time students are also an edge case for coding. Formal attendance certificates may only apply to statutory school age pupils. Personal attendance may need to reflect ‘Attendance Mode’

Example calls are listed after the diagram and will help to fill in the gaps but much depends on what the partner system needs to know as to which calls will be most efficient for them.

Writing Attendance

The onus is on the supplying system to decide whether a mark should be written or not. For example, if John Doe 4A left on Friday and is still on the register then a mark could still be collected.

Validation rules to follow

Part time model extension to the above

 

Attendance Enhanced APIs (Contracted only)

 

 

Reading Attendance Records (GET)

  • Attendance Records read API end point:

https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords?$filter=AttendableEventStart gt {{date}} and AttendableEventStart lt {{date}}

· This endpoint must be called with the following filter conditions:

$filter=AttendableEventStart gt {{date}} and AttendableEventStart lt {{date}}

· Date range search cannot be greater than 90 days

  • Example:

https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords?$filter=AttendableEventStart gt 2018-05-01T00:00:00Z and AttendableEventStart lt 2018-05-16T00:00:00Z

  • Required request headers are:

Ocp-Apim-Subscription-Key:{{subscription_key}}

Authorization:bearer {{token}}

{{subscription_key}} – Subscription key from the Partner Portal

{{token}} – Access token received calling https://sts.sims.co.uk/connect/token with client credentials obtained from the Partner Portal

 

Attendance Records – Change Tracking (GET)

 

 

  • Attendance Records Change Tracking endpoint:

https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/ AttendanceRecords/ChangeTracking.GetChanges(startDate=@startDate,endDate=@endDate)?@startDate={{startDate}}&@endDate={{endDate}}

  • Example

https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords/ChangeTracking.GetChanges(startDate=@startDate,endDate=@endDate)?@startDate=2018-06-01T00:00:00Z&@endDate=2018-08-31T23:59:59Z

  • Required request headers are:

Ocp-Apim-Subscription-Key:{{subscription_key}}

Authorization:bearer {{token}}

 

 

 

Writing back a Batch of Attendance Records (POST)

  • Attendance record batch write back endpoint:

https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/$batch

  • Request headers required:

Ocp-Apim-Subscription-Key:{{subscription_key}}

Authorization:bearer {{token}}

Content-Type:multipart/mixed; boundary=batch_{{batch_id}}

{{batch_id}} – Unique identifier for the batch (a new guid). The batch id used in the request body should be included in the content type request header.

Please see the below example, {{batch_id}} = 5692664d-a5be-4bfe-ac5b-4c711026d780.

  • Request body (example):

Below example includes two attendance records: attendance mark for the learner: dc5dba32-f47b-4693-b970-409453539d36 for the attendable events 2f33782e-0177-43bb-a132-356a6d5b3cec and cd9eb549-ca39-4d31-9d5d-cbcd5858d28d.

Batch identifier should be included at the beginning of each record and the end of the batch. Changeset identifier beginning of each record of the changeset.

More than one changeset can be included in a batch.

A batch can be posted using more than one post.


--batch_5692664d-a5be-4bfe-ac5b-4c711026d780

Content-Type: multipart/mixed; boundary=changeset_cbbd877d-e393-4b7a-b4d2-b2b4e83b465a

--changeset_cbbd877d-e393-4b7a-b4d2-b2b4e83b465a

Content-Type: application/http

Content-Transfer-Encoding: binary

Content-ID: 1

POST https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords HTTP/1.1

Content-Type: application/json;odata.metadata=minimal

Prefer: return=representation

Accept: application/json;odata.metadata=minimal

Accept-Charset:UTF-8

{

"Learner": "dc5dba32-f47b-4693-b970-409453539d36",

"Present": true,

"Absent": false,

"AttendableEvent": "2f33782e-0177-43bb-a132-356a6d5b3cec",

"SchoolAttendanceCode": "c5ebbfcd-421e-4e8d-8a93-30e26a4fdad6",

"MinutesLate": null,

"Comment": "Test Comment Added by PS"

}

--batch_5692664d-a5be-4bfe-ac5b-4c711026d780

Content-Type: multipart/mixed; boundary=changeset_cbbd877d-e393-4b7a-b4d2-b2b4e83b465a

--changeset_cbbd877d-e393-4b7a-b4d2-b2b4e83b465a

Content-Type: application/http

Content-Transfer-Encoding: binary

Content-ID: 2

POST https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords HTTP/1.1

Content-Type: application/json;odata.metadata=minimal

Prefer: return=representation

Accept: application/json;odata.metadata=minimal

Accept-Charset:UTF-8

{

"Learner": "dc5dba32-f47b-4693-b970-409453539d36",

"Present": true,

"Absent": false,

"AttendableEvent": "cd9eb549-ca39-4d31-9d5d-cbcd5858d28d",

"SchoolAttendanceCode": "4d756a5c-0461-448e-9cbb-5ab0e0d3938d",

"MinutesLate": null,

"Comment": "Test Comment Added by PS"

}

--changeset_cbbd877d-e393-4b7a-b4d2-b2b4e83b465a--

--batch_5692664d-a5be-4bfe-ac5b-4c711026d780—

v Queries required for obtaining identifiers for attendable events and school attendance codes can be found at the end of this document.

  • Response

Response body will state whether the request was successful and the response status code(s). There will be a response including the status code for each record that was in the posted batch.

  • Response body (example):

 


--batchresponse_469ba124-efc9-4e85-b956-6ff1b4788793

Content-Type: multipart/mixed; boundary=changesetresponse_fbb5a699-be67-4e22-89f9-e8864244c06e

--changesetresponse_fbb5a699-be67-4e22-89f9-e8864244c06e

Content-Type: application/http

Content-Transfer-Encoding: binary

Content-ID: 1

HTTP/1.1 201 Created

Location: https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords(9472d0c5-78ec-4c10-9359-ec2b1d6ca820)

Content-Type: application/json; odata.metadata=minimal; charset=utf-8

OData-Version: 4.0

{

"@odata.context":"https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/$metadata#AttendanceRecords/$entity","ExternalID":"9472d0c5-78ec-4c10-9359-ec2b1d6ca820","Present":true,"Absent":false,"SchoolAttendanceCode":"c5ebbfcd-421e-4e8d-8a93-30e26a4fdad6","AttendanceHistorys":[

],"Learner":"dc5dba32-f47b-4693-b970-409453539d36","AttendableEvent":"2f33782e-0177-43bb-a132-356a6d5b3cec","MinutesLate":null,"Comment":"Test Comment Added by PS","RecordedBy":null,"RecordedOn":null,"ChangeProcessName":null,"AttendableEventStart":null

}

--changesetresponse_fbb5a699-be67-4e22-89f9-e8864244c06e--

--batchresponse_469ba124-efc9-4e85-b956-6ff1b4788793

Content-Type: multipart/mixed; boundary=changesetresponse_885c831d-23fa-4ec9-a65b-10015ad323d4

--changesetresponse_885c831d-23fa-4ec9-a65b-10015ad323d4

Content-Type: application/http

Content-Transfer-Encoding: binary

Content-ID: 2

HTTP/1.1 201 Created

Location: https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords(d6d8c03c-db04-4669-9560-afbe073cad06)

Content-Type: application/json; odata.metadata=minimal; charset=utf-8

OData-Version: 4.0{

"@odata.context":"https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/$metadata#AttendanceRecords/$entity","ExternalID":"d6d8c03c-db04-4669-9560-afbe073cad06","Present":true,"Absent":false,"SchoolAttendanceCode":"4d756a5c-0461-448e-9cbb-5ab0e0d3938d","AttendanceHistorys":[

],"Learner":"dc5dba32-f47b-4693-b970-409453539d36","AttendableEvent":"cd9eb549-ca39-4d31-9d5d-cbcd5858d28d","MinutesLate":null,"Comment":"Test Comment Added by PS","RecordedBy":null,"RecordedOn":null,"ChangeProcessName":null,"AttendableEventStart":null

}

--changesetresponse_885c831d-23fa-4ec9-a65b-10015ad323d4--

--batchresponse_469ba124-efc9-4e85-b956-6ff1b4788793—

Writing back a Single Record (POST)

 

  • Attendance Records write API end point:

https://pmapis.azure-api.net/sp-api-write-back-partner-live/V2/Attendance/AttendanceRecords

  • Request headers required:

Ocp-Apim-Subscription-Key:{{subscription_key}}

Authorization:bearer {{token}}

Content-Type:application/json

  • Request body (example):

{

"Learner": "dc5dba32-f47b-4693-b970-409453539d36",

"Present": true,

"Absent": false,

"AttendableEvent": "9abc15e2-4a58-4669-b20a-d7776d314b95",

"SchoolAttendanceCode": "c5ebbfcd-421e-4e8d-8a93-30e26a4fdad6",

"MinutesLate": null,

"Comment": "Test Comment Added by PS"

}

v Queries required for obtaining identifiers for attendable events and school attendance codes can be found at the end of this document.

  • Response:

If the request is successful, the response will be returned with status code ‘201 Created’. The response body will include the ExternalID of the attendance record.

  • Response body (example):

{

"ExternalID": "55848c98-f036-4178-ae92-1a7ed641512a",

"Present": true,

"Absent": false,

"SchoolAttendanceCode": "c5ebbfcd-421e-4e8d-8a93-30e26a4fdad6",

"AttendanceHistorys": [],

"Learner": "dc5dba32-f47b-4693-b970-409453539d36",

"AttendableEvent": "9abc15e2-4a58-4669-b20a-d7776d314b95",

"MinutesLate": null,

"Comment": "Test Comment Added by PS",

"RecordedBy": null,

"RecordedOn": null,

"ChangeProcessName": null,

"AttendableEventStart": null

}

 

Useful Attendance related OData Queries

 

Below queries are from the Standard APIs list, therefore the Standard API endpoint base URI should be prefixed to the below OData queries.

Contracted: https://pmapis.azure-api.net/sp-api-partner-live

(Freemium: https://pmapis.azure-api.net/sp-api-partner-dev )

· School term dates and school holidays:

/V2/School/Schools?$expand=Event($expand=AcademicYears($expand=SchoolTerms,SchoolHolidays))&$filter=Details/IsRegistered eq true and Event/AcademicYears/any(y:y/ExternalID eq {{academic_year_external_id}})

· Public holidays and school inset days:

/V2/School/Schools?$expand=Event($expand=AcademicYears($expand=PublicHolidays,InsetDays))&$filter=Details/IsRegistered eq true and Event/AcademicYears/any(y:y/ExternalID eq {{academic_year_external_id}})

· School’s working week pattern:

/V2/School/Schools?$expand=Event($expand=AcademicYears($expand=WorkingWeekPatterns($expand=WorkingWeekSession)))&$filter=Details/IsRegistered eq true and Event/AcademicYears/any(y:y/ExternalID eq eq {{academic_year_external_id}})

· Learners’ attendance modes:

/V2/Learner/Learners?$expand=Registration($expand=LearnerAttendanceModes($expand=AttendanceMode))

§ Attendance modes lookup:

/V2/Lookup/Learner/AttendanceModes

· Learners’ enrolment statuses:

/V2/Learner/Learners?$expand=Registration($expand=LearnerEnrolments($expand=MultipleLearnerEnrolmentStatus($expand=EnrolmentStatus)))

§ Enrolment statuses lookup:

/V2/Lookup/Learner/EnrolmentStatus

· Statutory attendance sessions – Attendable sessions:

/V2/Attendance/StatutoryAttendanceSessionAttendanceSessions

Example with filter:

V2/Attendance/StatutoryAttendanceSessionAttendanceSessions?$filter=StartDateTime gt 2017-09-01T00:00:00Z and StartDateTime lt 2018-08-31T00:00:00Z

· Exceptional Circumstances:
Ø Sessions - (working week sessions (3rd point - above) includes session definitions)

/V2/Attendance/ExceptionalCircumstances?$expand=StartSession,EndSession

Ø Type of the exceptional circumstances (whole school / selected pupils):

/V2/Attendance/ExceptionalCircumstances?$expand=ExceptionalCircumstanceType

Ø Learners the exceptional circumstance applicable to – example with a filter to retrieve the exceptional circumstances applicable to a list of ‘selected pupils’ only and the pupils it was applicable to:

/V2/Attendance/ExceptionalCircumstances?$expand=ExceptionalCircumstanceType,LearnerExceptionalCircumstances($expand=Learner)&$filter=ExceptionalCircumstanceType/ExternalID eq {{exceptional_circumstance_type_external_id_for_selected_pupils}}

§ Exceptional circumstance type definition:

/V2/Attendance/ExceptionalCircumstanceTypes

Ø Attendance code applied for the exceptional circumstance (# / Y):

/V2/Attendance/ExceptionalCircumstances?$expand=SchoolAttendanceCode

§ Attendance codes lookup:

/V2/Lookup/Attendance/SchoolAttendanceCodes

Assessment Results Enhanced APIs

These should be used for bulk read & write of assessment results. Please note the advice for bulk read for attendance above and please note that the same principle would apply here.

 

Additional Guidance - Attendable events

The only current attendanble event is a StatutoryAttendanceSessionAttendanceSessions

The API Defintion can be found here

{
  "IsDeleted": true,
  "ExternalID": "string",
  "StartDateTime": "2019-03-01T10:31:23.894Z",
  "EndDateTime": "2019-03-01T10:31:23.894Z",
  "IsInsetDay": true,
  "WorkingWeekSession": {
    "IsDeleted": true,
    "ExternalID": "string",
    "AttendanceSessions": [
      {}
    ]
  },
  "SchoolAdministrationDay": {
    "IsDeleted": true,
    "ExternalID": "string",
    "AttendanceSessions": [
      {}
    ]
  }
}

 

RESOURCES

Related resources for