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 oldest scope 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 A takes effect. The override from scope B is recorded but silently ignored for that property until scope A's override is removed.
• This is evaluated per property, not per scope. If scope B overrides a different property on the same entity (say, owner), that one applies normally even though A is older.

This behavior is deliberate: it prevents a new sync job from accidentally trampling an override another team has already established. If you need to change an existing override, update the scope that owns 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 OVERRIDE-supplied value takes precedence. Removing the override (by re-finalizing the OVERRIDE scope without the entity, or clearing the scope) restores the value from the most recent updateEntity call.

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.