Administering Messaging Attributes and Features

Madhuri Dange

April 04, 2022 06:13

Aptify includes the ability to configure and generate personalized email messages for one or more recipients. Users access a Messaging dialog from certain services in the system.

An administrator enables and configures the messaging functionality by working with Message Systems, Message Sources, and Message Parts records. Administrators can also set up messaging templates for the users, although the users have the ability to configure or modify templates as well.

This topic includes the following sub-topics that describe the following services and tasks related to messaging:

The Message Run Overrides and Message User Profile services are reserved for future use.

Configuring Message Systems
Defining a Message Source
Configuring Message Parts
Creating Message Templates
Configuring Message Actions
About Message Runs
Message Schedules and Recurring Delivery
Bulk Messaging and Faxes
Bulk Messages from Temporary Views
Capturing Message Details from a Message Run for Use in a Process Flow
Configuring an Email Control to Launch Aptify Messaging

Configuring Message Systems

Message system records define how bulk messages may be sent. By setting up more than one messaging system, Aptify's bulk messaging functionality supports multiple mail programs.

A standard Aptify installation includes three default Message Systems:

Dot Net SMTP Client: When this message system is selected for a message run, Aptify sends the message using Microsoft .NET's SMTP (Simple Mail Transfer Protocol) components and supports SMTP Authentication. Note that you must configure the Dot Net SMTP Client attributes before users can send messages via this Message System. See Configuring Dot Net SMTP Client Attributes.
Dot Net Mail: When this message system is selected for a message run, Aptify sends the messages using Microsoft .NET's SMTP (Simple Mail Transfer Protocol) components. Note that you must configure the Dot Net Mail attributes before users can send messages via this Message System. See Configuring Dot Net Mail Attributes.

If your mail server is configured to use SMTP authentication use the Dot Net SMTP Client messaging system. See Configuring Dot Net SMTP Client Attributes.

Outlook Mail: When this message system is selected for a message run, Aptify sends the messages using Microsoft Outlook. This option requires that the client computer has Microsoft Outlook installed and that the Windows user who is logged into the computer has an Outlook account on the organization's Exchange server. By default, users can send messages using the Outlook Mail message system without any initial configuration.

An organization can add more message systems, as needed.

This topic includes the following topics related to Aptify Message Systems:

Configuring Dot Net SMTP Client Attributes
Configuring Dot Net Mail Attributes
Defining a New Message System
Creating Audit Lists
Requiring Approval to Send Messages
Scheduling Messages for Future Delivery
Configuring the Message System Confirmation

Configuring Dot Net SMTP Client Attributes

Before an organization can use the Dot Net SMTP client message system, an administrator needs to configure the system's attributes to specify the SMTP server that the system should use for sending messages.

Follow these steps to configure the attributes:

Open the Dot Net Mail SMTP Client record.
Click the Attributes tab.
Open the DefaultFromEmail sub-type record and enter a default From email address in the Value field (replace the [Enter valid Email Address] default value).
- The system will use this address as the default From email address for messages sent using the Dot Net Mail SMTP Client if the user did not specify a From address in the Messaging dialog.
Open the UserName sub-type record and enter the user name of the SMTP account holder for the SMTP mail server (replace the [Enter valid Username] default value).
- This attribute is required if UseDefaultCredentials is set to False.
Open the Password sub-type record and enter the password of the account holder, having the account in the SMTP mail server (replace the [Enter valid Password] default value).
- This attribute is required if UseDefaultCredentials is set to False.
Open the Host sub-type record and enter the name or IP address of your organization's SMTP server (replace the [Enter valid IP Address of the host] default value).
Open the Port sub-type record and specify the port used by your organization's SMTP server (replace the [Enter valid Port] default value).
Open the UseDefaultCredentials sub-type record and configure what user credential will be used for sending messages from this Messaging System:
- True (or 1): The SMTP server will use the default credentials when sending email.
- False (or 0): The SMTP server will use the UserName and Password values as credentials for sending email.
Open the DeliveryMethod sub-type record and specify the deliver method of email:.
- Network: Email sent through the network to the SMTP server.
- PickupDirectoryFromIis: Email is copied to the pickup directory used by a local Internet Information Services (IIS) for delivery.
- SpecifiedPickupDirectory: Email is copied to the directory specified by the PickupDirectoryLocation attribute for delivery by an external application.
Open the EnableSSL sub-type record and specify whether the SMTP client uses SSL (Secure Socket Layer) to encrypt the connection. If True it will use SSL to encrypt the connection, otherwise, if set to False, it will not (replace the [True/False] default value).
Open the PickupDirectoryLocation sub-type record and specify the folder where applications save mail messages to be processed by the local SMTP server (replace the [Enter valid Folder Path] default value).
- This attribute is required when the DeliverMethod attribute has value SpecifiedPickupDirectory.
Open the Timeout sub-type record and specify a value that indicates the amount of time after which a synchronous Send call times out (replace the [Enter value in Milliseconds] default value).
- The default value is 100000 (100 seconds)
- Save and close the Message Systems record.

Configuring Dot Net Mail Attributes

Before an organization can use the Dot Net Mail message system, an administrator needs to configure the system's attributes to specify the SMTP server that the system should use for sending messages.

Concerning SMTP Authentication

If your mail server is configured to use SMTP authentication use the Dot Net SMTP Client messaging system. See Configuring Dot Net SMTP Client Attributes for details.

Follow these steps to configure the attributes:

Open the Dot Net Mail Message Systems record.
Select the Attributes tab.
Open the DefaultFromEmail sub-type record and enter a default From email address in the Value field (replace the [Replace Me] default value).
- The system will use this address as the default From email address for messages sent using Dot Net Mail if the user did not specify a From address in the Messaging dialog.
Open the SMTP Server sub-type record and enter the network address for your organization's SMTP server (replace the [Replace Me] default value).
Save and close the Message Systems record.

Defining a New Message System

Open a new Message Systems form from the Message Systems service.
Enter a Name and Description for the messaging system.
If you want to create audit lists for messages sent using this message system, select the Create Audit List check box. See Creating Audit Lists for more information.
Locate the Object which defines the messaging system by clicking the button to the right of the Object field.
Enter the name of the class for the messaging system in the Class field.
Enter the assembly's name for the messaging system in the Assembly field.

The developer who created the message system object should provide the Object, Class, and Assembly information to you. Creating a new message system object is beyond the scope of this document.
If messages through this system require approval prior to being sent, select the Requires Approval option.
Place a check mark in the Active box to make this Message System available to users.
If the Message System supports HTML, select the Supports HTML option.
If the Message System supports only plain text and not HTML, clear the Supports HTML option. When disabled, Aptify saves the HTML body field as an empty string. Also, users cannot enter HTML text on the HTML tab within the Aptify Messaging dialog (the tab and related buttons are grayed out).
Specify the character used by the message system to separate multiple email addresses within the Address Separator field. This information is used by the View Scheduling functionality.

The Footer fields, the Allow From field, and the Allow Reply To field are reserved for future use.
Save and close the new Message Systems record.

Creating Audit Lists

You can configure the system to create an audit list that identifies all of the records included in a message run for all runs that use a particular message system. This feature can be used to track and review the recipients of a bulk message. The topic includes the following:

Concerning Enabling Audit Lists

By default, this functionality is disabled since audit lists require storage space and may increase the system's performance time. Therefore, create audit lists only as necessary.

Configuring Message Audit Lists

Follow these steps to enable it for a particular message system:

Open the Message Systems record you want to configure.
Clear the Create Audit List option.
Save and close the record.

Reviewing a Message Audit List

When checked, the system creates a Lists record for each message run that is sent using this message system. Follow these steps to review the audit list for a bulk message:

Create or open a view of the Lists service.
Locate the List that corresponds to the Message Run you want to review.
You can identify the audit list based on the Message Run's ID. The list name appears in the following format: Message Run of 'X', where X is the ID of the Message Run. Note that you can also filter records based on List Type, since all audit lists share the same Message Run List list type.
Double-click to open the Lists record. The List Items tab displays the message recipients.

Requiring Approval to Send Messages

By default, when a user clicks the Send Messages button on the Aptify Messaging dialog, the system sends the messages immediately. However, an organization can configure a message system to require that a supervisor or administrator review all messages before they are sent.

Follow these steps to enable this option:

Open a Message Systems record.
On the General tab, place a check mark in the Requires Approval box.
Save and close the record.

When this option is an enabled, a message run is not sent until it is marked as approved. The following is an example approval process:

A user creates a bulk message with the Messaging dialog and clicks the Send Messages button.
- This generates a Message Runs record with Approval Status set to Pending.
The user notifies the approver that the bulk message is ready for approval.
- Alternatively, an organization can create a process flow to handle this notification automatically.
The approver opens the Message Runs record and reviews the message details stored in the record.
Once the approver is satisfied that the message is suitable to be sent, he or she changes the Approval Status to Approved and saves the record.
The system then sends out the email messages.
- Note that an organization may want to enable Field Level Security for the Approval Status field to limit the set of users who can approve a message run.

An organization can use Aptify's Process Pipeline functionality to automate some of the approval process (such as sending an email message to the person when a message run is ready for approval). See Managing Process Flows for information on creating a process flow.

Scheduling Messages for Future Delivery

When the appropriate fields are completed on a Message Systems record, a user can specify that the message system send bulk messages at a future date or time within the Aptify Messaging dialog. When a user specifies a future date and time for delivery, Aptify creates a Scheduled Tasks record that fires a process flow which sends the messages at the appointed time. This topic includes the following:

Using Outlook Mail

Aptify strongly recommends that you use an SMTP-based messaging system, such as the SMTP-based Dot Net Mail and Dot Net Mail SMTP Client systems, for message scheduling and for bulk messaging rather than Outlook Mail. If you decide to use message scheduling with Outlook Mail, keep the following in mind:

Messages will be sent from the Application Server user's Outlook account and not from the user who originally composed the message.
Microsoft Outlook may require that no user be logged into the Application Server in order to successfully generate and send bulk messages at the appointed time.
You may also need to reduce Outlook's security settings to allow messages to be sent from Aptify without user intervention.
The Application Server user is the trusted user account who is running the asynchronous processor service. See Configuring an Application Server for details. This user account must have an active Outlook account to send Outlook messages using Application Server.

Configuring Message Scheduling

To support this functionality, an administrator must configure the Scheduling options for the applicable Message Systems used by the organization. Follow these steps:

Application Server Must Be Configured

Your Aptify installation must include one or more Application Servers to schedule messages for future delivery. When a user specifies a future delivery date and time, the system creates a Scheduled Task to execute the Message Run at the date and time specified. See Creating a Scheduled Task for more information.

Open a Message Systems record.
Select the Scheduling tab.
Enter an application server that will send the messages marked for future delivery in the Application Server field.
Enter Remote Scheduler in the Scheduled Task Service field.
- You can also use Windows Scheduler as the Scheduled Task Service but in this case, all users who attempt to schedule messages for future delivery must have the necessary permissions on the Application Server to create Windows Scheduled Tasks.
With Remote Scheduler, all users can schedule messages for future delivery, regardless of their permission level (since the Application Server user will create the Windows Scheduled Task).
Enter a category in the Scheduled Task Category field. This is the category that will be assigned to the Scheduled Tasks records created to track the future delivery of messages.
Enter a Job Account Name for the Scheduled Task. This is the Aptify user account that will run the Scheduled Task to create a Process Flow Runs record.
Enter a Job Account Password for the Scheduled Task. This is the password of the specified Job Account user.
- See Managing Scheduled Tasks for more information on these fields related to the Scheduled Tasks functionality.
In the standard Aptify installation, the Job Account Password is encrypted using the Generic Entity Encryption Key. By default, the sa user and members of the Accounting, Administrators, or Users group have access to this key. Only users who have access to the key can enter a value in this field. Also, any user who will use Remote Scheduling also needs access rights to this key in order save the scheduled message's corresponding Scheduled Tasks record.
- Depending on the security model that your organization has implemented, you may want to create a new key to encrypt this field and allow only designated users access to that key. This is the recommended approach, but you should use the same key to encrypt this field that you use to encrypt the Default Job Account Password field in the Application Servers entity. See Installing an Application Server for more information on this field.
- The Default Job Account Password is used by the View Scheduling feature. See Enabling View Scheduling for more details.
- See Enabling Field Level Encryption for more information on field level encryption.
- Users who will use remote scheduling also need access to the Security Key that encrypts the Scheduled Tasks entity's Job Account Password field. See Creating a Scheduled Task for more information on this field.
  
  You must specify a Job Account Name and Job Account Password to enable delayed message delivery (even if the Application Server has a default Job Account Name and Password already configured).
Save and close the Message Systems record.

About the Schedule Messaging Process

The following is an overview of the schedule messaging process:

User creates a bulk message in the Aptify Messaging dialog and specifies a future date and time for delivery. The user clicks the Send Messages button.
Aptify creates a Scheduled Tasks record that stores the information about the message.
- This Scheduled Task uses the Remote Scheduler service (since not all users will have the appropriate permissions to create Windows Scheduled Tasks on the Application Server).
The Remote Scheduler service creates a Process Flow Runs record to change the Scheduled Task's service from Remote Scheduler to Windows Scheduler.
The Application Server executes the Process Flow Run and updates the Scheduled Task's service to Windows Scheduler. This generates a Windows Scheduled Task on the Application Server that send the email message at the appropriate date and time specified by the user.
- Since the Application Server's user account modifies the Scheduled Tasks record, that user account, which should already have the necessary permissions, creates the Windows Scheduled Task in lieu of the user who originally saved the view.
At the specified date and time, the Scheduled Task creates a Process Flow Runs record to send the email.
The assigned Application Server executes the Process Flow Runs record and sends the email message.

Configuring the Message System Confirmation

By default, when a user sends a bulk message Aptify asks the user to confirm that the message is ready to be sent. In addition, a user has the option to disable this confirmation dialog, so it no longer appears. An administrator can configure Aptify's Messaging to disable this feature by default or re-enable for individual users.

This behavior is controlled by the DisplaySendConfirmationMessage attribute found on the Configuration > Attributes tab of the Message Systems entity. When set to 1, Aptify asks the user to confirm that the message is ready to be sent to recipients after the user clicks Send. Note that a user can turn off this message if desired. When set to 0, Aptify does not display the confirmation message and sends the message immediately after the user clicks send.

Defining a Message Source

Message Sources records define where Bulk Messaging may be run. Message sources must be configured for each service where messaging is required. Aptify provides a Message Source for the following services: Persons, Companies, Organizations, Employees, Orders, and Campaign List Detail. Additionally, message sources may also provide filters to limit the records which can be used for bulk messaging.

The bulk messaging icon appears in the view toolbar for a service if it meets the following two criteria:

The service has at least one active and properly configured Message Source.
The service has at least one email field (that is, a field with an Extended Type of Email). This can be a virtual field.

Follow these steps to create a Message Source to enable messaging for a particular entity that has one or more email fields:

Open a new record from the Message Sources service.
Enter a Name and Description for the message source.
Enter the name of the entity for the message source in the Entity field.

The entity you specify must have at least one field that uses the Email Extended Type.
Place a check mark in the Active box.
To apply a filter to the entity, enter the text of the filter into the Auto Filter field.
- The Auto Filter appends a WHERE clause to the Message Source SQL statement so you can target email recipients.
- For example, to filter the view so that only those records with an email address are included in the bulk message, the Auto Filter is set to Email1 <> ' '.
- If your organization uses the Exclude from Email option on the Persons record to indicate that a person does not wish to receive email communications, you can enter a filter of EmailExclude=0 to automatically filter those people out of a message run.
  - EmailExclude is the field name in the Persons entity for the Exclude From Email option.
  - To combine multiple filters together, use standard operators. For example, to filter out blank email addresses and people who have opted out of emails, enter Email1 <> ' ' AND EmailExclude=0 in the Auto Filter field.
Save the record.
Specify the appropriate Defining Messaging Fields.

Defining Messaging Fields

When configuring a bulk message, the user has the option of selecting to which email address the message should be sent. Messaging fields define the fields in the message source that contain valid email addresses. For example, in the Persons service, the fields that could be used as a valid "To" address for email are Email1, Email2, and Email3.

From the Messaging Fields tab of the Message Sources record, open a new Messaging Fields form.
Enter the name of a field that contains a valid To address into the Field Name field.
- The name you enter must match the name of an email field (that is, a field with an Extended Type of Email) in the Entity specified on the Message Sources record's General tab.
Click OK to save and close the Messaging Fields record.
Repeat steps 1 through 3 to define additional messaging fields.
- Alternatively, you can click OK and New in Step 3 to save the current record and open a new Messaging Fields record in one step.
Save and close the Message Sources record.

Configuring Message Parts

Message parts are used to insert pre-defined, formatted segments into bulk messages. This could include an address in a particular format, a person's order history, and so on. Users can select and insert these parts into their messages.

This topic includes the following sub-topics provides related to Message Parts:

Creating Message Part Categories
Creating a Message Part
About Message Part Examples
About Delivered Message Parts

Creating Message Part Categories

Message parts are organized by category into a hierarchal folder structure. Follow these steps to create a Message Part Categories record:

Open a new record from the Message Part Categories service.
Enter a Name and Description for the message part category in the fields provided.
If the new category is a sub-category, enter the name of the parent Message Part Categories record in the Parent field.
If you want this category to be visible to all users in the Messaging dialog's Select Part dialog, leave the Allow Everyone box checked. If you want to limit this category so that it only appears in the Select Part window for specific users and/or groups (this also applies to any related Message Parts). Follow these steps:
1. Remove the check mark from the Allow Everyone box.
2. Add the users and groups who should have access to this category under the Group Permissions and User Permissions tabs. Any user or group that has a sub-type record under one of these tabs will be able to see the category.
3. Configure the category's availability settings.
If you want this category to be available system wide, select Global from the Availability drop-down menu.If you want to limit access to this category to a set of Message Sources, select MessageSource and define Message Source records on the Message Source tab.
- When selecting a Message Part in the Messaging dialog, a part will only be available if its Availability is Global or if its Availability is MessageSource and the current message source is specified on the part record's Message Sources tab. Likewise, a part's category must be visible in the selection list (based on its Availability setting) in order to see the items in that category. In other words, if a part is available for a particular message source but its category is not, then the part will not be available for selection.
- Also note that a user's ability to select a particular part in the Messaging dialog depends upon the part's availability as well as on the user's access permissions.
  
  The Read, Edit, and Delete check boxes on the permissions form are not reserved for future use.
Save and close the record.

Creating a Message Part

Message parts can be configured for text-based or html-based messages, or both. Message parts can be based on a formatted series of fields from the message source. They can also be based on a Visual Basic script written to extract and format data from other sources.

This topic describes how administrators can create several types of Message Parts from within the Message Parts service. Users can also create simple Message Parts directly within the Aptify Messaging form using the Save Part As... menu option. See the Creating a New Message Part for more details.

Follow these general steps to create a new message part from the Message Parts service:

Open a new record from the Message Parts service.
Enter a Name and Description for the message part.
Select the Type of Message Part.
- Standard: this option is selected by default. Standard message parts are based on fields that exist only in the current message source. For example, a message part for the Persons service could display the person's default address.
- Script: message parts that include information derived from outside the current message source can be set up using a Visual Basic.NET script. For example, a message part for the Persons service could display the order history for that person as a formatted list.
- Component: this option specifies that the message part uses the object specified on the Component tab.
Enter the category for the Message Part in the Category field.
Configure the Message Part as necessary, based on the type of part you are creating.
- For a Standard Part, see Creating a Standard Part.
- For a Script Part, see Creating a Script Part.
- For a Component Part, see Creating a Component Part.
- For a Generic Base Part, see Creating a Generic Base Part.
- For a Derived Part, see Creating a Derived Part.
  
  See the sample Message Parts records included with Aptify for an example of a scripted Generic Base Part (Data Table) and of a derived part (Other People at Same Company Table).
If you want this part to be visible to all users in the Messaging dialog's Select Part window and, in the Part, Quick Select link box, leave the Allow Everyone box checked. To limit access to this part to specific users and/or groups, follow these steps:
- Remove the check mark from the Allow Everyone box.
- Add the users and groups who should have access to this part under the Group Permissions and User Permissions tabs. Any user or group that has a sub-type record under one of these tabs will be able to add the part to a message.
If you want this part to be available system wide, select Global from the Availability drop-down menu. If you want to limit access to this part to a set of Message Sources, select MessageSource and defined Message Source records on the Message Source tab.
- When selecting a Message Part in the Messaging dialog, a part will only be available if its Availability is Global or if its Availability is MessageSource and the current message source is specified on the part record's Message Sources tab.
- Also note that a user's ability to select a particular part in the Messaging dialog depends upon the part's availability as well as on the user's access permissions.
  
  The Read, Edit, and Delete check boxes on the permissions form are reserved for future use.
Save and close the record.

Creating a Standard Part

To create a standard part, follow the basic steps in Creating a Message Part and follow with the additional steps:

On the General tab, leave the Base Part field blank and make sure Only Derived option is unchecked.
Select Standard from the Type drop-down list.
Enter the text for the Message Part on the HTML and/or Text tabs.
- If the Message System supports HTML, then enter the appropriate text on the HTML tab and optionally on the Text tab (if you want to support a fallback option to a plain text message for recipients whose email program does not support HTML). If the Message System does not support HTML, then specify the appropriate text on the Text tab.
- The syntax on the HTML tab should use HTML tags, where appropriate.
- For a Standard message part, the syntax is typically basic and includes field tags from the current message source and any additional text as necessary.

Creating a Script Part

To create a part that is defined by a VB.NET script, follow the basic steps in Creating a Message Part and follow the additional steps:

On the General tab, leave the Base Part field blank and leave the Only Derived box unchecked.
Select Script from the Type drop-down list.
Enter the script to define the contents of the Message Part on the HTML and/or Text tabs.
- If the Message System supports HTML, then enter the appropriate text on the HTML tab and optionally on the Text tab (if you want to support a fallback option to a plain text message for recipients whose email program does not support HTML). If the Message System does not support HTML, specify the appropriate text on the Text tab.
- See the Data Table message part, which is included with the standard Aptify installation, for a sample script.
- Use the Scripting icons to assist you with writing the script. See Administering Scripts for more information.
- See Scripting Response Object for information on the intrinsic Response object, which is available for Messaging scripts.
Aptify's Messaging Engine supports the ability to pass in record data to a message's HTML code using Aptify's mark-up convention (the <<Field Name>> format).
In addition, the Messaging Engine can use C formatting tag to display numeric fields with a currency symbol and a d tag to display date/time fields in the date only (short date) format. For example, you can format money fields with its proper currency symbol using this convention: <<Money Field:C>>. Other formatting options appear below. Note that a value after a format character specifies the number of significant digits or decimal places to display. (For example, the format string, <<Number Field:F2>>, displays a fixed-point number with two decimal places.)
- C: Displays numeric values in currency format.
- D: Displays numeric values in decimal format.
- E: Displays numeric values in scientific (exponential) format.
- F: Displays numeric values in fixed format.
- G: Displays numeric values in general format.
- N: Displays numeric values in number format.
- X: Displays numeric values in hexadecimal format. This is case sensitive. The hexadecimal characters are displayed in the case specified.
  
  For more information about other formatting types, including dates, please visit Microsoft's page on Formatting types in .NET.
See About the Order Confirmation Message Template for Dot Net Mail for information on the sample Message Template that illustrates these features.

Scripting Response Object

Each message part has the ability to execute its own script. In that script, the part can act on an intrinsic object called Response. The Response Object exposes the following members:

WriteText (ByVal NewText As String): Sends new text to the Internal Buffer of the response object.
GetText as string: Returns all text in the Internal Buffer of the response object.
Clear: Removes all text from the Internal Buffer of the response object.
MarkupString(ByVal S As String) as string: Replaces tag items with actual values located in the place of the tags. A tag is considered to be the name of a field. It should have a format such as <%fieldname%>, where fieldname is the name of a database field.
ExecutePart(ByVal PartID As Long): Accepts the ID of another Message Part and attempts to execute it. The resulting text for that execution is buffered at the current end of the Internal buffer of the Response Object. Note that recursive parts are prohibited. If the ExecutePart command results in a recursive call, an error message appears in the Messaging Preview window, which states that recursive parts are not allowed.

See the Data Table Message Parts record included with Aptify for one example of how to use the Response object.

Creating a Component Part

To create a part that uses a .NET component, follow the basic steps in Creating a Message Part and follow the additional steps:

On the General tab, leave the Base Part field blank and make sure the Only Derived option is unchecked.
Select Component from the Type drop-down list.
Select the Component tab and complete the object fields.
- Object: Enter the location of the component object file in the Aptify Object Repository.
- Assembly: Specify the assembly's name of the object.
- Class: Specify the class within the object that defines the message part functionality.

The developer who created the message part object should provide the Object, Class, and Assembly information to you. Creating a new message part object is beyond the scope of this document.

Creating a Generic Base Part

To create a generic part that can serve as the base part for derived parts, follow the basic steps in Creating a Message Part and follow the additional steps:

On the General tab, leave the Base Part field blank.
Place a check mark in the Only Derived box if you do not want this part to appear in the Messaging dialog's Select Part window or Part Quick Select link box.
- In other words, check this box if you only want this part used as the base part for derived parts.
Select the appropriate type from the Type drop-down list. Typically, a generic base part is either a Script or Component-based part.
Define the part as necessary.
- For a script-based generic part, see Creating a Script Part for information on defining the script.
- For a component-based generic part, see Creating a Component Part for information on how to specify the component.
Select the Input Properties tab and add a sub-type record for each property or variable defined in the script or component.
- A derived part leverages the existing functionality of this base part and specifies values for these input properties.
Place a check mark in the Required box for any input property that must be specified by a derived part to successfully use the base part.

Creating a Derived Part

A derived part leverages the functionality of a generic Base Part. To create a derived part, follow the basic steps in Creating a Message Part and follow the additional steps:

On the General tab, enter the generic base part that you want to use in the Base Part field.
Select Standard from the Type drop-down list.
Click the Input Map tab.
Add an Input Map sub-type record for each of the base part's Input Properties that you want to specify.
In the Name field, enter the name of the input property.
In the Value field, enter the value that you want this derived part to insert into the base part for the specified input property.
- At a minimum, you must specify all of the base part's required Input Properties.
- Refer to the base part's Input Properties tab for the list of available inputs.

About Message Part Examples

The following examples illustrate how message parts can be configured for either HTMLbased or text-based messages. All of these examples are based on the Persons service.

Standard Message Part Examples

In the following examples, the message part is configured to display the person's mailing address within the email message. The information to display in this part comes from the current message source. The field tags, << >>, indicate the fields from which the information is retrieved.

Standard Message_ HTML Only

<<AddressLine1>><BR>
<<AddressLine2>><BR>
<<City>>, <<State>> <<ZipCode>><BR>
<<Country>><BR>

Standard Message_ Text Only

<<AddressLine1>>
<<AddressLine2>>
<<City>>, <<State>> <<ZipCode>>
<<Country>>

Script Based Message Part Examples

In the following examples, the message part is configured to display the person's order history. The Visual Basic scripts provided capture the required information from the Orders service and format the information for inclusion within the message.

Script-Based Message: Text Only

Using oDT As System.Data.DataTable = oDataAction.GetDataTable -(oResponse.MarkupString(System.Convert.ToString("SELECT ID,-OrderDate,Line1_ProductName,GrandTotal,Balance FROM APTIFY.dbo.vwOrders WHERE ShipToID=<%ID%>")))

-If oDT.Rows.Count > 0 Then 

Dim sLineBreakString As New String("-"c, oDT.Columns.Count * 20) 

oResponse.WriteText(System.Convert.ToString(oProperties.GetProperty("This is your order history")))

oResponse.WriteText(System.Environment.NewLine) '' Line break

oResponse.WriteText(System.Environment.NewLine) '' Line break
oResponse.WriteText(sLineBreakString)

oResponse.WriteText(System.Environment.NewLine) '' Line break
For Each oCol As System.Data.DataColumn In oDT.Columns

oResponse.WriteText(String.Concat(oCol.ColumnName, " "))
Next 

oResponse.WriteText(System.Environment.NewLine) '' Line break
oResponse.WriteText(sLineBreakString)

oResponse.WriteText(System.Environment.NewLine) '' Line break
For Each oRow As System.Data.DataRow In oDT.Rows
For Each oItem As Object In oRow.ItemArray

oResponse.WriteText(String.Concat(System.Convert.ToString(oItem), " "))
Next
oResponse.WriteText(System.Environment.NewLine)
Next 

oResponse.WriteText(System.Environment.NewLine) '' Line break
oResponse.WriteText(sLineBreakString)

oResponse.WriteText(System.Environment.NewLine) '' Line break
End If
End Using

Script-Based Message: HTML Only

Using oDT As System.Data.DataTable = oDataAction.GetDataTable -(oResponse.MarkupString(System.Convert.ToString("SELECT ID, -OrderDate,Line1_ProductName,GrandTotal,Balance FROM APTIFY.dbo.vwOrders WHERE ShipToID=<%ID%>")))

If oDT.Rows.Count > 0 Then

oResponse.WriteText ("<h2>This is your order history</h2><HR>")

oResponse.WriteText ("<TABLE BORDER=1 CELLSPACING=2 CELLPADDING=3>") 

oResponse.WriteText("<TR>")
For Each oCol As System.Data.DataColumn In oDT.Columns

oResponse.WriteText("<TD>")
oResponse.WriteText(oCol.ColumnName)

oResponse.WriteText("</TD>")
Next

oResponse.WriteText("</TR>") 
For Each oRow As System.Data.DataRow In oDT.Rows

oResponse.WriteText("<TR>")
For Each oItem As Object In oRow.ItemArray

oResponse.WriteText("<TD>")
oResponse.WriteText(System.Convert.ToString(oItem))

oResponse.WriteText("</TD>")
Next

oResponse.WriteText("</TR>")
Next 

oResponse.WriteText("</TABLE>")
End If
End Using

About Delivered Message Parts

The following message parts are delivered with the standard installation of Aptify.

About the Address Update Message Part

This sample part illustrates how an administrator can create a part that interacts with an Aptify e-Business website to allow recipients of a message to update their address directly from the received email. Since this part uses HTML code, it only has an HTML implementation (there is no corresponding Plain Text version). This part rendered a person's address information in a series of text boxes that can be modified and then submitted back to the e-Business server when a recipient clicks the Submit button.

The rendered preview for this part is shown below. Keep in mind that this part is not functional by default; it requires a Web developer to create a page that can process the update information back into Aptify and requires an administrator to update the part to specify the correct website URL where updates should be directed.

About the Data Table Message Part

This is a script-based generic message part that creates a data table using input values provided by a derived message part (such as Other People at Same Company Table). See Creating a Generic Base Part for more information on this type of message part. This data table supports the following input properties:

SQL: A source SQL statement that populates the table. This is required to generate and display a data table.
Title: Specifies a title for the rendered table.
CellSpacing: The amount of spacing in pixels placed between the HTML cells (for an HTML message).
CellPadding: The amount of padding in pixels added to each HTML cell (for an HTML message).
Border: Determines if the table when rendered for an HTML message should use -borders (0 = no borders; 1 = borders).

About the Extended Data Table Message Part

This is a script-based generic message part that creates a data table using input values provided by a derived message part (such as Order Lines). It provides more formatting options than the standard Data Table part. See Creating a Generic Base Part for more information on this type of message part. This data table supports the following input properties:

SQL: A source SQL statement that populates the table. This is required to generate and display a data table.
Title: Specifies a title for the rendered table.
TitleFont: This property accepts a complete FONT tag to set the font for the title. For example: <font face="Tahoma" size="2" color="White"><b>.
CellSpacing: The amount of spacing in pixels placed between the HTML cells (for an HTML message).
CellPadding: The amount of padding in pixels added to each HTML cell (for an HTML message).
Border: Determines if the table when rendered for an HTML message should use -borders (0 = no borders; 1 = borders).
HeaderCellAttributes: Specifies attributes to add to the TD tag for the table header cells (such as bgcolor="white" valign="top").
RowCellAttributes: Specifies attributes to add to the TD tag for every other table body row (first, third, fifth, etc.).
AlternateRowAttributes: Specifies attributes to add to the TD tag for the alternating rows in the table's body (second, fourth, sixth, etc.).
HeaderFont: This property accepts a complete FONT tag to set the font for the header cells.
RowFont: This property accepts a complete FONT tag to set the font for the first, third, fifth, etc. rows in the table.
AlternateRowFont: This property accepts a complete FONT tag to set the font for the alternating rows in the table.
ShowLine: Set this input property to 1 to display a line above the data table (to separate it from other areas of the message). Set this to 0 to omit the line.
AddSummaryRow: Set to 1 to add a summary row to the bottom of the table. For numeric columns, this row displays the total for that column by adding together the values in the individual cells. Set this to 0 to omit a summary row.

About the Meeting City Message Part

This script-based message part provides the city in which the meeting is taken place, based on the Meeting location's address information.

About the Meeting Details Message Part

This part uses a SQL statement to specify that the Meeting Title Base Part should display a table with information about the meeting details from a particular order. See Creating a Derived Part for more information on this type of message part.

This part uses the following SQL statement to populate the Data Table:

SELECT m.SessionWParent AS 'Meeting',m.StartDate AS 'Start Date and Time',omd.AttendeeID_Name As 'Registrant',omd.AttendeeStatus_Name As 'Current Status' FROM dbo.vwOrderMeetDetail omd INNER JOIN dbo.vwMeetings m On omd.ProductID=m.ProductID WHERE omd.OrderID=<%ID%> ORDER BY omd.AttendeeID_Name,m.StartDate

The remaining input properties specify formatting options for the table. See the Message Parts record's Input Map tab for details.

About the Meeting Location Message Part

This script-based message part provides the location of the meeting, based on the Place field in the linked Meetings record.

About the Meeting StartDate Message Part

This script-based message part provides the start date of the linked meeting.

About the Meeting State Message Part

This script-based message part provides the state in which the meeting is taken place, based on the Meeting location's address information.

About the Meeting Title Message Part

This is a script-based message part that displays the Meeting Title (from the Meetings record linked to a campaign).

About the Meeting URL Message Part

This script-based message part provides the website location of the meeting. This information is based on the Web Page field from the linked Meeting's Products record.

About the One Line Address Block Message Part

This part adds the following fields from a record to a message:

AddressLine1
City
State
ZipCode
Country

About the Order History Part Message Part

This part uses a SQL statement to specify that the Data Table Base Part should display a table of the orders where the message recipient is the Ship To person. See Creating a Derived Part for more information on this type of message part.

This part provides these input values for the Data Table:

SQL: SELECT ID, OrderDate 'Order Date', Line1_ProductName 'Product Name', CALC_GrandTotal 'Grand Total' FROM APTIFY.dbo.vwOrders WHERE ShipToID=<%ID%>
Title: This is your order history

Note that the other optional input properties are not specified, and they use default HTML settings.

About the Order Lines Message Part

This part uses a SQL statement to specify that the Meeting Title Base Part should display a table with information the order lines from a particular order. See Creating a Derived Part for more information on this type of message part.

This part uses the following SQL statement to populate the Data Table:

SQL: SELECT Description, Quantity, Price, Discount, Extended FROM APTIFY..vwOrderDetails WHERE OrderID=<%ID%> ORDER BY Sequence

The remaining input properties specify formatting options for the table. See the Message Parts record's Input Map tab for details.

About the Other People at Same Company Table Message Part

This part uses a SQL statement to specify that the Data Table Base Part should display a table of all other Persons who are at the same company as the message recipient. See Creating a Derived Part for more information on this type of message part.

This part provides these input values for the Data Table:

SQL: SELECT FirstName,LastName,Title,Email1,CompanyID FROM APTIFY.dbo.vwPersons WHERE CompanyID=<%CompanyID%> AND ID<><%ID%> ORDER BY LastName, FirstName
Title: People at Your Company in OUR DB

Note that the other optional input properties are not specified, and they use default HTML settings.

About the Two-Line Address Block Message Part

This part adds the same information as the One Line Address Block part, except this part adds the AddressLine2 field.

Creating Message Templates

Message templates make setting up bulk messages quick and easy for users by providing pre-defined messages which can be loaded into the Messaging form. Once loaded, the messages can then be modified to meet the user's requirements prior to being sent.

Templates can include fields or even previously defined Message Parts to allow the user to personalize the message. The user can load existing templates or create new ones from the Bulk Messaging system. Administrators may also define message templates from the Message Templates service and arrange them in a hierarchal folder structure through the use of categories.

This topic provides the following sub-topics related to Message Templates:

Creating Message Template Categories

Message Templates are presented to the user in a hierarchical folder structure. These folders and hierarchy are configured through the use of message template categories. Follow these steps to create a new category:

Open a new record from the Message Template Categories service.
Enter a Name and Description for the category.
If the new category is a sub-category, enter the parent message template category in the Parent field.
- If you enter a Parent, then the new category will appear as a sub-folder beneath its parent in the Messaging dialog's Load Template window.
Select the Scope for the message template category.
- If the scope is set to Global, all users can see this category in the Load Template window, assuming they have the necessary permissions (see below).
- If the scope is set to User, only the user listed in the Who Created field can see this category (even if the Allow Everyone To Access box is checked).
Enter any optional details about this category in the Comments field.
Configure the category's security settings (if Scope is set to Global).
- If you want this category to be visible to all users in the Messaging dialog's Load Template window, leave the Allow Everyone To Access box checked.
- To limit access to this category to specific users and/or groups, follow these steps:
1. 1. Remove the check mark from the Allow Everyone To Access box.
  2. Add the users and groups who should have access to this category under the Group Permissions and User Permissions tabs. Any user or group that has a sub-type record under one of these tabs will be able to see this category.
Configure the category's availability settings.
- If you want this category to be available system wide, select Global from the Availability drop-down menu.
- You can limit access to this category to a set of Message Sources by selecting MessageSource and defining Message Source records on the Message Source tab.
1. - When selecting a Message Template in the Messaging dialog, a template will only be available if its Availability is Global or if its Availability is MessageSource and the current message source is specified on the template record's Message Sources tab. Likewise, a template's category must be visible in the selection list (based on its Availability setting) in order to see the items in that category. In other words, if a template is available for a particular message source but its category is not, then the template will not be available for selection.
  - Also note that a user's ability to select a particular template in the Messaging dialog depends upon the template's availability as well as on the user's access permissions.
    
    Fields Reserved for Future Use
    
    The Read, Edit, and Delete check boxes on the permissions form are reserved for future use.
Save and close the record.
- The Who Created and Date Created fields, which are visible in a Message Template Categories view, are automatically populated by the system when the record is first saved.

Creating a New Template from the Message Templates Service

Message templates can be defined either manually by creating a new Message Templates record or through the user interface on the Messaging form. The manual method is described in the steps below.

For the sake of simplicity, Aptify recommends that templates be created using the Messaging dialog and then modified as needed (as described in the Modifying a Template's Security Settings steps). See Creating a New Message Template and Modifying a Message Template for details.

Open a new record from the Message Templates service.
Enter a Name and Description for the message template.
Enter the Category for the message template. This determines where in the template folder structure the template is stored and displayed to the user. within the Load Template dialog.
Enter a Subject to be placed in the Subject line of all messages based on this template.
Enter a message system into the Default Message System field. This specifies the message system that is used when this template is loaded.
- If this message system specified in the template is different from the Messaging dialog's default, then a notification appears prompting the user to override the Messaging dialog's default setting.
Enter a message source into the Default Message Source field. This field is required.
- This field does not limit the template to a particular Message Source; all templates with the appropriate security settings are available for selection within the Messaging dialog regardless of the Message Source that is loaded.
- This field is primarily used for messages that are generated automatically by Aptify outside of the messaging dialog (for example, as part of a process flow). Message Source is a required property to send messages.
Set the Scope for the message template. By default, the scope is set to Global for templates created from the Message Templates services.
- When set to Global, all users may use the template (depending on the Share Template option).
- When set to User, only the user listed in the Who Created field may have access to this template. Note that templates created in the Messaging dialog default to Global scope.
- When the Share Template option is selected on a message template, the Scope is set to Global.
Configure the template's security settings (if Scope is set to Global).
- If you want this template to be visible to all users in the Messaging dialog's Load Template window, leave the Allow Everyone box checked.
- To limit access to this template to specific users and/or groups, follow these steps:
  1. Clear the Allow Everyone option.
  2. Add the users and groups who should have access to this template under the Group Permissions and User Permissions tabs. Any user or group that has a sub-type record under one of these tabs will be able to use this template.
    
    Fields Reserved for Future Use
    
    The Read, Edit, and Delete check boxes on the permissions form are reserved for future use.
Configure the template's availability settings.
1. If you want this part to be available system wide, select Global from the Availability drop-down menu.
2. You can limit access to this template to a set of Message Sources by selecting MessageSource and defining Message Source records on the Message Source tab.
  - When selecting a Message Template in the Messaging dialog, a template will only be available if its Availability is Global or if its Availability is MessageSource and the current message source is specified on the template record's Message Sources tab.
  - Also note that a user's ability to select a particular template in the Messaging dialog depends upon the part's availability as well as on the user's access permissions.
Click the Delivery tab and configure the delivery options.
- See About the Message Templates Form for the complete list of options.
- These fields automatically flow down to the Messaging dialog's Options > Delivery tab when the template is loaded.
Enter the message text on the HTML and/or Plain Text tabs. Use the proper syntax when entering the message on a particular tab.
1. If the template is for text-only messages (that is, a message sent by a Message System that does not support HTML), enter the message syntax into the Text Body field. The information entered into the Text Body field is written so that the data can be viewed in a text-based message.
2. If the message is to be sent by a Message System that supports HTML, enter the message syntax into the HTML Body field. This syntax is written using normal syntax from the HTML language to format the appropriate information so that it can appear in an HTMLbased message.
  - Aptify's Messaging Engine also supports the ability to pass in record data to a message's HTML code using Aptify's mark-up convention (the <<Field Name>> format). In addition, the Messaging Engine can format money fields with its proper currency symbol if a field uses this convention: <<Money Field:C>>. See About the Order Confirmation Message Template for Dot Net Mail for information on the sample Message Template that illustrates these features.
3. Also, if the Message System supports HTML, you can enter the message on either tab or on both tabs. If you enter the message on both tabs, a recipient receives the HTML message unless the recipient's email program does not support HTML. In that case, the recipient receives the message in Plain Text.
Define any applicable actions that should be executed after the message template is sent on the Actions tab.
- See Configuring Message Actions for more details.
Save and close the record.

About the Delivered Message Templates

The following delivered message templates are included in the standard Aptify installation.

About the Address & Order History Message Template

This template for the Persons service generates an email message that asks the recipient to verify his or her address and includes information on that person's order history with the organization. By default, this template is available to all users in the Verification Email category, and it uses the Outlook Mail message system. To display the address fields from the Persons record, this template uses the One Line Address Block message part. To display the order history information, the template uses the Order History Part message part.

About the Address Verification Message Template

This template for the Persons service generates an email message that asks the recipient to verify his or her address based on address fields obtained from that person's Persons record in Aptify. By default, this template is available to all users in the Verification Email category, and it uses the Outlook Mail message system.

About the Aptify Bulk Message Template

This template for the Persons service generates an email message and illustrates how an organization can create standardized email templates using an organization's logo and contact information to send bulk email messages. By default, this template is available to all users in the Marketing category, and it uses the Outlook Mail message system. Note that the HTML code for this template illustrates how you can use Aptify's mark-up convention (using the <<Field Name>> format) to pass record data into a message.

About the Aptify Order Confirmation Message Template for Outlook

This template for the Orders service generates an email message that provides an order summary to a Ship To person. By default, this template is available to all users in the Order Processing category, and it uses the Microsoft Outlook Mail message system. To display the order lines information from the Orders record, this template uses the Order Lines message part. Note that the HTML code for this template illustrates how you can use Aptify's mark-up convention (using the <<Field Name>> format) to pass record data into a message. In addition, this template illustrates how to configure the message to display money fields with its proper currency symbol using this convention: <<Money Field:C>>.

This template is similar to the Order Confirmation template used for the Dot Net Mail message system. See About the Order Confirmation Message Template for Dot Net Mail for more information.

About the Meeting Activity Notification Message Template

This template for the Orders service generates an email message that provides a notification of any recent registration activities, including the ID of the registration order and the meeting's start date and time and other meeting related information. By default, this template is available to all users in the Order Processing category, and it uses the Outlook Mail message system by default. To display details about the meeting, this template uses the Order Lines message part.

About the Meeting Invitation Message Template

This template for the Campaign List Details service generates an email message that provides a invitation to register for a meeting that includes the meeting title, meeting date and time, and the location and website location of the meeting. By default, this template is available to all users in the Seminar Promotion category, and it uses the Dot Net Mail message system by default. To display the meeting related information, this template uses the Meeting Title, Meeting URL, Meeting StartDate, Meeting Location, Meeting City, and Meeting State message parts.

About the Order Confirmation Message Template for Dot Net Mail

This template for the Orders service generates an email message that provides an order summary to a Ship To and Bill To person (as an additional address in the CC: field). By default, this template is available to all users in the Order Processing category, and it uses the Dot Net Mail message system. To display the order lines information from the Orders record, this template uses the Order Lines message part. Note that the HTML code for this template illustrates how you can use Aptify's mark-up convention (using the <<Field Name>> format) to pass record data into a message. In addition, this template illustrates how to configure the message to display money fields with its proper currency symbol using this convention: <<Money Field:C>>.

This template is similar to the Aptify Order Confirmation template, which uses the Microsoft Outlook Mail message system. See About the Aptify Order Confirmation Message Template for Outlook for more information.

Configuring Message Actions

When a user has completed a bulk message configuration and presses the Send Messages button, Aptify can automatically fire a process flow to automate actions that need to take place after the message is sent. For example, if you want to create a contact log for each bulk message recipient, you could define an action that creates and links Contact Logs record to a corresponding record automatically (the contact log is linked to the Message Runs record as well). By default, Aptify includes a message action to perform this action when sending a message from a Persons or Organizations record.

Message Actions records store information about a defined message action, including the process flow that will be fired to execute the action and the services where this action is available. Once a Message Actions record has been created, it is accessible for the specified service(s) from the Actions tab of the Aptify Messaging form. You also add Message Actions directly to Message Templates records.

Follow the steps below to create a Message Actions record:

Open a new record from the Message Actions service.
Enter a Name and Description for the message action.
Enter the name of the Process Flow that will be fired after the message is sent.
- This field links to the Process Flows service.
Place a check mark in the Active box to make this Message Action available to users.
If you want to make the action available for all messages sent from a particular entity, select the Message Action Entities tab.
- Specifying an entity for a Message Action makes it accessible for all messages sent from the particular entity through the Aptify Messaging form. If you want to specify the action for a particular message and not an entity as a whole, you can do so by creating a Message Templates record and specifying the message action on the template's Actions tab. See Creating Message Templates for details.
Click the New icon to open a new Message Action Entities record.
Enter the service in which you want the action to be available for in the Entity ID field.
Place a check mark in the Auto Add box if you want this message action to be automatically available (and executed if the action is not removed by the user) each time a message sent from this service.
- Note that when using a message template that has message actions specified or when loading a template from a service that has associated message actions, a user must confirm whether or not to replace the existing actions for the service with the actions associated with the selected message template. See Loading a Message Template for details.
Click OK to close the Message Action Entities sub-type record.
Repeat Steps 6 through 8 as needed to add additional entities.
- Alternatively, you can select OK and New in Step 9 to close the current record and open a new Message Actions Entities record in one step.
Save and close the Message Actions record.

About Message Runs

When a user has completed a bulk message configuration and pressed the Send Messages button on the Messaging form, the system automatically generates a Message Runs record and then prepares the necessary email message for the Message System (if the Message Run does not require approval first). Message Runs records store all the relevant information about the defined messages, including the message system, message source, message text (whether in HTML, plain text format, or both), message recipients, and so on. See About the Message Runs Form for more information.

Message Runs records are created automatically by the system. They should not be created manually, and should only be updated by a system administrator, as necessary (for example, to approve a Message Run for transmission, as described in Requiring Approval to Send Messages ).

Message Schedules and Recurring Delivery

Message Schedules and Recurring Delivery allow an organization to schedule the delivery of periodic messages to a target audience. It also provides the ability to rotate among multiple pre-defined Message Templates so that the same message does not necessarily need to be transmitted each time a scheduled message run occurs. Message Scheduling leverages the same Aptify Scheduled Task infrastructure that is also used by features such as View Scheduling and delayed message delivery.

This section covers the following topics dealing with Message Schedules:

Configuring the Message Schedules Entity

To support the Message Schedule functionality, an administrator must configure the Message Scheduling default options in the Message Schedules entity. Follow these steps to enable support for message scheduling:

Open the Message Schedules record from the Entities service.
The Entities service is found under the Messaging Administration or Framework application.
Click the Configuration > Attributes tab.
Configure the following attributes, as necessary:
- ScheduledViewProcessFlow: This is the name of the Process Flow that handles auto-execution of the message run for the schedule Messages. By default, this attribute is set to Execute Message Schedule, which is the Process Flow provided by Aptify. If you have created your own Process Flow to handle Message Scheduling, edit this attribute to use that Process Flow's name.
- ScheduledViewScheduledTaskService: This is the name of the Scheduled Task Service that will be used to save Scheduled Tasks records generated by message scheduling. By default, this attribute is set to Remote Scheduler, which is the Scheduled Task Service that allows users without elevated permissions to save Scheduled Tasks records. After the initial save, the Remote Scheduler creates a Process Flow Runs record to use the Application Server to convert the Scheduled Task Service to the standard Windows Scheduler and consequently create the Windows Scheduled Task on the Application Server.
- ScheduledViewScheduledTaskCategory: This is the name of the Scheduled Task Category that will be assigned to all Scheduled Tasks created by Message Scheduling. By default, this attribute is set to Scheduled Messages. If you have created your own Scheduled Task Categories record and want to use it as the default category for Message Scheduling, enter that category's name as the attribute value.
- ScheduledViewApplicationServer: This is the name of the Application Server on your network that will execute the message schedules based on the information stored in the Scheduled Tasks record. You must enter the name of an installed Application Server in order to support Message Scheduling. This Application Server must have a default Job Account Username and Password.

When enabling Message Scheduling, you only need to specify an Application Server's name as the value for the ScheduleMessageApplicationServer attribute. You can leave the other attributes at their default setting.

Creating Message Schedule Categories

This service stores the set of categories that can be applied to Message Schedules records and is required in order for Message Schedules records to be saved.

Note that by default, Aptify does not include a Message Schedule Categories record.

Follow these steps to create a new category:

Open a new record from the Message Schedule Categories service.
Enter a Name and Description for the category.
If the new category is a sub-category, enter the parent message schedule category in the Parent field.
Enter any optional details about this category in the Comments tab.
Save the record and close the record.

Modifying Message Schedules

Only an administrator can modify existing Message Schedules records and/or Scheduled Tasks records directly if changes are required to the message schedule. For example, to disable a Message Schedules record so it no longer sends out a recurring message, an administrator should disable the corresponding Scheduled Tasks record. Follow these steps to disable a message schedule:

Open the Scheduled Task record for the Message Schedules record in which you want to modify.
The Scheduled Tasks service is in the Process Pipeline Administration application.
Go to the General tab.
Remove the check mark from the Is Enabled field.
Save and close the record.
- The Scheduled Task record is no longer active and will no longer send out a recurring message.

About the Message Schedule Process

The following is an overview of the message scheduling process:

A user runs the Schedule Message Wizard to create a Message Schedules record and the corresponding Scheduled Task that will execute the message schedule on a recurring basis. This wizard can be launched from either the Aptify Messaging dialog or from the Message Schedules service. Typically, the wizard will be launched from the Aptify Messaging dialog since users will generally not have access to the Message Schedules service directly.
- See the Scheduling Recurring Messages for information on how to use the Schedule Message wizard to create message schedules.
When the user saves the message schedule, Aptify creates a "Message Auto-Scheduler" Scheduled Tasks record that contains the information specified by the user.
- This Scheduled Task uses the Remote Scheduler service (since not all users will have the appropriate permissions to create Windows Scheduled Tasks on the Application Server).
The Remote Scheduler service creates a Process Flow Runs record to change the Scheduled Task's service from Remote Scheduler to Windows Scheduler.
The Application Server executes the Process Flow Run and updates the Scheduled Task's service to Windows Scheduler. This generates a Windows Scheduled Task on the Application Server that will execute the bulk message run.
- Since the Application Server's user account modifies the Scheduled Tasks record, that user account, which should already have the necessary permissions, creates the Windows Scheduled Task in lieu of the user who originally saved the message schedule.
At the specified date and time, the Scheduled Task creates a Process Flow Runs record that fires the "Execute Message Schedule" process flow using the input values provided by the user.
The assigned Application Server executes the Process Flow Runs record and sends the email message.

Bulk Messaging and Faxes

Many clients transmit a mix of email messages and faxes to clients. To send faxes from Aptify's bulk messaging system, an organization can use a third-party fax server program, such as RightFax from Captaris, Inc., that integrates with the organization's email server (typically, an SMTP server). The following is an example of one implementation that can send the same message as an email or fax depending on a person's communication preferences:

An administrator installs a third-party fax server program on the organization's email server that acts as a fax "gateway." This fax gateway automatically pulls out the messages to fax recipients and directs them to the outgoing fax process instead of sending the messages as email.
An administrator adds a new calculated virtual field to the Persons entity with a name like "PreferredEmailFax." The SQL statement that defines the field should contain a CASE statement that switches between an email address or a fax number depending on a Person's PrefCommMethodID (either email or fax). Also, the field may need to reformat the fax number to match the required format of the fax server program. For example, a fax server program may require that a fax number of 202-223-2800 be in the following format to successfully send the fax: "Fax@12022232800". See Creating a Field of a Specific Type for information on how to create a calculated field.
An administrator creates a Message Source for the Persons service that uses the virtual field as the Messaging Field. Then, a user can launch the bulk messaging icon from a view and the system will automatically insert a Person's email or fax number as the message's To address based on the Person's preference. See Defining a Message Source for information.

A second implementation would be to create a Message Source for fax transmissions only. In this case, an administrator would create a calculated virtual field to format the fax number in the appropriate format (such as "Fax@12022232800") and then use this virtual field as the Messaging Field in the Message Sources record.

Bulk Messages from Temporary Views

Many forms in Aptify contain tabs that display a view of related records. This view can either be sourced by a Views record or by a SQL statement. Views that use a SQL statement as its source are referred to as "temporary views" in Aptify.

If you are defining a complex view for a form's tab that joins one or more database objects, the view must meet the following criteria to successfully interact with the Messaging system:

Each field referenced in the SQL statement must be fully qualified (such as "APTIFY..vwPersons.ID," rather specifying only "ID").
The SQL statement cannot select all fields using SELECT * FROM....
The ID field in the SELECT clause must use an alias in the format shown in the following example: APTIFY..vwPersons.ID ID...

Here is an example of a complex SQL view in the format required for messaging:

SELECT APTIFY..vwPersons.ID ID,APTIFY..vwPersons.FirstName FirstName,APTIFY..vwPersons.LastName LastName 
FROM APTIFY..vwPersons 
INNER JOIN APTIFY..vwPersonFunctions ON APTIFY..vwPersonFunctions.PersonID = APTIFY..vwPersons.ID 
INNER JOIN APTIFY..vwOrders ON APTIFY..vwOrders.ShipToCompanyID = APTIFY..vwPersons.CompanyID 
WHERE APTIFY..vwOrders.ID = <an OrderID> AND APTIFY..vwPersonFunctions.FunctionID = <a FunctionID>

Capturing Message Details from a Message Run for Use in a Process Flow

Aptify includes two global events (the BeforeSendMessage and AfterSendMessage Event Definitions) that capture information when a message is sent out by Aptify's Message Engine. Using these events, you can pass message details into a process flow as needed, such as to automatically generate a Contact Log record when a message is sent.

Keep in mind that these values apply to a specific message in a Message Run. In other words, if a Message Run has four recipients, the global event is fired four times, once per recipient.

The following is the list of properties that are captured as part of the BeforeSendMessage and AfterSendMessage events. They constitute the entire set of properties available when using the BeforeSendMessage and AfterSendMessage global events and generally correspond to fields found in a Message Runs record.

ToEmail: Email address of recipient.
CCEmail: Email address of any carbon-copied recipients.
BCCEmail: Email address of any blind carbon-copied recipients.
Priority: The email's assigned priority level.
FromDisplayName: The display name for the email sender.
FromEmail: The sender's email address.
ReplyToEmail: The message's Reply To email address.
Subject: The message's subject.
TextBody: The plain text version of the message.
HTMLBody: The HTML Body version of the message.
EntityID: The ID of the entity from which the message was sent. That is, the Entity linked to the message run's Message Source.
MessageDataRow: The position of this message within the Message Runs data set.
ToType: The type of email address used for the recipient (Static or dynamic based on a Field value).
CCType: The type of email address used for CC recipients (Static or dynamic based on a Field value).
BCCType: The type of email address used for BCC recipients (Static or dynamic based on a Field value).

Note that when creating an Event Handler for a process flow that uses these messaging properties as Input Properties, use a Global Event Scope (which means that the process flow will fire whenever a message is sent by the Aptify Messaging Engine). In this case, the Source and Source Type information in the Event Handler Input Map populate automatically based on the Input Properties of the specified Process Flow and the Input Map grid is read-only and does not allow a user to make any changes to the global property information.

The figure below illustrates a Global Event Handler for the BeforeSendMessage event definition linked to a process flow that uses all of the available message fields as Input Properties.

Using this type of Global Event Handler, an administrator or developer can create a process flow that leverages Aptify's standard CRUD components to automatically generate Contact Log records for each message that is sent by the system. This type of process flow could include:

A Rule-based step to obtain information not directly provided by the message fields (such as obtaining the recipient's PersonID record based on the ToEmail address).
A Create Contact Log component step to generate a Contact Log record that passes the message's Subject and HTMLBody field to a Contact Log's Description and Details fields.
One or more Create Contact Log Links steps to generate links to Persons, Companies, and Employees for this new Contact Log record.

See How to Create a Process Pipeline for information on how to create process flows and define event handlers.

Configuring an Email Control to Launch Aptify Messaging

By default, when a user selects the icon that appears next to an Email control on a form, a new mail message is opened from the user's Outlook application. However, an administrator can also configure an Email control to launch Aptify's Messaging form so that users can access message templates and other mail-related features directly from a record.

This behavior is controlled by the GlobalUseAptifyMessaging attribute found on the Configuration > Attributes tab of the Message Systems entity. When set to 1, the system launches the Aptify Messaging form. When set to 0 (the default value), Aptify opens a new Outlook Mail message.

An administrator can modify this attribute at the global level as necessary based on the system functionality desired. In addition, an administrator can add the UseAptifyMessaging attribute to any entity to control the behavior for email fields on a per-entity basis. When set to 1, the system overrides the global attribute and launches the Aptify Messaging form for the particular service. When set to 0, Aptify overrides the global attribute and opens a new Outlook Mail message for the particular service.

Note that the email field that appears on the standard Persons form is configured to launch the Aptify Messaging dialog by default.

Notice

We have upgraded our support system to serve you better. For Support, please go to our Momentive Support Hub located here.