Set Up SOCS Connector

Before setting up the SOCS Connector, make sure you have administrator access to Schoolbox and the connection details supplied for your school.

• The General Feed Host for calendar events, music lessons, and co-curricular activities.
• The Sports Fixture Feed Host for sports fixtures, teams, and results.
• Your SOCS Endpoint ID.
• Your SOCS Endpoint Token.

General feeds and sports fixture feeds can use different hosts.

Configure the shared SOCS credentials once, then enable the import types your school wants to use.

1. Go to Administration > Modules > SOCS Connector.
2. Turn on Enable SOCS Integration.
3. Enter the following details:
   • General Feed Host: for most schools, enter https://www.socscms.com/. This host is used for calendar events, music lessons, and co-curricular activities.
   • Sports Fixture Feed Host: for most schools, enter https://www.schoolssports.com/. This host is used for sports fixtures, teams, and results.
   • SOCS Endpoint ID: enter only your school's SOCS endpoint ID. This is usually a whole number, for example 1234.
   • SOCS Endpoint Token: enter only your school's SOCS endpoint token. This is usually a GUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
4. Select Save.

Do not enter a complete feed URL in any of these fields. Schoolbox combines the hosts, endpoint ID, and endpoint token to build the required SOCS feed URLs. Only use different host values if SOCS has supplied them for your school.

User matching

Sports, co-curricular activities and music lessons match participants using the user’s External ID in Schoolbox. Matching does not use names or email addresses.

• Sports: pupils and staff contain comma-separated participant IDs.
• Co-curricular: pupilid on register records and staff on event records.
• Music: pupilid for students and staffid for staff. The parser also accepts studentid for students.

These values must match the participant’s Schoolbox External ID. For the recommended setup, SOCS should supply the school’s SIS student/staff IDs in these fields, and Schoolbox should use those same IDs as users’ External IDs. Confirm this alignment with SOCS during setup. Schoolbox requires matching values but does not enforce which system originally issued them.

Unmatched sports and co-curricular participants are skipped when assigning team membership or coaches. Music lessons are visible only when the user whose calendar is being viewed matches the lesson’s student or staff member, including the corresponding student/staff role.

Enable calendar events if you want SOCS calendar items to appear as Schoolbox calendar events.

1. Turn on Import Calendar Events.
2. Enter a Calendar Event Feed Name.
3. Select a Default Calendar Category.
4. Select Save.

Campus-specific visibility

SOCS general calendar events support campus-specific visibility. Schoolbox matches the School or Schools values against Schoolbox campus names, not campus IDs.

Matching is exact and case-sensitive: Senior Campus matches Senior Campus, but senior campus does not. Leading and trailing spaces are trimmed from SOCS values before matching.

An event can specify multiple comma-separated campuses. It appears only when at least one matched campus belongs to the user whose calendar is being viewed. Events with missing or unmatched campus names are excluded; they do not automatically become whole-school events.

Refresh timing and date windows

General calendar events are retrieved on demand when calendar data is requested, with responses cached for 20 minutes. Schoolbox requests the date range being loaded in the calendar.

The 20-minute cache is not a background sync schedule. The next request after the cached response expires fetches fresh data. External calendar applications may have their own refresh schedules.

Enable sports fixtures if you want SOCS fixture data to appear in the Schoolbox Fixtures module.

1. Turn on Import Sports Fixtures.
2. Select Save.

Sports fixture, team, and result feeds use the Sports Fixture Feed Host with the shared SOCS endpoint ID and token.

Refresh timing and date windows

The scheduled importer runs every four hours, with an additional random delay of up to 30 minutes. Fixtures and results are requested for the previous 30 days and the next 100 days.

Team sheets are fetched separately. According to the SOCS restriction documented in the Schoolbox code, requests that include team sheets return only the previous seven days and the next seven days, regardless of the requested date range.

Enable co-curricular imports if you want SOCS clubs, events, and registrations to appear in the Schoolbox Fixtures module.

1. Turn on Import Co-Curricular.
2. Select Save.

Co-curricular feeds use the General Feed Host with the shared SOCS endpoint ID and token.

Refresh timing and date windows

Co-curricular activities use the same four-hour scheduled importer as sports fixtures, including an additional random delay of up to 30 minutes. Events are requested for the previous 30 days and the next 100 days. Registrations are then fetched for the event dates returned.

Enable music lessons if you want SOCS music lessons to appear in staff and student calendars.

1. Turn on Import Music Lessons.
2. Enter a Music Lesson Feed Name.
3. Select a Default Music Lesson Category.
4. Select Save.

Music lesson feeds use the General Feed Host with the shared SOCS endpoint ID and token. Lessons are linked to staff and students using external IDs from SOCS.

Refresh timing and date windows

Music lessons are retrieved on demand, with responses cached for 20 minutes. Schoolbox does not send a date window to SOCS for this feed. It retrieves the lessons SOCS returns and filters them locally to the requested calendar range. The available date coverage therefore depends on the SOCS response.

The 20-minute cache is not a background sync schedule. The next request after the cached response expires fetches fresh data. External calendar applications may have their own refresh schedules.

After saving the SOCS Connector settings, confirm that each enabled import appears in Schoolbox.

• Calendar events appear in the Schoolbox Calendar.
• Sports fixtures appear in the Fixtures module.
• Music lessons appear in matched staff and student calendars.
• Co-curricular clubs and events appear in the Fixtures module for matched pupils and staff.

The SOCS Connector page displays warnings when Schoolbox cannot map calendar events, when calendar or music feeds repeatedly fail, or when individual co-curricular records fail.

If enabled data does not appear:

1. Confirm that Enable SOCS Integration and the relevant import setting are turned on.
2. Check the appropriate feed host, SOCS endpoint ID, and SOCS endpoint token.
3. For calendar events, confirm that SOCS school names exactly match Schoolbox campus names.
4. For music lessons, sports fixtures, and co-curricular participants, confirm that SOCS staff and pupil IDs match Schoolbox user external IDs.
5. Confirm that the corresponding SOCS feed is available.

If a warning remains after correcting the settings or source data, contact Schoolbox Support and include the warning text.