Copyright © 1999, William Weiland
The addendum module allows you to collect supplemental responses from customers at checkout. You can add as many questions to your form as you want. The responses are exported to a delimited text file which can be imported into most database management systems for further analysis. You can also have those responses appear in the Email notification and batch processing.
Use the Merchant admin upload feature to upload the modules addendum.mv and cim_add.mv. As each are uploaded, click the Add button to add them to the mall/domain.
In admin, under your store, click on the link for the System Extension Configuration screen. Assign the CIM Addendum Extension module and Update it to install it in your store.
In admin, under your store, click on the link for the Fulfillment Configuration screen. Assign the Addendum module and Update it to install it in your store.
Click the link for Addendum to enter the configuration settings and add Addendum questions. You can have radio, select, checkbox, text and textarea type inputs. Note: if you are using PayPal, paylink or any of the other payment modules that send the customer off-site to complete payment information, you cannot place the addendum questions on the last checkout screen (order payment). Rather, you should use the next to the last screen (shipping and payment selection).
You can also designate one or more of the questions to be required. If the customer does not answer the question, they will be recycled to the same page and will not be able to continue. In many cases this will be in the form of a checkbox to Accept terms of the purchase/sale. Simply include the number of the question(s) you want to be mandatory.
In the compiled version you can limit the display of Addendum questions based on specific product codes. If you list product codes in the admin input, the questions will only be displayed if one of those products is in the basket at checkout. You can also use the wild card product code like 1AA*. If the applicable products all begin with the same characters, you can use the asterisk. This can only be used for the beginning characters in the product codes. If you leave the product code input blank, the addendum questions will appear at checkout no matter what product were ordered.
Also in the compiled version, you can optionally include the questions in the emails along with the responses. If using the OpenUI, you can select in admin whether to insert the response in the merchant notification or customer confirmation emails or both. Previous versions it was automatically put in the merchant notification only. If using the MMUI, it can be done in the new and old versions of Addendum by editing the meremail and custeml files. Editing in the compiled version requires having the source code and the compiler to re-compile the files. Most store owners will not have this option so the OpenUI is the easiest and least expensive way to implement this feature.
In the compiled version you have the ability to use tokens to save and retrieve Addendum responses when a screen is refreshed due to missing data, e.g. the customer does not choose a shipping or payment method. These are very specialized tokens and are fairly complex in their implementation. The example page of each question input type will help you understand their implementation.
Special note: If you are using a payment processor that takes the customer offsite to enter CC data (PayPal, etc) and want the responses to show up in your merchant notification email, the Addendum module must be assigned to the store after your mail notifications. When looking at the tabs on the fulfillment configuration screen, the Addendum tab should be to the left and above (if more than one row of tabs) of the merchant email module tab.
If you are using the Miva Merchant User Interface (mmui) you will need to make some very simple edits to the core files. Be sure to do that with a text editor (NO WYSIWYG editors) such as Programmer's File Editor (PFE) so as not to damage the mv files. ALWAYS BACKUP your unmodified mv files in case you make a mistake. Choose one of the two locations below to insert the questions. Note: If you are using compiled Merchant 4.14 and newer, you will not be able to edit the mmui.mv unless you have the source kit from Miva Corp AND the mivascript compiler (which is expensive). For that reason, you will probably install the OpenUI to use Addendum and most other 3rd party modules in your compiled Merchant store.
1) Places the questions on the last checkout page (cannot use with the PayPal module):
In your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_Payment" and
insert the following line just before the table with the continue button
<MvDO FILE="{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME="l.addmore" VALUE="{show_questions(Stores.d.code)}">
Also, in your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_CustomerInformation" and
insert the following line just before the table with the continue button
<MvIF EXPR = "{NOT l.total}">
<MvDO FILE="{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME="l.addmore" VALUE="{show_questions(Stores.d.code)}">
</MvIF>
Also, in your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_Upsell_Single" and
insert the following line just after the first FORM tag in the function
<MvDO FILE = "{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME = "l.inputhide" VALUE = "{Make_Inputs()}">
Also, in your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_Upsell_Multiple" and
insert the following line just after the FORM tag in the function
<MvDO FILE = "{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME = "l.inputhide" VALUE = "{Make_Inputs()}">
2) Places the questions on the next to the last checkout page (must use this location
if you are also using the PayPal module):
In your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_Payment" and
insert the following line just before the table with the continue button
<MvDO FILE = "{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME = "l.inputhide" VALUE = "{Make_Inputs()}">
In your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_ShippingPaymentSelection" and
insert the following line just before the table with the continue button
<MvDO FILE="{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME="l.addmore" VALUE="{show_questions(Stores.d.code)}">
Also, in your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_CustomerInformation" and
insert the following line just before the table with the continue button
<MvIF EXPR = "{NOT l.total}">
<MvDO FILE="{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME="l.addmore" VALUE="{show_questions(Stores.d.code)}">
</MvIF>
Also, in your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_Upsell_Single" and
insert the following line just after the first FORM tag in the function
<MvDO FILE = "{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME = "l.inputhide" VALUE = "{Make_Inputs()}">
Also, in your mmui.mv file find <MvFUNCTION NAME = "MMUI_Order_Upsell_Multiple" and
insert the following line just after the FORM tag in the function
<MvDO FILE = "{g.Module_Root$'modules/fulfill/addendum.mv'}" NAME = "l.inputhide" VALUE = "{Make_Inputs()}">
The most recent responses are stored in a file called addendum.dat in the addendum subdirectory of the store data files, for example 00000001/addendum/addendum.dat This file contains responses since the last time you purged responses. All purged responses are maintained in the addendum.arc flat file so it holds the complete history unless you delete it. If you delete it, it will start over. You can download either file to your hard drive and import it to a word processor or database manager as you see fit. If you make the selections as optional selections, and the customer chooses not to respond, a line will not be added for that customer. Text input and select inputs can be optional, radio will not be. In addition to the responses, which are captured, the addendum.dat will contain three fields from the customer's order. You can add to that list with Merchant 4.13 and older if you want to capture more data by modifying the addendum.mv module. However, it is essential that you do not change the first entry field, Orders.d.id.
In Merchant 4.14 or newer you can go to the admin:stores:system extension configuration screen and click the tab for Addendum View. You can enter search criteria and display either the complete response list or just the order numbers that match.
If you are using our Mail Manager in compiled Merchant (4.14 and newer), you can include the Addendum responses as either text or html using tokens.
If you are using the OpenUI, the Addendum responses are automatically added to the merchant notification email. If using the mmui, you can add code to the meremail.mv or other merchant notification module you might be using.
In the meremail.mv prior to Merchant version 4.10, locate the tag </MvSMTP> Immediately
preceding that tag, insert the text you want to appear for each question
you want to show up. Below is an example of the code which displays the
questions and responses for three items.
<MvEVAL EXPR = "{ asciichar( 10 ) $ 'Found us......: ' $ g.question2}">
<MvEVAL EXPR = "{ asciichar( 10 ) $ 'Server speed..: ' $ g.question3}">
In the meremail.mv starting with Merchant 4.10, locate the line:
Add the following immediately preceeding that line:
<MvIF EXPR = "{g.maxquestions}">
<MvASSIGN NAME="l.i" VALUE="1">
<MvWHILE EXPR = "{l.i LE g.maxquestions}">
<MvASSIGN NAME = "l.message" VALUE = "{ l.message $ asciichar( 10 ) $ l.i $ '. ' $ miva_variable_value('g.question' $ l.i) $ asciichar( 10 )}">
<MvASSIGN NAME="l.i" VALUE="{l.i+1}">
</MvWHILE>
</MvIF>
The install notes for including responses in the batch reports are contained in the comments section of iacctadd.mv for uncompiled Merchant. You will NOT need to use this file if you are using the current OpenUI as an OpenUI Batch Report incorporates the hooks for the addendum responses.
If you are using Merchant 4.14 or newer we have created EZ Batch (ordered separately). You also can use the EZ Batch report for printing the batches with or without the addendum responses. Our batch report allows several configuration parameters like page break between orders, ability to exclude payment, shipping, and bill to name/address, and prices. These latter features are usefull if you want to use the batch report for creating packing slips. Whether you need Addendum responses in the batch report or not, this module will create packing slips so you don't need to buy another module elsewhere. In addition to reporting from an existing batch, you can insert one or more order numbers and it will report them as long as they still exist in the orders database.
I have included an optional module that can be used with compiled Merchant and the OpenUI Batch Report. It will create a page break after each order in the batch file when printing. If you want the page break in the OpenUI Batch Report, install the batpgbrk.mvc as a store utility module. If you don't want the page break do not install batpgbrk.mvc.
Q: The responses are not being saved in the addendum.dat file nor are they showing in the emails
A: Make sure that you named the question inputs correctly, e.g. question1, question2, question3, and so on. Then at the end of the questions you need a hidden input for maxquestions which will have a value of the highest numbered question, e.g. <input type="hidden" name="maxquestions" value="3">
Q: I am using compiled Merchant and want to setup an optional charge at checkout. How do I use this feature?
A: You include a question that has an answer that triggers the fee. It is best to use a specific value for the answer, but you could use a text input that any data entered would trigger the fee. Note that the fee can be positive or negative. In the image
you can see that I made a negative fee if the customer answered "Yes" to
question number 6. The actual question number 6 in the addendum questions
for this example is <INPUT TYPE="checkbox" NAME="question6" VALUE="Yes">
Q: One of the module in the zip file is iacctadd.mv. When I try to upload it, I get the error message: /Merchant2/4.12/MIVA_FUP00000001: Line 1: Expression Error: Call to undefined function 'Module_Type'.
A: iacctadd.mv is not a module. It is a library file. In uncompiled Merchant (4.13 or older), the install notes for including responses in the batch reports are contained in the comments section of iacctadd.mv. You can read that section with notepad in iacctadd.mv (not iacctadd.mvc). That said, you will NOT need to use this file if you are using the current OpenUI as an OpenUI Batch Report incorporates the hooks for the addendum responses. Only use this file for stores not using OpenUI.
Q: I replaced the standard Merchant checkout screens with templates and now my Addendum questions are not there. What do I do?
A: In the OpenDesigner and other templates you can use tokens in the format %module|addendum|13_114% instead of hook points. Screens likely to be replaced with OpenDesigner are OINF=13, OSEL=15, and OPAY=14. Hence, the following tokens are to be placed on each of the checkout screens.
OINF - %module|addendum|13_114%
OSEL - %module|addendum|15_21%
OPAY - %module|addendum|14_31%
These tokens need to be placed inside the form on each of those pages no matter which page you have the questions on. The module's admin determines which page they will show and which pages they will merely be saved as hidden inputs and passed to the next page.