PyJIIT Webportal Integration

Purpose and Scope

This document covers the PyJIIT webportal integration system, which provides programmatic access to the JIIT (Jaypee Institute of Information Technology) student webportal. The system implements a comprehensive client library for authentication, attendance tracking, grade retrieval, exam schedules, and other student-related data from https://webportal.jiit.ac.in:6011/StudentPortalAPI.

For information about how PyJIIT is used as an agent tool within the React Agent system, see Agent Tool System. For details on the PyJIIT router's role in the overall API architecture, see API Routers.

Sources: tools/pyjiit/wrapper.py1-646 routers/pyjiit.py1-93

System Architecture

The PyJIIT integration follows the standard three-tier architecture pattern: Router → Service → Tool. The router handles HTTP request/response, the service layer manages business logic and error handling, and the tool layer provides the low-level client implementation with encryption.

Sources: routers/pyjiit.py1-93 tools/pyjiit/wrapper.py1-646 tools/pyjiit/encryption.py1-60

API Endpoints

The PyJIIT router exposes three primary endpoints for webportal operations:

Login Endpoint

The login flow routers/pyjiit.py39-51 handles authentication by:

1. Accepting username and password via BasicAuthRequest
2. Fetching a captcha token (currently uses default captcha)
3. Performing two-step authentication with the JIIT API
4. Returning a WebportalSession object containing authentication tokens

Sources: routers/pyjiit.py12-51 tools/pyjiit/wrapper.py162-199

Semesters Endpoint

The /semesters endpoint routers/pyjiit.py54-72 initializes a Webportal session from the login response payload and retrieves the list of registered semesters. Each semester contains registration_id and registration_code fields required for subsequent operations.

Sources: routers/pyjiit.py54-72 tools/pyjiit/wrapper.py309-330

Attendance Endpoint

The /attendence endpoint routers/pyjiit.py75-92 (note the intentional spelling matching the user's requirement) retrieves attendance data for a specific semester. If no registration_code is provided, it defaults to the latest semester from attendance metadata.

Sources: routers/pyjiit.py75-92 tools/pyjiit/wrapper.py234-282

Authentication and Encryption

Payload Encryption

All API requests to the JIIT webportal require encrypted payloads using AES-256 in CBC mode. The encryption system generates daily-rotating keys based on the current date.

Encryption Details:

• Algorithm: AES-256-CBC
• Initialization Vector (IV): Fixed value dcek9wb8frty1pnm tools/pyjiit/encryption.py7
• Key Generation: "qa8y" + date_seq + "ty1pn" tools/pyjiit/encryption.py10-12
• Key Rotation: Daily at 0000 hrs IST
• Functions:
  • serialize_payload(payload: dict) -> str - Encrypts dict to base64 string tools/pyjiit/encryption.py48-53
  • deserialize_payload(payload: str) -> dict - Decrypts base64 string to dict tools/pyjiit/encryption.py40-45

Sources: tools/pyjiit/encryption.py1-60

HTTP Headers

Every request to the JIIT API requires two headers:

The LocalName header contains an encrypted random string combined with a date sequence, regenerated for each request.

Sources: tools/pyjiit/wrapper.py109-116 tools/pyjiit/encryption.py15-23

WebportalSession Model

The WebportalSession class tools/pyjiit/wrapper.py49-117 is a Pydantic model that encapsulates authentication state and session information.

Session Fields

Session Initialization

The WebportalSession constructor tools/pyjiit/wrapper.py70-107 performs the following operations:

1. Extracts institute information from regdata["institutelist"][0]
2. Parses the JWT-like token to extract expiration timestamp
3. Decodes the base64-encoded token payload (handling URL-safe encoding without padding)
4. Falls back to current time if token parsing fails

Sources: tools/pyjiit/wrapper.py49-117

Webportal Client

Core Class Structure

Sources: tools/pyjiit/wrapper.py119-646

Authentication Decorator

The @authenticated decorator tools/pyjiit/wrapper.py27-46 ensures that methods requiring authentication have a valid session:

1. Checks if self.session is not None (raises NotLoggedIn if missing)
2. Session expiry checks are commented out due to API bugs returning incorrect expiry times
3. Wraps any method that requires authenticated access

Sources: tools/pyjiit/wrapper.py27-46

Private HTTP Method

The __hit() method tools/pyjiit/wrapper.py131-160 is the central HTTP request handler:

Features:

• Accepts custom exception types via exception kwarg (defaults to APIError)
• Automatically adds authentication headers when authenticated=True
• Generates LocalName header for all requests
• Validates response status and raises appropriate exceptions:
  • SessionExpired when status code is 401
  • Custom exception when responseStatus != "Success"

Sources: tools/pyjiit/wrapper.py131-160

Attendance System

The attendance retrieval system involves multiple steps and data models:

Attendance Methods

Data Models

AttendanceHeader: Contains stynumber field required for attendance queries tools/pyjiit/wrapper.py15

Semester: Contains registration_id and registration_code fields required for semester-specific queries tools/pyjiit/wrapper.py15

AttendanceMeta: Aggregates attendance headers and semester information tools/pyjiit/wrapper.py15

Sources: tools/pyjiit/wrapper.py233-330 tools/pyjiit/attendance.py (imported at line 15)

Academic Records

The webportal client provides comprehensive access to academic records:

Examination System

Exam Methods:

Sources: tools/pyjiit/wrapper.py357-433

Grades and Marks

Methods for Grade Retrieval:

The download_marks() method tools/pyjiit/wrapper.py458-479 returns raw PDF bytes, while other methods return structured dictionaries.

Sources: tools/pyjiit/wrapper.py435-577

Additional Functionality

Registration and Subject Management

Sources: tools/pyjiit/wrapper.py332-355 tools/pyjiit/wrapper.py623-645

Financial Information

Note: The get_fines_msc_charges() method returns an API error "NO APPROVED REQUEST FOUND" when there are no pending payments tools/pyjiit/wrapper.py583-586

Sources: tools/pyjiit/wrapper.py212-231 tools/pyjiit/wrapper.py579-621

Account Management

The set_password() method tools/pyjiit/wrapper.py284-306 allows password changes:

# Changes student password
# Requires: old_pswd, new_pswd
# Endpoint: /clxuser/changepassword
# Exception: AccountAPIError

Sources: tools/pyjiit/wrapper.py284-306

Exception Hierarchy

The system defines custom exceptions for error handling:

Sources: tools/pyjiit/wrapper.py8-14

Integration with Agent System

The PyJIIT client is exposed as an agent tool pyjiit_agent within the React Agent system. The tool requires a pyjiit_login_response context parameter containing the WebportalSession data obtained from the /login endpoint.

For details on how the PyJIIT tool is constructed and used within the agent workflow, see Agent Tool System and Dynamic Tool Construction and Context Management.

Sources: Referenced from high-level architecture diagrams