OVERRIDE sync mode

OVERRIDE is the answer to a recurring frustration: a managed integration owns an entity, you set a custom property on that entity, and the next time the integration runs, your property gets wiped out.

OVERRIDE fixes that. When you push an OVERRIDE for a property on an entity, JupiterOne records the override and reapplies it after every subsequent integration sync. Your value sticks.

Before you use OVERRIDE

OVERRIDE is a powerful tool — it lets you pin custom values onto entities owned by a managed integration so those values survive every future integration sync. That's exactly what makes it useful, and it's also why it's worth using deliberately.

Once you set a property with OVERRIDE, the source integration won't reconcile or correct it for you, so you become the source of truth for that value. That matters most when overrides touch properties that drive security decisions — things like riskLevel, complianceTier, or publicAccessApproved — because what you set is what alert rules, queries, and the people responding to them will see. A stale or incorrect override can quietly hide the integration's real view and lead to missed alerts or a misleading picture of risk.

This is why we gate access to OVERRIDE. Contact JupiterOne support to request access for your account.

When to use OVERRIDE

• The entity is managed by an integration (you can see _integrationInstanceId on it).
• You want a custom property to persist across that integration's future runs.
• You only need to set entity properties — relationships are not allowed.
• You are working with up to 10,000 entities per sync job. Larger updates need to be split.

If the entity isn't owned by an integration, or you don't need persistence across integration runs, PATCH is simpler.

Example use cases

Criticality tiers on managed repositories

Your platform team labels every GitHub repo with a criticality tier (tier-1, tier-2, tier-3) used by your incident response runbook. The labels live in an internal spreadsheet, not GitHub topics.

• Scope: repo-criticality
• Mode: OVERRIDE
• Why OVERRIDE: GitHub doesn't store this attribute, so the GitHub integration never produces it — but it also re-syncs the entity completely each run, which would clear a property set with PATCH. OVERRIDE makes the criticality stick.

Compliance scope on managed devices

Your compliance team determines which laptops are in scope for SOC 2 evidence collection. The Jamf integration provides device entities; your team pushes complianceScope: "soc2" onto the relevant subset.

• Scope: device-compliance-scope
• Mode: OVERRIDE

Restrictions

• Entity-only. Relationships are rejected with Relationship uploads are not allowed for OVERRIDE sync jobs.
• _id is required on every entity. The entity must already exist; entries whose _id does not match a current entity are silently skipped on finalize.
• 10,000 entities maximum per sync job. Larger updates need to be split into separate sync jobs (different scopes).
• source must be api.
• New sync mode. OVERRIDE is in early release. Contact JupiterOne support to enable it for your account.

Required entity fields

Property	Type	Description
_id	string	Required. The JupiterOne _id of the existing entity to override. Entries with no matching entity are silently skipped.

Any custom property keys (those without a leading _) included alongside _id are applied as overrides. Properties starting with _ are reserved for system metadata and ignored.

Updating and removing overrides

Overrides are tracked per (entity, scope) pair. To change what's overridden:

• Update values for an entity: re-upload the entity with the new property values to the same scope. Properties not included in the new upload are removed from that scope's overrides on that entity.
• Stop overriding a specific entity: re-upload the scope without that entity included. Its overrides for that scope are dropped on the next finalize.
• Clear all overrides for a scope: start a new OVERRIDE sync job with the same scope, finalize without uploading any entities. Every override registered in that scope is removed.
• Restore the integration's value immediately: after clearing the override, re-run the source integration. The next integration sync writes its own value.

Precedence when multiple scopes override the same property

Two OVERRIDE sync jobs in different scopes can target the same entity. The rule is the override that most recently changed the value wins, per property:

• If scope A (created Monday) overrides criticality on entity X, and scope B (created Tuesday) also overrides criticality on entity X, the value from scope B takes effect — it is the more recent override. Scope A's value is recorded but does not apply for that property while B's override exists.
• This is evaluated per property, not per scope. If scope B overrides a different property on the same entity (say, owner), each property is resolved independently — B wins criticality, and whichever scope most recently changed owner wins that one.
• If the winning scope's override is removed, the property falls back to the next most recent remaining override for that property, and only when no scope overrides it at all does it return to the integration's value.

This behavior is deliberate: the override that most recently changed a property takes effect immediately rather than being silently blocked by an older scope. To take over a property, change its value in another scope; to hand it back, remove the override that currently wins.

Change from earlier behavior

Prior to this change, precedence was oldest scope wins — the first scope to override a property held it until removed, and later overrides were silently ignored. That could leave a stale scope pinning a value no live override could update. Precedence is now recency-based. If you relied on the old rule, review scopes that override the same property on the same entity.

Example: newest override wins

Repository X is managed by the GitHub integration. Two teams each run an OVERRIDE scope that sets criticality on it.

Step	Action	criticality on X	Why
1	GitHub integration syncs X; no override yet	(integration value)	Nothing overrides criticality.
2	Scope repo-criticality overrides criticality = tier-3	tier-3	Only override present.
3	Scope ir-priority overrides criticality = tier-1	tier-1	ir-priority changed the value more recently, so it wins.
4	GitHub integration syncs X again	tier-1	Overrides are re-applied after every sync; the newest still wins.
5	ir-priority removes its override (re-finalize without X)	tier-3	Falls back to the next most recent remaining override — repo-criticality.
6	repo-criticality removes its override too	(integration value)	No scope overrides criticality; it returns to what GitHub provides.

The key point is step 3: the newer scope takes the property immediately — under the old oldest-wins rule, repo-criticality (step 2) would have kept tier-3 and ir-priority would have been ignored. Steps 5–6 show the reverse on removal: the property falls back through remaining overrides by recency, and only returns to the integration value when nothing overrides it.

OVERRIDE vs the entity mutation API

The GraphQL updateEntity mutation also sets properties that persist across managed-integration syncs. The two tools are complementary, not interchangeable:

• OVERRIDE is a sync job. You group up to 10,000 entities under a scope, push them in one batch, and finalize. The scope is the unit of management — you update or remove the whole set together.
• updateEntity is a single-entity mutation over GraphQL. It's the right tool for "I just need to set criticality = tier-1 on this one repository" or scripts that walk a small list of entities. There's no scope and no finalize step.

If both an OVERRIDE sync job and an updateEntity call have set the same property on the same entity, the one that most recently changed the value takes precedence — they are resolved by recency, the same way two OVERRIDE scopes are. Removing the winner restores the other channel's value, and removing both restores the integration's value.

note

This changed alongside the precedence rule above. Previously the OVERRIDE-supplied value always took precedence over updateEntity. Overrides applied by a tagging rule are a separate case and still outrank both OVERRIDE sync jobs and updateEntity regardless of recency.

In practice, pick one channel per property to avoid surprises. Use OVERRIDE when you have a list and want it managed as a unit; use updateEntity when you don't.

Edge case: PATCH followed by OVERRIDE

If a PATCH sync job previously set the same property on an entity, and you later create an OVERRIDE for that property and then remove the override, the value visible immediately after removal may be the old PATCH value rather than the integration's value. The next managed-integration run reconciles this and restores the integration's value.

In practice, this rarely matters — but if you're switching a property from PATCH to OVERRIDE management, expect a brief window after override removal where the property shows the PATCH value.

Example: full OVERRIDE sync job

POST /persister/synchronization/jobs

{
  "source": "api",
  "syncMode": "OVERRIDE",
  "scope": "repo-criticality"
}

POST /persister/synchronization/jobs/{jobId}/upload

{
  "entities": [
    {
      "_id": "b75aad77-89eb-5ce6-939c-86322517af6b",
      "criticality": "tier-1"
    },
    {
      "_id": "da1c53ef-a543-5daa-8206-37e652c795cf",
      "criticality": "tier-2"
    }
  ]
}

POST /persister/synchronization/jobs/{jobId}/finalize

After finalize, the two repositories carry the criticality property, and they will continue to do so after every GitHub integration sync.

Operational notes

• Find a target entity's _id with J1QL. For example: FIND github_repo WITH name='platform-api' RETURN _id.
• Reuse stable scopes. Treat each scope as a long-lived label for one logical override set (repo-criticality, not override-2026-04-28). Reusing the scope is how you update or remove overrides cleanly.
• OVERRIDE does not create entities. If _id doesn't match an existing entity, that row is silently skipped — no error, no creation.
• Custom property names cannot start with _. Those are reserved for system metadata.

Common errors

Error	Cause	Fix
OVERRIDE sync mode is not enabled for this account	Account is not on the allowlist.	Contact JupiterOne support to request access.
Relationship uploads are not allowed for OVERRIDE sync jobs	Uploaded relationships to an OVERRIDE job.	OVERRIDE only accepts entities.
OVERRIDE sync jobs are limited to 10000 entities per job	Upload exceeds the per-job entity cap.	Split across multiple sync jobs.
Entity property not visible after finalize	_id did not match any existing entity.	Confirm the _id exists; OVERRIDE silently skips unknown _ids.

See the API reference for the complete error table.