SIS Integration

Connect your InstinctHub Student Information System (SIS) to Leadboard CRM so that student lifecycle events -- registration, course enrollment, grades, graduation -- automatically create and update leads with academic data.

Overview#

The SIS integration follows the same pattern as the Admission Integration but tracks a different lifecycle:

1. Student registration -- When a student record is created in the SIS (usually after admission approval)
2. Academic progress -- Course registrations, grade postings, and credit accumulation
3. Status changes -- Graduation, suspension, transfer

Like admission, the SIS integration auto-creates leads if they don't exist and assigns them to a "Students" group.

Supported Events#

Custom Fields Created#

Step 1: Connect from SIS Admin#

The SIS connection is initiated from the SIS admin panel (sis-admin-ft), which is a separate app from the LMS admin.

1. Log into the SIS admin panel

2. Go to Finance > Settings (from the sidebar)

3. Click the Integrations tab

4. Find the Leadboard CRM -- Student Records card (indigo-colored)

5. Click Connect to Leadboard CRM

6. A popup opens to Leadboard CRM. Log in if prompted.

7. Select the CRM company you want to connect to

8. Click Approve

9. The popup closes automatically. The card now shows Connected with your company name and event stats.

Note: The SIS admin is a separate Next.js application from the LMS admin (creators_nextjs). It runs on its own port and has its own environment variables.

Step 2: Enable SIS Integration in the CRM#

1. Go to /default/integrations/sis

2. Toggle SIS Integration to enabled

3. Default scoring rules are created automatically

4. A "Students" group is created for your company

5. Custom fields are auto-created (see table above)

Step 3: Configure Scoring Rules#

1. Go to /default/integrations/sis

2. In the Scoring Rules table, edit the Points value for any event type

3. Toggle individual rules on/off with the Active switch

4. Click Save Scoring

How Scoring Works#

• Points are added to sis_score in the lead's custom fields
• The enrollment_status field is automatically updated based on the event type:
  • STUDENT_REGISTERED -> "Registered"
  • COURSE_REGISTERED / GRADE_POSTED -> "Active"
  • GRADUATION -> "Graduated"
  • SUSPENSION -> "Suspended"
  • TRANSFER -> "Transferred"
• When a GRADE_POSTED event includes credit units, the credits_completed field is incremented

Step 4: Fetch Existing Records (Optional)#

Pull in existing student records from InstinctHub SIS as leads.

1. Go to /default/integrations/sis

2. Click Fetch Existing Records

3. Provide the InstinctHub host, channel username, and API key

4. Click Start Sync

5. Each student record creates a STUDENT_REGISTERED event and processes through the pipeline

Note: Existing records are matched by email + matric_number to avoid duplicates.

View Events#

1. Go to /default/integrations/sis

2. The Event Log shows: email, event type, student ID, course name, score applied, status, and timestamp

3. Use the search bar to filter by email

Stats Cards#

• Total Events -- All SIS events received
• Processed -- Events that have been scored
• Unprocessed -- Events waiting for processing
• Total Score Applied -- Sum of all points applied

How Events Flow (Technical)#

Signal-to-CRM Pipeline#

On InstinctHub SIS (sender side):

1. StudentRecord is created or its status changes (e.g., graduated, suspended)
2. Django post_save signal fires
3. transaction.on_commit() schedules Celery task
4. send_sis_event_to_crm task looks up SISConnection for the channel
5. If connected, POSTs event to Leadboard's ingestion endpoint

On Leadboard CRM (receiver side):

6. POST /api/v1/integrations/default/third-party/sis/events/ receives the event
7. SISEvent record is created in the database
8. process_sis_event Celery task is dispatched
9. Task finds (or creates) a lead by email
10. Lead is added to the "Students" group
11. Lead's custom_fields are updated (student_id, enrollment_status, GPA, credits)
12. Scoring rules are applied
13. lead.score_changed webhook is emitted
14. SCORE_THRESHOLD workflow rules are evaluated

Status-to-Event Mapping#

Event Payload Formats#

STUDENT_REGISTERED:

{
  "event_type": "STUDENT_REGISTERED",
  "email": "student@example.com",
  "student_id": "MAT/2025/001",
  "metadata": {
    "level": "100",
    "programme": "Computer Science",
    "status": "ACTIVE",
    "first_name": "John",
    "last_name": "Doe"
  }
}

GRADE_POSTED:

{
  "event_type": "GRADE_POSTED",
  "email": "student@example.com",
  "student_id": "MAT/2025/001",
  "course_code": "CSC101",
  "course_name": "Introduction to Computer Science",
  "grade": "A",
  "credits": 3,
  "metadata": {
    "points": "5.0",
    "level": "100",
    "semester": "1"
  }
}

API Endpoints#

Third-party event ingestion (API key auth):

Required scope: sis.events

Dashboard endpoints (JWT auth, admin only):

OAuth endpoints:

Generate OAuth Credentials#

Before configuring environment variables, you need to generate the OAuth client ID and secret. This is done once on the Leadboard CRM server.

Step 1. SSH into your Leadboard API server (or use your local dev environment)

Step 2. Run the management command:

python manage.py create_oauth_apps --type sis

Step 3. The command outputs the credentials:

Created: InstinctHub SIS
  Client ID:     9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b
  Client Secret:  f0e1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a7f8e9d0c1b2a3f4e5d6c7b8a9f0e1
  Redirect URIs: http://localhost:3001/api/integrations/leadboard-sis/callback
  Scope:         sis.events

Step 4. Copy the Client ID and Client Secret values -- you will need them for the environment variables below.

Important: The Client Secret is only shown once during creation. If you lose it, you will need to delete and recreate the OAuth application.

Note: To create both Admission and SIS OAuth apps at once, run python manage.py create_oauth_apps (without --type).

Environment Variables#

Using the Client ID and Client Secret from the step above, configure the following environment variables:

SIS admin (sis-admin-ft .env.local):

# The URL where your Leadboard CRM frontend is hosted
NEXT_PUBLIC_LEADBOARD_CRM_HOST=https://crm.yourcompany.com

# Client ID from the create_oauth_apps command output
NEXT_PUBLIC_LEADBOARD_SIS_OAUTH_CLIENT_ID=9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b

# The callback URL — must match the Redirect URI registered in the OAuth app
# For local dev: http://localhost:3001/api/integrations/leadboard-sis/callback
NEXT_PUBLIC_LEADBOARD_SIS_OAUTH_REDIRECT_URI=https://sis-admin.instincthub.com/api/integrations/leadboard-sis/callback

InstinctHub API (instincthub_apis .env):

# The URL where your Leadboard CRM API is hosted (include trailing slash)
LEADBOARD_API_HOST=https://crm-api.yourcompany.com/

# Client ID and Secret from the create_oauth_apps command output
LEADBOARD_SIS_CLIENT_ID=9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b
LEADBOARD_SIS_CLIENT_SECRET=f0e1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a7f8e9d0c1b2a3f4e5d6c7b8a9f0e1

# Must match the Redirect URI above
LEADBOARD_SIS_REDIRECT_URI=https://sis-admin.instincthub.com/api/integrations/leadboard-sis/callback

Local development: Replace the production URLs with your local ones (e.g., http://localhost:3000 for CRM host, http://127.0.0.1:8080/ for API host, http://localhost:3001/api/integrations/leadboard-sis/callback for the redirect URI). Note the SIS admin typically runs on port 3001, different from the LMS admin on 8008.

Celery Tasks Required#

InstinctHub: send_sis_event_to_crm (in channels/sis_tasks.py)

Leadboard: process_sis_event (in integrations/tasks.py)

Database Models#

InstinctHub: SISConnection (in channels/models.py)

Leadboard: SISEvent, SISScoringConfig (in integrations/models.py)

Disconnect#

From SIS Admin#

1. Go to Finance > Settings > Integrations in SIS admin
2. Click Disconnect on the Leadboard CRM card

From Leadboard#

1. Go to /default/integrations/api-keys
2. Revoke the key named "InstinctHub SIS: {channel}"

Troubleshooting#

Events not appearing#

1. Verify the SIS connection is active in SIS admin settings
2. Verify SIS integration is enabled in the CRM: /default/integrations/sis
3. Check Celery workers on both systems
4. The SIS admin uses different env vars than the LMS admin -- verify LEADBOARD_SIS_CLIENT_ID etc.

Student not showing as lead#

• The student must have a valid email in their InstinctHub user profile
• Check the "Students" group in your CRM for the lead
• Check the lead's lead_source field -- it should show "SIS" for auto-created leads

GPA / credits not updating#

• current_gpa is updated from the metadata.points field of GRADE_POSTED events
• credits_completed is accumulated from the credits field of GRADE_POSTED events
• If the InstinctHub SIS doesn't send grade events yet, these fields remain empty (COURSE_REGISTERED and GRADE_POSTED signals for sis_academic will be added in a future update)

Connection popup doesn't work#

• You must be logged into Leadboard CRM in the same browser
• The SIS admin runs on a different port than the LMS admin -- verify NEXT_PUBLIC_LEADBOARD_SIS_OAUTH_REDIRECT_URI matches the SIS admin URL
• Verify NEXT_PUBLIC_LEADBOARD_CRM_HOST is set in the SIS admin .env.local

Related#

• Admission Integration -- Connect admission events (application -> acceptance)
• LMS Integration -- Connect learning events for course-based scoring
• Automation -- Create workflows triggered by SIS score thresholds
• Leads Management -- View lead scores, custom fields, and groups