Skip to content

VSU Data Gateway Setup Guide

This guide enables the VSU Data Gateway connector, which lets a Virginia State University student ask the chat about their own records: profile and GPA, advisors, appointments, courses and posted grades, current Canvas scores and grades, degree progress, checklist items, holds and alerts, account charges, payments and campus card balances, financial aid awards and disbursements, and housing.

The connector is specific to VSU, so only VSU's environments carry it, and it ships dormant there until an operator turns it on. It reads from VSU's gateway API, a service VSU runs inside its own VPC, with one institution-wide key that VSU issues. CampusCore decides who may read whom: a person reads their own records only, named by the V-number on their profile.

Prerequisites

  • The deployment's environment listed under [institutions.vsu] in campuscore_app/institutions.toml. The image build deletes the connector from every other environment's images, so on an environment the file does not list there is no connector to set up.
  • A network path from the CampusCore deployment's VPC to the gateway. The gateway is reachable only inside VSU's network, so this is AWS PrivateLink: an endpoint service in VSU's VPC in front of the gateway, an interface endpoint in ours, and a private hosted zone so the gateway's name resolves to that endpoint. Those resources are built by hand and are not in Terraform; the per-client provisioning strategy decides how they are codified.
  • The gateway's address as reached from our VPC, such as https://datagw-test.vsu.edu, and the key VSU issued.
  • Single sign-on configured so that each student's V-number lands on UserProfile.external_id. The SSO provider's "external id" claim is the one that carries it (Configuring SSO Roles covers the provider record).
  • Access to the Django admin and to Settings -> Workspace Connectors.

Step 1: Make the connector available

The boot sequence's catalog sync creates the VSU Data Gateway row on the first start of an image that carries the connector, with Is available off.

  1. Sign in to the Django admin as an operator.
  2. Open Connectors and the VSU Data Gateway row.
  3. Tick Is available and save. This is CampusCore's switch; the institution's switch is the next step.

Step 2: Store the gateway address and key

  1. Sign in to CampusCore as a workspace admin.
  2. Open Settings -> Workspace Connectors and find the VSU Data Gateway card.
  3. Fill in the two fields:
  4. Gateway URL: the gateway's address as reached from this deployment, such as https://datagw-test.vsu.edu, with no path.
  5. Gateway key: the key VSU issued. It is stored encrypted and never shown again.
  6. Save, then turn the connector on. The switch refuses until both fields hold a value.

Step 3: Review the actions

Every action is a read, and every action is enabled for every role when the connector first syncs, including an action a later release adds. There is one action for each gateway endpoint, such as the account charges, the payments, the campus card balances, the aid awards, the aid disbursements and the course grades with the current Canvas score, and two summaries that read the account lists or the aid lists at once. Under the connector's actions, narrow any you do not want a role to reach. Nothing here needs a confirmation card, because the gateway has no writes.

Step 4: Connect as a student

  1. Sign in as a student whose profile carries a V-number.
  2. Open Settings -> Connectors and click Connect on the VSU Data Gateway card. There is no form: the key is the workspace's and the identity is the profile's. Connect asks the gateway for the student's own profile, so it proves the key, the network path and that VSU holds a record for the student. It refuses a person whose account has no V-number, and a person VSU has no record for, with a sentence that sends them to the IT help desk, and it stores no connection.
  3. Ask the chat a question about your own record, such as "what classes am I taking" or "do I have any holds".

What a person reads when something is wrong

  • No V-number on the account. Connect refuses with one sentence: the account is not linked to a VSU V-number, so the gateway cannot look up their records, and the IT help desk can link it. If the link is removed after the person connected, the chat answers with the same sentence, and the connection stays active; linking the account again fixes it with no reconnect.
  • The gateway has no record for the V-number. Connect refuses with a sentence saying VSU has no student record for the V-number on the account and the IT help desk must check the V-number linked to it. If the record goes away after the person connected, the chat and the drawer's Test connection read the same sentence.
  • Anything else. Connect refuses with one sentence, "We could not connect your account. Contact an administrator.", and never asks the person to try again.

The web log's warning "VSU Data Gateway person check failed: " tells an administrator which failure it was. A Django ValidationError means the connector's catalog row is missing. A ConnectorConfigError line carries its own message after the type, which names the missing workspace value, the Gateway URL that is not an address, or the refused key, and the fix is under Workspace Connectors. A refused key on an existing connection fails each action without expiring the connection, and the chat says the connector is not set up correctly and an administrator must check its settings. An httpx type, such as ConnectError or ConnectTimeout, means the gateway could not be reached: check the PrivateLink endpoint, the private hosted zone and the security group that lets the ECS tasks reach the endpoint on 443. Any other type is a gateway failure or an answer the connector cannot read, and its message names the gateway path.

Local development

The vsu_datagw_mock compose service serves the gateway's committed OpenAPI spec through Prism with generated answers. Start it with docker compose --profile vsu up -d vsu_datagw_mock, store http://vsu_datagw_mock:4010 as the Gateway URL and any text as the key, and connect as a user whose external_id is set. It publishes no host port; to probe it by hand, send a request from the web container:

docker compose exec -T web python -c "import httpx; print(httpx.get('http://vsu_datagw_mock:4010/v1/me/profile', headers={'X-VSU-Test-VNumber': 'V1'}).text[:200])"

Generated answers are random, so a list may be empty and a profile may be null. A null profile makes Connect refuse with the no-record sentence and the chat report no record; try again for a different draw.