Create a new contract¶
As a Contract role user, I want to add a new contract record and set up its initial Contract Terms and Contract Roles, so that a jobsite can be attached to it and dues/wage calculation and invoicing have somewhere correct to draw from.
Screen: Contracts, then the Details tab's nested bar (Contract Terms / Contract Roles / Contract Summary)
Steps¶
-
From the Contracts landing search/grid, click Add Contract (a page-level action — it is not inside any tab).

-
On Details, fill the identity fields: Contract Name, Form (e.g. Master), Master Contract link if this is a sub-contract, Effective Date, Expiration Date, Contract Type (e.g. HO/HI-M), Contract Status. Click Save Changes.
- Under Details > Contract Terms (the default nested tab), click Add Contract Term for each whole-contract benefit obligation that applies — e.g. "H&W Coverage," "HRA Coverage," "ETF Obligation" — setting the Term, Trade Codes it covers (or "Entire Contract"), and the P1–P6 period dollar amounts.
- Under Contract Roles, use the "Assign A Person To A Role" panel to put the contract's initial named roles in place — see Assign a person to a contract role for the full procedure.
- Under Contract Summary, record any Comments and Contract Changes/New Language/Modified Language notes, then Save Changes.
Before you start: confirming the right Employer¶
A contract always attaches to an Employer first (the required sequence is Employer -> Contract -> Jobsite), so getting the Employer side right before you start building Contract Terms matters.
A stuck or empty Employer type-ahead is often a stale-cache issue, not a search bug
If the Employer type-ahead on the Choose Employer screen won't populate consistently while you're loading in a Contract, a hard refresh (Ctrl+F5) is the confirmed fix for the one documented root cause (stale browser cache across a UI deployment) — try that before assuming the employer doesn't exist or search is broken. Separately, the Local/Sector dropdown in that same modal is a known point of confusion: if you leave it blank expecting "no filter," try selecting "NONE" explicitly instead. (IUOE-2137)
Employer Number/ID is system-assigned at submission — never hand-entered
The Employer Number (sometimes still labeled "Shop ID" in older screens/reports — same field, legacy naming) is generated by the system only once the Add Employer form is submitted, not when the form opens, specifically to prevent two users opening the form at the same time from being handed the same number. It isn't meant to be end-user-editable after the fact — editing it where still possible risks breaking the Employer-to-Jobsite relationship your new contract depends on. (IUOE-1790)
Things to watch out for¶
Contract Terms are a separate data store from Rates
Contract Terms (Details > Contract Terms) are whole-contract dollar amounts per benefit type — "H&W Coverage," "HRA Coverage," "ETF Obligation" — billed per period (P1–P6). The Rates tab is a completely different store: a trade-code-level hourly wage schedule. A brand-new contract can have real Contract Terms and still show 0 rows on Rates — that's expected, not a sign the contract wasn't saved correctly. See Maintain contract rates and dates for the Rates tab itself.
A contract doesn't need a signature to exist
Three contract statuses are invoiceable before final signature: Active, Active - Out for Sig, and In Negotiation. Don't block creating or attaching a contract on waiting for a signed copy — the required sequence is Employer -> Contract -> Jobsite, and the Contract step can use any of these three statuses. (IUOE-2231)
Percentage-type Contract Terms display as dollars, not a percent
If a Contract Term is defined as percentage-based, the UI still shows the rate field as a dollar amount rather than a percent symbol. This is accepted behavior after review with JayStar, not a data-entry mistake — don't re-enter the term expecting the display to change. (IUOE-2263)
An ETF Obligation Date doesn't carry over automatically
Adding an "ETF Obligation" Contract Term does not by itself set the Dates-tab ETF Obligation Date — that date drives which month ETF invoices generate and is deliberately independent of the contract's rate-effective date. Set it explicitly on the Dates tab; see Maintain contract rates and dates.
A new jobsite's trade-code dropdown depends on this contract having an active rate
Once this contract is attached to a jobsite, the trade-code dropdown on that jobsite's members' Add Work Record screen is sourced from this contract's active (non-expired) wage rate records — not from the member's own imported data. If a jobsite reports an empty trade-code dropdown after you've attached a contract, check that the contract actually has an active Rates row for the trade code in question before assuming it's a UI bug. See Troubleshoot common contract and jobsite data issues.