Sending a Purchase Confirmation by E-mail

This section describes the procedure for adding a pipeline component that will automatically send an e-mail order confirmation message when a new order is received. This example assumes that an e-mail address is required when users fill out their profile. This e-mail address is stored with the user information, and is therefore available in the order form.

In this example, the format of the confirmation e-mail is as follows:

Subject: Order Confirmation

Thank you for shopping at our store. Your order is confirmed. 

Tracking number: 93LFF5XNE9SK2TVX00L1R0D9N7

Total purchase: $57.25

This section contains:

Step 1: Adding the text strings to the MessageManager object

Step 2: Creating a script to format the e-mail message

Step 3: Adding the Scriptor component to the pipeline

Step 4: Adding the SendSMTP component to the pipeline

Step 1: Adding the text strings to the MessageManager object

The first step is to add the text of the message to the MessageManager object. Although this step is not strictly necessary (the text could appear as string literals in the script), using the MessageManager object centralizes all text for the site and makes it easy to add support for additional languages at a later time. Add the necessary messages to the MessageManager object by performing the following steps:

  1. Using a text editor, such as Notepad, open the retail site Global.asa file. The file is usually located at C:\Inetpub\wwwroot\retail.

  2. After the call to Main at the end of the list of MessageManager strings, add the following lines:

    Dim oMessageManager
    Set  oMessageManager = Server.CreateObject(""Commerce.MessageManager"")
    Call oMessageManager.AddLanguage(""usa"", &H0409)
    Call oMessageManager.AddLanguage(""FRA"", &H040c)
    Call oMessageManager.AddLanguage(""ENC"", &H1009)
    oMessageManager.defaultLanguage = ""usa""
    Call oMessageManager.AddMessage(""email_subject"", ""Order Confirmation"")
    Call oMessageManager.AddMessage(""email_body"", ""Thank you for shopping at our store. Your order is confirmed. "")
    Call oMessageManager.AddMessage(""email_tracking"", ""Tracking number: "")
    Call oMessageManager.AddMessage(""email_total"", ""Total purchase: "")
    

Step 2: Creating a script to format the e-mail message

After the proper code has been added to the Global.asa file, the next step is to create a script that formats the e-mail message. The script is to be used in a Scriptor component. The script must add the subject and message body text to the order form, so that a later component in the pipeline can send the e-mail.

Create a file named Email.vbs in the <drive:>\Inetpub\wwwroot\<sitename>\pipeline directory. Using a text editor such as Notepad, type or copy the following script into the file:

Function mscsexecute(config, orderform, context, flags)
    Dim oMessageManager, oDataFunctions 
    Set oMessageManager = context.MessageManager
    Set oDataFunctions = context.DataFunctions
        
    orderform.[_email_subject] = _
              oMessageManager.GetMessage(""email_subject"")
    orderform.[_email_body] = _
              oMessageManager.GetMessage(""email_body"") _
              & chr(10) & chr(13) _
              & oMessageManager.GetMessage(""email_tracking"") _
              & orderform.[order_id] _
              & chr(10) & chr(13) _
              & oMessagemanager.GetMessage(""email_total"") _
              & oDataFunctions.Money(CLng(orderform.[_total_total]))
    mscsexecute = 1
End Function

When this script is run by the Scriptor component in the pipeline, it adds two new fields to the order form: _email_subject is used as the subject line for the e-mail, and _email_body is used as the body of the e-mail.

The script formats these strings by getting the appropriate messages from the MessageManager object and concatenating these strings with values from the order form, including the tracking number (order_id) and the purchase total (_total_total).

mscsMessagemanager.GetMessage(""email_tracking"") & orderform.[order_id] 

generates this portion of the e-mail message body:

Tracking number: 93LFF5XNE9SK2TVX00L1R0D9N7

To format the total price as text in the local currency, the price is converted from numeric form as it is stored in the order form, using the DataFunctions.Money method.

Because the script uses methods of both the MessageManager object and the DataFunctions object, it first creates references to these objects. These references are provided by the PipeContext dictionary, which is passed in as an argument to the pipeline.

The function concludes with the following script, which indicates that the component ran successfully in the pipeline:

mscsexecute = 1

Ee783749.note(en-US,CS.20).gif Note

  • In a site where the e-mail field is optional, make sure that the SendSMTP component does not attempt to send e-mail. You can disable the SendSMTP component by submitting a To field that contains the text None. The Email.vbs script can check for the existence of an e-mail name. If the user did not provide such a name, the script would substitute the text None.

Step 3: Adding the Scriptor component to the pipeline

In order to run the Email.vbs script within the OPP, a Scriptor component must be added to the Purchase pipeline configuration, as described in the following steps:

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Pipeline Editor.

  2. Open the Purchase.pct template, or the purchase pipeline for your site. Pipelines used in active sites are usually stored at C:/Inetpub/wwwroot/<site name>/pipeline.

  3. Open the Accept stage.

  4. Right-click the last component in that stage, or on the Accept stage itself if there are no components in the stage.

  5. Right-click Insert Component, and then click After.

  6. In the Choose a component dialog box, click Scriptor, and then click OK.

    The Scriptor component is added to the Accept stage.

  7. Double-click the Scriptor component icon.

  8. In the Component Properties dialog box, do the following:

    Use this To do this
    Scripting Engine Select VBScript.
    Source Select External.
    Filename Click Browse to find the location of the Email.vbs file, or type the path to the Email.vbs file.
  9. On the Component Properties tab, edit the Label box to provide a more helpful description (for example, Scriptor: Email.vbs (Format e-mail confirmation).

  10. Click OK to close the property page.

Step 4: Adding the SendSMTP component to the pipeline

The final step is to add the SendSMTP component to the Purchase pipeline configuration:

  1. In the Pipeline Editor, right-click the Scriptor component that you just added in Step 3: Adding the Scriptor Component to the Pipeline.

  2. Right-click Insert Component, and then click After.

  3. In the Choose a component dialog box, click SendSMTP, and then click OK.

  4. Double-click the SendSMTP component or its icon in the Pipeline Editor.

  5. In the ComponentProperties dialog box, on the SendSMTP tab, do the following.

    Use this To do this
    From Type the e-mail account of the computer from which the e-mail is sent.
    SMTP Host Type the active SMTP host name that the computer uses to send e-mail.
    To Type _shopper_email.
    cc Leave blank.
    Subject Type _email_subject.
    Message Body Type _email_body.
    Message Body Contains Select one of the three choices based on the content of your e-mail. For our example, select TextBody.

    These values in the OrderForm object will be used to format the e-mail. On the To line, _shopper_email is part of the user information that is added to the order form; on the Subject and Message Body lines, _email_subject and _email_body are the values added to the order form by the Email.vbs script.

  6. In the Component Properties dialog box, on the SendSMTP tab, do the following:

    Use this To do this
    Email address to send test message to Type an e-mail address to send the test message to.
  7. Click Send test Email.

  8. On the Component Properties tab, in the Label box, type a description.

  9. Click OK to close the property pages.

  10. On the File menu, click Save As.

  11. In the Save As dialog box, browse to the location where you would like to save the file, and then click Save.

  12. On the File menu, click Exit.

Reload the site so that your changes to the Global.asa file take effect.

Ee783749.note(en-US,CS.20).gif Note

  • When adding components to a pipeline, it is important to consider the order in which the components appear. In the case of confirmation by e-mail, after the SendSMTP component has successfully sent the e-mail, the e-mail cannot be recalled if subsequent pipeline components fail. For this reason, the e-mail components have been placed last in the pipeline configuration. In this way, the e-mail is sent only if all other components succeed.

Using a Template

Depending on the complexity of the text you want in the e-mail reply, you might prefer to use a template to generate the e-mail message body. The component combines values on the order form with text in a template file.

To use a template, create a script to format the subject line and to convert any numeric values to their displayable text form. The following script does not generate the message body. The following file, Email.vbs, is loaded into a Scriptor component:

Function mscsexecute(config, orderform, context, flags)
    Dim mscsDataFunctions 
    Set mscsDataFunctions = context.DataFunctions

    orderform.[_email_subject] = ""Order Confirmation""
    orderform.[_email_total] = mscsDataFunctions.Money(CLng(orderform.[_total_total])) 
    mscsexecute = 1
End Function

Next, create a template file. In this example, the file is named Confirm_Template.vbs, and resides in the <drive:>\Inetpub\wwwroot\<sitename>\pipeline directory:

Thank you for shopping at our store. Your order is on its way. 

Tracking number: <%%= order_id %%>
<%% Dim nItemcount
    nItemCount = Items.Items.count
if (nitemcount > 0) then
    dim iItem,Item
    for iItem = 0 to nitemcount - 1
    Set Item = Items.Items.Item(iItem) %%> 
<%%= item.quantity %%> <%%= item.[_product_name] %%> <%%
    next
end if  %%>

Total purchase: <%%= [_email_total] %%>

Using the Pipeline Editor, insert a MakePO component in the Accept stage, immediately following the Scriptor component. Open the Component Properties dialog box by right-clicking the component and clicking Properties. Specify the Template File Name to indicate the template file just created (Confirm_Template.exe). Specify the Output Property Name as _email_body. The MakePO component, when run, will merge the template text with the values on the order form specified by the commands in the template, and will write the result to the _email_body name/value pair in the order form.

Insert the SendSMTP component after the MakePO component as described in Step 4: Adding the SendSMTP Component to the Pipeline. The SendSMTP component, when run, will use the subject line text generated by the Scriptor component, and the body message generated by the MakePO component.

The following is an example of a message body generated by this template:

Thank you for shopping at our store. Your order is on its way. 

Tracking number: 8BMKQ3NHKES12M9D00L1R0D8N7
 
1 Plastic Commuter Mug 

Total purchase: $14.28

Copyright © 2005 Microsoft Corporation.
All rights reserved.