email

AFCON SOFTWARE AND ELECTRONICS LTD

P-CIM Email


Table of Contents

Overview ....................................................................................................................................................... 3

System Requirements................................................................................................................................... 3

Using P-CIM Email in Interactive Mode.................................................................................................... 4 Runtime Usage in Interactive Mode ........................................................................................................... 4

Using P-CIM Email in Background Mode ................................................................................................. 5

Examples ....................................................................................................................................................... 6 AutoAction Example .................................................................................................................................. 6 Advanced Alarm Handler Example............................................................................................................ 7

Sending Email using P-CIM Alarm Pager Notification ............................................................................ 7 Send Rate and Dispatch Cycles .................................................................................................................. 8

System Requirements................................................................................................................................... 8

Setup Instructions......................................................................................................................................... 8 Enabling P-CIM Database Blocks.............................................................................................................. 9 Configuring the ODBC Data Source .......................................................................................................... 9 Configure the Email Parameters............................................................................................................... 10 Scheduling ................................................................................................................................................ 11 Message Format ....................................................................................................................................... 12

Run Time Usage.......................................................................................................................................... 13 Accessing the Dispatcher Configurator ................................................................................................. 13

Email Sender and Dispatcher 2 of 13


Overview

With P-CIM Email you can dispatch alarm and system event messages to any email recipient or to a group of email recipients. P-CIM Email can also be incorporated into the runtime (Operator Workstation) display to allow a user to manually generate and dispatch email messages.

P-CIM Email integrates with a resident MAPI mail server to enable transmission.

P-CIM Email can operate in two modes:

Interactive

Background In Interactive mode, the application displays the Email Sender form at the users station. The user manually configures the content of the email message and sends it.

In Background mode, the parameters and layout of the email message are configured as an Action command during the application development using a command-line syntax. This Action command can then be associated with an:

Action Button

AutoAction

Alarm Class When the Action is triggered, P-CIM Email composes and dispatches the email message automatically.

System Requirements To use P-CIM for Windows Email your system must include:

Any 32 Bit Windows OS P-CIM for Windows or P-CIM for the Web Rev. 6.54+ A resident MAPI mail exchange service Internet Mail access For P-CIM Revision 6.54 - SEK enabled for Pager and Email transmission For P-CIM Revision 6.60+ - SEK enabled for Email transmission (Pager not necessary)

Important Check that the resident mail exchange service is running before invoking P-CIM Email.



Using P-CIM Email in Interactive Mode Any user with access to the P-CIM Group can use P-CIM Email in Interactive mode as a stand-alone utility.

Accessing the Email Sender

1. Click on the Email Sender icon.

2. Enter the relevant information for Address, Subject, and Message.

3. Choose the options for level of Importance and Read/Delivery receipt request.

4. Enter the profile that handles your mail services into the Profile field. If this field is left blank, the default profile is called.

5. Choose Send to send or Cancel to quit.

Runtime Usage in Interactive Mode You can configure a P-CIM display to invoke the P-CIM Email Sender form. To do this:

1. Create an Action button.

2. Configure the buttons Action with the following command: Email (no arguments). Choosing this button at runtime invokes the form and allows the user to compose and send an email message.



Using P-CIM Email in Background Mode You can configure a P-CIM Button, an AutoAction, or an Alarm Class (using Advanced Alarm Handler) to generate email messages for automatic transmission. This is called Background mode because, in this case, the P-CIM Email Sender form does not need to appear as all the activity takes place in the background.

To do so, create a Button, AutoAction or an Alarm Class and configure it using the Email command.

In the Action property command line, configure the email parameters using the following syntax: Email [{address|groupname} subject-text body-text [profile-name] [-R|-D|-L|-H] [-#]] Where:

Argument Description Comments Address Address(es) of recipient or group of

recipients Maximum 256 characters. Multiple recipients must be separated with a ;. Recognizes individual and group nicknames. Address is not optional.

Subject Subject text Maximum 256 characters. Subject is not optional but can be left blank by inserting .

Body-text Text of actual message Maximum 512 characters. Body-text is not optional but can be left blank by inserting .

Profile name Mail service profile that is to be used Can be omitted, in which case the default profile is called.

-R Notification is sent to the sender when the message is actually read

If the recipient deletes the message without reading, a notification as such is sent to the sender. Optional

-D Notification is sent to the sender when the message is delivered

Optional

-L Message labeled for Low importance

-H Message labeled for High importance

If both switches are omitted, the message is labeled Normal by default. If both switches are inadvertently inserted, the system recognizes the latter.

-# Number of retries to execute if delivery fails

Range of 1-9.



Examples Email user1@afcon-inc PLC failure L

When executed, email is sent to user1 with the Subject PLC failure and no message text, labeled for Low importance. Uses default mail profile.

Email Shift Managers; Plant Foremen New Holiday Schedule Labor Day night workers outlook R 3

When executed, email is sent to all users in the Shift Managers group and in the Plant Foremen group. The message contains the Subject New Holiday Schedule and a text message that contains Labor Day night workers (remainder of message). This message is labeled for Normal importance (by default) and for Read notification. It specifies the profile outlook. It is configured for 3 retries if not successful.

Email [email protected]; All Users Engine room is on fire R D H 9

When executed, email is sent to [email protected] and to all users in the All Users group. This message contains no Subject and a text message that contains the specified text. It is labeled for Delivery and Read notification, High importance, and 9 (maximum) retries. Uses default profile.

AutoAction Example To email to all plant foremen that the trend reports for the month are to be submitted. A possible AutoAction script may be:

Action Name: TrendReportEmail

Trigger: |!@AtDate(XXXX15)

Mode: Up Action: Email Plant Foremen Trend Report Today is ?|!?. Trend Reports are due! outlook D 3



Advanced Alarm Handler Example You can assign Email as an Alarm action when configuring an Alarm Class in the Database Editor (Database > Zones > Classes).

In this example, when a block associated with class OffHours Alarm triggers an alarm, email is dispatched to the Off Premises Users group containing the readout of the alarm as the Subject. There is no message text in this example, importance is Normal and there are no retries.

Sending Email using P-CIM Alarm Pager Notification Alarm enabled blocks can be configured to dispatch email messages at regular intervals that contain a summary of the alarms that were generated over the duration of the interval.

To understand how to do this it is important to have a look behind-the-scenes.

If a Database block is Alarm Enabled i.e., the Enable option in the Alarm Table section is checked AND one or both of the following options are likewise checked:

Pager on alarm

Pager on RTN THEN, when an alarm occurs, an alarm message is written to the system variable $DispatchAlarm. The alarm message is comprised of the following fields:

Node# The node number of the P-CIM client station originating the alarm. Date The date of the alarm formatted using the Windows regional setting. Time The time of the alarm formatted using the Windows regional setting. Tag-Name The name of P-CIM database block. Alarm-Type Type of alarm (HIGH, LOW, ROC etc.). Tag-Value EGU The value of the block causing the alarm followed by the EGU notation as

specified in the block. Tag-Description The description of the block as specified in the database.



Each message is buffered in an ODBC database table. From this database, the alarm data is retrieved and formatted and subsequently dispatched as email.

The P-CIM Email Dispatcher-Configurator is a utility for configuring recipient and message parameters, formatting the alarm data, and for scheduling the time intervals for dispatch: Once the message, format, and schedules are configured and the database block is enabled for dispatch by enabling one or both of the Pager options at every Send Rate period, the P-CIM Email Dispatcher retrieves the alarm data, formats the email message, and sends it to the target recipient(s). No further user input is required.

Send Rate and Dispatch Cycles Email is dispatched per message on a FIFO (First In First Out). That means that when a block begins generating alarms they are buffered in the database table in chronological order. When the email is to be dispatched, the application retrieves the first alarm in the buffer and dispatches it to each recipient one by one (that is, for ten recipients there are ten consecutive email dispatches NOT one simultaneous dispatch). When all the recipients have been served, that alarm is cleared from the buffer.

It then retrieves the next alarm and repeats the dispatch procedure. This continues as long as there are alarms in the buffer.

The rate of dispatch is called the Send Rate and is configured in the P-CIM Email Dispatcher-Configurator. Minimum Send Rate is one second.

This is important since email is dispatched consecutively and not simultaneously. This means that if you have, for example, ten recipients and the Send Rate is one second, you must allow at least ten seconds per alarm for dispatch (it may actually take longer especially if retries are requested).

Likewise, for ten recipients, if the Send Rate is three seconds, you must allow 30 seconds for a complete dispatch. This can be problematic if alarm generation is quite frequent and new alarms arrive faster than they are dispatched. This can cause the buffer to back up and ultimately overload. Care must be taken to avoid this scenario.

System Requirements In addition to the components listed above (page 3), the host computer must also be equipped with one of the following ODBC compatible database systems:

MS Access SQL Server

Setup Instructions There are three steps to setting up your P-CIM system for Alarm Pager Notification via email:

1. Properly enable the P-CIM database blocks.

2. Configure the ODBC Data Source.



3. Configure the email parameters for dispatch (i.e., Send Rate, recipients, scheduling, message format, etc.).

Enabling P-CIM Database Blocks For every database block that is to generate alarms for transmission, you must enable the following options that appear in the Alarm Table section of the Properties box:

Enable One or both of the following:

Pager on alarm

Pager on RTN

This tells P-CIM to send the alarm data to the ODBC buffer.

Configuring the ODBC Data Source The second step is to define an ODBC data source.

The data source is the destination database format to which you want the ODBC Server to convert the data (i*.dbf format, *.mdb format, SQL format, etc.). The file location must also be defined in the data source definition. In step 3, you will reference this data source as the server for the alarm data.

To define an ODBC data source:

1. From the Windows Start menu choose Settings >Control Panel > ODBC(32 BIT).

2. In User DSN, choose Add. The Create New Data Source dialog box appears.

3. Select the desired driver (for MS Access, select Microsoft Access Driver [*.mdb]; for SQL select SQL Server, etc.). Click Finish.

4. In the Setup dialog box choose Create.

5. Specify a name and path for the data source. Click OK.

The new data source appears in the ODBC32 main window.



Configure the Email Parameters The third step is to configure the email dispatch parameters. To do this:

1. Make sure that P-CIM is running.

2. From the P-CIM icon group, choose the P-CIM E-mail Dispatcher icon . The P-CIM Email Dispatcher-Configurator appears.

Note The Dispatcher Configurator appears only at the first use. After that, the Email Dispatcher window appears (see Run Time Usage, page 13). To invoke the Dispatcher Configurator from the Dispatcher window, choose File > Configuration

1. Begin at the Preferences tab.

2. Select the ODBC Data Source that you created earlier (see above, page 9) from the drop-down list.

3. Enter a value for Send Rate (see page 8) in seconds. (Range: 1-999 seconds).

4. Enter a value for maximum retries (1-9).

5. Proceed to the Scheduler tab.



6. On the left side of the form, create a list of recipients.

7. To add new recipients: Type the email address of the entry into the upper field. You can also type in a nickname or group name that is listed in your default address book.

8. Choose Add. The entry appears in the lower field. You can also invoke your default address book and select the desired recipients. To do this, click on Browse Address Book.

9. To edit recipients: Select the desired recipient from the list in the lower field. The entry appears in the upper field.

10. Make your changes in the upper field.

11. Choose Change. The revised entry appears in the lower field.

12. To remove recipients: Select the desired recipient from the list in the lower field.

13. Choose Delete. The entry disappears.

Scheduling By default all recipients receive email at all times. Use the Scheduler to designate time periods for withholding transmission for each recipient.

To schedule a recipient:

1. Select the desired recipient from the list.

2. Enable the weekdays that are to be scheduled (choose Mute All to enable scheduling - i.e. withholding - for all times).

3. Set the time periods for non-transmission (up to two time periods per weekday). Use 24-hour format.

4. Repeat this procedure for all recipients that are to be scheduled.

Proceed to the Message Format tab.



Message Format You can customize the message format for each recipient. To do this:

1. Select the recipient.

2. There are seven possible message fields as described above (page 7). Place those that you wish to appear in the message in the Message Fields window. Place the remainder in the Available Fields window. Use the Add and Remove buttons to move the fields between windows.

3. The included fields appear in the Message Sample window. You can rearrange the order by selecting the desired field in the Message Fields window and repositioning it using the Move Right and Move Left buttons.

To restore the format to the default layout, choose Reset.

4. Choose the options for level of Importance, Profile, Read/Delivery receipt request.

5. Repeat steps 1-4 for all the recipients for whom you wish a customized format.

6. Click on Save. All of the settings configured in this session are stored in an INI file.

7. Click on Close to close the Dispatcher - Configurator.



Run Time Usage Once the Email Dispatcher Configurator has been configured with an ODBC data source and at least one recipient, Email Dispatcher can be invoked at run time both from the P-CIM icon group and in a display.

To invoke P-CIM Email Dispatcher from the P-CIM icon group:

1. Choose the Email Dispatcher icon . The icon appears in the Windows taskbar to indicate that Email Dispatcher is running.

2. Double click on the icon or right-click on it and choose Open from the popup menu. The P-CIM Email Dispatcher window appears. The window displays a line item indicating a successful connection to the ODBC data source followed by a log of the messages that are currently stored in the buffer.

3. To invoke P-CIM Email Dispatcher from a display:

4. Create an Action button and configure it with the following command: Run edispatch.exe

Accessing the Dispatcher Configurator To access the Dispatcher Configurator from the Email Dispatcher:

From the taskbar icon (window is minimized) right-click on the icon and choose Configuration

From the Dispatcher (window is maximized choose File > Configuration


OverviewSystem RequirementsUsing P-CIM Email in Interactive ModeRuntime Usage in Interactive Mode

Using P-CIM Email in Background ModeExamplesAutoAction ExampleAdvanced Alarm Handler Example

Sending Email using P-CIM Alarm Pager NotificationSend Rate and Dispatch Cycles

System RequirementsSetup InstructionsEnabling P-CIM Database BlocksConfiguring the ODBC Data SourceConfigure the Email ParametersSchedulingMessage Format

Run Time UsageAccessing the Dispatcher Configurator

email

Documents

pcim email afcon software

email sender

email parameters

pcim database blocks

group of email recipients

pcim alarm pager notification

interactive mode

system requirements