🔍 Code Extractor

Manages Microsoft 365 directory synchronization jobs that periodically poll for changes in one directory and push them to another directory, specific to an application instance in a tenant.

Purpose

The SynchronizationJob class represents and controls a background synchronization job in Microsoft 365 that handles directory synchronization between systems. It provides methods to start and pause synchronization operations, and access to the job's current status and schema configuration. This class is used to manage the lifecycle of synchronization jobs, monitor their state, and control their execution. It inherits from Entity, indicating it's part of a larger Microsoft Graph API object model.

Source Code

class SynchronizationJob(Entity):
    """
    Performs synchronization by periodically running in the background, polling for changes in one directory,
    and pushing them to another directory. The synchronization job is always specific to a particular instance
    of an application in your tenant. As part of the synchronization job setup, you need to give authorization
    to read and write objects in your target directory, and customize the job's synchronization schema.
    """

    def pause(self):
        """
        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.
        """
        qry = ServiceOperationQuery(self, "pause")
        self.context.add_query(qry)
        return self

    def start(self):
        """
        Start an existing synchronization job. If the job is in a paused state, it will continue processing changes
        from the point where it was paused. If the job is in quarantine, the quarantine status will be cleared.
        Do not 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.
        """
        qry = ServiceOperationQuery(self, "start")
        self.context.add_query(qry)
        return self

    @property
    def status(self):
        """Status of the job, which includes when the job was last run, current job state, and errors."""
        return self.properties.get("status", SynchronizationStatus())

    @property
    def schema(self):
        """The synchronization schema configured for the job."""
        return self.properties.get(
            "schema",
            SynchronizationSchema(
                self.context, ResourcePath("schema", self.resource_path)
            ),
        )

Parameters

Parameter Details

__init__: The constructor is inherited from Entity base class. Typically requires a context object (for API communication) and resource path information to identify the specific synchronization job instance in the Microsoft 365 tenant.

Return Value

Instantiation returns a SynchronizationJob object representing a specific synchronization job. The pause() and start() methods return self for method chaining. The status property returns a SynchronizationStatus object containing job execution state and error information. The schema property returns a SynchronizationSchema object representing the synchronization configuration.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.directory.synchronization.job import SynchronizationJob
from office365.directory.synchronization.schema import SynchronizationSchema
from office365.directory.synchronization.status import SynchronizationStatus
from office365.entity import Entity
from office365.runtime.paths.resource_path import ResourcePath
from office365.runtime.queries.service_operation import ServiceOperationQuery

Usage Example

# Assuming you have a configured context object
from office365.directory.synchronization.job import SynchronizationJob

# Get or create a synchronization job instance (typically from a service principal)
# sync_job = service_principal.synchronization.jobs.get_by_id('job_id')

# Start the synchronization job
sync_job.start()
context.execute_query()

# Check the job status
status = sync_job.status
print(f"Job state: {status.state}")
print(f"Last execution: {status.lastExecution}")

# Access the synchronization schema
schema = sync_job.schema
print(f"Schema directories: {schema.directories}")

# Pause the job when needed
sync_job.pause()
context.execute_query()

# Method chaining is supported
sync_job.start().pause()
context.execute_query()

Best Practices

• Always call context.execute_query() after start() or pause() to execute the queued operations
• Do not create scripts that continuously call start() while the job is running, as this can cause service disruption
• Use start() only when the job is paused or in quarantine state
• Monitor the status property to check job state before performing operations
• Ensure proper authorization is configured before starting synchronization
• The job maintains state between pause and start operations, continuing from where it left off
• Check for quarantine status in the job status before attempting to restart
• Methods return self for fluent interface/method chaining support
• Properties (status, schema) are lazily loaded from the properties dictionary

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class SynchronizationStatus 71.7% similar

  A data class representing the current status of a synchronization job, including progress details and quarantine information.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/synchronization/status.py

• class Synchronization 71.6% similar

  Represents Azure Active Directory (Azure AD) identity synchronization capabilities through Microsoft Graph API, managing automated provisioning and de-provisioning of user identities and roles.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/synchronization/synchronization.py

• class SynchronizationSchema 70.5% similar

  A class representing a synchronization schema that defines what objects will be synchronized and how they will be synchronized between systems.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/synchronization/schema.py

• class SynchronizationProgress 65.6% similar

  A class representing the progress of a synchronization job toward completion in Microsoft Office 365 services.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/synchronization/progress.py

• class SynchronizationJobRestartCriteria 61.2% similar

  A class representing the criteria for restarting a synchronization job in Microsoft 365/Office 365 services.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/synchronization/job_restart_criteria.py