Skip to main content

Onboard/Offboard a user in M365 Cloud

This powerful action automates the complex, multi-step processes of onboarding new users into your Microsoft 365 environment or offboarding existing users. It intelligently plans and executes a series of tasks, with optional human approval, to ensure consistency and efficiency.

Why is it useful?

Automating user onboarding and offboarding saves significant technician time, reduces manual errors, ensures security protocols are consistently followed (like blocking sign-ins for departing users), and provides a smoother experience for new and departing employees. It handles tasks like user creation, license assignment, group management, mailbox configurations, and PSA contact updates.

info

This action is available only as a Triggered action in a workflow. Let us know if you'd like to use it as a Scheduled one.

What It Does​

The "Onboard/Offboard a user in M365 Cloud" action performs a sequence of administrative tasks in Microsoft Entra ID (Azure Active Directory), Microsoft 365 services, and your PSA, based on whether you're onboarding or offboarding a user.

Key functionalities include:

  • AI-Driven Task Planning: Analyzes the input ticket and configured settings to determine the precise sequence of operations needed.
  • Human-in-the-Loop Approval: Optionally sends an approval request (as an Adaptive Card in Teams) to designated approvers before executing any changes. This approval can also be managed from the PSA Pod interface.
  • Microsoft Entra ID User Management:
    • Creates new user accounts with specified details (name, email, job title).
    • Resets passwords for existing users.
    • Blocks user sign-in and revokes active sessions.
  • License Management:
    • Assigns specified Microsoft licenses to new users.
    • Unassigns licenses from offboarded users (integrates with Pax8 or Microsoft Partner Center if configured via license_manager_type).
  • Group Management: Adds users to specified Microsoft Entra ID or Microsoft 365 groups.
  • Mailbox Management (via PowerShell integration):
    • Converts user mailboxes to shared mailboxes.
    • Sets up email forwarding.
    • Delegates mailbox access (grants Full Access permission).
  • Device Management: Can initiate an account-only wipe for a user's mobile devices registered in Entra ID.
  • PSA Contact Management:
    • Creates new contacts in your PSA.
    • Deactivates existing contacts in your PSA.
  • Ticket Updates: Can update the originating ticket's title.
  • Password Sharing: Securely shares newly created passwords based on the chosen password_share_strategy.
  • Customizable Steps: Allows fine-grained control over which specific sub-tasks are performed through onboard_user_settings and offboard_user_settings.

How It Works​

This action automates user lifecycle management in Microsoft 365 by orchestrating a series of sub-tasks.

1. Input and Context Gathering​

  • The action is triggered by a PsaTicket that describes the onboarding or offboarding request.
  • It evaluates the type field ("Onboard a User" or "Offboard a User") to determine the primary goal.
  • It incorporates custom_instructions (if use_custom_instructions is enabled) and relevant company-level custom instructions from the EndClientCompany record to tailor the process.
  • The specific settings for onboarding (defined in onboard_user_settings) or offboarding (in offboard_user_settings) dictate which sub-tasks are enabled for execution.

2. AI-Powered Task Planning​

  • Based on the ticket content, selected type, custom_instructions, and the detailed settings within onboard_user_settings or offboard_user_settings, an AI model intelligently determines the sequence of operations required.
  • For Onboarding, this plan might include steps like:
    • Confirming ticket approval (if enabled).
    • Creating the user in Microsoft Entra ID.
    • Assigning specified Microsoft licenses.
    • Adding the user to relevant groups.
    • Creating a corresponding contact in your PSA.
    • Updating the ticket title.
  • For Offboarding, the plan might include:
    • Confirming ticket approval (if enabled).
    • Resetting the user's password.
    • Blocking sign-in access and revoking sessions.
    • Converting the mailbox to a shared mailbox.
    • Setting up email forwarding.
    • Delegating mailbox access.
    • Initiating a wipe for mobile devices.
    • Unassigning Microsoft licenses.
    • Deactivating the contact in your PSA.
    • Updating the ticket title.
  • The AI also identifies any requested actions mentioned in the ticket that are not covered by the standard, enabled steps. These are noted in the tell_msp_about_extra_steps part of the plan for your team's manual review and action.

3. Human Approval (Optional & Recommended)​

  • If individuals are specified in the human_in_the_loop_approvers field, Neo initiates an approval workflow.
  • An Adaptive Card is sent via Microsoft Teams to each selected approver. This card details the ticket and the planned sequence of automated actions.
  • The automation pauses, awaiting an "Accept" or "Decline" response from an approver.
  • Approvers can also manage these requests directly from within your PSA interface if Neo's PSA Pod integration is active for your ConnectWise environment.
  • If the plan is rejected, the automation stops, and a notification is logged. If approved, or if no approvers were designated, the automation proceeds to the execution phase.

4. Automated Execution of Steps​

  • Once approval is granted (or if it wasn't required), Neo systematically executes each step in the AI-generated plan.
  • This involves direct API interactions with Microsoft Entra ID (via Microsoft Graph API) for tasks like creating users, managing licenses, blocking sign-ins, and group memberships.
  • For advanced Exchange Online tasks such as mailbox conversions, email forwarding, and full access delegation, Neo utilizes its PowerShell integration.
  • PSA interactions, like creating or deactivating contacts, are performed using the API of your connected PSA system.
  • The password_share_strategy (e.g., using a Password Pusher link, sending the password directly to the user, or not sharing it at all) is applied if a new password is generated during onboarding.

5. Output and Reporting​

  • Upon completion, the action provides detailed feedback:
    • default_messages_for_msp: A log of all actions taken, their success or failure, and any important notes for the MSP.
    • default_messages_for_end_client: If the process successfully completes tasks with direct end-user impact (e.g., new account creation), user-friendly messages are generated.
    • default_fields_to_update: Any changes made that should be reflected on the PSA ticket (e.g., an updated ticket title).
    • ticket_is_resolved: A boolean flag indicating whether the primary goal (onboarding or offboarding) was successfully accomplished.

Configuration Fields​

When you add the "Onboard/Offboard a user in M365 Cloud" action to a workflow, you'll configure the following:

type​

Determines the overall goal of the automation.

  • Onboard a User: Initiates the process for setting up a new user.
  • Offboard a User: Initiates the process for deactivating an existing user.

license_manager_type​

Specifies the system Neo should use for managing Microsoft licenses, if applicable. (default: NONE)

  • NONE: Neo will manage licenses directly via Microsoft Graph API without a third-party license manager.
  • PAX8: Neo will interact with your Pax8 account for license assignments/unassignments.
  • MS_PARTNER_CENTER: Neo will interact with Microsoft Partner Center for license management.

password_share_strategy​

Defines how a newly generated password (during onboarding) should be shared. (default: Directly to user)

  • Password Pusher Link (https://pwpush.com/): Generates a secure, one-time link via Password Pusher to share the password.
  • Directly to user: Includes the password directly in the notification message to the end user.
  • None: The password is not automatically shared by Neo.

human_in_the_loop_approvers​

(Optional) A list of internal users (selected from Neo's Teams integration) who will receive an approval request in Teams before Neo proceeds with the onboarding/offboarding tasks. Neo will pause until one of the users approves or declines.

use_custom_instructions​

Determines whether to use custom instructions for this action. (default: False) Set to True to provide specific guidance.

custom_instructions​

(Optional) Additional instructions for Neo to consider during the process. This can guide the AI in interpreting the ticket, making decisions about specific steps, or handling unique scenarios. This field is available if use_custom_instructions is True.

onboard_user_settings​

(Optional) Specific settings that control which steps are performed when the type is "Onboard a User". If not configured, default behaviors apply. These settings become available in the UI when "Onboard a User" is selected.

  • Confirm Ticket Approval: (default: False) If True, Neo verifies if the ticket has been approved by an authorized representative (e.g., HR Manager, C-level executive) before proceeding.
  • Create User in Microsoft Entra ID: (default: True) If True, Neo will create the user account in Microsoft Entra (Office 365).
  • Assign Microsoft Licenses: (default: False) If True, Neo will attempt to assign Microsoft licenses to the user. License names should typically be mentioned in the ticket or custom instructions.
  • Add to Groups: (default: False) If True, Neo will add the user to specified groups. Group names should be in the ticket or custom instructions. A Group can be a Microsoft Entra group, a Microsoft 365 group, or a security group.
  • Create PSA Contact: (default: False) If True, Neo will create a corresponding contact in your PSA.
  • Update Ticket Title: (default: False) If True, Neo will update the ticket title with the new user's name.

offboard_user_settings​

(Optional) Specific settings that control which steps are performed when the type is "Offboard a User". If not configured, default behaviors apply. These settings become available in the UI when "Offboard a User" is selected.

  • Confirm Ticket Approval: (default: False) If True, Neo verifies if the ticket has been approved by an authorized representative for offboarding.
  • Reset Password: (default: False) If True, Neo will reset the user's password.
  • Block Sign-in: (default: False) If True, Neo will block the user's sign-in access and revoke active sessions.
  • Convert to Shared Mailbox: (default: False) If True, Neo will convert the user's mailbox to a shared mailbox.
  • Forward Emails: (default: False) If True, Neo will set up email forwarding.
  • Delegate Mailbox: (default: False) If True, Neo will delegate mailbox access (Full Access) to other specified users.
  • Migrate Files: (default: False) If True, Neo will attempt to manage file migration (often involves OneDrive/SharePoint permissions and may log instructions for manual steps if full automation isn't feasible).
  • Wipe Mobile Device: (default: False) If True, Neo will perform an account-only wipe of the user's mobile devices registered in Entra ID.
  • Unassign Microsoft Licenses: (default: False) If True, Neo will unassign Microsoft licenses from the user.
  • Deactivate PSA Contact: (default: False) If True, Neo will mark the corresponding contact as inactive in your PSA.
  • Update Ticket Title: (default: False) If True, Neo will update the ticket title with the offboarded user's name.

Output Fields​

This action makes the following information available to subsequent actions in the workflow:

ticket_is_resolved​

A boolean value (True or False) indicating whether the core onboarding or offboarding process was completed successfully by Neo.

default_messages_for_dashboard​

A list of messages detailing the actions taken by Neo. This is primarily for logging and review in the Neo Dashboard Event History.

default_messages_for_msp​

A list of WorkflowMessages objects containing detailed internal notes about what was done, including successes, failures, and any warnings. These can be used to add notes to the PSA ticket or for internal team notifications.

default_messages_for_end_client​

A list of WorkflowMessages objects containing messages suitable for sending to the end client or the user being onboarded/offboarded (e.g., new account details, confirmation of offboarding).

default_fields_to_update​

A list of field updates that should be applied to the PSA ticket (e.g., changes to the ticket title).

credits_consumed​

An integer indicating the number of credits consumed by this action. Typically, this is 1 credit for the overall process, but sub-actions like license management might incur additional costs if they involve many API calls.

Use Cases​

Fully Automated User Onboarding​

  • Scenario: A new employee hiring process is initiated via a ticket.
  • Workflow Trigger: New ticket created with "New Hire" or "User Onboarding" in the title/type.
  • Actions:
    1. Onboard/Offboard a user in M365 Cloud (Type: Onboard a User)
      • Configure human_in_the_loop_approvers (e.g., IT Manager).
      • Enable relevant onboard_user_settings (create user, assign standard licenses, add to default groups, create PSA contact).
    2. Add Ticket Note (using default_messages_for_msp to log actions taken).
    3. Notify Ticket's Contact (using default_messages_for_end_client to send new account details to the hiring manager or new user).
    4. Update Ticket Fields (using default_fields_to_update for title changes, and potentially setting status to "Pending User Setup" or "Resolved").

Streamlined User Offboarding with Approval​

  • Scenario: An employee resignation ticket is received.
  • Workflow Trigger: Ticket status changed to "Pending Offboarding" or similar.
  • Actions:
    1. Onboard/Offboard a user in M365 Cloud (Type: Offboard a User)
      • Configure human_in_the_loop_approvers (e.g., HR, Security Officer).
      • Enable relevant offboard_user_settings (block sign-in, reset password, convert to shared mailbox, unassign licenses, deactivate PSA contact).
    2. Add Ticket Note (logging actions from default_messages_for_msp).
    3. Notify Internal Team (e.g., Security team, HR) with a summary from default_messages_for_msp.
    4. Update Ticket Fields (to change status to "Offboarding Complete" or "Closed").

Best Practices​

  • Human Approval: For critical processes like user onboarding and especially offboarding, always configure human_in_the_loop_approvers. This provides an essential review step before changes are made. Ensure approvers are trained on how to review the Adaptive Cards in Teams or via the PSA Pod.
  • Detailed Settings: Carefully configure onboard_user_settings and offboard_user_settings to match your organization's standard procedures. Be explicit about which steps Neo should automate.
  • Custom Instructions: Use custom_instructions to handle variations or company-specific requirements not covered by the standard settings. For example, "If the ticket mentions 'VIP user', also add them to the 'VIP Support' M365 group."
  • License Management Integration: If you use Pax8 or Microsoft Partner Center, ensure license_manager_type is correctly set up for seamless license operations.
  • Password Policy: Understand the implications of the chosen password_share_strategy. For maximum security, consider strategies that don't send passwords directly in messages or use temporary passwords that must be changed on first login.
  • PSA Pod: If you use ConnectWise, leverage the PSA Pod integration. This allows technicians to view pending approvals and even trigger these automations directly from the ticket interface.
  • Testing: Thoroughly test your onboarding and offboarding workflows in a non-production environment if possible, or with test user accounts, before enabling them for live tickets.
  • Permissions: Ensure Neo's service principal has the necessary Microsoft Graph API permissions for all the actions you enable (e.g., User.ReadWrite.All, Group.ReadWrite.All, MailboxSettings.ReadWrite, etc.). Refer to NeoAgent documentation for required permissions.
  • Monitor Event History: Regularly review the Event History for this action to see the outcomes, any errors, and the default_messages_for_msp. This helps in refining the process and troubleshooting.
  • Iterate: Start with a few core automated steps and gradually add more complexity as you gain confidence and observe the automation's performance.
  • Teams Notifications: To allow Neo to ask for approval or notify individuals in Teams, ensure the Neo Teams application is correctly configured and users are mapped. Refer to NeoAgent documentation on setting up Teams notifications.