Redact rules
Redact finds personal data with its own detectors. Your organisation's rules add what only you know about, such as case numbers, project names and internal IDs, and exempt text that must stay readable. The rules apply to every Redact run in your organisation: in the Redact workspace in the hub, through the API and in Redact in Word.
Where you manage rules
Rules are under Organisation › Redact › Rules (/settings/redaction-rules). The page is open to administrators who are assigned Redact, because rules often contain the very names and numbers you want to hide. komplai stores the rules on its servers in Germany until you delete them, and applies them there.
The list has the views Active, Disabled and, if your organisation uses Documents, Suggestions. Search by pattern, and select several rules to Activate, Disable or Delete them at once.
What a rule does
Each rule has one of two effects:
- Pseudonymise: matching text is replaced with a numbered label such as
[CASE-1]. The same text gets the same label throughout a run. - Exempt (never pseudonymise): matching text is never pseudonymised, even when a detector or another rule finds it. An exempt rule removes every finding that overlaps its match.
When a literal exempt rule overlaps the text of a literal pseudonymise rule, the list says so next to the pseudonymise rule: An exception rule takes precedence, so this rule is not used.
Create a rule
- On Rules, choose Create rule.
- Choose the Effect.
- Under Pattern type, choose Literal for an exact text, or Pattern (advanced) for a regular expression. Write the text or pattern, at most 256 characters.
- For a pseudonymise rule, choose a Type. Write a Label if you want your own word in the label:
CASEgives[CASE-1]. Without one, the type's own label is used. - Choose where it Applies to.
- For a pseudonymise rule, add a Fixed replacement if every match should read the same, such as
[CONFIDENTIAL]. - Tick Case-sensitive if upper and lower case must match. By default they don't.
- Choose Create rule. The rule is active at once and applies from the next run.
A label can contain A to Z, 0 to 9, hyphen and underscore, and is saved in capitals. A fixed replacement has at most 128 characters, and it cannot have the same form as Redact's numbered labels, such as [CASE-1], because it could be mistaken for one. Saving a rule with the same pattern type, pattern and effect as an existing one keeps the existing rule, and the hub says Rule already existed.
How patterns match
- A Literal rule matches the text wherever it occurs, also inside a longer word:
Falkalso matches inFalkenberg. Use a pattern with\bto match whole words only. - A Pattern (advanced) is a JavaScript regular expression, written without slashes or flags. It is checked before the rule is saved, and a pattern that could overload processing, for example one with repetitions nested inside other repetitions, is refused.
- A pattern must never match empty text, as
\d*does. While one active rule for the API does, every Redact call through the API fails withinvalid_organisation_policy.
Example
Case numbers of the form 24/01234, and a project name that must always read the same:
| Effect | Pattern type | Pattern | Label | Fixed replacement |
|---|---|---|---|---|
| Pseudonymise | Pattern (advanced) | \b\d{2}/\d{5}\b | CASE | |
| Pseudonymise | Literal | Project Falcon | [CONFIDENTIAL] |
Where rules apply
A rule applies to the Redact workspace in the hub, the Redact API and Redact in Word. Applies to shows this as Redact, API and Word. Redact in Word gets its rules through the API.
If your organisation uses Documents, Applies to has two choices instead:
| Applies to | Used by |
|---|---|
| Redact, API, Word and Documents | The Redact workspace, the Redact API, Redact in Word and Documents |
| Documents only | Documents |
Older rules for Word add-in only are not used anywhere, and the list says so. Create such a rule again for Redact, API and Word if it should apply in Word.
In the Redact workspace
The rules apply to every run, whichever methods the person chooses. Findings from rules are listed under Own masks and rules, grouped as Rule: followed by the label. A fixed replacement cannot be changed in the workspace: the finding says that the organisation's rule sets the wording.
Through the API
POST /v1/redact, text jobs (POST /v1/redact/jobs) and the file operations POST /v1/redact/file and POST /v1/redact/file/jobs Beta apply every active rule your organisation has for Redact, API and Word (or Redact, API, Word and Documents) to every call, with any key and whichever detectors you choose. POST /v1/redact/detect applies them too, and so does Redact in Word, which scans through it. In the answer, a finding from a rule has source and type set to custom.
With the two rules from the example:
curl https://api.komplai.dk/v1/redact \
-H "Authorization: Bearer $KOMPLAI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"text": "Case 24/01234 about Project Falcon is closed. See also case 24/01234 and 25/00077.",
"detectors": ["regex"],
"include": ["mapping"]
}'The answer, shortened to the fields that matter here:
{
"redacted": "Case [CASE-1] about [CONFIDENTIAL] is closed. See also case [CASE-1] and [CASE-2].",
"mapping": {
"[CASE-1]": "24/01234",
"[CONFIDENTIAL]": "Project Falcon",
"[CASE-2]": "25/00077"
},
"entries": [
{ "placeholder": "[CASE-1]", "type": "custom", "value": "24/01234", "confidence": "high", "source": "custom" },
{ "placeholder": "[CONFIDENTIAL]", "type": "custom", "value": "Project Falcon", "confidence": "high", "source": "custom" },
{ "placeholder": "[CASE-2]", "type": "custom", "value": "25/00077", "confidence": "high", "source": "custom" }
]
}A fixed replacement can stand for several originals, so POST /v1/redact/restore never puts it back. It stays in the text and is listed in fixedTokens. The Redact reference has every field.
| Code | When |
|---|---|
processing_policy_changed | The rules changed while the call ran. Send it again. |
invalid_organisation_policy | More than 500 active rules apply to the API, or one of them cannot be used. |
incoherent_redaction_policy | Two rules with different fixed replacements find overlapping text. |
unsafe_placeholder | The text already contains a fixed replacement, or a fixed replacement collides with a label. |
processing_access_withdrawn | You read a text job created before the rules changed. |
Changing rules ends existing text jobs
A text job belongs to the rules it was created under. When the rules that apply to the API change, for example when you create, activate, disable or delete one, or when a suggestion from Documents becomes active, a job created before the change can no longer be read. The next time the job is read or processed, komplai invalidates it and deletes its text and result, and reading it answers 403 processing_access_withdrawn. Read the results you need before you change the rules, and submit the text again as a new job afterwards.
Suggestions from Documents
If your organisation uses Documents, text that people pseudonymise by hand there becomes a suggestion under Suggestions. Only text that looks like a name counts: at least three characters, starting with a capital letter, and not a common word.
Each suggestion shows how many users, sessions and events it is based on. View the evidence lists who pseudonymised the text, in which document and when, up to the 200 most recent events, with a link to open the document and check it.
A suggestion becomes an active rule by itself when two different people, or one person in three different documents, have pseudonymised the same text as the same type. It then applies to Redact, API, Word and Documents. Choose Activate rule to activate a suggestion before that. To stop a rule that came from suggestions, choose Disable: a disabled rule stays disabled when people go on pseudonymising the text, while a deleted rule is created again the next time someone pseudonymises the text by hand.
Lookup sources
Redact Agentic Alpha is an experimental Redact method that can look things up in registers while it works. It runs on komplai's local infrastructure in Denmark. Organisation › Redact › Lookup sources (/settings/redact-sources) has two settings for it:
- Redact Agentic: when it is on, people in your organisation can choose the method, and NER models in alpha and beta, both in Redact and with personal API keys.
- Sources: the sources the method may look up. People choose sources for each run from those you allow. A source that is not ready shows why.
| Source | What is sent | Recipient | Kept by the recipient |
|---|---|---|---|
| CVR | The CVR number or registered company name. Person lookups are not available. | Datafordeleren / Klimadatastyrelsen. Processing location not confirmed. | IP address and user name are logged for up to 9 months. |
| BBR | Building, house-number or property IDs. Lookups do not include residents. | Datafordeleren / Klimadatastyrelsen. Processing location not confirmed. | IP address and user name are logged for up to 9 months. |
| Web search | Bounded search terms, never the whole document. | Brave Software Inc., USA, outside the EU/EEA. | Search queries for up to 90 days. |
| Danish Address Register | Street name, postcode and optional house number. Lookups do not include residents. | Klimadatastyrelsen (Adressevælger). Processing location not confirmed. | Not confirmed. |
| Wikidata, local | Nothing is sent to Wikidata: search terms and Wikidata IDs are looked up in a local copy. | Local infrastructure. | Search terms are not stored. |
CVR and BBR use komplai's access, or your own Datafordeler key. Web search needs your own Brave Search API key. The Danish Address Register needs no key. Wikidata, local appears where komplai's local copy is ready. Keys you save are stored encrypted and never shown again.
Through the API, the method is the request fields engine and sources on POST /v1/redact, text jobs and the file operations. They need a personal API key: an organisation integration key gets integration_not_permitted. Without the setting the call answers agentic_preview_not_enabled, and a source you have not allowed answers agentic_lookup_not_allowed.