ActiveMail Quick Installation And User`s Guide

ActiveMail
(for Calls and Prospero)
Version 7.20.00
Quick Installation
And
User’s Guide
© 2005-2014 Mpowered Ventures Ltd.
45 – 15833 26 Ave
South Surrey BC V3S 2X5
Canada
http://www.mpowered.biz
1
What’s New for 7.20.00
Tempest 720 Upgrade. Changes to support Tempest annual upgrade.
Documentation changes indicated with teal arrow. Now you can see what
has changed in this document by looking for the teal arrows. This saves existing
users time having to read the entire document looking for changes!
Upgrading from a previous version? See the Upgrade Notes at the end of this
document for helpful advice.
2
1. Installing ActiveMail
(required for both
ActiveMail/Calls and ActiveMail/Prospero)
System Requirements
Internet Server:
• Requires an IIS server, running ColdFusion MX 8, with a Data
Source connection to the Tempest database
Tempest Licences:
• Calls
• Web Customer
Mail Server:
• ColdFusion MX on the Internet Server above must be able to
route mail to an email server
Run the Install package
Go to the www.mpowered.biz and click on Downloads. Run the
appropriate setup package with highest patch number corresponding to
your Tempest version. The Setup Wizard will guide you through set
up. When done, you will have a new program group: Start > Programs
> Mpowered > ActiveMail. Under this entry is a shortcut to this
document, the Quick Installation and User’s Guide.
Copy the cfm to a virtual directory on the Web server
There will be one cfm file installed to the C:\Program
Files\Mpowered\ActiveMail\ColdFusion directory:
activemail.cfm
This .cfm file needs to be copied into a virtual directory on the Web
Server. The recommended location for this directory is:
C:\Inetpub\wwwroot\Mpowered\ActiveMail
3
Ensure that ColdFusion is connected to a mail server
On your Web Server, go into the ColdFusion Administrator, click on
Mail Server, and ensure that a valid (i.e. verified) Mail Connection
exists:
4
MpoweredWeb database user and permissions
The Tempest Live and Test databases will both require a new database
user - MpoweredWeb. With your database Enterprise Manager, give
the following table permissions to MpoweredWeb:
Table
wc_customer_notes
Permission
INSERT, UPDATE
and specifically for ActiveMail/Prospero:
amprostask
land_relation
land_notes
INSERT, UPDATE, DELETE
INSERT
INSERT
These SELECT permissions are also required:
grant select on calls_calls to mpoweredweb;
grant select on calls_problems to mpoweredweb;
grant select on calls_problem_classes to mpoweredweb;
grant select on calls_workflow to mpoweredweb;
grant select on land_relation to mpoweredweb;
grant select on land_legal to mpoweredweb;
grant select on tempest_client to mpoweredweb;
grant select on tempest_release_header to mpoweredweb;
grant select on tempest_resource_contact_dtls to mpoweredweb;
grant select on tempest_resources to mpoweredweb;
grant select on tempestv_security_all to mpoweredweb;
grant select on wc_customers to mpoweredweb;
grant select on wc_customer_notes to mpoweredweb;
Ensure that valid ColdFusion Data Sources exist
The installation requires two Data Sources (DSNs in ColdFusion
Admin), one to the Live and Test Tempest databases logging in as the
database user MpoweredWeb. Appropriate names for these Data
Sources would be "MpoweredLive" and "MpoweredTest". (Note: be
sure to use JDBC drivers in ColdFusion for Oracle by using the
"other" Driver type. The Adobe ColdFusion web site has information
on setting up JDBC data sources if this is your first time. SQL Server
users should use the built-in Microsoft SQL Server driver.)
On your Web Server, go into the Cold Fusion Administrator, and
ensure that valid (i.e. verified) Data Sources to the Tempest Live
(MpoweredLive) and Test (MpoweredTest) databases exist. The
UserName (under Advanced Settings for the Data Source) should be
MpoweredWeb – do not use TempestWeb.
5
Create the FieldWorksUsers customer in Web Customer
In Tempest create a FIELDWORKSUSERS customer if you do not
already have one. Make the user an INTERNAL type:
6
Run activemail.cfm in a browser
Open up a browser and run activemail.cfm with a URL variable named
v04 set to the ColdFusion datasource from above. In the example
below, the datasource is fieldworkssql, but you will most likely have a
datasource named TempestTest, or something similar:
By running the activemail.cfm for this Data Source, it has created the
record in the FIELDWORKSUSER that tracks the last time
ActiveMail ran. This is used the next time ActiveMail runs to
determine the timeframe to check for newly-assigned Calls in. The
control record is always dated Jan 10, 2005:
As the Note in this record states, you should not disturb (i.e. delete or
change) this note using Web Customer. ActiveMail uses it for
processing. Note that if the note is deleted, ActiveMail will simply build itself a
new one the next time it is run.)
7
Create the AM_SYSADMIN resource and email address
In Tempest, create an AM_SYSADMIN resource as shown below:
Note that the login will usually be disabled for this resource, and no
database login is required. ActiveMail will use this account’s email
address, which is set up on the Contact Details tab in the next step:
The email address you set up for AM_SYSADMIN should be the
person who will receive system administration messages related to
ActiveMail (system upgrade messages, system error messages, etc.)
8
2. ActiveMail/Calls setup
ActiveMail/Calls will require an additional control record (or a control
file – discussed later) to indicate which users should have Calls emails
sent to them. This control record must be dated Jan 11, 2005, and a
sample showing the userid GEORGE with an email address of
george@mpowered.biz and an email style of full (more about that
later) is shown below:
Create a similar control record for a userid and email address that you
can assign a call to. Follow the above example exactly, substituting in
the userid and email address where appropriate in the xml. If you do
not form the xml correctly, ActiveMail will complain in the next step.
For example, if your userid is PSMITH and the email address is
psmith@city.ca, then you would enter the following into the Jan 11,
2005 note:
<CALLS>
<users><x>PSMITH</x></users>
<details>
<PSMITH><email>psmith@city.ca</email><style>full</style></PSMITH>
</details>
</CALLS>
9
Run activemail.cfm again
Run activemail.cfm again:
ActiveMail is now scanning through Calls to find newly assigned
Calls, and send them via email. In the next step, we will assign (or reassign) a Call, and watch it pop up in our email inbox.
Some things to note:
1.
The message “CALLS Licence key NOT found, processing first
user in list only” is to let you know that ActiveMail is not licenced, and it
will only process one user as a trial. You can continue to use ActiveMail with
one user for as long as you like. When you want to activate ActiveMail for
more than one user, contact www.mpowered.biz for licence pricing and to
purchase a licence. You only need one licence for ActiveMail, and you can set
up as many users as you like!
2.
The message “CALLS email 'from' parameter NOT found,
defaulting to: am@yourcity.ca” is to let you know that a ‘from’
email address has not been set in the ActiveMail Calls control record. Emails
will be tagged as being from ‘am@yourcity.ca’ until you create the ‘from’ email
address, a process that is described later. It will not hurt anything to leave this as
is for now.
10
Assign (or re-assign) a Call to the user
In Calls, create a new Call for the user that you created above:
Now, run ActiveMail again:
11
Check the Inbox you set up
Did you get the “you have mail” ding? ActiveMail found the newly
assigned Call, and since GEORGE is on the list to be emailed, it sent
off the notification!
12
Alternatively use a control file
If you find that the control record needs to be larger than what can be
stored in the WebCust note (2000 bytes), you can use a file stored in
the same web directory as the ActiveMail ColdFusion files. The name
of this file must be ‘callscontrolfile.txt’. If found, this file completely
overrides any information in the WebCust control record:
The downside to using a control file (as opposed to the WebCust note)
is that the configuration data is not backed up along with your
database, so you should ensure that appropriate backup steps are in
place for the callscontrolfile.txt file.
13
Adding more users to the user list
To add more users (once you have a registered licence), go into the
FIELDWORKSUSERS customer, and add the userid to the <users>
list, and then add the email details for the user to the <details> list.
For example, we have added userid FRANK below:
ActiveMail currently supports up to approximately 20 users when
using the WebCust method. If you are using the callscontrolfile.txt
method, you have an unlimited number of users.
NOTE: You can only have one email address per userid. The one-toone relationship of Calls user to email address is enforced because
having multiple emails per user may result in confusion as to which
inbox should answer the Call.
14
Changing a user’s email style
ActiveMail can send two types of message: a ‘full’ email style (which
is the default), and ‘sms’ style. You can use ‘sms’ style for sending
notifications to cell phones that accept sms messaging to an email
address. For example, if your phone number is 6045551234, your
carrier may allow you to send ‘sms’ messages to an email such as
6045551234@carrier.net (review your cell phone documentation or
contact your carrier (e.g. Bell, Telus, Rogers) for more details).
Change the user’s email style in FIELDWORKSUSERS:
When you run ActiveMail, it will send a short message indicating a
new Call has been assigned:
15
Adding the ‘from’ email address
The default ‘from’ address is am@yourcity.ca and you may wish to
change this, although it will not hurt anything to leave it as is. For
example, you could change this to the email address of your dispatch
centre if you wanted your users to reply to indicate receipt
Add a line as shown below to the Calls control record in
FIELDWORKSUSERS, changing the actual email address as
appropriate:
Running ActiveMail will produce a message similar to the following:
16
3. ActiveMail/Prospero setup
Note that some of the steps in this section require a Tempest DBA and a
Tempest Prospero Super User. Do not attempt to perform these steps if you are
not sure! If you do not have this expertise, contact Mpowered to assist you. It is
strongly recommended to build Task SQL Functions in the Test system and
thoroughly test them there before putting them into the Live system. See the
end of this section regarding errors in Task SQL Functions.
Once the DBA and SuperUser tasks are completed, day-to-day use does not
require this expertise.
Step 1: Creating the AMPROSTASK holding table (one-time DBA
step)
ActiveMail/Prospero requires you to create an inhouse table named
AMPROSTASK. You can do this with Tempest’s Tool Builder or
using your favourite DBA tool. Tool Builder screenshots are shown in
the examples below. This table must be set up exactly as shown in the
screen shots (except as noted).
Columns
Note: your client name should be chosen as you create the table, do not
use MPOWERED as shown. Also ensure that the inhouse flag is
turned on.
17
Synonyms
Indexes
When you have added the information in these screen shots, ensure
that you go back to the Columns screen and click the “building blocks”
button. This will create the table in the database.
18
Step 2: Creating a suitable task to trigger emails (Super User)
(Note: You already may have a suitable task to attach the Task SQL Function to. In
that case, you can use that task and move on to the next step.)
Let’s assume we have a requirement by Jody in Finance who wishes to
have an email notification to release deposits on RESIDENTIAL
permits that have been completed. Let’s look at the tasks for our
RESIDENTIAL permit and see how we can do this.
We see that our RESIDENTIAL permit has a task type of DEPOSIT
RELEASE as task 32. This is the task that Finance performs to
actually release the deposits. What we need is a task before this, to
trigger notification that the deposit(s) are approved for release. We
need to create a new task APPROVE DEPOSIT RELEASE between
FILE COMPLETED and DEPOSIT RELEASE:
19
Step 3: Creating the Task SQL Function (DBA)
Now that we have a suitable task to trigger the email, we need to
create the Task SQL Function which, when attached to the
APPROVED status of the task, will email Jody whenever APPROVE
DEPOSIT RELEASE tasks are approved.
Task SQL Functions will control who gets email notification, what
goes into the text of the notification, and how that notification is
triggered.
Below is a screen shot of the sample ORACLE SQL that will email
Jody (JHARDING):
There are several things to note about creating Task SQL Functions:
Choose your Client, do not use MPOWERED when creating your
SQL. Ensure the object is marked as InHouse or the SQL object will
be deleted next Tempest release. System must be COMDEV and the
program name must be CD_TASK_21. The Title must begin with:
‘TASK SQL FUNCTION: ‘ and end with ‘ – 001’. Watch where the
spaces are! Between those two parts of the Title is where you identify
the function - in this case ‘SEND EMAIL TO FINANCE (DEP RLS)’.
In the SQL itself, you can see where we have chosen Jody to receive
the email (her Resource ID is JHARDING). The rest of the SQL
should be fairly self-explanatory.
20
Note: ensure that you always use the “building blocks” button to get a valid “explain
plan” (Oracle only) any time you change the SQL and before saving. This will help
ensure that the SQL used in the function will not cause errors for end-users,
especially once the function is in use. See the section Errors in the Task SQL
Function below for an example of the messages you will receive if there is an error
in the Task SQL.
Here is the full statement name so you can see where the spaces go:
TASK SQL FUNCTION: SEND EMAIL TO FINANCE (DEP RLS) - 001
Here is the full Oracle SQL text. You can copy it as you see fit:
INSERT
INTO
SELECT
amprostask
(amprostask_id, task_id, error_user_id, from_user_id, to_user_id, cc_user_id, subject, body,
sentattempts, sentflag, sentmessage,
created_user_stamp, created_date_stamp, user_stamp, date_stamp)
:sRunId,
:sTaskId,
'AM_ERRORS', /* errors Resource */
(SELECT user_id FROM tempest_resources WHERE resource_id =
(SELECT resource_id FROM cd_tasks WHERE task_id = :sTaskId)), /* from Resource */
'JHARDING', /* to list of Resource(s) - comma seperated */
'', /* cc list of Resource(s) - comma seperated */
tasktype || ' task has been ' || taskstatus || ' for folder ' || fldrnum,
'This is an automated message. DO NOT REPLY' || Chr(13) || Chr(10) || Chr(13) || Chr(10) ||
'Please begin the release of deposits for this folder. Thank you.' || Chr(13) || Chr(10) ||
'Sent by task sql function ''SEND EMAIL TO FINANCE (DEP RLS)''',
0, /* 0 attempts so far */
'0', /* 0 = not sent yet, 1 = sent */
'Message created.',
:SqlUser,
:dtDATESTAMP,
:SqlUser,
:dtDATESTAMP
FROM
(
SELECT
(select folder_number from cd_folders where folder_id = base_table.folder_id) fldrnum,
(select type from cd_task_types where type_id = base_table.task_type_id) tasktype,
(select status from cd_task_status where status_id = base_table.status_id) taskstatus
FROM
(
SELECT
folder_id,
type_id task_type_id,
status_id
FROM
cd_tasks
WHERE
deleted_date
IS NULL
AND
task_id
= :sTaskId
) base_table
) outer_table
For SQL Server, simply replace the || characters with + in the above
SQL.
21
Let’s go through each field, and describe what it does and what your
options are:
Field
amprostask_id
Value
Description
Always use these here.
task_id
:sRunId,
:sTaskID,
error_user_id
'AM_ERRORS',
from_user_id
(SELECT user_id FROM
tempest_resources WHERE
resource_id = (SELECT
resource_id FROM cd_tasks
WHERE task_id = :sTaskId)),
to_user_id
'JHARDING',
cc_user_id
'',
subject
sentattempts
tasktype || ' task has been ' ||
taskstatus || ' for folder ' ||
fldrnum,
'This is an automated message.
DO NOT REPLY' || Chr(13) ||
Chr(10) || Chr(13) || Chr(10)
||
'Please
begin the release of deposits for
this folder. Thank you.' ||
Chr(13) || Chr(10) ||
'Sent by
task sql function ''SEND EMAIL
TO FINANCE (DEP RLS)''',
0,
sentflag
'0',
sentmessage
'Message created.',
created_user_stamp
created_date_stamp
user_stamp
date_stamp
:SqlUser,
:dtDATESTAMP,
:SqlUser,
:dtDATESTAMP
body
22
The User ID that will receive any
errors related to sending the message.
In this case, we are using resource
AM_ERRORS. Resource
AM_ERRORS must have an email
contact set up.
The ‘from’ Resource User ID. Here
we are getting the User ID for the
Resource that set the Task status. If
you want to use the logged-in User’s
User ID, use :SqlUser instead of this.
Any possible ‘from’ resources must
have an email contact set up in
Resources.
A comma-separated list of User IDs
this email is ‘to’, e.g.
‘JHARDING,PSMITH’ Any ‘to’
resources must have an email contact
set up in Resources.
An optional comma-separated list of
User IDs this email is ‘cc’d to, e.g.
‘FJONES,GRAYMOND’ Any ‘cc’
resources must have an email contact
set up in Resources.
The email subject.
The email body. Note that the body
must be customized for each
purpose – the system does not
know why you are sending the
email (in plain English), so you will
have to code that into the body.
Count of times ActiveMail has
attempted to send this email.
ActiveMail will stop after three
failed attempts. Always initially set
this to 0.
A flag to indicate that the email has
not been sent yet. Always initially
set this to ‘0’.
The status of the email. Always use
‘Message created.’ here. It will be
updated as the record is processed by
ActiveMail.
Always use these here.
You can customize the SQL you need in any way to produce the email
results you need, so long as the AMPROSTASK table is filled with the
appropriate fields. The cc_user_id field can be Null (as above); every
other field is required.
You can create as many Task SQL Functions as required, and attach
them to as many task statuses as required to meet your business needs.
Any User Ids (Resources) used in the SQL must have a valid email
address in the Tempest Resources program, or an error message will
be sent to the error_user_id as ActiveMail tries to process it. If the
error_user_id does not have a valid email address, an error message is
sent to the AM_SYSADMIN Resource. ActiveMail will not operate at
all where the AM_SYSADMIN Resource does not have a valid email
address.
Step 4: Attach the Task SQL Function to a task status (Super User)
Once we have the Task SQL Function built, we can attach it to any
task status. Here in Prospero Configuration, we are going to attach the
function to the APPROVED status of the APPROVE DEPOSIT
RELEASE task. Click on the “add new function” button:
23
Choose “SQL Function”:
Now you will see the new SQL Function on the list. Choose it and
click Finish.
As of clicking Finish, any time an APPROVE DEPOSIT RELEASE
task is set to APPROVED status, a record will be entered in the
AMPROSTASK table, and ActiveMail will pick it up and send the
email. (See Section 4. Setting up ActiveMail to run on a schedule
below.)
24
Step 5: Sending the mail by setting a task status (End User)
And finally, here is a screen shot of the end-user task approval:
A sample resulting email:
APPROVE DEPOSIT RELEASE task has been APPROVED for
folder BP098263
Mon, January 15, 2010 8:47:08 PM
From:
Kyle Woods <kwoods@city.com>
To:
Jody Harding <jharding@city.com>
This is an automated message. DO NOT REPLY
Please begin the release of deposits for this folder. Thank you.
Sent by task sql function 'SEND EMAIL TO FINANCE (DEP RLS)'
25
Errors in the Task SQL Function
The flexibility of creating your own Task SQL Functions also means
that there is the potential for SQL coding errors. Your Task SQL
Function should always be tested in a test environment before putting
it into production. This will alleviate many issues. If there is a SQL
error in the Task SQL Function, Tempest will display an error message
similar to the following when trying to update the task to the status:
In this case, the error is showing us that we tried to insert an empty
“to” user, which the table does not allow.
Many other kinds of error can occur, depending on how the SQL is
written. You can always tell which statement caused the error by the
second error message that comes up. Note that users will not be able
to select that status for the task until the error is corrected.
26
4. Setting up ActiveMail to run on a schedule
To make ActiveMail really useful, you will want to set it up so that
runs on a regular basis. ColdFusion allows you to set up a scheduled
task that will run at regular intervals. Go into your ColdFusion
administrator, click on Scheduled Tasks, and click on the Schedule
New Task button. Add a task similar to the following:
In this example, we’re calling the task ActiveMail, and we’re going to
run it every 10 minutes, starting at 6AM until 11PM.
27
Upgrading from a previous version
1.
2.
3.
Upgrade the Coldfusion server with the new 7.20.00 cfm files.
Run the following SQL using a system DBA account:
grant select on tempestv_security_all to mpoweredweb;
Update your licence key with the new licence key emailed to you by
Mpowered for ActiveMail 720nn. Your existing 71900 licence key will be
stored in one of two places: 1) a note in Tempest WebCust under Customer
FIELDWORKSUSERS dated Jan 11, 2005; or 2) using a text file on the
web server in the same virtual directory as activemail.cfm. The text file
will be named callscontrolfile.txt. Option 2, if used, will trump option 1.
You will find the licence key stored as xml something like this:
<licencekey>3200E6E7110459F4BCB95B8AAADF6D5B</licencekey>
Replace the inner numbers with the new licence key.
General upgrade notes
All releases and patches are cumulative and include fixes from previous updates.
ActiveMail is integrated with Tempest, and may or may not require maintenance as
Tempest releases major versions and patches as described below.
Major releases
A major release of ActiveMail (AM) will coincide with a major Tempest release,
that is, when any of the first 3 digits of a release change, e.g. 71900 to 72000. You
must (and can only) upgrade AM when you have upgraded the underlying database
in order to continue using AM. (You will need new licence keys from Mpowered at
each major release, which will be automatically shipped to you.) All major releases
are full (i.e. cumulative), i.e. all Coldfusion programs/modules are released as a full
package, and will usually require upgrading the Coldfusion server with the new
version of code. After every major release, run the SQL in Step 2 above using a
system DBA account.
Patch releases
When any of the last 2 digits of a ActiveMail release change, e.g. 72000 to 72001,
this is known as a patch release. Mpowered does not synchronize these patches with
Tempest. Therefore, when Tempest releases a patch, there will not necessarily be a
corresponding patch release by Mpowered. Mpowered releases patches in order to
fix bugs and/or introduce new features. All patch releases are full (i.e. cumulative),
i.e. all Coldfusion programs/modules are released as a full package, and will usually
require upgrading the Coldfusion server with the new version of code. After every
patch release, run the SQL in Step 2 above using a system DBA account.
Testing releases/upgrades
Clients may wish to test releases before going into production. This can be
accomplished by setting up an …\mpowered\activemail\test subdirectory on the Web
server and loading patches/release CFMs to this directory. Test ActiveMail from this
new directory. Once testing is complete, the CFMs can be moved to the
…\mpowered\activemail subdirectory.
28