Company Records: Telling Decisions What the Company Knows
When you give Contexa your company's records (approvals, tickets, assignments, on-call shifts, business trips), a decision on an unusual request also checks whether a record explains the difference. This page covers the records you can put, the requests a company rule covers, the values your application states per request, the facts a decision sees, and the API and storage.
At a glance
The same request can be normal or dangerous depending on what the company knows. Exporting 1,000 customer records you never looked at before is explained by an approved approval, and suspicious without one. Company records are how you tell Contexa what it needs for that judgement.
Company records do not decide. Contexa only states what it found by matching the request against the records (which approval comes closest, which conditions it fails, and so on) and the company's own check under its rules. The AI model reads those facts and chooses to allow, ask for more authentication or block.
- Put recordsYour integration or an administrator puts them through the admin API. An application can also supply its own store
- A request a rule coversOnly requests whose action and resource category match a company rule
- Match against recordsThe approvals, tickets, assignments, shifts and trips of the requester (for an agent, the person who answers for it) at the request time
- DecisionThe matched facts go into the decision prompt and the AI model chooses the response
Company records are on by default, but they do nothing until you put company rules (policies) and people (people).
Records you can put
You put records of several kinds together as one JSON document. The field names are the JSON fields in the table below.
| Kind (JSON field) | Meaning | Main values |
|---|---|---|
PERSON (people) | A person Contexa knows. Requests of a person with no person record are not looked at. | subject (the Contexa user id), companyId (the id your company's systems use for the person, compared with approvers), displayName |
ASSIGNMENT (assignments) | A person assigned to a target | subject, target, responsibility (ACCOUNT_MANAGER makes the person the account manager), from · until (dates, both included, open when empty) |
APPROVAL (approvals) | An approval of work on a target | id, subject, approver, target, purpose, actions (empty for every action), maxItems, status, validFrom · validUntil, decidedAt, usageReported, recordedBy · recordedAt |
TICKET (tickets) | A ticket of your ticket system | id, subject, kind (CHANGE, INCIDENT, ...), approver, target, purpose, actions, status, validFrom · validUntil, recordedBy · recordedAt |
ON_CALL (onCall) | An on-call shift | id, subject, team, startsAt (included) · endsAt (excluded) |
TRAVEL (travel) | A registered business trip and the network used during it | id, subject, city, country, network (CIDR), validFrom · validUntil |
ACCESS_HISTORY (accessDays) | A day the person worked on a target | subject, target, day |
USAGE (usage) | Items your application delivered to the person from a target (an export, a download) | id, subject, target, items, at |
POLICY (policies) | A company rule (below) | id, statement, requirement, actions, categories, exceptions, ... |
NETWORK (networks) | A company network and its zone | cidr, zone (CORPORATE, VPN, PARTNER, ...) |
SOURCE (sources) | States "we integrate this kind" without a record | A list of kind names (for example ["TICKET", "ON_CALL"]) |
- Valid states. An approval covers a request when its
statusisAPPROVED,GRANTEDorCOMPLETED; a ticket when it isOPEN,APPROVED,ACTIVEorIN_PROGRESS. An emptystatusis not checked. - Items already used. When an approval's
usageReportedistrue, the items your application reported inusagecount as already used under it. When it isfalseor empty, the items already used are "not known". - The target (
target) is the key your company's records use for it (for example projectHX-310). Your application states the target of each request (below).
"None found" and "not looked up"
For six kinds (ASSIGNMENT, APPROVAL, TICKET, ON_CALL, TRAVEL, ACCESS_HISTORY) Contexa tells apart whether your company integrates the kind.
- A kind you integrate with no record for the person reaches the decision as "none found". Example: tickets are integrated and no matching ticket exists.
- A kind you do not integrate stays "not looked up". It does not mean there is none, so it is not a fact against the request.
- Putting even one record of a kind integrates that kind. To state that you integrate a kind before you have records of it, name it in
sources.
Company rules: which requests are looked at
Company records look only at requests a company rule covers. A rule states what a request needs.
| Field | Meaning | When empty |
|---|---|---|
id | The rule id | Required |
statement | The rule as a sentence. It goes into the decision prompt as written | None |
requirement | The record that must cover the request: APPROVAL or TICKET | None |
requiredTicketKind | The ticket kind needed (for example CHANGE) | Any kind |
actions | The actions the rule covers | Every action |
categories | The resource categories the rule covers (@Protectable(category = ...)) | Every category |
exceptions | When no covering record is needed (below). {"kind": "...", "limit": number} | No exception |
records | The record kinds a request is matched against | The kinds requirement and exceptions name, with TRAVEL |
historyDays | How many days of work history (days worked) the decision is shown | The RECENT_WORK limit, else 90 days |
A request is looked at under three conditions. If any is missing, no company records reach that request.
- At least one rule matches the request's action and resource category.
- The records' holder (below) has a person record (
people). - The request time is known. Without it, only a summary saying the records were not looked up because the time is unknown goes in.
Rule exceptions and the company's own check
Exception (kind) | Holds when | limit |
|---|---|---|
ASSIGNED | The person is assigned to the target on the request day (not as account manager) | Only when the request's items are at most this number. It does not hold when the items are unknown |
ACCOUNT_MANAGER | The person is the account manager of the customer the request names (a URL variable value) or of the target | Not used |
RECENT_WORK | The person worked on the target recently | How many days back to look (else historyDays, else 90 days) |
TICKET_WHILE_ON_CALL | The person is on call and has a ticket that meets every condition | Not used |
For each rule Contexa states the company's own check: "no covering record needed" when any exception holds, "needed" when none holds, and "unknown" when an exception cannot be decided because its kind is not integrated. This check is one more fact; the model still chooses the response.
Values your application states per request
Records name targets by your company's keys, which the request URL alone does not reveal. Contexa does not guess the target from the request's text. Your application states it as request attributes.
| Request attribute | Format | Use |
|---|---|---|
resourceScope | name=value (for example projectKey=HX-310). The name starts with a letter, letters, digits and _, at most 64 characters; the value uses letters, digits and . _ : -, at most 128 characters. A value in another format is dropped | The request's target. The value (HX-310) is compared with the records' target. Without it, the comparisons that need a target (assignment, approval, ticket, days worked) are not made |
requestItems | A number | How many items the request handles. Compared with an approval's maxItems and the ASSIGNED limit |
claimedRecord | A ticket key | A key the requester offers as "this ticket covers it". It is not trusted as evidence: Contexa checks whether the person really has that ticket and whether it meets the conditions, and states the result |
// In a controller or filter, before calling the protected method
request.setAttribute("resourceScope", "projectKey=" + project.getKey());
request.setAttribute("requestItems", rows.size());
request.setAttribute("claimedRecord", form.getTicketKey()); // the ticket key the requester typed, when there is one
State the action and resource category with @Protectable(actions = ..., category = ...) (@Protectable). Without a declared action, rules are matched with the action family Contexa infers from the request (READ, WRITE, EXPORT, DELETE, ADMIN, EXECUTE).
Whose records are looked at
- A person's own request is matched with that person's records.
- An agent's request is matched with the records of the person who answers for it: the delegator for a delegated agent, the registered sponsor for an agent acting on its own. An agent has no assignments, shifts or tickets of its own. The decision prompt also states whose records they are (own, delegator, sponsor) (Agents as Security Subjects).
- Tenants. A person's records are those of the request's tenant together with those put without a tenant (shared by the deployment). Rules and networks are the tenant's when it has any, else the shared ones.
What the decision sees
For a request a rule covers, these facts go into the decision prompt.
| Fact | Content |
|---|---|
| Rules that apply | The rule statement, the record needed, the exceptions and the company's own check (needed, not needed, unknown) |
| Closest approval and ticket | Among the person's approvals and tickets, the one that comes closest to covering the request and the conditions it fails: APPROVER (approved by the requester), TARGET (another target), PURPOSE (another action), ITEMS (too many items, approvals only), VALIDITY (outside its validity), STATUS (not in a valid state) |
| A ticket the requester names | Whether that ticket exists (NO_TICKET when it does not) and, if it does, the same condition checks |
| Assignment, work history, on-call | Whether the person is assigned (or account manager) on the request day, recent days worked on the target, whether the person is on call at the request time |
| Network zone | The zone of the company network the request address is in, the trip network (TRAVEL), or anything else (EXTERNAL, only when you put company networks) |
| Computed at the request time | The engine computes again: whether the approval was decided before the request, whether the request is within its validity, whether the item limit is exceeded by this request alone or together with what the same session already exported, whether the rule is met by a record or an exception |
Where they appear depends on the prompt version (The Decision Prompt).
| Version | Place |
|---|---|
| Every version | The RECORDS AND COMPARISONS block. It holds the records and comparisons without the engine's conclusions, and the system text tells the model to check for itself, for every way the request differs from the usual, whether a record explains it by its target, purpose, period, limit and decision time, and whether the rule was met at the request time |
| A version with the prepared part "Decision rules" | The same block, with the engine's conclusion lines DeviationsExplained (each difference unexplained or explained by the record that covers it) and PolicySatisfied (whether the rule is met and why) |
Putting records: the admin API
Every API needs the ADMIN role. Each put and delete is written to the audit log with who did it (COMPANY_RECORDS_RECORDED, COMPANY_RECORDS_DELETED).
| Request | What it does | Response |
|---|---|---|
POST /contexa/admin/api/company-records?tenantId=... | Put records. The body is JSON holding the kinds above. At most 20,000 records at once. A record with the same kind and key is replaced | {"records": number put, "integratedKinds": [...]} |
GET /contexa/admin/api/company-records | List records. Filter by tenantId, kind, subject, target; newest put first, limit records (default 200, at most 1,000) | A list of records (kind, key, person, target, content, put by, put at) |
POST /contexa/admin/api/company-records/delete | Delete by key. Body {"tenantId": ..., "kind": "TICKET", "keys": ["CHG-1042"]} | {"removed": number removed} |
An empty tenantId means the deployment's shared records. If any record misses a required value or has a period that ends before it starts, nothing is put and the response is 400 with a list of problems (problems).
{
"people": [
{ "subject": "alice", "companyId": "E1024", "displayName": "Alice Kim" }
],
"assignments": [
{ "subject": "alice", "target": "HX-310", "from": "2026-10-01" }
],
"approvals": [{
"id": "APR-7781", "subject": "alice", "approver": "E2001", "target": "HX-310",
"purpose": "Quarterly audit data", "actions": ["EXPORT"], "maxItems": 1000, "status": "APPROVED",
"validFrom": "2026-11-01T00:00:00Z", "validUntil": "2026-11-08T00:00:00Z",
"decidedAt": "2026-10-31T09:12:00Z", "usageReported": true
}],
"policies": [{
"id": "EXPORT-NEEDS-APPROVAL", "statement": "Exporting customer data needs an approval",
"requirement": "APPROVAL", "actions": ["EXPORT"], "categories": ["customer-data"],
"exceptions": [{ "kind": "ASSIGNED", "limit": 100 }]
}],
"networks": [
{ "cidr": "10.0.0.0/8", "zone": "CORPORATE" }
]
}
In this example, when alice exports 1,000 customer records with projectKey=HX-310 on November 3 from the office network through a method protected with @Protectable(actions = "EXPORT", category = "customer-data"), the rule EXPORT-NEEDS-APPROVAL applies. She is assigned, but the items exceed the exception limit (100), so the company's own check is "approval needed", and the approval APR-7781 is stated as a record whose target, action, items, validity and status all match.
In the admin console, Security → Company Records (/contexa/admin/company-records) lists up to the 200 newest records, filtered by kind, person, target and tenant. The screen only shows records and decides nothing (Admin Console).
The key of each kind: subject for a person; subject, target, responsibility and from together for an assignment; subject, target and day together for a day worked; id for usage (else subject, target and at); cidr for a network; id for the rest.
Where records are kept
- With a Contexa database they are kept in the
ctxa_company_recordtable (contexa-iam). Without one they are kept in memory and are lost on restart. - When your records live elsewhere, declare your own
CompanyRecordStorebean; it is used instead of the default store. Its methods: put (put), delete (delete), a person's records (ofSubject), the company's rules and networks (company), a listing (list), and deleting all of a person's records (deleteSubject). - When an account is deleted, that person's company records are deleted in every tenant.
- An application's own
FrictionContextProviderbean runs beside company records and can add the application's records to the same context.
Checking that the records were really used
The SOURCE_TRUTH check of prompt inspection reads the company records and delegation records again from their stores at the request time for each sealed decision, and checks that the prompt's on-call, assignment, approval (approver, item limit, items already used) and delegation lines match them. Records gone because the account was deleted are reported as not kept (Prompt Inspection and Replay).
Where to read next
- Decision Engine: how facts, company records included, are gathered into a decision
- The Decision Prompt: how the prompt states the facts
- Delegation and Objective Contracts: what the delegation record does for an agent's request