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:

1. Open a new record from the Message Parts service.
2. Enter a Name and Description for the message part.
3. 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. 
4. Enter the category for the Message Part in the Category field.
   
    
5. 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). 

6. 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. 
7. 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. 

8. 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:

1. On the General tab, leave the Base Part field blank and make sure Only Derived option is unchecked.
2. Select Standard from the Type drop-down list.
3. 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:

1. On the General tab, leave the Base Part field blank and leave the Only Derived box unchecked.
2. Select Script from the Type drop-down list.
3. 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. 
4. 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).
5. 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.
     
     
6. 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:

1. On the General tab, leave the Base Part field blank and make sure the Only Derived option is unchecked.
2. Select Component from the Type drop-down list.
3. 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:

1. On the General tab, leave the Base Part field blank.
2. 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. 
3. Select the appropriate type from the Type drop-down list. Typically, a generic base part is either a Script or Component-based part.
4. 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. 
5. 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. 
6. 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:

1. On the General tab, enter the generic base part that you want to use in the Base Part field.
2. Select Standard from the Type drop-down list.
3. Click the Input Map tab.
4. Add an Input Map sub-type record for each of the base part's Input Properties that you want to specify.
5. In the Name field, enter the name of the input property.
6. 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.