Administrator Guide

On this page

This guide covers system administration tasks in CRAIG. It is intended for users with the admin role who are responsible for user management, rules configuration, data exchange setup, and security oversight.

User Management

CRAIG delegates user authentication and role assignment to Keycloak, an identity management system. You manage users through the Keycloak admin console, not through the CRAIG web interface.

Accessing the Keycloak Admin Console

  1. Open the Keycloak admin console in your browser (your IT department will provide the URL).

  2. Log in with your Keycloak administrator credentials.

  3. Select the craig realm from the realm selector in the upper left.

Creating a New User

  1. In the Keycloak admin console, click Users in the left menu.

  2. Click Add user.

  3. Fill in the required fields:

    • Username — the login name the person will use (for example, maria.garcia).

    • Email — the user’s email address.

    • First Name and Last Name — used for display in CRAIG.

  4. Click Create.

  5. Go to the Credentials tab and set an initial password. Toggle Temporary on if you want the user to change it at first login.

Assigning Roles

CRAIG uses nine roles to control what each user can see and do. Six are OPERATIONAL roles (what a user can do); three are OFFICE roles (what approval authority a user carries — an orthogonal axis introduced by the subsidy review workflow, ADR-054):

Role What It Grants

admin

Full system access: rules engine, security module (audit log, NIST controls, archive), admin unit management, exchange partner creation, federal submission generation and transmission, rate table management.

supervisor

Oversight across all workers' caseloads, access to reporting and data quality, exchange and financial modules, ability to approve case plans and payments.

caseworker

Day-to-day case management: intake screening, case creation, investigations, placements, contacts, court orders, and document uploads.

eligibility_worker

Reserved for the IV-E eligibility-determination flows. Under the jurisdiction authz rulesets this role currently confers no additional financial access on its own — rate tables, claiming records, and payment lists are admin/supervisor/ readonly surfaces (#1062 leading-DENY; #1087 made every denied financial list an explicit 403), and a user holding this role sees financial data only through their other roles.

icpc_coordinator

Interstate Compact on the Placement of Children: create and manage ICPC requests, upload home studies and attachments, track request status.

readonly

View-only access to case data. Cannot create, edit, or delete records.

county_director

Office authority (subsidy approvals): routine agreement transitions, terminations for most causes, terms amendments. Holders also need an operational role for day-to-day access.

regional_director

Office authority above county: guardianship-dissolved terminations, routine reinstatements, out-of-window review scheduling, sweep execution.

state_office

The highest office authority: reinstatements whose termination cause demands state review (fail-closed default for unknown causes).

To assign roles:

  1. In the Keycloak admin console, click Users and select the user.

  2. Go to the Role mapping tab.

  3. Click Assign role.

  4. Select the appropriate roles from the list and click Assign.

A user can hold multiple roles. For example, a caseworker who also handles eligibility determinations would have both caseworker and eligibility_worker.

Keycloak Clients

CRAIG uses two Keycloak clients:

Client Purpose

craig-api

Used by the CLI tool and automated tests (Resource Owner Password Credentials grant).

craig-ui

Used by the web interface (Authorization Code + PKCE flow).

You do not normally need to modify these clients. They are configured during deployment.

How Roles Affect the Web Interface

The CRAIG web interface shows or hides navigation links and action buttons based on the logged-in user’s roles:

  • Rules link in the navigation bar — visible only to admin.

  • Security link — visible only to admin.

  • Exchange link — visible to supervisor, admin, and icpc_coordinator.

  • Financial link — visible to eligibility_worker, supervisor, and admin.

  • Cases, Intake, Placement — visible to caseworker and above.

  • Admin-only buttons (such as "+ New Rule Set", "+ New Partner", "Delete Rule Set") are hidden for non-admin users.

Authorization is enforced at the API level. Even if a user navigates directly to a URL, the backend API will reject unauthorized requests.

Rules Configuration

The Rules Engine uses JDM (JSON Decision Model) rule sets to evaluate decisions automatically. Rule sets drive safety assessments, eligibility determinations, data quality checks, and timeliness monitoring.

Viewing Rule Sets

  1. Click Rules in the navigation bar (visible only to admin users).

  2. The Rule Sets page shows a table with all configured rule sets.

  3. Each row displays the rule set name, version, status (Active or Inactive), description, last update date, and who updated it.

  4. Use the Search box to find a specific rule set by name.

  5. Click any column header to sort the table.

Creating a Rule Set

  1. On the Rule Sets page, click the + New Rule Set button (upper right).

  2. A dialog appears with three fields:

    • Name — a unique identifier, typically in the format jurisdiction-purpose (for example, georgia-safety-assessment).

    • Version — a version string (for example, 1.0.0).

    • Description — an optional description of what the rule set evaluates.

  3. Click Create.

  4. A success message confirms the rule set was created.

After creation, you need to import the JDM content that defines the actual decision logic. This is done through the API (the import endpoint) or the CLI tool.

Viewing Rule Set Details

  1. Click a rule set name in the table to open its detail page.

  2. The detail page shows:

    • Rule set metadata (name, version, description, created/updated timestamps, created/updated by).

    • The full JDM content rendered as formatted JSON.

  3. The JDM content defines the decision model — the inputs it expects, the decision tables and rules it applies, and the outputs it produces.

Deleting a Rule Set

  1. Open the rule set detail page.

  2. Click Delete Rule Set (visible only to admin users).

  3. Confirm the deletion in the dialog that appears.

Deletion is a soft-delete — the rule set is marked inactive rather than permanently removed. Existing evaluation records that reference the rule set are preserved.

Jurisdiction-Specific Rule Sets

Rule sets are prefixed by jurisdiction (for example, georgia-safety-assessment, georgia-placement-matching). CRAIG currently ships with 10 seeded rule sets covering two jurisdictions. When configuring a new jurisdiction, create rule sets following the same naming convention.

Admin Units

Admin units represent the counties or regions in your jurisdiction. CRAIG uses admin units for case assignment, reporting boundaries, and geographic filtering.

Viewing Admin Units

Admin units are managed through the Security service API. The admin unit registry is seeded with 159 Georgia counties by default.

Each admin unit record includes:

Field Description

Name

The county or region name (for example, "Fulton").

Unit Type

The type of administrative unit (for example, "county").

FIPS Code

The federal FIPS code for the geographic area.

State FIPS

The state-level FIPS code.

Jurisdiction

The jurisdiction this unit belongs to (for example, "georgia").

Active

Whether the unit is currently in use.

Managing Admin Units

Admin unit management is done through the API or CLI. The following operations are available:

  1. List — retrieve all admin units (paginated, searchable).

  2. Create — add a new admin unit with name, type, FIPS code, and jurisdiction.

  3. Update — modify an existing admin unit’s fields.

  4. Delete — soft-delete an admin unit (sets active to false).

The deployment configuration endpoint (/v1/security/admin/config) returns the current jurisdiction and admin unit label, which other services use to display the correct terminology (for example, "County" vs "Region").

Data Exchange Partners

The Exchange module manages connections with external organizations that send or receive data.

Viewing Exchange Partners

  1. Click Exchange in the navigation bar.

  2. The Exchange Partners page shows a table of all configured partners.

  3. Each row displays:

    • Partner Name — the organization name (clickable to view details).

    • Type — the category of partner (for example, court, law enforcement, medical).

    • Direction — Inbound, Outbound, or Bidirectional.

    • Format — the data exchange format.

    • Active — whether the partner connection is active.

    • Endpoint — the partner’s API endpoint URL (if configured).

Creating a New Partner

  1. On the Exchange Partners page, click + New Partner (visible only to admin users).

  2. Fill in the partner details: name, type, direction, exchange format, and endpoint URL.

  3. Click Create.

Partner Detail Page

Click a partner name to view the detail page. The detail page shows:

  • Partner metadata (type, direction, endpoint URL, format).

  • Data Sharing Agreements — a table of agreements with this partner, showing title, effective and expiration dates, status (Draft, Active, Expired), and who approved each agreement.

  • Recent Transactions — a log of data exchanges with this partner, including date, direction, type, status (Completed, Pending, Failed), record count, and who initiated the exchange.

Creating Data Sharing Agreements

On the partner detail page:

  1. Click + New Agreement.

  2. Fill in:

    • Agreement Title — a descriptive name.

    • Effective Date — when the agreement takes effect.

    • Expiration Date — optional end date.

    • Legal Authority — the legal basis for the data sharing (for example, "ICPC Article III").

    • Status — Draft, Active, or Expired.

  3. Click Create Agreement.

Agreements follow a state machine: draft → active → expired or terminated. Only draft agreements can be deleted; active or expired agreements are retained for the audit trail.

Testing Partner Connectivity

You can test whether a partner endpoint is reachable through the API’s test endpoint. This sends a test request to the configured endpoint URL and reports whether the connection succeeded.

Security and Compliance

As an administrator, you have access to the full Security module. Click Security in the navigation bar to access these pages.

Audit Log

The audit log page shows every action recorded across all CRAIG services.

  1. Navigate to Security > Audit Log (this is the default Security page).

  2. The table displays:

    • Timestamp — when the action occurred.

    • Action — the operation type (sortable).

    • User — who performed it (sortable).

    • Service — which CRAIG module processed it (sortable).

    • Resource Type — the type of record affected, with its ID.

    • Success — whether the action succeeded (green "Yes" badge) or failed (red "No" badge).

  3. Use the Search box to filter entries by any visible field.

  4. Click column headers to sort.

  5. Use pagination controls at the bottom to navigate through results.

The audit log captures events automatically through a wildcard subscriber. Every create, update, delete, evaluation, and state transition across all services is recorded without any manual configuration.

Security Reviews

Security reviews track periodic assessments of the system’s security posture.

  1. Click the Reviews button at the top of any Security page.

  2. The table shows each review with:

    • Type — the kind of review (for example, "biennial").

    • Scheduled — the target date (sortable).

    • Completed — the actual completion date.

    • Reviewer — who conducted the review (sortable).

    • Status — Completed (green), In Progress (yellow), or Overdue (red).

  3. Reviews follow a state machine: scheduled → in_progress → completed, or scheduled → overdue.

NIST SP 800-53 Controls

The NIST Controls page tracks your agency’s compliance with the NIST SP 800-53 security framework.

  1. Click the NIST Controls button at the top of any Security page.

  2. Each control shows:

    • Control ID — the NIST identifier (for example, AC-2, AU-3).

    • Family — the control family (for example, Access Control, Audit and Accountability).

    • Name — the control’s descriptive name.

    • Status — Implemented (green), Partial (yellow), Not Applicable, or other states (red).

    • Notes — the last assessment date.

    • Evidence — who performed the assessment.

  3. Use the Search box to find specific controls.

  4. Sort by Control ID, Family, or Status using the column headers.

Archive Records

The Archive page shows records that have been moved to long-term storage based on retention policies.

  1. Click the Archive button at the top of any Security page.

  2. The table displays:

    • Source Service — which CRAIG service the records came from (sortable).

    • Source Table — the database table that was archived (sortable).

    • Record Count — how many records were archived.

    • Archived At — when the archive was created (sortable).

    • Retention Until — the date until which records must be retained (sortable).

    • Purge Eligible — whether the retention period has expired (red "Yes" means records can be purged).

    • Purged At — when records were permanently removed (if applicable).

Archive and purge operations are run through the API:

  1. Run Archive — moves eligible records from active tables to archive storage.

  2. Purge — permanently removes archived records whose retention period has expired.

Access Control Summary

The following table summarizes which Security pages and actions are available by role:

Action Admin Supervisor Other Roles

View Audit Log

Yes

No

No

View Audit by Resource

Yes

Yes (supervisor+)

No

Manage Security Reviews

Yes

No

No

Manage NIST Controls

Yes

No

No

View/Run Archive

Yes

No

No

Manage Admin Units

Yes

No

No

System Health

Each CRAIG service exposes a health check endpoint that you can use to verify the system is running.

Health Check Endpoints

Service URL Port

Rules Engine

/healthz

8001

Case Management

/healthz

8002

Placement

/healthz

8003

Data Exchange

/healthz

8004

Financial

/healthz

8005

Reporting

/healthz

8006

Security

/healthz

8007

Intake

/healthz

8008

Web UI

/healthz

8080

A healthy service returns an HTTP 200 response. If a service is unreachable or returns an error, it may need to be restarted. Contact your IT department if services are consistently unhealthy.

Monitoring Tips

  • Check all services — a problem in one service does not necessarily affect others. CRAIG’s microservice architecture means each service operates independently.

  • Session timeouts — Keycloak tokens expire after 30 minutes. If users report being logged out unexpectedly, this is normal behavior. They will be redirected to the login page automatically.

  • Database connectivity — each service connects to its own database. If a specific module is not loading, the issue may be with that service’s database connection rather than the entire system.

Edit this page · latest