🔍 Code Extractor

Represents an invitation entity for adding external users to an organization, providing access to invitation details and the invited user information.

Purpose

This class models an invitation in Microsoft Graph API for onboarding external users to an organization. It encapsulates invitation properties including the invited user's display name, email address, custom message information, and the resulting user entity. The class follows the Microsoft Graph invitation flow where invitations are created, sent via email with redemption URLs, and redeemed by users through a browser-based process. It inherits from Entity and provides property-based access to invitation data with lazy loading of related objects.

Source Code

class Invitation(Entity):
    """Represents an invitation that is used to add external users to an organization.

    The invitation process uses the following flow:

      - An invitation is created
      - An invitation is sent to the invited user (containing an invitation link)
      - The invited user clicks on the invitation link, signs in and redeems the invitation and creation of the
        user entity representing the invited user completes
      - The user is redirected to a specific page after redemption completes

     Creating an invitation will return a redemption URL in the response (inviteRedeemUrl).
     The create invitation API can automatically send an email containing the redemption URL to the invited user,
     by setting the sendInvitationMessage to true. You can also customize the message that will be sent to
     the invited user. Instead, if you wish to send the redemption URL through some other means, you can set the
     sendInvitationMessage to false and use the redeem URL from the response to craft your own communication.
     Currently, there is no API to perform the redemption process. The invited user has to click on the inviteRedeemUrl
     link sent in the communication in the step above, and go through the interactive redemption process in a browser.
     Once completed, the invited user becomes an external user in the organization.
    """

    @property
    def invited_user_display_name(self):
        # type: () -> Optional[str]
        """The display name of the user being invited."""
        return self.properties.get("invitedUserDisplayName", None)

    @property
    def invited_user_email_address(self):
        # type: () -> Optional[str]
        """The email address of the user being invited."""
        return self.properties.get("invitedUserEmailAddress", None)

    @property
    def invited_user_message_info(self):
        """"""
        return self.properties.get("invitedUserMessageInfo", InvitedUserMessageInfo())

    @property
    def invited_user(self):
        """The user created as part of the invitation creation."""
        return self.properties.get(
            "invitedUser",
            User(self.context, ResourcePath("invitedUser", self.resource_path)),
        )

    def get_property(self, name, default_value=None):
        if default_value is None:
            property_mapping = {
                "invitedUserMessageInfo": self.invited_user_message_info,
                "invitedUser": self.invited_user,
            }
            default_value = property_mapping.get(name, None)
        return super(Invitation, self).get_property(name, default_value)

Parameters

Parameter Details

context: The client context object required for API communication, inherited from Entity base class. Used to make requests to Microsoft Graph API.

resource_path: The resource path identifying this invitation entity in the Microsoft Graph API hierarchy, inherited from Entity base class.

Return Value

Instantiation returns an Invitation object that provides read-only access to invitation properties. The properties return various types: invited_user_display_name and invited_user_email_address return Optional[str], invited_user_message_info returns InvitedUserMessageInfo object, invited_user returns User object, and get_property returns the requested property value or default_value if not found.

Class Interface

Methods

Attributes

Dependencies

• typing
• office365.directory.invitations.message_info
• office365.directory.users.user
• office365.entity
• office365.runtime.paths.resource_path

Required Imports

from typing import Optional
from office365.directory.invitations.message_info import InvitedUserMessageInfo
from office365.directory.users.user import User
from office365.entity import Entity
from office365.runtime.paths.resource_path import ResourcePath

Usage Example

# Assuming you have a configured GraphClient context
from office365.graph_client import GraphClient
from office365.directory.invitations.invitation import Invitation

# Initialize client with credentials
client = GraphClient.with_credentials(tenant_id, client_id, client_secret)

# Create an invitation (typically done through client.invitations.add())
invitation = client.invitations.get_by_id('invitation-id')

# Access invitation properties
print(f"Display Name: {invitation.invited_user_display_name}")
print(f"Email: {invitation.invited_user_email_address}")

# Access the invited user entity
user = invitation.invited_user
print(f"User ID: {user.id}")

# Access message info
message_info = invitation.invited_user_message_info

# Use get_property for flexible property access
email = invitation.get_property('invitedUserEmailAddress', 'default@example.com')

Best Practices

• This class is typically instantiated by the Microsoft Graph client library, not directly by users. Use client.invitations methods to create or retrieve invitations.
• Properties are read-only and lazily loaded from the underlying properties dictionary. Access them through property decorators rather than direct dictionary access.
• The invited_user property returns a User object with its own resource path, allowing navigation to related user data.
• Use get_property() method for safe property access with default values to handle missing properties gracefully.
• The invitation redemption process is browser-based and cannot be automated through this API. Users must click the inviteRedeemUrl link.
• When creating invitations through the API, set sendInvitationMessage appropriately based on whether you want automatic email sending or custom communication.
• The class inherits from Entity, so it has access to standard entity operations like update, delete, and property management.
• Properties are cached in the internal properties dictionary; refresh the entity if you need updated data from the server.

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class InvitationCollection 77.8% similar

  A collection class for managing Microsoft Graph Invitation entities, providing methods to create and manage invitations for external users to join an organization.

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

• class InvitedUserMessageInfo 62.0% similar

  A data class that configures invitation messages for invited users, including CC recipients, custom message body, and language preferences.

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

• class InvitationParticipantInfo 61.1% similar

  A data class representing an entity being invited to a group call, containing participant identification, visibility settings, and call routing configuration.

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

• class SPInvitationCreationResult 55.5% similar

  A data class representing the result of creating a SharePoint invitation, containing email, invitation link, and success status.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/sharing/invitation/creation_result.py

• class InviteParticipantsOperation 54.6% 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