mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-07 16:04:41 +08:00
251 lines
11 KiB
Markdown
251 lines
11 KiB
Markdown
# Policy Schema — Full Element Reference
|
|
|
|
Source: `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/`
|
|
|
|
---
|
|
|
|
## Path Enums
|
|
|
|
> **Surface principle.** The MDAPI surface is the narrower `*Type` enum in `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/`. The wider runtime enums (`RulePrincipalPath`, `RuleResourcePath`, `RuleContextPath` in `enforce-o-matic-api/.../enums/`) drive Cedar evaluation and DAO behavior; values absent from the `*Type` enums are **not authorable via MDAPI**.
|
|
|
|
### `<principalPath>` / `<valuePrincipalPath>` — `RulePrincipalPathType` (6 values)
|
|
|
|
| Value | Meaning |
|
|
|-------|---------|
|
|
| `IS_AUTHENTICATED_USER_PATH` | Boolean "is principal an authenticated user" |
|
|
| `ASSIGNED_PERMISSIONS_PATH` | Principal's assigned permissions (pair with `valueReferenceType=CUSTOM_PERMISSION`) |
|
|
| `USER_ID` | Principal user ID |
|
|
| `ORGANIZATION_ID` | Principal org ID |
|
|
| `USER_ROLE_ID` | Principal role ID |
|
|
| `RBAC_TAGS` | Principal RBAC tags |
|
|
|
|
Outside contract (not in `RulePrincipalPathType`): `IS_INTERNAL`, `CONTACT_ID`, `SCALAR_ATTRIBUTE`, `PLURAL_ATTRIBUTE`, `PLACEHOLDER`. Use a runtime RuleProvider for these.
|
|
|
|
### `<resourcePath>` / `<valueResourcePath>` — `RuleResourcePathType` (16 values)
|
|
|
|
| Value | Meaning |
|
|
|-------|---------|
|
|
| `NAMESPACE` | Resource namespace |
|
|
| `ENTITY` | Entity (object) reference |
|
|
| `FIELD` | Field reference |
|
|
| `ENTITYTYPE` | Entity type — pair with `IS` operator and `{"t":"Text","v":"FIELD"}` literal |
|
|
| `ENTITYKIND` | Entity kind bits |
|
|
| `FIELDKIND` | Field kind bits |
|
|
| `DATASPACE` | Resource dataspace |
|
|
| `TAG` | Custom or standard tag |
|
|
| `OBJECT_TAG` | Object-level tag |
|
|
| `CLASSIFICATION` | Custom or standard classification |
|
|
| `IMPLICITTAG` | Implicit tag |
|
|
| `RECORDFIELD` | Field of the record being evaluated (RLS) — pair with `<valueDomain>Schema:field</valueDomain>` |
|
|
| `OBJECT_CLASSIFICATION` | Object-level classification |
|
|
| `EXPRESSION` | Compound expression — pair with `<resourceExpression>` PROJECTION |
|
|
| `OBJECT_DATASPACE` | Object-level dataspace |
|
|
| `RECORDFIELDTYPE` | Type of a record field |
|
|
|
|
### `<contextPath>` / `<valueContextPath>` — `RuleContextPathType` (1 value)
|
|
|
|
| Value | Cedar attribute | Use case |
|
|
|-------|-----------------|----------|
|
|
| `SESSION_DATASPACE` | `context.sessionDataspace` | Session-scoped dataspace check |
|
|
|
|
Outside contract: `SESSION_CONSUMER_ID`, `CONTEXT_AGENT_ID`, `CONTEXT_AGENT_VERSION_ID` (IDENTIFIED_RECORD / agentic — runtime RuleProvider only).
|
|
|
|
> Some steelthread fixtures use `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` in `<valuePrincipalPath>` (`conditionScalarAttributeValidSteelThread`). They deploy in the ftest harness because the entity object is type-tolerant, but these values are outside `RulePrincipalPathType` — not sanctioned for new work.
|
|
|
|
---
|
|
|
|
## `<operator>` — `RuleDefinitionOperatorType`
|
|
|
|
| Operator | Use with |
|
|
|----------|----------|
|
|
| `EQUALS` / `NOT_EQUALS` | Scalar equality |
|
|
| `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUALS` | Numeric / date |
|
|
| `IN` | Scalar IN set |
|
|
| `LIKE` | String pattern |
|
|
| `CONTAINS_ANY` | Set has at least one of |
|
|
| `CONTAINS_ALL` | Set has all of |
|
|
| `CONTAINS_NONE` | Set has none of |
|
|
| `IS` | Type / kind check (pair with `ENTITYTYPE` + `{"t":"Text","v":"FIELD"}` literal) |
|
|
| `EXISTS` | RLS join exists (pair with `resourcePath=EXPRESSION` + PROJECTION) |
|
|
| `HIERARCHICALLY_ABOVE` / `HIERARCHICALLY_BELOW` | Hierarchy traversal — pair with `valueReferenceType=HIERARCHY` |
|
|
|
|
---
|
|
|
|
## `<conditions>` — Full Schema (`PolicyRuleDefinitionCondition.java`)
|
|
|
|
| Element | Notes |
|
|
|---------|-------|
|
|
| `<clause>` | `WHEN` or `UNLESS` — match the wrapper |
|
|
| `<operator>` | Always required |
|
|
| `<resourcePath>` | What about the resource to inspect |
|
|
| `<principalPath>` | What about the principal to inspect |
|
|
| `<contextPath>` | Context attribute (SESSION_DATASPACE only) |
|
|
| `<valueDomain>` | `Schema:field` — for RECORDFIELD comparisons |
|
|
| `<resourceAlias>` | Used in PROJECTION join expressions |
|
|
| `<valueBit>` | Entity/field-kind bits |
|
|
| `<valuePrincipalPath>` | Path the value comes from |
|
|
| `<valueResourcePath>` | Path the value comes from |
|
|
| `<valueContextPath>` | Path the value comes from |
|
|
| `<policyRuleValueSet>` | Literal or named-reference values (see below) |
|
|
| `<resourceExpression>` | `PolicyJsonExpression` type=PROJECTION (RLS join) |
|
|
| `<principalExpression>` | `PolicyJsonExpression` type=SOQLTARGETLISTEXPR (SOQL principal) |
|
|
| `<whereClauseConjunction>` | Sub-expression for nested conditions |
|
|
| `<policyRuleDefinitionCondition>` | Nested children — used with `whereClauseConjunction` |
|
|
|
|
---
|
|
|
|
## `<policyRuleValueSet>` — `PolicyRuleValueSet.java`
|
|
|
|
Three fields (all optional at schema level, but a non-empty value set needs at least one):
|
|
|
|
### Literal values — `<valueString>`
|
|
|
|
For typed literals, embed JSON (escape `"` to `"`):
|
|
```xml
|
|
<valueString>{"t":"Text","v":"FIELD"}</valueString>
|
|
<valueString>{"t":"Boolean","v":true}</valueString>
|
|
<valueString>{"t":"Number","v":42}</valueString>
|
|
```
|
|
|
|
For plain string equality:
|
|
```xml
|
|
<valueString>Toxico</valueString>
|
|
```
|
|
|
|
### Named references — `<valueReference>` + `<valueReferenceType>`
|
|
|
|
| `valueReferenceType` | Refers to | Typical path pairing |
|
|
|----------------------|-----------|----------------------|
|
|
| `CUSTOM_TAG` | Custom tag by devName | `resourcePath=TAG` |
|
|
| `STANDARD_TAG` | Standard tag — **fully qualified** (e.g. `DataGovernanceTags.ExternalData.Visibility.Public`) | `resourcePath=TAG` |
|
|
| `CUSTOM_CLASSIFICATION` | Custom classification | `resourcePath=CLASSIFICATION` |
|
|
| `STANDARD_CLASSIFICATION` | Standard classification — **fully qualified** (e.g. `DataGovernanceClassifications.DataCategorization.FieldUsage.Active`) | `resourcePath=CLASSIFICATION` |
|
|
| `HIERARCHY` | Hierarchy definition | `operator=HIERARCHICALLY_BELOW/ABOVE`, `resourcePath=RECORDFIELD` |
|
|
| `CUSTOM_PERMISSION` | Custom permission | `principalPath=ASSIGNED_PERMISSIONS_PATH` |
|
|
| `DATASPACE` | Dataspace | `resourcePath=DATASPACE` or `contextPath=SESSION_DATASPACE` |
|
|
|
|
> **Tag/classification dev names are NOT free-form.** The deploy-time validator checks `<valueReference>` against the org's taxonomy. To find the exact string: `sf project retrieve start --target-org <alias> --metadata "PolicyRuleDefinition:<existing-rule-name>"` and copy `<valueReference>` verbatim.
|
|
|
|
Multiple `<policyRuleValueSet>` siblings inside one condition are OR-combined.
|
|
|
|
---
|
|
|
|
## JSON Expressions — `PolicyJsonExpression.java` (min API 66.0)
|
|
|
|
`<type>` must match the location:
|
|
|
|
| Location | Required `type` |
|
|
|----------|-----------------|
|
|
| Top-level `<resourceExpression>` (TRANSFORM rule arg list) | `ARGLIST` |
|
|
| `<conditions>` `<resourceExpression>` (RLS join) | `PROJECTION` |
|
|
| `<conditions>` `<principalExpression>` (SOQL principal) | `SOQLTARGETLISTEXPR` |
|
|
|
|
### ARGLIST — Transform argument list
|
|
|
|
```xml
|
|
<resourceExpression>
|
|
<type>ARGLIST</type>
|
|
<version>1</version>
|
|
<transformExpression>
|
|
<argument>
|
|
<type>NUMBER</type>
|
|
<value>4</value>
|
|
</argument>
|
|
</transformExpression>
|
|
</resourceExpression>
|
|
```
|
|
|
|
`TransformExpressionArgumentType` = `STRING` or `NUMBER`. Use when `<resourceTransform>` takes parameters (e.g. `LAST_N_CHARS_RESOURCE_TRANSFORM` needs N).
|
|
|
|
### PROJECTION — RLS join
|
|
|
|
Used inside `<conditions>` with `resourcePath=EXPRESSION` and `operator=EXISTS`:
|
|
|
|
```xml
|
|
<resourceExpression>
|
|
<type>PROJECTION</type>
|
|
<version>1</version>
|
|
<projection>
|
|
<join>
|
|
<schema>testDMO__dlm</schema>
|
|
<alias>test 1</alias>
|
|
<predicate>
|
|
<comparator>EQUALS</comparator>
|
|
<attribute>testDMO__dlm:name__c</attribute>
|
|
<on>
|
|
<resourceAlias>resource</resourceAlias>
|
|
<schema>testDMO__dlm</schema>
|
|
<field>age__c</field>
|
|
</on>
|
|
</predicate>
|
|
</join>
|
|
</projection>
|
|
</resourceExpression>
|
|
```
|
|
|
|
### SOQLTARGETLISTEXPR — Principal SOQL target
|
|
|
|
Scalar:
|
|
```xml
|
|
<principalExpression>
|
|
<type>SOQLTARGETLISTEXPR</type>
|
|
<version>1</version>
|
|
<soqlTarget>
|
|
<select>age__c</select>
|
|
</soqlTarget>
|
|
</principalExpression>
|
|
```
|
|
|
|
Plural (use a set operator: `CONTAINS_ANY` / `CONTAINS_NONE` / `CONTAINS_ALL`):
|
|
```xml
|
|
<principalExpression>
|
|
<type>SOQLTARGETLISTEXPR</type>
|
|
<version>1</version>
|
|
<soqlTarget>
|
|
<plural>true</plural>
|
|
<relationship>pluralAttributes__r</relationship>
|
|
<select>name__c</select>
|
|
</soqlTarget>
|
|
</principalExpression>
|
|
```
|
|
|
|
> `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` principal expressions are outside MDAPI contract. Fixture-only.
|
|
|
|
---
|
|
|
|
## `<resourceTransform>` Enum (TRANSFORM rules only)
|
|
|
|
| Value | Effect |
|
|
|-------|--------|
|
|
| `NULL_RESOURCE_TRANSFORM` | Replace with NULL |
|
|
| `EMPTY_STRING_RESOURCE_TRANSFORM` | Replace with `""` |
|
|
| `LAST_N_CHARS_RESOURCE_TRANSFORM` | Keep last N chars (N via ARGLIST) |
|
|
| `FIRST_N_CHARS_RESOURCE_TRANSFORM` | Keep first N chars (N via ARGLIST) |
|
|
| `ALL_BUT_LAST_N_CHARS_RESOURCE_TRANSFORM` | Mask last N |
|
|
| `ALL_BUT_FIRST_N_CHARS_RESOURCE_TRANSFORM` | Mask first N |
|
|
| `CLOSEST_ORDER_OF_MAGNITUDE_RESOURCE_TRANSFORM` | Round to nearest power of 10 |
|
|
| `TRUNCATE_DATE_RESOURCE_TRANSFORM` | Truncate date precision |
|
|
| `ROUND_RESOURCE_TRANSFORM` | Round number |
|
|
| `REPLACE_ALL_CHARS_RESOURCE_TRANSFORM` | Replace each char |
|
|
|
|
Pure transforms (NULL, EMPTY_STRING) need no `<resourceExpression>`. Parameterized transforms (FIRST_N, LAST_N, ROUND, REPLACE_ALL_CHARS, TRUNCATE_DATE) take args via ARGLIST.
|
|
|
|
---
|
|
|
|
## File Cross-References
|
|
|
|
| Concern | File |
|
|
|---------|------|
|
|
| Rule wrapper | `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/PolicyRuleDefinition.java` |
|
|
| Set wrapper | `…/PolicyRuleDefinitionSet.java` |
|
|
| Conditions | `…/PolicyRuleDefinitionClauseConjunction.java`, `…/PolicyRuleDefinitionCondition.java` |
|
|
| Value set | `…/PolicyRuleValueSet.java` + `…/PolicyRuleValueSetReferenceType.java` |
|
|
| JSON expression | `…/PolicyJsonExpression.java` + `…/PolicyJsonExpressionType.java` |
|
|
| ARGLIST | `…/TransformExpression.java` + `…/TransformExpressionArgument.java` |
|
|
| PROJECTION | `…/ProjectionExpression.java` + `…/ProjectionJoin.java` + `…/PolicyJoinPredicate.java` |
|
|
| SOQLTARGETLISTEXPR | `…/PrincipalExpression.java` |
|
|
| Resource domain | `…/PolicyRuleResourceDomain.java` |
|
|
| Enums | `Category.java`, `Effect.java`, `RuleConsumer.java`, `PrincipalAuthenticationLevel.java`, `RulePrincipalScopeType.java`, `RuleResourceScopeType.java`, `RulePrincipalPathType.java`, `RuleResourcePathType.java`, `RuleContextPathType.java`, `RuleDefinitionClauseType.java`, `RuleDefinitionOperatorType.java`, `ResourceTransform.java` |
|
|
| IDENTIFIED_RECORD condition validator | `PolicyRuleDefinitionCondObject.java:332-339` |
|
|
| Agentic RuleProvider canonical builder | `AgenticPolicyRuleProviderService.java:130-260` |
|