Configure Office 365 Litigation Hold in Custom Command

Question

Hey Support,

Were in the process of just spinning up Adaxes 2014.1 in our environment, and I'm working on build the employee off boarding custom command and can get everything to work but setting the mailbox on litigation hold for the account. We currently do this via powershell using the following command

Set-Mailbox "%displayName%" -LitigationHoldEnabled $true –Itemholdperiod 365

I'll be the first to admit I'm not great at powershell, but when I perform this command and can get it to work successfully I have to establish a remote powershell session. I wish this was that easy (just add that line of pshell to my custom command) but it says the Set-Mailbox is not a recognized cmdlet. This makes sense since I don't have the exchange tools installed on our Adaxes server.

I wanted to you guys what you suggest prior to moving forward. Should I try and come up with a custom script that can do that via a remote session? If thats the case I may need some help. Any other suggestions?

This would be a huge win for me (and im sure others) as if anyone has tried to place a mailbox on litigation hold through Outlook 365's web portal it's so slow. Thanks!

Comments

Hello Ben,

Hmm. maybe you meant In-Place Hold? As stated by Microsoft:

Whereas In-Place Hold provides granular hold capability based on query parameters, hold period, and the ability to place multiple holds, litigation hold only allows you to place all items on hold indefinitely or until hold is removed.

http://technet.microsoft.com/en-us/libr ... 50%29.aspx

So, there is no hold period for a litigation hold. Also, there is no such parameter for Set-Mailbox as –Itemholdperiod.

Also, are you doing this in a federated environment or not? Do you have Exchange installed on-premises?

---

Support,

This is my mistake, the command we use is "Set-Mailbox "Display Name" -LitigationHoldEnabled $true -LitigationHoldDuration 365". This enables litigation hold on the mailbox for 365 days.

http://help.outlook.com/en-us/140/ms.ex ... x#duration

I believe we do run in a federated environment (our team does not serve as the exchange administrators), and we to NOT have an exchange server on premise.

You can log into the Office 365 web console and and perform the same task (without the duration configured) also but we would like to implement this into one command from adaxes. It would be nice to have this all setup into one offboarding task or command.

Thank you!

Answer 1

Hello Ben,

Adaxes allows putting Exchange mailboxes on litigation hold, however currently you cannot specify the hold duration using the built-in functionality. We'll add the possibility to specify a hold duration in the future.

Nevertheless, you can still use a script for this purpose. The following script puts a mailbox on litigation hold for $litigationHoldDuration days:

$litigationHoldDuration = 365 # TODO: modify me

# Get credentials of the Office 365 tenant associated with the user
$o365Credential = $Context.GetOffice365Credential()

# Create a remote PowerShell session to Exchange Online
$session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $o365Credential -Authentication Basic -AllowRedirection
Import-PSSession $session -AllowClobber -DisableNameChecking

# Enable litigation hold
Set-Mailbox "%sAMAccountName%" -LitigationHoldEnabled $true -LitigationHoldDuration $litigationHoldDuration

# Close the remote session and free up resources
Remove-PSSession $session

To put mailboxes on hold automatically once a user gets deprovisioned, you can add the script to the Custom Command that you use for the off-boarding process. To do this:

1. Launch Adaxes Administration Console.
2. In the Console Tree, expand the service node that represents your Adaxes service.
3. Navigate to and select the Custom Command that you use for the off-boarding process. The actions and conditions of the Custom Command will be displayed in the Result Pane (located to the right).
4. Click the Add action to a new set link.
   
5. Select the Run a program or PowerShell script action.
6. Paste the above script in the Script field.
   
7. Enter a short description for the script and click OK.
8. Double-click Always.
9. Select the If has an Exchange mailbox condition.
10. Select has.
    
11. Click OK and save the Custom Command.

Comments

Support, thanks for this! I was able to set the custom command up to execute the powershell script but I am receiving an error on execution (see below).

---

Hello Ben,

The GetOffice365Credential method was introduced only in Update 1 to Adaxes 2014.1 released on July 21, 2014. Probably, you are using an earlier version. You can chose one of the two available options:

1. Upgrade to the latest version of Adaxes.
2. Hard-code the administrative credentials for your Office 365 tenant directly in the script.

If you chose to upgrade, you can download the latest build here. Please follow the upgrade instructions.

For a full list of changes included in the update, see What's New.

If you don't want to upgrade, we'll provide you with a script that uses hard-coded credentials.

---

Thanks again for the response. We are in the middle of a production freeze currently so i'm not sure when I would be able to perform an upgrade to to Adaxes. How difficult would it be to create this script? If you could assist with that we would put it to use.

Thanks!

---

Hello,

Here you are:

$litigationHoldDuration = 365 # TODO: modify me

# Get credentials of the Office 365 tenant associated with the user
$adminName = $Context.RunAs.UserName
$adminPassword = ConvertTo-SecureString -AsPlainText -String $Context.RunAs.Password -Force

$o365Credential = New-Object System.Management.Automation.PsCredential($adminName, $adminPassword)

# Create a remote PowerShell session to Exchange Online
$session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $o365Credential -Authentication Basic -AllowRedirection
Import-PSSession $session -AllowClobber -DisableNameChecking

# Enable litigation hold
Set-Mailbox "%sAMAccountName%" -LitigationHoldEnabled $true -LitigationHoldDuration $litigationHoldDuration

# Close the remote session and free up resources
Remove-PSSession $session

The script imports credentials stored in the parameters of the Run a program or PowerShell script action that launches it. To specify the credentials:

1. In the Run as section of the parameters of the Run a program or PowerShell script action that launches the script, switch the radio button to This account.
2. Click Specify.
   
3. Enter credentials of a user that has administrative access to your Exchange organization and click OK. The credentials will be securely saved in Adaxes service configuration.

---

Hey Support,

I know it's been quite some time since responded to this thread, but I'm back to working on this again and could use some more assistance. We have some users who are on an "Unlimited" litigation hold. We do not want to over write that attribute on these users to a 365 hold, so I need to add some logic to the script.

Update: We are now running Adaxes 2014.1.

So Ideally it needs to...
1. Check to see if the user is on litigation hold
a. If the user is on litigation hold, leave hold as is (do not overwrite to 365 Days)
b. Then remove the Office 365 License (Set-MsolUserLicense -UserPrincipalName "user@xxx.com" –RemoveLicenses “xxxxxxx:ENTERPRISEPACK”)

c. If the user is NOT on Hold, set the Mailbox to a 365 day hold
d. Remove Office 365 License

Is this something you can assist with?

Thanks,

---

Hello Ben,

Yes, that can be done. For this purpose, you'll need to create a new Custom Command as follows:

1. Create a new Custom Command.

2. On step 2 of the Create Custom Command wizard, select the User object type.
   

3. On step 3, add the Run a program or Poweshell script action and paste the following script. The script will check whether Litigation Hold is enabled for the user on which the Custom Command is executed. For users who are not on hold, it will enable Litigation Hold for 365 days.
   

    $litigationHoldDuration = 365 # TODO: modify me
   
    # Get credentials of the Office 365 tenant associated with the user
    $adminName = $Context.RunAs.UserName
    $adminPassword = ConvertTo-SecureString -AsPlainText -String $Context.RunAs.Password -Force
   
    # Get the user's unique identifier in Office 365
    try
    {
        $objectId = [Guid]$Context.TargetObject.Get("adm-O365ObjectId")
    }
    catch
    {
        $Context.LogMessage("The user doesn't have an account in Office 365", "Warning")
        return
    }
   
    $o365Credential = New-Object System.Management.Automation.PsCredential($adminName, $adminPassword)
    try
    {
        # Create a remote PowerShell session to Exchange Online
        $session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $o365Credential -Authentication Basic -AllowRedirection
        Import-PSSession $session -AllowClobber -DisableNameChecking
   
        # Check whether Litigation Hold is enabled
        $mailbox = Get-mailbox $objectId.ToString()
        if ($mailbox.LitigationHoldEnabled)
        {
            return
        }
   
        # Enable litigation hold
        Set-Mailbox $objectId.ToString() -LitigationHoldEnabled $True -LitigationHoldDuration $litigationHoldDuration
    }
    finally
    {
        # Close the remote session and free up resources
        Remove-PSSession $session
    }
   

4. Enter a short description for the script and click OK.

5. Now, you need to add an action that will revoke the Office 365 license. To do this, right-click the action you've just added and click Add New Action.
   

6. Select Activate or modify Office 365 account.

7. Select Modify properties and click the Office 365 Properties button.
   

8. Select only the 1st checkbox for the license you want to revoke.
   

9. Click OK 2 times.

10. Click Next, then click Finish.

---

Thanks Support, this worked perfectly !

---

Hey Guys,

Waaayyy back when you helped me out with creating this script to check on legal holds. It's been working for some time until recently...and now it appears to be a problem with the way the script calls the actors user credentials.

Are we unable to use what I have below anymore? I'll attach an image also of the error i'm receiving.

# Get credentials of the Office 365 tenant associated with the user
$adminName = $Context.RunAs.UserName
$adminPassword = ConvertTo-SecureString -AsPlainText -String $Context.RunAs.Password -Force

---

Attaching error...

---

Hello Ben,

What version of Adaxes are you using?

What radio-button did you select in the Run as section of the Run a program or PowerShell script action? You can check that as follows:

1. Launch Adaxes Administration Console.
2. Navigate to the Custom Command and select it.
3. Double-click the Run a program or PowerShell script action.
4. Check the Run as section.
   

---

Support,

From a Admin console we are using version Version 3.7.13430.0 (64 bit). We also upgraded to the most recent release (2016) about two months ago. When we run this as the "Default Service Administrator" account which is a Global Administrator in Office 365.

Thanks,

---

Hello Ben,

In the latest version of Adaxes you can achieve what you need using If PowerShell script returns true condition and Modify Exchange Properties action. The script will check if Exchange mailbox is put on Litigation hold and return True if it is not. If the script returns true the action will put the mailbox on Litigation hold for 365 days. To do this:

1. Launch Adaxes Administration Console.

2. In the Console Tree, expand the service node that represents your Adaxes service.

3. Navigate to and select the Custom Command that you use for the off-boarding process. The actions and conditions of the Custom Command will be displayed in the Result Pane (located to the right).

4. Double-click the Run a program or PowerShell script action you have for the old script.

5. Select Modify Exchange Properties and click Exchange properties.
   

6. Activate Mailbox Features tab.

7. Select both checkboxes in front of Litigation Hold .
   

8. Select Litigation hold duration (days) and enter the number of days.
   

9. Click OK three times.

10. Right-click the set in the right view pane and click Add condition.

11. Select If PowerShell script returns true, enter a short description and paste the script into the Script field.

     $mailboxParams = $Context.TargetObject.GetMailParameters()
    
     # Get properties of Litigation Hold
     $litigationHold = $mailboxParams.MailboxFeatures.GetItemByType(
         "ADM_EXCHANGE_MAILBOXFEATURETYPE_LITIGATIONHOLD")
    
     $Context.ConditionIsMet = -not($litigationHold.Enabled)
    

    

12. Click OK and save the changes.

Finally you will have a set like the following: