Troubleshooting
Problem
A Planning Analytics administrator would like to send email notifications by using a TM1 Turbo Integrator process.
Resolving The Problem
Note: SMTP is enabled by default in all Planning Analytics on Cloud environments.
1. Create a Powershell script noting this information:
- SMTP Server: mail.planning-analytics.ibmcloud.com.
- Sender Address: <ENV>@mail.planning-analytics.ibmcloud.com, where <ENV> is the portion of your environment's URL before the .planning-analytics.ibmcloud.com. For example, given the URL "abcyxzprod.planning-analytics.ibmcloud.com" the sender address would be "abcyxzprod@mail.planning-analytics.ibmcloud.com".
- Port: 587.
- Protocol: TLS 1.2 script updates might be needed to specify the protocol.
- Body Message Encoding: UTF-8, script updates might be needed to specify the encoding.
- No username or password is required.
Script Example A - Attachment
[System.Net.ServicePointManager]::SecurityProtocol = 'TLS12'
Send-MailMessage -SmtpServer 'mail.planning-analytics.ibmcloud.com' -UseSsl -Port 587 -From 'abcyxzprod@mail.planning-analytics.ibmcloud.com' -To 'recipient@domain.com' -Attachment '.\file.txt' -Subject 'Test Email from the Cloud with attachment' -Body 'Test Email from the Cloud' -BodyAsHtml -Encoding ([System.Text.Encoding]::UTF8)
Notes.
i) The attachment path above is relative to from where the script is run; in this case both script and text file are in the same location. However, you can use the physical path instead:
-Attachment 's:\prod\tm1\file.txt'
If there is a space in the path to the attachment, then you need to use a workaround, as PowerShell does not play nicely with spaces in paths.
Workaround: Use the Windows Server MKLINK feature.
ii) When writing an email that uses Powershell, we must consider the following two facts.
a. The spaces between words are not read by Powershell, so whenever we are writing a long email, use single quotation marks, for example:
-Subject 'Test Email from the Cloud'
Or
-Body 'Test Email from the Cloud via Bat that Calls PS1 in S drive with attachments.'
b. If we are using special characters in subject or body of the email, then enclose them in double quotation marks, such as:
-Subject 'Planning Analytics Admin "-" Daily updates "-" In Balance' -Body 'The task listed in "-"text"-" file has completed.'
iii) If you want to include multiple recipients, create a variable on the line before the Send-MailMessage in the Powershell script, and include the email addresses in single quotation marks, separated by a comma.
Script Example B - Multiple Recipients
[System.Net.ServicePointManager]::SecurityProtocol = 'TLS12'
$recipients = 'email1@domain.com', 'email2@domain.com'
Send-MailMessage -SmtpServer 'mail.planning-analytics.ibmcloud.com' -UseSsl -Port 587 -From 'abcyxzprod@mail.planning-analytics.ibmcloud.com' -To $recipients -Subject 'Test Email from the Cloud' -Body 'Test Email from the Cloud' -BodyAsHtml -Encoding ([System.Text.Encoding]::UTF8)
2. Execute the script from the Turbo Integrator process - NOTE: this will not run from Powershell on the Rich tier
- On the Epilog tab, insert an ExecuteCommand function.
- Syntax: ExecuteCommand( CommandLine, Wait );
Example
ExecuteCommand( 'Powershell S:\prod\tm1\email.ps1', 0 );
Note. When writing the ExecuteCommand in Turbo Integrator, if there are any spaces in the PS1 file path or file name, you must insert a grave (backtick) character to alert Powershell of an oncoming space.
Example
ExecuteCommand( 'Powershell S:\prod\planning` sample\email` notifications.ps1', 0 );
3. It is important to note that the entire email (header, body, attachment) cannot be larger than 20 MB. If the email size is greater, the email message will not be sent.
4. The Powershell script can be written to accept parameters, so that messages customized by the Turbo Integrator process at run time, can be sent.
Script Example C - Pass Parameters from a TI Process
param(
[String[]]$emailTo,
[String]$emailSubject = 'No subject',
[String]$emailBody = 'No message',
[String[]]$emailAttach,
[String]$emailServer = 'mail.planning-analytics.ibmcloud.com',
[Int32]$emailPort = 587,
[String]$emailFrom = 'abcyxzprod <abcyxzprod@mail.planning-analytics.ibmcloud.com>'
)
# Configure Transport Layer Security (TLS)
[System.Net.ServicePointManager]::SecurityProtocol = 'TLS12'
# Determine if a file attachment has been specified
if($emailAttach){
# Send email with attachment
Send-MailMessage -SmtpServer $emailServer -UseSsl -Port $emailPort -From $emailFrom -To $emailTo -Subject $emailSubject -Body $emailBody -BodyAsHtml -Attachments $emailAttach -Encoding ([System.Text.Encoding]::UTF8)
}else{
# Send email without attachment
Send-MailMessage -SmtpServer $emailServer -UseSsl -Port $emailPort -From $emailFrom -To $emailTo -Subject $emailSubject -Body $emailBody -BodyAsHtml -Encoding ([System.Text.Encoding]::UTF8)
}
If the above Powershell script:
- Is contained in a file named "email.ps1".
- That file is located in a folder named "Script" (a sibling folder to the TM1 Server data folder).
Then, the following sample Turbo Integrator code can be used to pass parameters to the Powershell script:
# Temp - Define sample text file used to test attachment functionality
sFilename = GetProcessErrorFileDirectory | GetProcessName | '.csv';
# Temp - Populate sample text file
TextOutput( sFilename, 'This', 'is', 'a', 'sample', 'CSV', 'file' );
# The single quote character (ie the apostrophe character)
sQuote = CHAR( 39 );
# Relative location of the PowerShell script
sScript = '..\Script\email.ps1';
# First recipient
sEmailTo = sQuote | 'Friendly name <recipient@domain.com>' | sQuote;
# Second recipient (optional)
#sEmailTo = sEmailTo | ', ';
#sEmailTo = sEmailTo | sQuote | 'Jack <john.smith@domain.com>' | sQuote;
# Third recipient (optional)
#sEmailTo = sEmailTo | ', ';
#sEmailTo = sEmailTo | sQuote | 'Jill <jillian.jones@domain.com>' | sQuote;
# Subject of the email
sEmailSubject = 'Test email from cloud';
# Email message (HTML tags optional)
sEmailBody = '<p>Test Email from the Cloud.</p><p>This is in <i>italics</i>, and this is in <b>bold</b>.</p>';
# File attachment
sEmailAttach = sFilename;
# or leave blank if no file to be attached
#sEmailAttach = '';
# Build command line
sCommand = 'Powershell ';
sCommand = sCommand | sScript | ' ';
sCommand = sCommand | '-emailTo ' | sEmailTo | ' ';
sCommand = sCommand | '-emailSubject ' | sQuote | sEmailSubject | sQuote | ' ';
sCommand = sCommand | '-emailBody ' | sQuote | sEmailBody | sQuote | ' ';
# Include the attachment if one has been specified
IF( sEmailAttach @<> '' );
sCommand = sCommand | '-emailAttach ' | sQuote | sEmailAttach | sQuote | ' ';
ENDIF;
# Do not wait for the command to finish executing, to minimise risk of hanging and locking
nWait = 0;
# Run the PowerShell script
ExecuteCommand( sCommand, nWait );
Related Information
Document Location
Worldwide
[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSD29G","label":"IBM Planning Analytics"},"Component":"","Platform":[{"code":"PF033","label":"Windows"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}}]
Was this topic helpful?
Document Information
Modified date:
10 August 2023
UID
ibm11115787