> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ITSM Contracts

> List, view, create, and edit vendor contracts by status and type with search, financial terms, and document links.

The Contracts screen lists all vendor contracts with filtering and is accessible at `/it/contracts`.

## Overview

The Contracts list page loads contracts via `useVendorContracts` with server-side pagination (page size 20) and filter parameters. A search input filters by contract name or number. Two dropdowns filter by status and contract type (values from `CONTRACT_STATUS_LABELS` and `CONTRACT_TYPE_LABELS`). A clear-filters button appears when any filter is active. The contracts table is rendered via the `ContractTable` component. A **New Contract** button navigates to `/it/contracts/new`. An error state renders when the data fetch fails, with a retry button.

## Who it's for

Requires `IT_PERMISSIONS.VIEW` (outer `ITViewGuard`). No additional per-route permission gate.

## Before you start

* You must hold `IT_PERMISSIONS.VIEW` to access this screen.

## Steps

<Steps>
  <Step title="Open Contracts">
    Navigate to `/it/contracts`. The contracts table loads with all contracts.
  </Step>

  <Step title="Search and filter">
    Type in the search box to search by contract name or number. Use the Status and Type dropdowns to filter. Click the X button to clear all filters.
  </Step>

  <Step title="Open a contract">
    Click any contract row to navigate to its detail page at `/it/contracts/:id`.
  </Step>

  <Step title="Create a new contract">
    Click **New Contract** to navigate to `/it/contracts/new`.
  </Step>
</Steps>

## Key concepts

* **CONTRACT\_STATUS\_LABELS** — Human-readable labels for contract status values; exact values in `src/cores/it/types/vendors.ts`.
* **CONTRACT\_TYPE\_LABELS** — Human-readable labels for contract type values; exact values in `src/cores/it/types/vendors.ts`.
* **Server-side pagination** — Page size of 20; the `page` state variable increments for subsequent pages.

## Viewing a contract

The Contract Details screen displays all information for a single vendor contract and is accessible at `/it/contracts/:id`.

The Contract Details page loads a single contract via `useVendorContract`. The header shows the contract name, contract number, a contract-type badge (from `CONTRACT_TYPE_LABELS`), a `ContractStatusBadge`, and an **Edit** button linking to `/it/contracts/:id/edit`. The content area is a two-column grid: a Contract Details card shows vendor name (linked to vendor detail), contract type, auto-renew status, and an optional document link; a Terms & Dates card shows start date, optional expiration date, and optional renewal date; a Financial card shows contract value (formatted as currency) and payment terms. An optional Description card appears when `contract_description` is present.

Before you start: the contract must exist in the system.

1. From `/it/contracts`, click any contract row to open the detail page.
2. Read the Contract Details, Terms & Dates, and Financial cards.
3. If a document URL is present in the Contract Details card, click **View** to open it in a new tab.
4. Click the vendor name in the Contract Details card to open the vendor detail page.
5. Click **Edit** to navigate to the edit form.

**ContractStatusBadge** — Visual indicator of the contract's current status.\
**auto\_renew** — Boolean; displayed as Yes/No.\
**contract\_value** — Formatted using the platform `formatCurrency` utility.

## Creating a contract

The New Contract page (`/it/contracts/new`) provides a form for creating a new vendor contract. It accepts an optional `vendor_id` query parameter to pre-select the associated vendor.

The page uses `useVendorContractMutations` for creation and `useVendors` to populate the vendor selector. If the URL includes `?vendor_id=<id>`, the vendor field is pre-selected. On success, a toast notification fires and the user is redirected to `/it/contracts/:id` for the newly created contract.

Form fields: `vendor_id` (required), `contract_name`, `contract_number`, `contract_type`, `status`, `start_date`, `expiration_date` (optional), `renewal_date` (optional), `auto_renew` (boolean), `contract_value` (optional), `payment_terms` (optional), `contract_description` (optional), `document_url` (optional).

No explicit secondary permission gate beyond the outer `ITViewGuard` (`it.view`). Creating contracts requires `it.contracts.create`.

Before you start: the vendor must already exist in the system (`/it/vendors`). Have the contract details (name, type, start and expiry dates, and value) ready.

1. From the Contracts list or a Vendor detail page, click **New Contract**, or navigate to `/it/contracts/new`. Append `?vendor_id=<id>` to pre-select a vendor.
2. Choose the vendor from the dropdown. All active vendors in the organization are listed.
3. Complete the contract name, number, type, status, start date, and expiry date. Optionally provide contract value, payment terms, description, and a document URL.
4. Toggle **Auto Renew** if the contract renews automatically. Set the renewal date if applicable.
5. Click the submit button. On success you are redirected to the new contract's detail page.

## Editing a contract

The Edit Contract screen allows updating an existing vendor contract and is accessible at `/it/contracts/:id/edit`.

The Edit Contract page loads the existing contract via `useVendorContract` and the vendor list via `useVendors`. Both are required before the form renders. The form is displayed in a card using the shared `ContractForm` component, which accepts the existing contract data and the vendor list as props. Fields include: vendor (select from vendor list), contract name, contract type, status, start date, optional expiration date, optional renewal date, auto-renew toggle, optional contract value, optional payment terms, optional description, and optional document URL. On save, `updateContract` is called and the user is redirected to the contract detail page.

Before you start: both the contract and vendor list must load successfully before the form appears.

1. From the contract detail page, click **Edit**.
2. In the `ContractForm`, modify vendor, name, type, status, dates, financial terms, and description as needed.
3. Click the save action in the form. On success, you are redirected to the contract detail page.
4. Click **Cancel** to return to the contract detail page without saving.

**ContractForm** — Shared component used for both creating and editing contracts.\
**document\_url** — Optional URL to an external contract document.

## Related

<Columns cols={2}>
  <Card title="IT Service Management" icon="headset" href="/it/overview">
    IT Service Management overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/it.tsx
  * src/cores/it/pages/vendors/ContractListPage.tsx
  * src/cores/it/pages/vendors/ContractDetailPage.tsx
  * src/cores/it/pages/vendors/NewContractPage.tsx
  * src/cores/it/pages/vendors/EditContractPage.tsx
  * src/cores/it/hooks/useVendorContractMutations.ts
  * src/cores/it/hooks/useVendors.ts
</Accordion>