🔍 Code Extractor

Represents the status of long-running communications operations in Microsoft Graph API, tracking operation progress and results through notifications.

Purpose

CommsOperation is an Entity subclass that models asynchronous communication operations in Microsoft 365. It tracks the lifecycle of long-running operations (like calls, meetings, or other communication actions) and provides status information. The class supports both immediate responses and notification-based updates. When an operation returns with 'completed' or 'failed' status, no further notifications occur. When status is 'notStarted', 'running', or null, subsequent updates arrive via notification channels. This enables proper handling of asynchronous communication workflows.

Source Code

class CommsOperation(Entity):
    """
    Represents the status of certain long-running operations.

    This resource can be returned as the response to an action, or as the content of a commsNotification.

    When it is returned as a response to an action, the status indicates whether there will be subsequent notifications.
    If, for example, an operation with status of completed or failed is returned, there will not be any subsequent
    operation via the notification channel.

    If a null operation, or an operation with a status of notStarted or running is returned, subsequent updates will
    come via the notification channel.
    """

    @property
    def client_context(self):
        """
        Unique Client Context string. Max limit is 256 chars.
        """
        return self.properties.get("clientContext", None)

    @property
    def result_info(self):
        """
        The result information.
        """
        return self.properties.get("resultInfo", ResultInfo())

Parameters

Parameter Details

bases: Inherits from Entity class, which provides base functionality for Microsoft Graph API entities including property storage and management

Return Value

Instantiation returns a CommsOperation object that provides access to operation status information. The client_context property returns a string (max 256 chars) or None. The result_info property returns a ResultInfo object containing operation result details, defaulting to an empty ResultInfo() if not present.

Class Interface

Methods

Attributes

Dependencies

• office365.communications.result_info
• office365.entity

Required Imports

from office365.communications.result_info import ResultInfo
from office365.entity import Entity
from office365.communications.comms_operation import CommsOperation

Usage Example

# Assuming you have a Graph API client configured
from office365.communications.comms_operation import CommsOperation

# Typically obtained from an API response, not directly instantiated
# Example: After initiating a call operation
operation = comms_client.start_call()  # Returns CommsOperation

# Check client context
context = operation.client_context
if context:
    print(f"Operation context: {context}")

# Get result information
result = operation.result_info
if result:
    print(f"Operation status: {result.status}")
    print(f"Result code: {result.code}")

# Check if operation needs monitoring
if operation.properties.get('status') in ['notStarted', 'running', None]:
    # Set up notification listener for updates
    print("Operation in progress, monitoring for notifications...")
elif operation.properties.get('status') in ['completed', 'failed']:
    print("Operation finished, no further notifications expected")

Best Practices

• CommsOperation objects are typically returned by API calls rather than directly instantiated by users
• Always check the operation status to determine if notification monitoring is needed
• Operations with 'completed' or 'failed' status will not send further notifications
• Operations with 'notStarted', 'running', or null status require notification channel setup
• The client_context property has a maximum length of 256 characters
• Use result_info property to access detailed operation results and error information
• The properties dictionary (inherited from Entity) contains the raw operation data
• Handle None values appropriately when accessing client_context as it may not always be present
• ResultInfo objects are created with default values if not present in the response

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Operation 65.3% similar

  A class representing the status of a long-running operation, inheriting from Entity to track operation metadata.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/onenote/operations/operation.py

• class InviteParticipantsOperation 65.1% similar

  Represents the status of a long-running participant invitation operation triggered by a call to the participant-invite API in Microsoft Graph Communications.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/operations/invite_participants.py

• class UpdateRecordingStatusOperation 64.5% similar

  A class representing the response format for an update recording status action in Microsoft 365 communications operations.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/operations/update_recording_status.py

• class UnmuteParticipantOperation 63.2% similar

  A class representing the response format for an unmute participant operation in a communications context, inheriting from CommsOperation.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/operations/unmute_participant.py

• class CancelMediaProcessingOperation 61.6% similar

  A class representing the response format for canceling a media processing operation in Microsoft 365 Communications services.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/operations/cancel_media_processing.py