synchronization_jobs

Creates, updates, deletes, gets or lists a synchronization_jobs resource.

Overview

Name	synchronization_jobs
Type	Resource
Id	entra_id.service_principals.synchronization_jobs

Fields

The following fields are returned by SELECT queries:

get

Retrieved navigation property

Name	Datatype	Description
id	string	The unique identifier for an entity. Read-only.
bulkUpload		The bulk upload operation for the job.
schedule		Schedule used to run the job. Read-only.
schema		The synchronization schema configured for the job.
status		Status of the job, which includes when the job was last run, current job state, and errors.
synchronizationJobSettings	array	Settings associated with the job. Some settings are inherited from the template.
templateId	string	Identifier of the synchronization template this job is based on.

list

Retrieved collection

Name	Datatype	Description
id	string	The unique identifier for an entity. Read-only.
bulkUpload		The bulk upload operation for the job.
schedule		Schedule used to run the job. Read-only.
schema		The synchronization schema configured for the job.
status		Status of the job, which includes when the job was last run, current job state, and errors.
synchronizationJobSettings	array	Settings associated with the job. Some settings are inherited from the template.
templateId	string	Identifier of the synchronization template this job is based on.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	service_principal_id, synchronization_job_id		Retrieve the existing synchronization job and its properties.
list	select	service_principal_id		List existing jobs for a given application instance (service principal).
insert	insert	service_principal_id		Create new synchronization job with a default synchronization schema. The job is created in a disabled state. Call Start job to start synchronization.
update	update	service_principal_id, synchronization_job_id
delete	delete	service_principal_id, synchronization_job_id	If-Match	Stop the synchronization job, and permanently delete all the state associated with it. Synchronized accounts are left as-is.
get_bulk_upload	exec	service_principal_id, synchronization_job_id		The bulk upload operation for the job.
update_bulk_upload	exec	service_principal_id, synchronization_job_id
delete_bulk_upload	exec	service_principal_id, synchronization_job_id	If-Match
pause	exec	service_principal_id, synchronization_job_id		Temporarily stop a running synchronization job. All the progress, including job state, is persisted, and the job will continue from where it left off when a start call is made.
provision_on_demand	exec	service_principal_id, synchronization_job_id		Select a user and provision the account on-demand. The rate limit for this API is 5 requests per 10 seconds.
restart	exec	service_principal_id, synchronization_job_id		Restart a stopped synchronization job, forcing it to reprocess all the objects in the directory. Optionally clears existing the synchronization state and previous errors.
start	exec	service_principal_id, synchronization_job_id		Start an existing synchronization job. If the job is in a paused state, it continues processing changes from the point where it was paused. If the job is in quarantine, the quarantine status is cleared. Don't create scripts to call the start job continuously while it's running because that can cause the service to stop running. Use the start job only when the job is currently paused or in quarantine.
validate_credentials	exec	service_principal_id, synchronization_job_id		Validate that the credentials are valid in the tenant.
schema_directories_discover	exec	service_principal_id, synchronization_job_id, directory_definition_id		Discover the latest schema definition for provisioning to an application.
schema_parse_expression	exec	service_principal_id, synchronization_job_id		Parse a given string expression into an attributeMappingSource object. For more information about expressions, see Writing Expressions for Attribute Mappings in Microsoft Entra ID.
validate_credentials_2	exec	service_principal_id

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
directory_definition_id	string	The unique identifier of directoryDefinition
service_principal_id	string	The unique identifier of servicePrincipal
synchronization_job_id	string	The unique identifier of synchronizationJob
If-Match	string	ETag

SELECT examples

get

Retrieve the existing synchronization job and its properties.

SELECT
id,
bulkUpload,
schedule,
schema,
status,
synchronizationJobSettings,
templateId
FROM entra_id.service_principals.synchronization_jobs
WHERE service_principal_id = '{{ service_principal_id }}' -- required
AND synchronization_job_id = '{{ synchronization_job_id }}' -- required
;

list

List existing jobs for a given application instance (service principal).

SELECT
id,
bulkUpload,
schedule,
schema,
status,
synchronizationJobSettings,
templateId
FROM entra_id.service_principals.synchronization_jobs
WHERE service_principal_id = '{{ service_principal_id }}' -- required
;

INSERT examples

insert

Create new synchronization job with a default synchronization schema. The job is created in a disabled state. Call Start job to start synchronization.

INSERT INTO entra_id.service_principals.synchronization_jobs (
id,
schedule,
status,
synchronizationJobSettings,
templateId,
bulkUpload,
schema,
service_principal_id
)
SELECT 
'{{ id }}',
'{{ schedule }}',
'{{ status }}',
'{{ synchronizationJobSettings }}',
'{{ templateId }}',
'{{ bulkUpload }}',
'{{ schema }}',
'{{ service_principal_id }}'
RETURNING
id,
bulkUpload,
schedule,
schema,
status,
synchronizationJobSettings,
templateId
;

Manifest

# Description fields are for documentation purposes
- name: synchronization_jobs
props:
  - name: service_principal_id
    value: "{{ service_principal_id }}"
    description: Required parameter for the synchronization_jobs resource.
  - name: id
    value: "{{ id }}"
    description: |
      The unique identifier for an entity. Read-only.
  - name: schedule
    value: "{{ schedule }}"
    description: |
      Schedule used to run the job. Read-only.
  - name: status
    value: "{{ status }}"
    description: |
      Status of the job, which includes when the job was last run, current job state, and errors.
  - name: synchronizationJobSettings
    description: |
      Settings associated with the job. Some settings are inherited from the template.
    value:
      - name: "{{ name }}"
        value: "{{ value }}"
  - name: templateId
    value: "{{ templateId }}"
    description: |
      Identifier of the synchronization template this job is based on.
  - name: bulkUpload
    value: "{{ bulkUpload }}"
    description: |
      The bulk upload operation for the job.
  - name: schema
    value: "{{ schema }}"
    description: |
      The synchronization schema configured for the job.

UPDATE examples

update

No description available.

UPDATE entra_id.service_principals.synchronization_jobs
SET 
id = '{{ id }}',
schedule = '{{ schedule }}',
status = '{{ status }}',
synchronizationJobSettings = '{{ synchronizationJobSettings }}',
templateId = '{{ templateId }}',
bulkUpload = '{{ bulkUpload }}',
schema = '{{ schema }}'
WHERE 
service_principal_id = '{{ service_principal_id }}' --required
AND synchronization_job_id = '{{ synchronization_job_id }}' --required
RETURNING
id,
bulkUpload,
schedule,
schema,
status,
synchronizationJobSettings,
templateId;

DELETE examples

delete

Stop the synchronization job, and permanently delete all the state associated with it. Synchronized accounts are left as-is.

DELETE FROM entra_id.service_principals.synchronization_jobs
WHERE service_principal_id = '{{ service_principal_id }}' --required
AND synchronization_job_id = '{{ synchronization_job_id }}' --required
AND If-Match = '{{ If-Match }}'
;

Lifecycle Methods

get_bulk_upload

The bulk upload operation for the job.

EXEC entra_id.service_principals.synchronization_jobs.get_bulk_upload 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required, 
@$select='{{ $select }}', 
@$expand='{{ $expand }}'
;

update_bulk_upload

Success

EXEC entra_id.service_principals.synchronization_jobs.update_bulk_upload 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required 
@@json=
'{
"id": "{{ id }}", 
}'
;

delete_bulk_upload

Success

EXEC entra_id.service_principals.synchronization_jobs.delete_bulk_upload 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required, 
@If-Match='{{ If-Match }}'
;

pause

Temporarily stop a running synchronization job. All the progress, including job state, is persisted, and the job will continue from where it left off when a start call is made.

EXEC entra_id.service_principals.synchronization_jobs.pause 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required
;

provision_on_demand

Select a user and provision the account on-demand. The rate limit for this API is 5 requests per 10 seconds.

EXEC entra_id.service_principals.synchronization_jobs.provision_on_demand 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required 
@@json=
'{
"parameters": "{{ parameters }}"
}'
;

restart

Restart a stopped synchronization job, forcing it to reprocess all the objects in the directory. Optionally clears existing the synchronization state and previous errors.

EXEC entra_id.service_principals.synchronization_jobs.restart 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required 
@@json=
'{
"criteria": "{{ criteria }}"
}'
;

start

Start an existing synchronization job. If the job is in a paused state, it continues processing changes from the point where it was paused. If the job is in quarantine, the quarantine status is cleared. Don't create scripts to call the start job continuously while it's running because that can cause the service to stop running. Use the start job only when the job is currently paused or in quarantine.

EXEC entra_id.service_principals.synchronization_jobs.start 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required
;

validate_credentials

Validate that the credentials are valid in the tenant.

EXEC entra_id.service_principals.synchronization_jobs.validate_credentials 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required 
@@json=
'{
"applicationIdentifier": "{{ applicationIdentifier }}", 
"templateId": "{{ templateId }}", 
"useSavedCredentials": {{ useSavedCredentials }}, 
"credentials": "{{ credentials }}"
}'
;

schema_directories_discover

Discover the latest schema definition for provisioning to an application.

EXEC entra_id.service_principals.synchronization_jobs.schema_directories_discover 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required, 
@directory_definition_id='{{ directory_definition_id }}' --required
;

schema_parse_expression

Parse a given string expression into an attributeMappingSource object. For more information about expressions, see Writing Expressions for Attribute Mappings in Microsoft Entra ID.

EXEC entra_id.service_principals.synchronization_jobs.schema_parse_expression 
@service_principal_id='{{ service_principal_id }}' --required, 
@synchronization_job_id='{{ synchronization_job_id }}' --required 
@@json=
'{
"expression": "{{ expression }}", 
"testInputObject": "{{ testInputObject }}", 
"targetAttributeDefinition": "{{ targetAttributeDefinition }}"
}'
;

validate_credentials_2

Success

EXEC entra_id.service_principals.synchronization_jobs.validate_credentials_2 
@service_principal_id='{{ service_principal_id }}' --required 
@@json=
'{
"applicationIdentifier": "{{ applicationIdentifier }}", 
"templateId": "{{ templateId }}", 
"useSavedCredentials": {{ useSavedCredentials }}, 
"credentials": "{{ credentials }}"
}'
;