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.
1) In admin, click Add Modules link (fig 2)
2) Click the file upload button
3) Browse to find the addendum.mvc file on your hard drive and upload (fig 3)
4) Click Add to add it to the domain
5) Then in admin click on the plus to the left of Stores
6) Click the plus to the left of your store name
7) Click on Order Fulfillment Configuration link (fig 9)
8) Check the box next to the Addendum
9) Click Update
10) Click on System Extension Configuration link
11) Check the box next to the Addendum
12) Click Update
13) Click on the word Utilities
14) Check the box next to the Addendum
15) Click Update
16) Click Pages link to get to the User Interface (fig 4)
17) Click Items link at the top of the User Interface page (fig 5)
18) Click the Add Item button (fig 6)
19) Enter addendum for the code
20) Look up and scroll to the last page of items and Addendum should be at the end of the list of items
21) Select Addendum (fig 8)
22) Click the Add button to assign the module
23) Return to the Order Fulfillment Configuration screen and click the link for Addendum to enter the configuration settings and add Addendum questions.
a. You can have radio, select, checkbox, text and textarea type inputs.
b. 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).
c. 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.
d. 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.
e. You can optionally include the questions in the emails along with the responses. We've included modified versions of both the customer and merchant notification emails which will include the responses. If you want more flexibility with your emails, our inexpensive email module Mail Manager is available.
f. 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. We recommend that you setup the Addendum with basic questions and test to make sure everything is working. Then you can experiment with the tokens.
24) Edit page templates per the Template Editing Requirements section below
The module is called within specific template screens with render tokens. They are in the format of
<mvt:item name="itemcode" param="xxxx" />
The templates are listed at the Pages link. You will edit the template by inserting the token and clicking the Update (fig 7). Important: After adding the render token to a template page, you must click the Items link for that page, scroll down to the item name and assign it to the page. These two steps are repeated for every page that a module's render token is used on. The first three of these page tokens are required no matter what page the questions will be placed on. The other three page tokens are optional (see note after each).
1) On page 'ocst' (customer information), insert <mvt:item name="addendum" param="ocst" /> just above the continue button code. Make sure it is above the closing </form> tag.
2) On page 'osel' (shipping/payment selection), insert <mvt:item name="addendum" param="osel" /> just above the continue button code. Make sure it is above the closing </form> tag.
3) On page 'opay' (order payment), insert <mvt:item name="addendum" param="opay" /> just above the continue button code. Make sure it is above the closing </form> tag.
4) On page 'ous1' (upsell single), insert <mvt:item name="addendum" param="ous1" /> just above the two </form> tags on this page. There is an add to order form and a do not add to order form, so both need to have the token inserted. If you are not going to have upsell products in your store, this screen edit is not needed.
5) On page 'ousm' (upsell multiple), insert <mvt:item name="addendum" param="ousm" /> just above the continue button code. Make sure it is above the closing </form> tag. If you are not going to have upsell products in your store, this screen edit is not needed.
6) On page 'invc' (invoice), insert <mvt:item name="addendum" param="invc1" /> if you want the responses numbered. Use <mvt:item name="addendum" param="invc2" /> if you do not want responses numbered. If you do not need the responses to display on the customer's invoice screen, this screen edit is not needed.
The most recent responses are stored in a file called addendum.dat in the addendum subdirectory of the store data files, for example s01/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 (order number, bill to last name, bill to zip).
You can go to the admin:storename:utilities screen and click the link for Addendum. 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 (ordered separately), you can include the Addendum responses as either text or html using tokens.
If you want the responses in the customer template email, you can include the store morph code for displaying a variable in the email body where you want it. For example, &mvte:global:question1; would display the response to question1.
If you are using the standard text merchant email that comes with Merchant 5x, you can replace that module with the included modified email (meremail.mvc for merchant notification).
If you are using our EZ Batch Report module (ordered separately), you simply configure the EZ Batch to include the reponses. You also can use the EZ Batch Report for printing the batches with or without the addendum responses. Our EZ 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.
We have included a modified Standard Batch Report (stdacct2.mvc) to replace the original batch report. It will also include the Addendum responses but does not have the configuration features like our EZ Batch Report.
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">
A: Make sure you put the required tokens (listed above) on ALL three pages and the other pages when applicable. Also, double check that you assigned the Addendum in the items list for ALL three pages and others, as applicable.
Q: The responses ARE being saved in the addendum.dat file but they are not showing in the emails.
A: If you are using the built in 5.5 template email module or the modified email module that came in the addendum.zip file in 5.x versions older than 5.5, it may be an issue with your payment module. If you are using a payment module that takes the customer offsite, e.g. paypal, you need change the order that the fulfillment modules run. You need to completely uninstall the customer and merchant notification emails by unassigning them from the order fulfillment page. Then under admin > modules remove them completely from the server. Then install them back to the server and assign them to the store under order fulfillment. This causes them to run after the addendum. Then the responses should show. If you weren't using paypal or other offsite payment collection module you wouldn't have to do this. If you are using our Mail Manager email module, you don't need to do this since it allows assignment of external items/tokens to the email. This executes code which runs in addendum to pull the data up even if its turn to run in the fulfillment module sequence has not come up.
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">
Still have a question?
