contexa-core contexa-iam

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.

How company records reach a decisionRecords are put in advance; each request is matched against its person's records.
  1. Put recordsYour integration or an administrator puts them through the admin API. An application can also supply its own store
  2. A request a rule coversOnly requests whose action and resource category match a company rule
  3. 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
  4. 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)MeaningMain 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 targetsubject, 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 targetid, subject, approver, target, purpose, actions (empty for every action), maxItems, status, validFrom · validUntil, decidedAt, usageReported, recordedBy · recordedAt
TICKET (tickets)A ticket of your ticket systemid, subject, kind (CHANGE, INCIDENT, ...), approver, target, purpose, actions, status, validFrom · validUntil, recordedBy · recordedAt
ON_CALL (onCall)An on-call shiftid, subject, team, startsAt (included) · endsAt (excluded)
TRAVEL (travel)A registered business trip and the network used during itid, subject, city, country, network (CIDR), validFrom · validUntil
ACCESS_HISTORY (accessDays)A day the person worked on a targetsubject, 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 zonecidr, zone (CORPORATE, VPN, PARTNER, ...)
SOURCE (sources)States "we integrate this kind" without a recordA list of kind names (for example ["TICKET", "ON_CALL"])
  • Valid states. An approval covers a request when its status is APPROVED, GRANTED or COMPLETED; a ticket when it is OPEN, APPROVED, ACTIVE or IN_PROGRESS. An empty status is not checked.
  • Items already used. When an approval's usageReported is true, the items your application reported in usage count as already used under it. When it is false or empty, the items already used are "not known".
  • The target (target) is the key your company's records use for it (for example project HX-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.

FieldMeaningWhen empty
idThe rule idRequired
statementThe rule as a sentence. It goes into the decision prompt as writtenNone
requirementThe record that must cover the request: APPROVAL or TICKETNone
requiredTicketKindThe ticket kind needed (for example CHANGE)Any kind
actionsThe actions the rule coversEvery action
categoriesThe resource categories the rule covers (@Protectable(category = ...))Every category
exceptionsWhen no covering record is needed (below). {"kind": "...", "limit": number}No exception
recordsThe record kinds a request is matched againstThe kinds requirement and exceptions name, with TRAVEL
historyDaysHow many days of work history (days worked) the decision is shownThe RECENT_WORK limit, else 90 days

A request is looked at under three conditions. If any is missing, no company records reach that request.

  1. At least one rule matches the request's action and resource category.
  2. The records' holder (below) has a person record (people).
  3. 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 whenlimit
ASSIGNEDThe 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_MANAGERThe person is the account manager of the customer the request names (a URL variable value) or of the targetNot used
RECENT_WORKThe person worked on the target recentlyHow many days back to look (else historyDays, else 90 days)
TICKET_WHILE_ON_CALLThe person is on call and has a ticket that meets every conditionNot 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 attributeFormatUse
resourceScopename=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 droppedThe 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
requestItemsA numberHow many items the request handles. Compared with an approval's maxItems and the ASSIGNED limit
claimedRecordA ticket keyA 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.

FactContent
Rules that applyThe rule statement, the record needed, the exceptions and the company's own check (needed, not needed, unknown)
Closest approval and ticketAmong 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 namesWhether that ticket exists (NO_TICKET when it does not) and, if it does, the same condition checks
Assignment, work history, on-callWhether 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 zoneThe 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 timeThe 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).

VersionPlace
Every versionThe 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).

RequestWhat it doesResponse
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-recordsList 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/deleteDelete 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_record table (contexa-iam). Without one they are kept in memory and are lost on restart.
  • When your records live elsewhere, declare your own CompanyRecordStore bean; 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 FrictionContextProvider bean 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