Using ORCA report in Azure Automation

[lindonm]

Hi, I managed to get this working in Azure Automation, however it left me with several feedback points / suggestions.

I will paste the entire AzA powershell runbook below so that you can provide advice to others & test yourself, comments & suggestions are inline.

#Runbook designed for Azure Automation

#Display verbose output in test pane
$VerbosePreference = "Continue"

#Imported (required) Modules
<#
ExchagneOnlineManagement
ORCA
#>

#Get credentials for use throughout runbook. Note that the user must have "View Only Configuration" role as a minimum.
Write-Output "Getting Credential"
$Credential = Get-AutomationPSCredential -Name 'EOPAdmin' -Verbose

#Set email parameters - Note that Azure servers are in UTC, so convert the time to a local timezone
$EmailFrom = 'valid o365 user@yourdomain.com'
$EmailTo = @('me@myaddress.com')
$EmailSubject = 'Exchange Online ORCA Report - ' + [System.TimeZoneInfo]::ConvertTimeBySystemTimeZoneId((Get-Date), 'AUS Eastern Standard Time')
$EmailBody = 'See attached file for the ORCA report
Generated using https://github.com/cammurray/orca
Report ran in Azure Automation'
$ReportPath = "$($env:LOCALAPPDATA)\Microsoft\ORCA\ORCAReport.html"

#Connect to Exchange Online - Don't let the Get-ORCAReport function attempt to connect, it needs to be the newer module & specify creds (No MFA)
Write-Output "Creating session"
Connect-ExchangeOnline -Credential $Credential

#Run the ORCA Report tools
Write-Output "Running ORCA - Expect a warning about no program to open HTML file"
#Note: The synopsis for Get-ORCAReport states to use "-Report" to specify the filename however the parameter is actually named "Output"
#Suggested updates for author (camurray@microsoft.com)

- Update synopsis with correct parameter names

- Update synposis / readme with required role "View Only Configuration"

- Add an option to not automatically attempt to execute the HTML file (running in Azure Automation this does not work) - Generates error "No application is associated with the specified file for this operation"

- Add a "Return" statement which is a string containing the full file path OR just return the HTML as a string so it can be used as an email body

---- Regarding the HTML itself, it does not render in Outlook or Outlook.com well if used as the message body - I believe this is due to the CSS used and the fact that it is not embedded.

---- Consider embedding the CSS and using more cross browser friendly HTML. Some tips here:

------- https://email.uplers.com/blog/email-rendering-issues-in-outlook-and-hacks/

------- https://www.emailonacid.com/blog/article/email-development/how-to-create-excellent-emails-for-outlook-com/

------- https://www.contactmonkey.com/blog/outlook-rendering-issues

------- https://litmus.com/blog/a-guide-to-rendering-differences-in-microsoft-outlook-clients

- Add an option to auto update (no user interaction) so that we don't have to manally import the updated module into our Automation account

---- Note that even with the "NoUpdate" parameter, an error is still generated if the NuGet module is not installed

------- "Find-Module : NuGet provider is required to interact with NuGet-based repositories. Please ensure that '2.8.5.201' or newer version of NuGet provider is installed."

------- This is caused by the "Invoke-ORCAVersionCheck" being run without checking if "NoUpdate" is specified

- Update HTML to include timezone info where it displays the date/time and/or allow user to specify timezone - Timezone of where the script is running can be found with "[System.TimeZoneInfo]::Local.ToString()"

#eg: (attachment)

$ReportFile = Get-ORCAReport -NoConnect -AutoUpdate -DontOpenHTML -OutputType 'FilePath'

Send-MailMessage -Attachments $ReportFile (+other SMTP parameters)

#eg: (string)

$ReportHTML = Get-ORCAReport -NoConnect -AutoUpdate -DontOpenHTML -OutputType 'HTMLString'

Send-MailMessage -Body $ReportHTML (+other SMTP parameters)

#Run the report
Get-ORCAReport -NoConnect -NoUpdate -Output $ReportPath

#If using the HTML as the email body, convert the system.object (array of strings) into a single string first
#Not using this as it doesn't render well as yet
#$FileContent = Get-Content -Path $ReportPath
#$EmailBody = Out-String -InputObject $FileContent

#For some reason, you have to get the credentials again or sending the email fails - Maybe a quirk of AZ Automation?
Write-Output "Getting Credential"
$Credential = Get-AutomationPSCredential -Name 'EOPAdmin' -Verbose

#Send an email with the report attached
Write-Output "Sending Email"
Send-MailMessage -Attachments $ReportPath
-Body $EmailBody -BodyAsHtml:$True
-DeliveryNotificationOption @('OnFailure') -From $EmailFrom
-SmtpServer 'smtp.office365.com' -Priority 'Normal'
-Subject $EmailSubject -To $EmailTo
-Credential $Credential -UseSsl:$True
-Port 587 -Verbose:$True
-Debug:$False -ErrorAction Continue
-WarningAction Continue

[lindonm]

Apologies for the formatting, not sure why some lines are massive text

[cammurray]

thanks @lindonm

Awesome idea! I did have a thought about putting this in to Azure Automation so it could regularly run. It would also be cool if we could develop some 'state' in to it as well, showing settings that have "changed" since the last run - some involvement there with azure table storage, maybe?

but in the mean time, love the idea. will definitely look at making it more 'automatable'.

[lindonm]

State view over time would be great, and a table would be the simplest option IMO - If you wanted to go all out it could be a web app (to display results), automation (to schedule the report) and a table to store history - But i'm guessing that would be some massive changes :)

[cammurray]

Hi @lindonm

Some updates here,

We now support modular outputs, which means a couple of things;

• Out of the box support for outputting now to HTML, JSON, and CosmosDB
• Support for running without displaying the HTML (running Invoke-ORCA -Output HTML -OutputOptions @{HTML=@{DisplayReport=$False}} will run ORCA without displaying the HTML and you'll just get back the path to the outputted HTML as a returned object)
• Support for adding an additional output type - i'll look at including SMTP as an output type

[cammurray]

I'm thinking that this is fixed now.. but feel free to re-open if there's further issues with automation.