psIMAlerts Usage

psIMAlerts is a Powershell® CmdLet (Send-Alert) for IT Administrators to send bulk Instant Messages Alerts. The (get-help -full) usage is listed below.

psIMAlerts provides a number of very flexible options to specify recipients by supplying:

1. the id of a single Active Directory account
2. the id of a single Active Directory group (all members of an group and nested groups are recipients)
3. the name of an Exchange server(accounts assigned a mailbox on the Exchange server are recipients)
4. the name of an Lync or OCS pool (accounts assigned to the pool are recipients)

In addition recipients can be provided by pipelining.
For step by step usage see the psIMAlerts tutorials.

Send-Alert

psIMAlerts Usage

Send-Alert

    -Identity <String>   
    or  -ExchangeServerName <String>  
    or  -PoolName <String> 
    or [-InputObject] <Object>

[-Priority <String>] [-SubjectLine <String>]
[-MessageText <String>] [-From <String>] [-IMAccountCredential <PSCredential>]
[-ExchangeAccountCredential <PSCredential>] [-MessageHtmlTemplateFName <String>]
[-ContextUrl <String>] [-PassThru] [-WhatIf] [-Log] [-LogFileName <String>]
[-FastLookupMode] [-WarningAction <ActionPreference>]
[-WarningVariable <String>] [<CommonParameters>]

DESCRIPTION
The Send-Alert cmdlet sends Instant Messaging (IM) alerts to a number of
recipients.

Recipients can be supplied using the ''Identity'' option, the ''ExchangeServer
Name'' option, the ''PoolName'' option, from the Pipeline or the ''InputObject''
option. If the ''Identity'' option is supplied the target can an
Active Directory group or account.

The alert message can be a plain text or a HTML message.

To lookup mailboxes in the Active Directory using a different account use
the ''ExchangeAdminCredentials'' option.

To send the message From another account use the ''From'' option.

To get the detailed results of the command, use the Verbose and PassThru
parameters.

PARAMETERS
-Priority <String>
Specifies the name of a priority of the message. Options are ''Normal'',
''Urgent'', ''Emergency'' and ''Non-Urgent''. The default value is ''Normal''.

Required? false
Position? named
Default value Normal
Accept pipeline input? false
Accept wildcard characters? false

-SubjectLine <String>
Specifies the title of the message.
This parameter is required.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-MessageText <String>
Specifies the plain text message to send to each recipient.

This option can not be used with ''MessageHtmlTemplateFName'' option.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-From <String>
Specifies the account which will appear as the sender of the Instant
MEssage alert. The default is IMAlerts@<default SIP domain>.

Required? false
Position? named
Default value IMAlerts@<default SIP domain>
Accept pipeline input? false
Accept wildcard characters? false

-IMAccountCredential <PSCredential>
Specifies a user account that has OCS Admin permission to perform this
action. The default is the current user.

Supply a PSCredential object, such as one generated by the Get-Credenti
al cmdlet.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ExchangeAccountCredential <PSCredential>
By default the lookup of mailbox accounts is performed by the current a
ccount or the ''default exchange admin'' account specified during the ins
tall.

Use the ''ExchangeAccountCredentials'' option to specify an alternate Exc
hange Admin account (with View-Only or greater permission) to perform l
ookups of recipients.

''ExchangeAccountCredentials'' option is used only if the ''ExchangeServer
Name'' option is supplied.

Supply a PSCredential object, such as one generated by the Get-Credenti
al cmdlet.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-MessageHtmlTemplateFName <String>
Specifies the name of a (.html) text file which contains the Hypertext
message to send. This option can not be used with ''MessageText'' option.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ContextUrl <String>
Specifies a URL that the desktop client will display in the context pan
e of the conversation window (a mini webpage displayed to right of the
message text). The URL can be an internal or external however as the co
ntext pane is of small fixed size it is recommended the the URL provide
d is customised for the small dimensions. Note: OCS2007R2 platform ONLY
.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-PassThru
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WhatIf
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Log
Text file logging is off by default. If this option is supplied text fi
le logging is turned on. The default log location is

%ProgramData%\\Blue Quality Studios\\psIMAlert\\psIMAlert.log

Use the ''LogFileName'' option to supply an alternative log file name.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-LogFileName <String>
Text file logging is off by default. If the ''Log'' option is supplied
then ''LogFileName'' option provides the log file name.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-FastLookupMode
By default each recipient lookup is performed sequentially. To improvem
ent performance use ''FastLookupMode'' switch.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WarningAction <ActionPreference>
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WarningVariable <String>

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ExchangeServerName <String>
Specifies the short name of an Exchange server. Recipients will be all
online accounts with a mailbox on this server.

This option can not be used with the ''Identity'' option.

To obtain the list of accounts the default account must have Exchange A
dmin rights. To use another account use the ''ExchangeAccountCredential''
option.

Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Identity <String>
Specifies a single target from the Active Directory. The target can a b
e single account or a single group.

If the target is a group then all online members (including nested grou
p members) will be recipients.

A single account can be supplied as a Login Id (samAccountName), SIP UR
I (msRTCSIP-PrimaryUserAddress), Primary SMTP Email Address (mail), Dis
play Name (displayName), Active Directory Distinguished Name (dn) or Le
gacy Exchange DN (legacyExchangeDn).

A single group can be supplied as a Security Id (samAccountName), Activ
e Directory Distinguished Name (dn) or Display Name (displayName).

Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-InputObject <Object>

Required? false
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-PoolName <String>
The RTC pool name. For OCS 2007 R2 enter the short pool name (eg. Pool001)
For Lync Server use the SiteId:PoolId (eg: 1:1 would be pool 1 in site 1)

Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
None

OUTPUTS
Microsoft.PowerShell.Commands.EnterpriseAlertReport

NOTES

-------------- EXAMPLE 1 --------------

C:\\PS>send-alert -MessageText "Close of business report is due at 3.30pm to
day." -Toast "COB 3.30 today" -Identity "NationalManagersGroup"

Send a message to each member of the National Manager''s Group who is online
with a popup tray icon bubble (Toast) of "COB 3.30 today" from the (defaul
t) account IMAlerts@<defaultsipdomain>.

-----------These command will generate a report listing each manager in the
group, their status (''online'' or ''offline'') and if they opened the alert m
essage.

-------------- EXAMPLE 2 --------------

C:\\PS>send-alert -ServerName Exch01 -Priority ''Urgent'' -MessageText "Corpor
ate Email server {ServerName} will go offline in 10 minutes for 1 hour for
routine maintenance." -Toast "Maintenance Corp Email Server" -From emailOut
This email address is being protected from spambots. You need JavaScript enabled to view it.

Send a message to each online account which has a corporate mailbox on Exch
ange Server named ''Exch01''. Accounts with status of ''offline'' are not sent
an alert. The pop-up tray icon bubble (Toast) is "Maintenance of Corp Email
Server". The default desktop account used to run the CmdLet is both an Ex
change Admin (to obtain the list of accounts from a privileged portion of t
he Active Directory) and OCS administrator. The message will come from an a
ccount with the SipUri of This email address is being protected from spambots. You need JavaScript enabled to view it.. If this is the first time r
un using ''From'' then psIMAlerts with register as a ''Trusted Application''.

-----------This command send an email outage alert to all accounts on the n
amed Exchange server. A report listing each account their status and if the
y open the message is created.

-------------- EXAMPLE 3 --------------

C:\\PS>([ADSI]"LDAP://CN=DL0001,OU=Groups,DC=Company,DC=com").member | send-
alert -MessageText "All analysis to the Green room (Level 1) for Director b
riefing on major changes in 15 minutes." -Toast "Special Briefing - Green R
oom - 15 minutes" -From This email address is being protected from spambots. You need JavaScript enabled to view it.

The members of an Active Directory Group as a list of accounts is piped to
the Send-Alert Cmdlet. Each online account in the piped list will be sent a
message with a popup tray bubble (Toast) of ''Special Briefing - Green Room
- 15 minutes''. The message will come from an account with the SipUri of IM
This email address is being protected from spambots. You need JavaScript enabled to view it..

Note: If this is the first time run using ''From'' then psIMAlerts with regis
ter as a ''Trusted Application''.

Note: On Windows Server 2008 use GetADgroupMember CmdLet to get group membe
rship.

Note: To get a group membership by the group''s displayname use
$searcher = New-Object System.DirectoryServices.DirectorySearcher
$searcher.Filter = ''(&(objectClass=User)(displayName=<ReplaceWithDisplayN
ame>))''
$objGroup= $searcher.FindOne()
$objGroup | send-alert ...

-----------This command sends alerts to accounts piped to the cmdlet and a
report is produced.

-------------- EXAMPLE 4 --------------

C:\\PS>send-alert -MessageHtmlTemplateFName c:\\Alerts\\Templates\\CEO-Market-B
riefing.html -Toast "Merger Announcement" -Identity "AllStaff" -From CEOsOf
fice

Send a message to each member of the AllStaff Group who are online with a p
opup tray icon bubble (Toast) of "Merger Announcement" from the account wit
h SipURI of CEOsOffice@.

----------- A report is generate of who was online and who opened the messa
ge.

-------------- EXAMPLE 5 --------------

C:\\PS>$secpasswd = ConvertTo-SecureString "PlainTextPassword" -AsPlainText
-Force
$credAdmin = New-Object System.Management.Automation.PSCredential ("ItAdmin
istrator", $secpasswd)
send-alert -MessageText "Close of business report is due at 3.30pm today."
-Toast "COB 3.30 today" -Identity "NationalManagersGroup" -IMAccountCredent
ial $credAdmin -ExchangeAccountCredential $credAdmin

Send a message to each online members of the National Manager''s Group with
a popup tray icon bubble (Toast) of "COB 3.30 today" from the (default) acc
ount IMAlerts@<defaultsipdomain>. Use the authority of account ''ItAdministr
ator'' with a password of ''PlainTextPassword'' to perform the operation.

----------- This command sends messages and generates a report of who was o
nline and who opened the message.