Unless an error of sufficient severity is returned, all the components in a given stage will be run on the OrderForm. By convention, components cooperate and do not overwrite a previous component’s results, unless the overwriting component is specifically designed for that purpose.
Consider, for example, a pipeline that includes the SimpleCanadaTax, SimpleUSTax, and SimpleJapanTax components in its Tax stage. All of these components read the same name/value pair, order.ship_to_country, to determine if they need to calculate tax on the OrderForm.
If the SimpleCanadaTax component precedes the SimpleUSTax component in the pipeline, and order._ship_to_country equals Canada, the SimpleCanadaTax component calculates the tax and writes the resulting value to order._tax_total. When the SimpleUSTax component, which appears next in the pipeline, reads the order.ship_to_country name/value pair and finds that it does not evaluate to US, the component should simply return without setting any values.
By convention, certain name/value pairs in the OrderForm help a component determine whether or not to write values. The following table shows the name/value pairs for four stages. These are the four stages in the pipeline in which errors are most likely to occur.
The Apply column in this table shows the name/value pairs that hold key information that a component can use to determine whether or not it should be used against this particular OrderForm’s contents. The Complete column shows what name/value pairs are set when the intended functionality of the stage is met.
| Stage | Apply | Complete |
|---|---|---|
| Shipping | shipping_method | _shipping_total |
| Handling | shipping_method | _handling_total |
| Tax | ship_to_country | _tax_total |
| Payment | payment_method, cc_name, cc_type, _cc_number, _cc_exp_month, _cc_exp_year | _payment_auth_code |
The single exception to the scenario outlined previously occurs in the case of components that are specifically designed to overwrite the values existing in a given name/value pair. To ensure that these components do not overwrite values that have been properly set, make sure that these components are inserted in their appropriate place in the pipeline.
Consider, for example, the following two components that have an affinity with the Shipping stage: the DefaultShipping and FixedShipping components. These components are all designed to set the shipping cost on an OrderForm.
The DefaultShipping component sets the OrderForm’s shipping cost to zero (0). The FixedShipping component writes a shipping cost to the OrderForm, if the shipping cost is not already set.
If these components are inserted into the Shipping stage in the order in which they are described in the preceding paragraph, they produce the expected result; they set the shipping cost for an order.
However, if the DefaultShipping component follows the FixedShipping component in the pipeline, unexpected results follow. The FixedShipping component sets the shipping cost on the order, and the DefaultShipping component overwrites the shipping cost with a zero (0).
After inserting a component into your pipeline, double-click it in the Win32®-based Pipeline Editor to display its property pages, and then click the Values Read and Written tab. This tab identifies the OrderForm values that are read and written for that component.
In addition, if a component writes a value to the OrderForm, consult the documentation on that component to find out the value it writes, and how it determines that value.
If you are writing a component, you should design the component so that if the value that it is designed to write already contains a value, the value is not overwritten by your component.
The following scenario is an example of a failure that can possibly occur if the coordination rules documented previously are not followed.
During the payment stage, the customer is presented with two payment options: pay by credit card or pay on account, probably by using a billing system statement. The customer chooses the billing method. If the credit card processing component ignores payment_method, the component will fail (because the customer did not enter a credit-card number). A possible solution might be to place the billing system component before the credit-card processing component in the OPP component sequence. However, if the billing system component does not set _payment_auth_code, the credit-card processor will still fail. Even if the billing system component does set _payment_auth_code, if the credit card component ignores the fact that _payment_auth_code is set, it will run and fail.