The following is a list of events invoked from Storefront.
DLL Extensions only — Since version 7.5
This is called before a step is processed by Storefront. This gives extensions which implement this step a chance to take their own actions or even skip the step.
Method
ApprovalStep_Before(string ApprovalStepID)
Parameters
■ ApprovalStepID — Internal ApprovalStep identifier of step about to be processed.
Returns
Return eSuccess to have the step proceed normally. Return eShouldAbort to have the step skipped.
Remarks
An aborted step works the same as if the approve had approved all documents subject to review in the step.
CalculateDocumentPrices (deprecated)
Note: This event has been deprecated. Use CalculateDocumentPrices3() instead (described below).
Invoked from the Printing Step, the Shopping Cart, and the Checkout Submit pages when the document prices need to be calculated.
Method
int CalculateDocumentPrices(string[] docids,
bool pricesOnly,
out double[] prices,
out string isoCurrencyCode)
Parameters
■ docids — Array of internal document identifiers.
■ pricesOnly — If true, this method was called from the Printing Step or the Shopping Cart, so no Payment or Shipping options have been selected. In that case, the module should ignore these options.
■ prices — Values in the prices array to be written to the database. The index into prices corresponds to the index into docids.
■ isoCurrencyCode — The currency of the prices array. This must match the site’s ISO currency code, otherwise the prices will not be written to the database.
Returns
This method should return eSuccess to write the prices array values to the database.
Remarks
Normally just one module will compute all the document prices for an order. However, it is possible for more than one module to be involved in computing prices for an order. Documents whose prices have not been set by a module may have their prices set by the CalculateDocumentPrices call to a subsequent module.
CalculateDocumentPrices2 (deprecated)
Note: This event has been deprecated. Use CalculateDocumentPrices3() instead (described below).
Invoked from the Printing Step, the Shopping Cart, and the Checkout Submit pages when the document prices need to be calculated. This event returns an array of document prices, and can indicate what portion of those prices is taxable, for each document.
Note: This supersedes the older CalculateDocumentPrices method. If the new method is not implemented in any SXI module then Storefront will call the older CalculateDocumentPrices methods on all modules. However, if CalculateDocumentPrices2 is implemented in any SXI module, Storefront will not call the older method at all.
Method
int CalculateDocumentPrices2(string[] docids,
bool pricesOnly,
TaxLocation taxloc,
out double[] docprices,
out double[] taxable,
out string isoCurrencycode)
Parameters
■ docids — Array of internal document identifiers.
■ pricesOnly — If true, this method was called from the Printing Step or the Shopping Cart, so no Payment or Shipping options have been selected. In that case, the module should ignore these options.
■ taxloc — Tax location for this order. May be the indeterminate tax location. See the description of the TaxLocation object for details.
■ prices — Values to be written to the database as document prices. The index into prices corresponds to the index into docids.
■ taxable — Taxable part of the price in the prices array. If null is returned, then each document's taxability is determined by looking at the product and user properties.
■ isoCurrencyCode — The currency of the prices array. This must match the site’s ISO currency code, otherwise the prices will not be written to the database.
Returns
This method should return eSuccess so that the prices and taxable array values will be written to the database.
Remarks
Normally just one module will compute all the document prices for an order. However, it is possible for more than one module to be involved in computing prices for an order.
■ Documents whose prices have not been set by a module may have their prices set by the CalculateDocumentPrices2 call to a subsequent module.
■ Documents whose prices have been set by a module may not have their prices set by the CalculateDocumentPrices2 call to a subsequent module.
Note: Document prices are not adjusted in the database until all SXI modules have been called, so that a GetValue call for the “Price” property of a document (or similar properties) will get the price as calculated by the price tables and not as modified by previously-called SXI modules.
Invoked from the Printing Step, the Shopping Cart, and the Checkout Submit pages when the document prices need to be calculated. A module that implements this event can override the price and taxable portion of a document.
Note: This supersedes the older CalculateDocumentPrices2 and CalculateDocumentPrices methods. If the new method is not implemented in a SXI module then Storefront will call the older CalculateDocumentPrices2/CalculateDocumentPrices methods on that module. However, if CalculateDocumentPrices3 is implemented in a SXI module, Storefront will not call the older methods if present in that module.
Method
int CalculateDocumentPrices3( string[] docids,
bool pricesOnly,
TaxLocation taxloc,
ref double[] docprices,
ref double[] taxable,
out string isoCurrencycode)
Parameters
■ docids — Array of internal document identifiers.
■ pricesOnly — If true, this method was called from the Printing Step or the Shopping Cart, so no Payment or Shipping options have been selected. In that case, the module should ignore these options.
■ taxloc — Tax location for this order. May be the indeterminate tax location. See the description of the TaxLocation object for details.
■ prices — Values to be written to the database as document prices. The index into prices corresponds to the index into docids.
■ taxable — Taxable part of the price in the prices array. It will be filled with the output of the tax tables. The index in taxable corresponds to the index in doc IDs. An extension can override or replace the built-in calculations. If you want the taxes recomputed by Storefront, set taxable to null.
■ isoCurrencyCode — The currency of the prices array. This must match the site’s ISO currency code, otherwise the prices will not be written to the database.
Returns
This method should return eSuccess so that the prices and taxable array values will be written to the database.
Remarks
Normally just one module will compute all the document prices for an order. However, it is possible for more than one module to be involved in computing prices for an order. As passing is done by reference in this method you will always see the price as currently determined. Modules will be called in the order in which they are listed on the Extensions screen, so it's possible to have one module adjust prices returned by another by placing that module farther down in the list.
■ Documents whose prices have not been set by a module may have their prices set by a CalculateDocumentPrices(2/3) call to a subsequent module.
■ Documents whose prices have been set by a module may have their prices changed by a CalculateDocumentPrices(2/3) call to a subsequent module.
■ Any module which overrides CalculateDocumentPrices may override the taxable portion set by an earlier call to CalculateDocumentPrices2 or CalculateDocumentPrices3, as that method does not support changing the taxable portion of a price.
Note: Document prices are not adjusted in the database until all SXI modules have been called, so that a GetValue call for the “Price” property of a document (or similar properties) will get the price as calculated by the price tables and not as modified by previously-called SXI modules. Use the prices[] array instead of GetValue calls.
Called when Storefront is computing the document weights for an order. A module that implements this method can override the usual answer which comes from the Price Tables.
Method
int CalculateDocumentWeights(string[] documentIDs,
out double[] weights,
out string weightUnitCode)
Parameters
■ documentIDs — internal IDs of the documents in the order
■ weights — values returned in this parameter will be used by Storefront as the weight (in units of weightUnitCode) of the corresponding items in the cart. Note that an item could include multiple documents.
■ weightUnitCode — the module returns of “g” or “oz” (whichever is appropriate) in this parameter indicating the weight unit. It is an error if this is different from the StoreWeightUnit in use by Storefront.
Returns
A module that chooses to assign document weights for these documents should return eSuccess; all others should return eFailure.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to assign weights to a set of documents.
Called when Storefront is computing the external ID for a document, that is: when a new document is created, or when a duplicate document is made from an old one. A module that implements this method can override the usual answer which is generated internally.
Method
int CalculateExternalDocumentId(string internalDocumentID,
string autoGeneratedExternalID,
ref string newExternalID)
Parameters
■ internalDocumentID — internal ID of the document.
■ autoGeneratedExternalID — a string which will be assigned as the external ID if no module supplies a new external ID.
■ newExternalID — the module returns a value for the external ID to be used, or null if it wishes to use the auto-generated ID.
Returns
A module that chooses to assign an external ID for the document should return eSuccess; all others should return eFailure.
Remarks
If more than one module returns eSuccess, the external ID is taken from the last of these. If no module returns eSuccess, or if the effective value of newExternalID is null, then the auto-generated ID is used.
Called when Storefront is computing the external ID for an order, that is, when an order is submitted. A module that implements this method can override the usual answer which is generated internally.
Method
int CalculateExternalOrderId(string internalOrderID,
string autoGeneratedExternalID,
ref string newExternalID)
Parameters
■ internalDocumentID — internal ID of the order.
■ autoGeneratedExternalID — a string which will be assigned as the external ID if no module supplies a new external ID.
■ newExternalID — the module returns a value for the external ID to be used, or null if it wishes to use the auto-generated ID.
Returns
A module that chooses to assign an external ID for the order should return eSuccess; all others should return eFailure.
Remarks
If more than one module returns eSuccess, the external ID is taken from the last of these. If no module returns eSuccess, or if the effective value of newExternalID is null, then the auto-generated ID is used.
Called when Storefront is computing the handling charge for an order. A module that implements this method can override the usual answer which comes from the Storefront Administrator Site Options page.
Method
int CalculateHandlingCharge(string orderId,
out double handlingCharge,
out string isoCurrencyCode)
Parameters
■ orderId — internal ID of the order.
■ handlingCharge — the module returns the amount of currency to charge for Handling in this order.
■ isoCurrencyCode — the module returns the ISO currency symbol for the currency in which the handlingCharge parameter is given. It is an error if it does not match the currency in use by Storefront.
Returns
A module that chooses to assign a handling charge for this order should return eSuccess; all others should return eFailure.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to assign a handling charge.
Called when the shipping step is initializing its list of documents. It may be called more than once, particularly if the user goes back to the multi-shipping step.
Method
int CalculateOriginCodes(string[] documentIds,
string[] productIds,
ref string[] originCodes,
ref string[] originDesignators)
Parameters
■ documentIds — array of document IDs in the order (excluding kit parts).
■ productIds —for each document, its associated product ID.
■ originCodes — an array of the same length as the previous two, to be filled in by the extension.
■ originDesignators— another array of the same length, which may be filled in (optionally) by the extension.
Returns
An extension implementing this method should return eSuccess; It should also fill in the originCodes array with codes indicating how the documents should be partitioned into shipments. For example, if some documents must be shipped from Boston and the others from Denver, the codes could be “BOSTON” and “DENVER”, and may fill in the originDesignators array to give the user a visual indication of the partition.
Remarks
If more than two distinct origin codes are returned, checkout will start on the Multi-Shipping page, and Storefront will hide the usual button to ship as a single shipment. The user can choose destination addresses on this page but items with different origin codes will always be forced into different shipments.
If the originDesignators array is filled in by the extension, the names for the shipping substeps will consist of the destination followed by the originDesignator for that origin. In the example above, the extension could have assigned origin designators "(from MA)" and "(from CO)", respectively, and the checkout step area would look like this (assuming the user picked "rick's house" as the destination for all items):
Shipping
* rick's house (from MA)
* rick's house (from CO)
Payment
Submit
CalculatePackingStrategy (deprecated)
Note: This event has been deprecated. Use CalculatePackingStrategy2() instead (described below).
Called when Storefront is computing the packing manifest for an order. A module that implements this method can override the usual packing strategy used by our algorithm.
Method
int CalculatePackingStrategy(string orderID,
string[] documentIDs,
out string[] boxContents)
Parameters
■ orderID — internal ID of the order.
■ documentID s — internal IDs of the documents in the order.
■ boxContents — the module should return in this parameter an array of strings of the form.
4.5oz: m of MM at 3.0oz, n of NN at 1.0oz
where MM and NN are internal document IDs and m and n are quantities of the respective documents. If a document’s output is split between two containers, the numbers should be prefixed by an asterisk, e.g.
19.0oz: *12 of 98 at 1.0oz, *7 of 98 at 1.0oz
Returns
A module that chooses to assign a packing strategy for an order should return eSuccess; all others should return eFailure.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to assign a packing strategy.
Called when Storefront is computing the packing manifest for a shipment. A module that implements this method can override the usual packing strategy used by our algorithm.
Method
int CalculatePackingStrategy2( string orderID,
string shipmentID,
string[] documentIDs,
out string[] boxContents)
Parameters
■ orderID — internal ID of the order.
■ shipmentID — Internal identifier of the shipment within the order
■ documentIDs — internal IDs of the documents in the shipment.
■ boxContents — the module should return in this parameter an array of strings of the form.
4.5oz: m of MM at 3.0oz, n of NN at 1.0oz
where MM and NN are internal document IDs and m and n are quantities of the respective documents. If a document’s output is split between two containers, the numbers should be prefixed by an asterisk, e.g.
19.0oz: *12 of 98 at 1.0oz, *7 of 98 at 1.0oz
Returns
A module that chooses to assign a packing strategy for a shipment should return eSuccess; all others should return eFailure.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to assign a packing strategy for the shipment.
For legacy purposes, if no module responds with eSuccess, and the order consists of only one shipment, then we call the deprecated SXI method CalculatePackingStrategy() with the same order ID.
CalculateShippingCharge (deprecated)
Since version 2.5
Note: This event has been deprecated. Use CalculateShippingCharge2() instead (described below).
This is called whenever the shipping charge needs to be recomputed, e.g. as the Submit Order page is being displayed, when it is called immediately after the SubmitOrderPage_Before() call.
Method
int CalculateShippingCharge(string orderID,
out double shippingCharge,
out string isoCurrencyCode)
Parameters
■ orderID — Internal identifier of the order.
■ shippingCharge — Shipping charge (the module needs to set this on output).
■ isoCurrencyCode — Currency of the shipping charge (the module needs to set this on output).
Returns
A module that chooses to assign a Shipping charge for this order should return eSuccess; all others should return eFailure. Your module should only return eSuccess if, after examining the order’s fields, it determines that it should take responsibility for computing the shipping charge for the order.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to make the decision about the Shipping charge for an order. A module that implements this method should also implement IsModuleType() in order to identify itself as a “shipping” module.
This is called whenever the shipping charge needs to be recomputed for a shipment, such as for a Shipping step for the order, or in the case of split shipping, when one of the Shipping sub-steps is being displayed.
Method
int CalculateShippingCharge2(string orderID,
string shipmentID,
out double shippingCharge,
out string isoCurrencyCode)
Parameters
■ orderID — Internal identifier of the order.
■ shipmentID — Internal identifier of the shipment within the order.
■ shippingCharge — Shipping charge (the module needs to set this on output).
■ isoCurrencyCode — Currency of the shipping charge (the module needs to set this on output).
Returns
A module that chooses to assign a Shipping charge for this shipment should return eSuccess; all others should return eFailure. Your module should only return eSuccess if, after examining the field values for the order and the shipment, it determines that it should take responsibility for computing the shipping charge for the shipment.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to make the decision about the Shipping charge for a shipment. A module that implements this method should also implement IsModuleType() in order to identify itself as a “shipping” module.
For legacy purposes, if no module responds with eSuccess, and the order consists of only one shipment, then we call the deprecated SXI method CalculateShippingCharge() with the same order ID.
CalculateTax (deprecated)
Note: This event has been deprecated. Use CalculateTax2() instead (described below).
Called when Storefront is computing the tax for an order. A module that implements this method can override the result from the tax tables.
Method
int CalculateTax(string orderID, double taxableAmount,
double previousTaxableAmount, ref TaxValue[] tax)
Parameters
■ orderID — internal ID of the order.
■ taxableAmount — taxable portion of the total price of the order, according to the default tax locale for the order.
■ previousTaxableAmount — the taxableAmount from the last time CalculateTax was called for this order.
■ tax — an array of TaxValue structures, indicating the tax amount(s) for a series of tax locales. The default tax locale for the order has a tax locale name of “”.
Returns
A module that chooses to assign a tax for an order should return eSuccess; all others should return eFailure.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to assign taxes.
Called when Storefront is computing the tax for an order. A module that implements this method can override the result from the tax tables.
Method
int CalculateTax(string orderID, double taxableAmount,
string currencyCode, string[] priceCategories,
string[] priceTaxLocales, double[] priceAmount,
string[] taxLocaleId, ref double[] taxAmount)
Example
public override int CalculateTax2(string OrderID, double taxableAmount, string currencyCode, string[] priceCategories, string[] priceTaxLocales, double[] priceAmount, string[] taxLocaleId, ref double[] taxAmount)
{
/*
* The length of the taxAmount array should equal the length of
* taxLocaleId array. A tax locale equals a shipment in this context.
* You need to calculate one tax total for each tax locale.
* The priceAmount and priceCategories arrays reflect how you
* configured your tax rates and categories.
**/
for (int j = 0; j < taxLocaleId.Length; j++)
{
double priceForThisLocale = 0;
for (int i = 0; i < priceTaxLocales.Length; i++)
{
if(priceTaxLocales[i] == taxLocaleId[j])
{
/* If you have different rates for different categories
* you’d look up the category here--priceCategories[i]--
* and apply the tax amount here based on the category.
**/
priceForThisLocale += priceAmount[i];
}
}
//remove this 10% example tax if applying tax in the above loop
taxAmount[j] = priceForThisLocale * .10;
}
return eSuccess;
}
Parameters
■ orderID — Internal ID of the order.
■ taxableAmount — Taxable portion of the total price of the order, according to the default tax locale for the order.
■ currencyCode — ISO 4217 currency code of the currency of the order
■ priceCategories, priceTaxLocales, priceAmount — Three parallel arrays splitting up the taxableAmount among tax locales and tax categories. For each combination of tax locale ID and tax category, Storefront provides the amount of the taxableAmount occurring within that tax locale for that tax category, and the corresponding elements of all three arrays are filled in accordingly. Storefront may omit combinations for which the amount is zero.
■ taxLocaleId — Array detailing each tax locale occurring in the order.
■ taxAmount — Array parallel to taxLocaleId initialized to all zeros. Holds the extension-computed taxes on return for each tax locale occurring in the order.
Returns
A module that chooses to assign a tax for an order should return eSuccess, and set values for entries in the taxAmount array; all others should return eFailure (or eDoNotCall).
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to assign taxes.
Note: This supersedes the older CalculateTax method. If the new method is not implemented in any SXI module then Storefront will call the older CalculateTax method on all modules. However, if CalculateTax2 is implemented in any SXI module, Storefront will not call the older method even if it is implemented in some SXI module.
Enables you to call a method in an extension from your product customization form using sfjs.watchField(). See watchField under the “Watching/Tracking Fields” section of Chapter 5, “sfjs API,”below.
Method
int CallExtensionForClient(string userId,
string keyword,
string clientData,
out Dictionary<string,string> responseData)
Parameters
■ userId—Internal identifier of the user.
■ keyword—Optional; can be whatever the extension developer wants or needs it to be. Our sample (see below) illustrates a conventional way to use this.
■ clientData—Optional; can be whatever the extension developer wants or needs it to be. Our sample (see below) illustrates a conventional way to use this.
■ responseData—The intention is that the (key,value) pairs from this will be assembled into a JSON object for the client. The “value” part of each pair must be a string in JSON syntax.
Returns
The extension in question should examine the (optional) keyword and clientData and if relevant should return eSuccess or eFailure (or equivalently eShouldAbort), and respond with responseData. If not relevant it should set responseData to null and return eSuccess.
Remarks
Invalid JSON syntax in the responseData will cause an exception to be returned to the client.
A sample extension demonstrating this method may be downloaded from the following URL:
https://downloads.pageflex.com/documentation/help/callextensionforclientsample.zip
Since version 9.8
Used to let extensions communicate with each other, this event can be called in a single extension and will return the result. Then a second extension overrides the specified method with the CallExtension() SINI method described on page 181 and returns the result back to the calling extension.
Method
int CallExtensionForSINI(string method, string arguments, out string result)
Example
An extension named WebExtension implements this SXI event as
public override int CallExtensionForSINI(string method, string arguments, out string result)
{
switch (method)
{
case "reverse":
string[] list = arguments.Split(',');
result = string.Join(",", list.Reverse());
return eSuccess;
... other cases ...
}
result = null;
return eSuccess;
}
Then an extension can call the CallExtension() SINI method:
string the_answer;
int n = Storefront.CallExtension("yourNamespace.WebExtension", "reverse", "1,2,3", out the_answer);
which returns “3,2,1” for the result.
Remarks
Implementations should be very careful about using the CallExtension() SINI method as it would be easy to create an infinite loop of calls that would be very hard to debug.
This is called when a batch of documents is being sent to the checkout step, preliminary to ordering. Currently this only happens when the user clicks “Proceed to Checkout” on the Shopping Cart page. For purposes of SXI, the documents are deemed to belong to a (temporary) order whose internal identifier is orderID, though they are not actually considered to be “Ordered” until the user places the order at the end of the checkout process.
Method
int CheckoutSteps_Before(string userID,
string orderID,
string[] documentIDs)
Parameters
■ userID — Internal identifier of the user.
■ orderID — Internal identifier of the order.
■ documentIDs — Array of internal identifiers for the documents in the shopping cart.
Returns
For this method, the eShouldAbort return value signals that the user should not proceed to the Checkout steps, but instead should be returned to the Shopping Cart page. The user will be informed of this and an entry will be made in the Storefront log.
Remarks
The SXI Module could (for example) take the opportunity to assign shipping information to the document order group, which would be displayed to the user when the page displays.
Since version 9.8
Allows the extension to override Storefront’s determination of which price table(s) to use.
Method
int ChoosePriceTable(string docPriceTableName,
string currency,
string documentId,
string userId,
ref string leafPriceTableName,
out string newDocPriceTableName)
Example
public override int ChoosePriceTable(string docPriceTableName, string currency, string documentId, string userId,
ref string leafPriceTableName, out string newDocPriceTableName) {
if (docPriceTableName == "StandardPricing")
newDocPriceTableName = "SpecialPricing";
else
newDocPriceTableName = null;
return eSuccess;
}
Remarks
An extension could use different price tables to compute the product price displayed to users based on any profile attribute.
This is called right before a data list selection is finalized. If the file required mapping the event will fire after mapping is completed and provide access to the remapped file. If the file did not require mapping the event will fire when the user presses submit on the data preview page.
Method
int DataListSubmit_Before(string userID,
string docId,
string originalFilePath,
string remappedFilePath,
out string errorType,
out string message)
Parameters
■ userId—The internal identifier of the user.
■ docId—The internal identifier of the document.
■ originalFilePath—The full path to the original uploaded file prior to any remapping. If an Excel file was uploaded this will be the location of the CSV created from the selected workbook sheet.
■ remappedFilePath—The full path to the remapped file, will be null if no remapping was done.
■ errorType—The extension should return either mapping or logic to indicate whether the extension thought the error was in file mapping or if the error was a failure in the business logic. If the return is mapping the user will be put back on the mapping screen of the data merge modal. If the return is logic the user will be put back on the initial file selection\upload screen of the modal.
■ message—If the extension chooses to reject the data list it may also choose to return a message specifying why. Only the extension will know why the file was rejected so it is recommended to set this value. This will be displayed in the data merge modal. If message is null the generic error message selected by the deployer will be displayed.
Returns
If the module wishes to reject the data list it should return eShouldAbort. In all other cases it should return eSuccess.
This is called when a status change has been made for an ordered document.
Note: When a fresh order with one document not subject to approval is placed, the “Status” property of this document is “Unreviewed” in OrderPlace_After. However, when the document is moved from “Unreviewed” to “DataPending” the first time DocChangeStatus_After executes, the oldStatus argument is an empty string.
Method
int DocChangeStatus_After(string documentID,
string oldStatus,
string newStatus,
bool viaSXI)
Parameters
■ documentID — Internal identifier of the document.
■ oldStatus — The old status of the document, either null for an unordered document or one those listed below.
Note: In a “Declined” order all documents have a status of “Rejected”.
■ newStatus — Indicates the new status of the document (see oldStatus).
■ viaSXI — This will be true if it was changed via the Storefront API, otherwise it will be false (e.g. if it was set manually by an administrator or when output has been rendered).
Returns
The module should return eSuccess.
The following document statuses are available.
This is called after a document is duplicated via the Shopping Cart “Duplicate” function, or the Orders Page “Reorder” function.
Method
int DocClone_After(string newDocumentID, string oldDocumentID)
Parameters
■ newDocumentID — Internal identifier of the new document.
■ oldDocumentID — Internal identifier of the document from which new document is created.
Returns
The module should return eSuccess.
Called when a document is about to be duplicated via the Duplicate link on the Shopping Cart page, the Reorder link on the Order Summary page, or the SINI DuplicateDocument method.
Method
int DocClone_Before(string documentId)
Parameters
■ documentID — Internal identifier of the document.
Returns
The module should return eSuccess. If the return value is eShouldAbort then the document will not be duplicated, the user will be notified, and a log entry will be made.
Note: If a SINI method can clone a document, the calling module will be notified as there is no user in that case.
Remarks
DocClone_Before will not be called for duplication of a file to make a temporary document for editing, or the moving of a document when changing owner.
This is called after the user has created a document from the Start page, just after the default values for the document fields (product variables and printing options) have been assigned to the document.
Method
int DocCreate_AfterFieldInit(string documentID)
Parameters
■ documentID — Internal identifier of the document.
Returns
The module should return eSuccess.
Remarks
The SXI Module could (as an example) make changes to the document fields, which would then be in effect when the User Edit steps are displayed.
Called when a document is about to be deleted via the Delete link on the shopping cart page or the SINI DeleteDocument method.
Method
int DocDelete_Before(string documentId)
Parameters
■ documentID — Internal identifier of the document.
Returns
The module should return eSuccess. If the return value is eShouldAbort then the document will not be deleted, the user will be notified, and a log entry will be made.
Note: If a SINI method can delete a document, the calling module will be notified as there is no user in that case.
Remarks
DocDelete_Before will not be called for deletions via the command line tool, the deletion of all assets of an anonymous user, or the deletion of a temporary file when a document is moved or edited.
This is called on the Storefront Administrator site when output has been generated or when output has failed for an ordered (and submitted) document. It is called just after the DocChangeStatus_After call is invoked, so that any status changes made by the SXI Module will be the last word on the ordered document's status.
Method
int DocOutput_After(string documentID)
Parameters
■ documentID — Internal identifier of the document.
Returns
The module should return eSuccess.
This is called on the Storefront Administrator site when ordered documents are submitted to produce final output. It is called before automatic submissions as well as manual submissions.
Method
int DocOutput_Before(string[] documentIDs)
Parameters
■ documentIDs — Array of internal identifiers of the documents to be submitted for output.
Returns
For this method, the eShouldAbort return value signals that the document submission should not take place. The administrator will be informed of this and an entry will be made in the Storefront log.
This is called just before a document is about to be stored in the Shopping Cart, either just after it is cloned (see the documentation for DocClone_After) or when the user has finished editing it.
Method
int DocToCart_Before(string documentID)
Parameters
■ documentID — Internal identifier of the document.
Returns
If the document should be placed in the Shopping Cart, the module should return eSuccess. For this method, the eShouldAbort return value signals that the document should be placed in the On Hold bin instead. The user will be informed of this and an entry will be made in the Storefront log.
This is called when the user attempts to download final output.
Method
int DownloadOutput_Before(string documentID,
string fileLocation)
Parameters
■ documentID — Internal identifier of the document.
■ fileLocation — Path to the file being downloaded.
Returns
For this method, the eShouldAbort return value signals that the download should not take place. The user will be informed of this and an entry will be made in the Storefront log.
This is called just before the Edit Finish step is displayed.
Method
int EditFinishPage_Before(string documentID)
Parameters
■ documentID — Internal identifier of the document.
Returns
The module should return eSuccess.
Remarks
The SXI Module could (as an example) take the opportunity to examine the document and decide whether to mark it valid or invalid for its own reasons by calling SINI method “SetDocumentExtensionError()”. This would be indicated to the user when the page displays.
ExternalProductSearch (deprecated)
Note: This event has been deprecated. Use ExternalProductSearch2() instead (described below).
Called to search for products according to a set of search terms, as a possible alternative to the internal Storefront product search methods.
Method
int ExternalProductSearch(string search, string context, out int returnType, out string[] productsFound)
Parameters
■ search — Search terms.
■ context — “ADMIN” or “USER” depending where the search is taking place.
■ returnType—Indicator for what kind of identifiers are returned; either
■ 1—for internal IDs
■ 2—for product codes
■ productsFound—The result of the search.
Returns
Implementations should return eSuccess, and an array of either internal product IDs or product codes for the matching products
Remarks
For this call, the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one product search module is consulted.
Since version 9.5
Allows extensions to implement their own product search in place of the internal Storefront product search.
Method
int ExternalProductSearch2(string search, string context, out int returnType, out string[] productsFound, out string extData)
Parameters
■ search — Search terms.
■ context — “ADMIN” or “USER” depending where the search is taking place.
■ returnType—Indicator for what kind of identifiers are returned; either
■ 1—for internal IDs
■ 2—for product codes
■ productsFound—The result of the search.
■ extData—Can be used by an extension to return an arbitrary string. Storefront will append this extData string to the query string in the catalog for the items it returns, so clicking on those items ultimately invokes the URL structured as follows
UserJDocumentCustomize.aspx?docid=999999&searchTerms=AAAAA
&searchUsed=true&SearchExtensionData=contents_of_extData
enabling further extension inserts to pick it up if desired.
Returns
Implementations should return eSuccess, and an array of either internal product IDs or product codes for the matching products
Remarks
For this call, the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one product search module is consulted.
If there is no implementation of ExternalProductSearch2() for the extension, Storefront will fall back to calling ExternalProductSearch().
Called when Storefront wishes to get rates for foreign exchange.
Method
int GetCurrencyExchangeRates(string storeCurrencyCode,
bool requestFresh,
string[] currencyCodes,
ref double[] rates)
Parameters
■ storeCurrencyCode — the ISO 4217 code of the deployment's default currency.
■ requestFresh — if true, the request was generated by an administrator clicking a button; if false, this is a periodic check of the rates. The module may use different strategies for returning values in each case; for example it might only get rates once a day for periodic checks, but always get the very latest rates if the button is clicked.
■ currencyCodes — the ISO 4217 codes of all currencies used in the deployment.
■ rates — the exchange rates in effect between each currency and the default currency, in the same order as the entries in the currencyCodes array. These may be updated by the module. The rates are the ratio of values of a unit of the given currency to a unit of the default currency. For example, with a default currency of USD, the entry corresponding to GBP might be around 1.56 in July 2012, indicating that a Pound Sterling is worth $1.56.
Returns
The module should return eSuccess.
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to assign exchange rates.
Since version 8.1
This is called when a scheduled task specifies an external (SXI module) action.
Method
int InitiateScheduledTaskInstance(string taskId,
string taskName,
string[] taskArguments,
DateTime scheduledTime)
Parameters
■ taskId — internal identifier of the scheduled task item which triggered this instance.
■ taskName — name of the task, interpreted by the SXI module.
■ taskArguments — an array of strings representing the arguments to be interpreted by the module.
■ scheduledTime — the time this instance was scheduled to run. It will usually be a few seconds in the past. If the deployment was deactivated and then reactivated, it could even be several days in the past.
Returns
The module should return eSuccess to indicate that the task was initiated. The module is responsible for all logging and exception handling. Return eFailure to indicate that the task could not be initiated (for instance, if the taskName is not recognized by the module).
Remarks
The call is typically sent only to the SXI module associated with the given scheduled task.
This is called right before the JSON is generated for the Customization page (UserJCustomize.aspx).
Method
int InsertCustomStep(string docID,
string productId,
string [] listOfSteps,
out CustomStep stepObject)
Parameters
■ docId—The internal id of the current document.
■ productId—The internal id of the current product.
■ listOfSteps—The list of steps on this form in order.
■ stepObject—Contains the required parameters for the custom step to be inserted.
Returns
The module should return eSuccess.
Example:
public override int CustomStep(string docID, string productId, string [] listOfSteps, out CustomStep stepObj) {
stepObj = new CustomStep() {
StepTitle = “Look! I inserted a step!”,
StepIndex = 1,
StepID = “customStepXYZ”,
StepContents = "<div>This is some HTML</div><div>and some more
HTML</div><div>and yet more</div>";
};
return stepObj;
}
This method lets the extension keep track of ledger changes in real time. It is called every time an entry is added to the Ledger.
Method
int LedgerChange_After(SINILedgerEntry ent)
Parameters
■ ent — A SINILedgerEntry object corresponding to the most recent Ledger entry.
Returns
The extension should return eSuccess.
This method lets the extension return a folder path that might vary depending on the document, potentially creating a folder tree of arbitrary depth for output file storage instead of using the default method of letting each document store its output in a subfolder of a single overarching folder (typically a sibling of the deployment WebPages folder, named “Output”).
Method
int MakeOutputDirectory_Before(string rootOutputFolder,
string documentID,
string externalDocID,
string context,
out string outputFolderPath,
out string outputHtmlUrl)
Parameters
■ rootOutputFolder — The current root of the output.
■ documentID — The internal document ID.
■ externalDocID — The external document ID.
■ context — A string specifying the circumstances for the call. One of the following:
FINAL/PRINT |
FINAL/HTML |
Meaning the application is about to generate final output (print or HTML) in the folder.
■ outputFolderPath — The subfolder of rootOutputFolder returned as a path relative to the rootOutputFolder.
■ outputHtmlUrl — The subfolder accessible externally so that it can be sent in an email. If it is set to NULL or to a URL relative to WebPages then Storefront will construct a URL using DataGlobal.UrlPrefixForLinksInEmails.
Returns
The extension should return eSuccess or eDoNotCall.
Remarks
Future versions may have other values for context than the two cited above; write your extension accordingly.
Example
The following event takes the external ID, makes it file-system-friendly if necessary, and splits it into a path after the 4th character; so D0012345 becomes D001\2345 and specifies that subfolder.
public override int MakeOutputDirectory_Before(string rootOutputFolder, string documentID, string s, string context, out string outputFolderPath, out string outputHtmlUrl)
{
outputHtmlUrl = null; // go with default
outputFolderPath = null;
s = s.Replace(":", "_");
s = s.Replace("\\", "_");
s = s.Replace("/", "_");
s = s.Replace("?", "_");
s = s.Replace("*", "_");
s = s.Replace(">", "_");
s = s.Replace("<", "_");
s = s.Replace("|", "_");
s = s.Replace("\"", "_");
string externalDocID = s;
if (context.StartsWith("FINAL/"))
{
if (externalDocID != null && externalDocID.Length >= 7)
outputFolderPath = externalDocID.Substring(0, 4) + "\\" + externalDocID.Substring(4);
else
outputFolderPath = externalDocID;
}
return eSuccess;
}
This is called when Storefront is about to send out a notification e-mail.
Method
int NotificationSend_Before(string notificationType,
ref string fromAddressTemplate,
ref string toAddressTemplate,
ref string ccAddressTemplate,
ref string bccAddressTemplate,
ref string messageSubjectTemplate,
ref string messageBodyTemplate,
string orderId,
string documentId,
string userId)
Parameters
■ notificationType — the notification types are listed below. The main recipient of the e-mail is listed within the name of the notification; such as User for the end-user of the site; Reviewer for a reviewer account; or Admin for an administrator:
■ TellUserOrderPendingApproval — sent when an order is placed that requires approval.
■ TellUserOrderPlaced — sent when the order is placed.
■ TellUserOrderApproved — sent when the order is approved.
■ TellUserOrderDeclined — sent when the order is declined.
■ TellUserItemShipped — sent when an item has shipped.
■ TellUserSelfRegistrationComplete — sent when self-registration is complete.
■ TellUserForgotPassword — sent to the user to remind them of their forgotten password.
■ TellReviewerApprovalNeeded — sent when an order is placed that requires approval.
■ TellAdminOrderPlaced — sent when an order is placed.
■ TellAdminOutputGenerated — sent when output has been generated.
■ TellAdminOutputFailed — sent when output has failed.
■ TellAdminUserSelfRegistered — sent when a user has self-registered.
■ fromAddressTemplate — “From” address of the e-mail, with angle-bracket parameters for substitutions if necessary.
■ toAddressTemplate — “To” address of the e-mail, with angle-bracket parameters for substitutions if necessary.
■ ccAddressTemplate — “Cc” address of the e-mail, with angle-bracket parameters for substitutions if necessary.
■ bccAddressTemplate — “Bcc” address of the e-mail, with angle-bracket parameters for substitutions if necessary.
■ messageSubjectTemplate — “Subject” field of the e-mail, with angle-bracket parameters for substitutions if necessary.
■ messageBodyTemplate — Body of the e-mail, with angle-bracket parameters for substitutions if necessary.
■ orderId — Internal ID of the order group for use in parameter substitutions.
■ documentId — Internal ID of the document for use in parameter substitutions.
■ userId — Internal ID of the user for use in parameter substitutions.
Returns
Return eSuccess to allow the notification to go through. Return eShouldAbort to cancel this instance of the notification.
Remarks
The fromAddressTemplate, toAddressTemplate, ccAddressTemplate, bccAddressTemplate, messageSubjectTemplate and messageBodyTemplate values may all be overridden by the module.
Called when a manual or SINI price adjustment is made to an order.
Method
int OrderAdjustment_After(string orderId, double adjustment,
string currencyCode, string reason)
Parameters
■ orderId — the internal ID of the order being adjusted.
■ adjustment — the amount of the adjustment; positive numbers indicate additions to the price, and negative numbers indicate reductions.
■ currencyCode — the ISO 4217 currency code of the adjustment. This should match the CurrencyCode property of the order.
■ reason — a human-readable string describing the reason for the adjustment, if available.
Returns
The module should return eSuccess.
OrderApproval_After (deprecated)
Since version 7.0
Note: This event has been deprecated. Use OrderApproval_After2() instead (described below).
Called after an order has been approved.
Method
int OrderApproval_After(string orderId, bool approved, string approver);
Parameters
■ orderId — Internal ID of the order group.
■ approved — “true” if approved, “false” otherwise.
■ approver — Internal ID of the approver, null if no approval was needed, or the empty string if approver was a SXI module.
Returns
The module should return eSuccess.
Called from Storefront after an approval step is done.
Method
int OrderApproval_After2(string orderId,
string[] approvedDocumentIDs,
string[] declinedDocumentIDs,
int approvalStep
string approver);
Parameters
■ orderId — Internal ID of the order group.
■ approvedDocumentIDs — Array of internal document IDs of documents approved.
■ declinedDocumentIDs — Array of internal document IDs of documents declined.
■ approvalStep — Step number of the just completed step.
■ approver — Internal ID of the approver, null if no approval was needed, or the empty string if approver was a SXI module.
Returns
The module should return eSuccess.
Remarks
The approved/declined arrays include the document IDs of the top-level documents, including kit documents but not kit parts. If the order property CurrentStepNumber is consulted it should be one greater than the “approvalStep” argument, since that argument refers to the step already completed. If this is greater than OrderProperty.StepCount, then the approval process is over and all documents are either “Rejected” or “In Process”.
If no module answers eSuccess from this event, then all modules will be called with the legacy call OrderApproval_After().
This is called after an order is placed, which in some workflows will be before all order-related tasks (such as approvals) have completed. See OrderPlace_After2, below, for an event that fires after all order-related tasks are finished.
Method
int OrderPlace_After(string orderID, string[] documentIDs)
Parameters
■ orderID — Internal identifier of the order.
■ documentIDs — Array of internal identifiers for the documents in the order.
Returns
The module should return eSuccess.
Remarks
The SXI Module could (for example) e-mail an order confirmation message to the user or log the order into an external billing system.
Since version 9.8
This is called after an order is placed and all order-related tasks have completed.
Method
int OrderPlace_After(string orderID, string[] documentIDs)
Parameters
■ orderID — Internal identifier of the order.
■ documentIDs — Array of internal identifiers for the documents in the order.
Returns
The module should return eSuccess.
Remarks
If approvals are part of the order workflow then with this event Storefront is guaranteed to be ready for AdvanceApproval(), described on page 237.
This is called after the user has selected the Place Order button but before the order is actually placed. It’s a last chance for the SXI Module to object.
Method
int OrderPlace_Before(string orderID, string[] documentIDs)
Parameters
■ orderID — Internal identifier of the order.
■ documentIDs — Array of internal identifiers for the documents in the order.
Returns
Normally the module should return eSuccess. For this method, the eShouldAbort return value signals that the order should not be placed, and the documents should be returned to the Shopping Cart. The user will be informed of this and an entry will be made in the Storefront log.
Remarks
The SXI Module could (for example) re-assign external identifiers for the order or the documents in the order.
This is called at multiple points in the workflow when an end user elects to download a product “instantly” effectively placing an order for that product without going through the traditional ordering workflow.
Method
int OrderPlace_DownloadNow (string orderId,
string outputLocation,
string context,
out string message)
Parameters
■ orderId—The internal identifier of the current order.
■ outputLocation—The location of the output that is generated, subject to context.
■ context—Refines the interpretation of outputLocation. Will be one of the following
■ OutputProduced_Before—The request has been made but Storefront has taken no action yet. outputLocation will be null unless this is a Hosted PDF product.
■ OutputProduced_After—Output has been generated which may consist of one or more files. outputLocation is the path to the directory containing the generated files.
■ OutputCollected—Storefront is ready to send the collected output to the end user. outputLocation will be the name of the file that is to be downloaded. DOCXXX.pdf in the case of a PDF or DOCXXX.zip in the case of multiple files that have been collected.
■ message- If the extension chooses to abort the order it may also choose to return a message specifying why. This will be displayed in the download modal. If message is null the generic error message selected by the deployer will be displayed.
Returns
If the module wishes to abort the download in progress it should return eShouldAbort. In all other cases it should return eSuccess.
Called after at least one document in an order goes from not being ready for production to being ready for production, and all are either ready for production or rejected.
Method
int OrderReadyToProduce_After(string orderId);
Parameters
■ orderId — Internal ID of the order group.
Returns
The module should return eSuccess.
Called after all documents in an order are rejected.
Method
int OrderRejected_After(string orderId);
Parameters
■ orderId — Internal ID of the order group.
Returns
The module should return eSuccess.
Called after at least one document in an order is ready for printing (either successfully run through Server or ready by virtue of being a static PDF, or by some other means) , and all are either ready for printing or rejected.
Method
int OrderRendered_After(string orderId);
Parameters
■ orderId — Internal ID of the order group.
Returns
The module should return eSuccess.
Called after at least one document in an order is marked as Shipped, and all are either shipped or rejected.
Method
int OrderShipped_After(string orderId);
Parameters
■ orderId — Internal ID of the order group.
Returns
The module should return eSuccess.
Called when Storefront executes the Init, Load, or PreRender event on a page from the Storefront end user or Administrator site.
Method
int PageLoad(string pageBaseName, string eventName)
Parameters
■ pageBaseName — Name of the page, normalized to lower case, with “.” replaced by “_”, e.g. “usercontentstart_aspx”.
■ eventName — One of “Init”, “Load”, “PreRender”, depending on which is occurring.
Returns
For this event, the meaning of eDoNotCall is special. The module should return eDoNotCall if it does need to be informed of PageLoad events for the given page. This is important for efficiency reasons.
Called when Storefront a user's password is changed by user or admin action, for example by self-registration or Change Password, or through SINI. It is not called when the password changes due to an admin uploading a user list.
Method
int PasswordChanged_After(string userId, string newPassword)
Parameters
■ userId — This is the internal ID of the user whose password has changed.
■ newPassword — This is the new password, if available. It is NULL if PasswordChanged_After is called due to setting the SINI property PasswordHashed, since Storefront doesn't know the password in this case.
Returns
The method should return eSuccess.
Remarks
Modules wishing to set a password expiration date will do it within this method.
This event is called when the UserJShoppingCart page loads (called once each for the cart, on hold, or in progress list).
Method
int ProcessDocumentListJson(string pageBaseName,
string context,
string[] documentIDs,
ref string jsonData)
Parameters
■ pageBaseName —Name of calling page, typically UserJShoppingCart.
■ context —String identifying which document list is being affected. One of the following constants
ShoppingCart |
OnHold |
InProgress |
■ documentIDs —Array of internal identifiers for the documents in the shopping cart.
■ jsonData —The JSON serialization for an array of ShoppingCartItem objects. The extension can modify this string as it wishes; it may add, remove, or modify the objects in the array. The modified string will be passed to the web client.
Returns
Extensions should return eSuccess if they process JSON for the given page, or eDoNotCall otherwise, meaning that they do not wish to be called anymore with respect to the given page.
Remarks
If the extension returns invalid JSON we won't do anything to prevent it.
Since 9.3, additional contexts added in 9.5
This is called when the UserJOrders or UserJApprovals page loads, plus every time the Show More button on those pages is clicked by the user in the client agent.
Method
int ProcessOrderListJson(string pageBaseName,
string context,
string[] orderIDs,
ref string jsonData)
Parameters
■ pageBaseName —Name of calling page.
■ context —String identifying which order list is being affected. One of the following constants
Orders |
OrderDetailsModal |
Approvals |
ApprovalDetailsModal |
■ orderIDs —For the Orders and Approvals contexts, an array of internal identifiers for the orders on the page. For the OrderDetailsModal and ApprovalDetailsModal contexts, an array with a single ID for the relevant order.
■ jsonData —For the Orders and Approvals contexts, the JSON serialization for an array of InfoObject objects. The extension can modify this string as it wishes; it may add, remove, or modify the objects in the array. The modified string will be passed to the web client. For the OrderDetailsModal and ApprovalDetailsModal contexts, the serialization of the corresponding OrderInfoObject in an array of length one. For example,
ProcessOrderListJson("userjorders",
"OrderDetailsModal",
new string[]{ "99" },
"[{\"InternalOrderID\":99,
\"ExternalOrderID\":\"G-010099\", ... }]");
Note the square brackets at the beginning and end of the serialized JSON. The extension should return an OrderInfoObject, possibly with added fields, in the same form.
Returns
Extensions should return eSuccess if they process JSON for the given page, or eDoNotCall otherwise, meaning that they do not wish to be called any more with respect to the given page.
Remarks
If the extension returns invalid JSON we won't do anything to prevent it.
During this event, extensions called can modify the page JSON data before it is sent to the client.
Method
int ProcessPageLoadJson(string pageBaseName, string eventName, bool postback,
Dictionary<string, string> jsonMenuVariables, Dictionary<string, string> jsonPageVariables)
Parameters
■ pageBaseName —the class name of the page, lower-cased, with “.” replaced by “_”, e.g. “userjshoppingcart_aspx”.
■ eventName —for consistency with the PageLoad method this is always “Load”.
■ postback —result of the request, or null if no information was provided
■ jsonMenuVariables —a dictionary of variable names and string values for use in the header. These may be overridden by like-named values in jsonPageVariables.
■ jsonPageVariables —a dictionary of variable names and string values for use in the page.
Returns
Extensions should return eSuccess if they process JSON for the given page, or eDoNotCall otherwise, meaning that they do not wish to be called anymore with respect to the given page. Extensions may add, modify, or remove variables from either of the dictionaries, and this will be reflected in the Javascript that makes its way to the client.
Example
The following rough-and-ready implementation adds an item to the header menu:
public override int ProcessPageLoadJson(string pageName, string stage, bool postback, Dictionary<string, string> jsonMenuVariables, Dictionary<string, string> jsonPageVariables)
{
if (pageName != "userjcatalog_aspx")
return StorefrontExtension.eDoNotCall;
string menu = jsonMenuVariables["Pageflex_Menu_Specification"];
int j = menu.IndexOf("\"menuItems\": [");
int k = menu.IndexOf("]", j + 1);
if (j > 0 && k > 0)
{
jsonMenuVariables["Pageflex_Menu_Specification"] =
menu.Substring(0, k) +
", {'name' : 'Old School','link' : 'UserContentStart.aspx'} " +
menu.Substring(k);
}
return eSuccess;
}
Called whenever a product is created, modified, or deleted, so that all extensions that care can keep an index of current products.
Method
int ProductChanged(string stagedProductId, string productCode, int typeOfChange)
Parameters
■ stageProductId — The internal product ID of the master version of the product.
■ productCode — Product code of the product.
■ typeOfChange—An indicator of one of the following changes:
■ 1 = StagedCreate; a new product has been created (initially just staged with no live release)
■ 2 = StagedEdit; the admin has edited the master product
■ 3 = Release; the staged version of the product has been released, which becomes the live product
■ 4 = Retire; the current live product has been retired
■ 5 = Archive; the product has been archived
■ 6 = Unarchive; the product has been restored from the archive
■ 7 = Delete; the product has been deleted
Returns
All implementations should return eSuccess.
QueryInventoryModules (deprecated)
Since version 8.1
Note: This event has been deprecated. Use QueryInventoryModules2() instead (described below).
This is called when Storefront needs information from active inventory extensions.
Method
int QueryInventoryModules(string code,
string[] productIDs,
ref string[] values)
Parameters
■ code — a code indicating what kind of information is being requested. For 8.1 the code will always be “AVAILABLE” indicating a request for “Available Quantity” for each of the products.
■ productIDs — an array of internal IDs for the Storefront products, some of which may be subject to inventory tracking.
■ values — an array of the same size as productIDs, to hold the information requested; initially filled with nulls.
Returns
A module that chooses to provide information for some of these products should return eSuccess; all others should return eFailure (or eDoNotCall). In the first case, the module should set values[i] to a decimal string representing the Available Quantity for the product identified by productIDs[i], for all relevant index numbers i. For any products not known to this module (possibly handled by some other inventory module) this call should not change the corresponding entries in the values array.
Remarks
All active inventory extensions will be called in sequence, with the answers from the previous ones already populating relevant entries in the values array. This way all the inventory modules can cooperate to give a full picture.
This is called when Storefront needs information from active inventory extensions.
Method
int QueryInventoryModules2(string code,
string[] productIDs,
ref InventoryItem[] values)
Parameters
■ code — a code indicating what kind of information is being requested. Currently the code will always be “AVAILABLE” indicating a request for “Available Quantity” for each of the products.
■ productIDs — an array of internal IDs for the Storefront products, some of which may be subject to inventory tracking.
■ values — an array of InventoryItem objects the same size as productIDs, to hold the information requested; initially filled with nulls.
Returns
A module that chooses to provide information for some of these products should return eSuccess; all others should return eFailure (or eDoNotCall). In the first case, the module should set values[i] to a structure with information for the product identified by productIDs[i], for all relevant index numbers i. For a description of the structure, see “InventoryItem” .
For any products not known to this module (possibly handled by some other inventory module) this call should not change the corresponding entries in the values array.
Remarks
All active inventory extensions will be called in sequence, with the answers from the previous ones already populating relevant entries in the values array. This way all the inventory modules can cooperate to give a full picture. If no active extensions implement this method, Storefront calls the legacy QueryInventoryModules() instead.
This is called when a Storefront deployment determines that it needs to refresh its cached information.
Method
int ResetCachedData(string storefrontName)
Parameters
■ storefrontName — The deployment name of the Storefront which is resetting.
Returns
The module should return eSuccess.
Remarks
The module should unload any cached data, at least any that is associated with the given deployment.
RetryAuthorization (deprecated)
Since version 7.6
Note: This event has been deprecatedUse RetryAuthorization2() instead (described below).
This is called from Storefront when an administrator clicks the Retry Authorization button, in the unusual case that the PaymentStatus order property is in the “PEND” (Pending) status for a long time.
Method
int RetryAuthorization(string orderId,
string authorizationTransID,
string collectionToken)
Parameters
■ orderId — The deployment name of the Storefront which is resetting.
■ authorizationTransID — The transaction ID of the original authorization attempt.
■ collectionToken — The collection token returned from the original authorization attempt, if any.
Returns
The module should return eSuccess. If the module can't check on delayed authorizations, then it should always return eDoNotCall.
Remarks
If there is some way to check on whether the authorization has finally cleared, the extension should do so and call DelayedAuthorizationComplete if appropriate.
If authorizationTransID is null, the module should do nothing and simply return eSuccess if it can handle this call usefully.
This call is only sent to the unique SXI module which originally replied to the AuthorizeTransaction call.
This is called from Storefront when an administrator clicks the Retry Authorization button. This can happen if the payment processor did not give an “APPROVE” or “DECLINE” answer from the AuthorizeTransaction event. Normally this is resolved automatically, but the admin has the option to request another attempt using the button.
Method
int RetryAuthorization2(string orderId,
string paymentId,
string authorizationTransID,
string collectionToken)
Parameters
■ orderId — The order ID of the order.
■ paymentId — The internal ID of the payment object for this authorization attempt.
■ authorizationTransID — The transaction ID of the original authorization attempt.
■ collectionToken — The collection token returned from the original authorization attempt, if any.
Returns
The module should return eSuccess. If the module doesn’t check on delayed authorizations, then it should always return eDoNotCall.
Remarks
If there is some way to check on whether the authorization has finally cleared, the extension should do so in response to this event and call DelayedAuthorizationComplete2() if appropriate.
If authorizationTransID is null, the module should do nothing and simply return eSuccess.
This call is only sent to the unique SXI module which originally replied to the AuthorizeTransaction call. If the extension does not implement this method, Storefront calls the legacy method RetryAuthorization() instead
This event fires when certain actions are taken by Storefront administrators— downloading a user file from an order, changing the membership of an admin group, or changing admin access privileges— which lets the extension react to the event as desired (e.g. triggering notifications).
Method
int SecurityEvent_After(string eventType,
string eventDetails,
string adminId,
string assetId);
Parameters
■ eventType — One of the following:
AccessUserFile |
ChangeAdminGroup |
ChangePermission |
■ eventDetails — A message describing the precise action.
■ adminId — The ID of the logged-in Storefront administrator performing the action.
■ assetId — If the eventType is “AccessUserFile” this is the ID of the downloaded user asset.
Returns
The extension should return eSuccess.
Remarks
Future versions may have other values for eventType than the three cited above; write your extension accordingly.
Since version 5.5
This is called after the user has finished self-registering.
Method
int SelfRegister_After(string userId)
Parameters
■ userId — Internal ID of the user which has been created.
Returns
The module should return eSuccess.
Since version 5.5
This is called when the user attempts to self-register.
Method
int SelfRegister_Before(string logonName, string password, FieldValue[] userFieldValues)
Parameters
■ logonName — The logon name of the user.
■ newPassword — Proposed password for this account.
■ userFieldValues — New values for User Profile fields
Returns
The module should return eSuccess to allow the self-registration to go forward. Return eShouldAbort to reject this self-registration.
Remarks
The extension may be called twice depending on what self registration options are enabled under the Login tab of the deployment’s admin Site Options page. When “Self Registration” is enabled the extension is always called after the self-registering user initially submits a user name and password at which point userFieldValues will always be null. When “Link to Registration Page” is enabled then the module will be called when the profile form on the registration page is submitted at which point userFieldValues will be populated with the data the user input on the form.
This is called just before the Shopping Cart page is displayed.
Method
int ShoppingCartPage_Before(string userID, string[] documentIDs)
Parameters
■ userID — Internal identifier of the user
■ documentIDs — Array of internal identifiers for the documents in the shopping cart.
Returns
The module should return eSuccess, or eFailure if an error condition is discovered, which results in a Warning bubble in the Shopping Cart page.
Remarks
The SXI Module could (for example) take the opportunity to assign external identifiers to the documents, which would be displayed to the user when the page displays. When overriding this event if your primary intent is to validate documents coming from the customization page(s) we would highly recommend using DocToCart_Before() instead.
Useful for instances where the command packet for a campaign job requires editing before the campaign is launched.
Method
int SubmitCampaignJob_Before2(string micrositeId,
string submittedJobId,
bool isTestData,
bool isEmailJob,
ref string commandPacket,
string deploymentCode,
string orderId,
string documentId,
string orderDetailFromSF,
string mailingName,
string trigger,
string context)
Parameters
■ micrositeId—Internal identifier of the campaign microsite.
■ submittedJobId—Internal identifier of the submitted job.
■ isTestData—True if the data is for test purposes only, false if the data is for live production.
■ isEmailJob—True if the campaign job only outputs email, false if it outputs anything else.
■ commandPacket—The XML command packet provided as a string.
■ deploymentCode—Deployment code of the deployment.
■ orderID—Internal identifier of the order.
■ orderDetailFromSF—Arbitrary additional Storefront data of your choosing.
■ mailingName—Descriptive label for email job.
■ trigger—Always null.
■ context—Reserved for future use; currently expected to be null.
Returns
Extension should return eSuccess if it wants Storefront to submit the job after manipulating the command packet, or eShouldAbort if it intends to take ownership of the mailing.
This is called during SINI PlaceOrder().
Method
int SubmitOrderPage_Before(string orderID, string[] documentIDs)
Parameters
■ orderID — Internal identifier of the order.
■ documentIDs — Array of internal identifiers for the documents in the shopping cart.
Returns
The module should return eSuccess.
Remarks
The SXI Module could (for example) take the opportunity to assign external identifiers to the documents, which would be displayed to the user when the page displays (in versions of the application prior to 9.0, when the SubmitOrder page ceased to exist).
DLL Extensions only —Since version 9.9
Called when Storefront is producing output of any kind. This provides access to the XML command packet that Storefront created to submit the job and the task log generated by Pageflex Server while producing the output.
Method
int SubmitStorefrontJob_After(string context, string docID, string packet,
string transID, string retString)
Parameters
■ context — The output job type requested. One of the following constants
final_output |
pdf_proof |
campaign_proof |
bitmap |
convert_file_to_pdf |
■ docID — The external ID of the document being processed
■ packet — The XML command packet provided as a string.
■ transID — The transaction ID for the task that produced the output.
■ retString — The task log for the output.
Returns
For any particular output job this event can be used to collect information to be used as you choose. For instance, to send data to an external system, or to gather information not readily available to Storefront. Consider this example: the output job may have a Document Action that executes code and returns a value— perhaps the number of pages produced, or even the output file type— to the task log. The task log can be parsed for that data.
DLL Extensions only —Since version 9.0
Called when Storefront is producing output of any kind. This provides access to the XML command packet that Storefront has generated for the current submission and allows an extension to modify it.
Method
int SubmitStorefrontJob_Before(string context, string docID, ref string commandPacket)
Parameters
■ context — The output job type requested. One of the following constants
final_output |
pdf_proof |
campaign_proof |
bitmap |
convert_file_to_pdf |
■ docID — The external ID of the document being processed
■ commandPacket — The XML command packet provided as a string.
Returns
If you wish to take the command packet, manipulate it and submit the job yourself in some other fashion you should return eShouldAbort. If you return eShouldAbort you are now responsible for updating the job status in Storefront. If you wish to allow Storefront to submit the job after you manipulate the command packet or simply wish to proceed without taking any action you should return eSuccess.
Example
The following rough-and-ready implementation adds a node for a new variable to the command packet. The command packet is provided as a string; how it’s manipulated is up to you. This example shows manipulating the command packet as an XmlDocument:
public override int SubmitStorefrontJob_Before(string context, string docID,
ref string commandPacket)
{
if (context == "bitmap")
{
commandpacket = AppendVarToCommandPacket(commandpacket,"NewVariable","NewValue");
}
return eSuccess;
}
private string AppendVarToCommandPacket(string cmdpkt, string varName,
string varValue)
{
XmlDocument xDoc = new XmlDocument();
string namespaceUri = "http://www.pageflex.com/schemas";
xDoc.LoadXml(cmdpkt);
var nsm = new XmlNamespaceManager(xDoc.NameTable);
nsm.AddNamespace("pf", namespaceUri);
XmlNode xElt =
xDoc.SelectSingleNode("//pf:job_command/pf:job_variables", nsm);
XmlNode x1 = xDoc.CreateNode(XmlNodeType.Element, "pfjob:var", namespaceUri);
x1.InnerText = "NewVariable";
XmlAttribute name1 = xDoc.CreateAttribute("name");
name1.Value = "NewValue";
x1.Attributes.Append(name1);
xElt.AppendChild(x1);
MemoryStream ms = new MemoryStream();
xDoc.Save(ms);
return xDoc.InnerXml;
}
This is called when a new asset has been uploaded to the user’s library, via any of the ways we offer (including the Free Edit step).
Method
int UserAssetUpload(string userID, string assetID)
Parameters
■ userID — Internal identifier of the user.
■ assetID — Internal identifier of the asset.
Returns
The module should return eSuccess.
Remarks
This takes place after the asset thumbnail has been generated, so the SXI Module can replace it (or the asset itself, or both) with something of its own devising.
UserAssetUploadValidate (deprecated)
Called when a User Asset has been updated (before making any thumbnail), and before it gets an asset identifier.
Method
int UserAssetUploadValidate(string userID,
string filePath,
string fileType)
Parameters
■ userID — Internal identifier of the user.
■ filePath — File location of the asset.
■ fileType — One of the following asset type constants
image | The asset is an image |
CSV_DB | The asset is a database for a data merge |
PDF_DOC | The asset is a PDF document |
Returns
Return eShouldAbort if the upload should be aborted, otherwise return eSuccess.
Remarks
The SXI Module could (for example) use this opportunity to ensure that an image asset meets some color depth or DPI guidelines, or even convert the asset into a different format.
Called when a User Asset has been updated (before making any thumbnail), and before it gets an asset identifier.
Method
int UserAssetUploadValidate(string userID,
string filePath,
string fileType,
out string errorMessage)
Parameters
■ userID — Internal identifier of the user.
■ filePath — File location of the asset.
■ fileType — One of the following asset type constants
image | The asset is an image |
CSV_DB | The asset is a database for a data merge |
PDF_DOC | The asset is a PDF document |
■ errorMessage — A message to be displayed to the user when an uploaded asset is rejected.
Returns
Return eShouldAbort if the upload should be aborted and populate errorMessage with a message to display to the user, otherwise return eSuccess.
Remarks
The SXI Module could (for example) use this opportunity to ensure that an image asset meets some color depth or DPI guidelines, or even convert the asset into a different format.
This is called from the User Profile Edit page after user profile field changes have been made to the database.
Method
int UserFieldsUpdate_After(string userID,
FieldValue[] changes)
Parameters
■ userID — Internal identifier of the user.
■ changes — Array containing all the new values of the User Profile fields.
Returns
The module should return eSuccess.
Remarks
The SXI Module could (for example) copy any changed values from the user profile into a central database for your entire website.
This is called from the User Profile Edit page after the user has hit “Accept” but before user profile field changes are actually made to the database.
Method
int UserFieldsUpdate_Before(string userID,
FieldValue[] changes)
Parameters
■ userID — Internal identifier of the user.
■ changes — Array containing all the new values of the User Profile fields.
Returns
For this method, the eShouldAbort return value signals that the changes should not take place. The user will be informed of this and an entry will be made in the Storefront log.
This is called after the user has logged in but before the page is redirected. This applies to user logins only and not admin logins.
Since version 5.5.2
Storefront does not call the UserLogon_After event in the SXI modules when starting an anonymous session.
Method
int UserLogon_After(string userID)
Parameters
■ userID — Internal identifier of the user.
Returns
The module should return eSuccess.
This is called from Storefront after the user hits the Login button but before they actually become the logged-on user. This applies to user logins only and not admin logins.
Method
int UserLogon_Before(string userID)
Parameters
■ userID — Internal identifier of the user about to be logged in.
Returns
Return eSuccess to allow the user to log in. Return eShouldAbort if the user should not be permitted to log in. If the user is denied the login, an entry will be made in the Storefront log.
DLL Extensions only — Since version 7.5
This is called after the order is placed and allows an extension to examine the ApprovalSteps as constructed by Storefront and modify, remove, or add steps.
Method
ValidateApprovalSteps(ref List<ApprovalStep> steps, string OrderID)
Parameters
■ steps — A list of the ApprovalStep objects to be validated. This will be an empty list in the case of no steps. It is passed by reference so any modifications to this List object will be reflected in Storefront.
■ OrderID — Internal order identifier of order being processed.
Returns
This method should return eSuccess.
ValidateForm (deprecated)
Note: This event has been deprecated. Use the sfjs object instead to add validation to form fields on the client side. See Chapter 5, “Adding Validation,” on page 339 for details.
This is invoked when forms are submitted to give an SXI module a chance to validate the form, optionally correct errors, and return validation error messages.
Method
int ValidateForm(string formName,
bool allowChange,
ref FieldValue[] fields,
out string[] errors)
Parameters
■ formName — One of the following form name constants:
AccountProfile | Validating a “User Profile” form |
AccountProfileAddressBookItem | Validating an item in the user’s address book. |
AddressBook | Validating an address book item automatically created from the user profile. |
AdminAccountProfile | Validating a “User Profile” form on the Storefront Administrator site. Click User Accounts on the Admin site and click a user account to see the user account profile fields that can be validated (on the AdminUserDetail.aspx page). This also works with Admin Accounts. |
AdminAccountProfileAddressBookItem | Validating a shared address book item on the Administrator site. |
AdminItemPrinting | Validating a “Printing” step form on the Storefront Administrator site. Click Orders on the Admin site, then click the Show Items tab, a document ID, Change Settings, and scroll down to see the Printing Options fields that can be validated (on the AdminItemDetails.aspx page). |
AdminOrderPayment | Validating a “Payment” form on the Storefront Administrator site. Click Orders on the Admin site, then click the Show Orders tab, an order ID, Change Settings, and scroll down to see the Payment Information fields that can be validated (on the AdminOrderDetails.aspx page). |
AdminOrderShipping | Validating a “Shipping” form on the Storefront Administrator site. Click Orders on the Admin site, then click the Show Orders tab, an order ID, Change Settings, and scroll down to see the Shipping Information fields that can be validated (on the AdminOrderDetails.aspx page). |
DataListAcquisition | Validating entries from the Data List Acquisition form |
FormFilling | Validating a “Form Filling” step form during document creation or editing. |
Payment | Validating a “Payment” form during checkout. |
Printing | Validating a “Printing” step form during document creation or editing. |
ROAccountProfile | Validating a read-only User Profile form |
Shipping | Validating a “Shipping” form during checkout. |
UserItemSummaryPrinting | Validating a read-only “Printing” step form in the user’s Order Item Details page |
UserOrderSummaryPayment | Validating a read-only “Payment” form in the user’s Order Summary page |
UserOrderSummaryShipping | Validating a read-only “Shipping” form in the user’s Order Summary page |
■ allowChange — This will be true if ValidateForm is permitted to modify the form field values in the fields array.
■ fields — Array of FieldValue objects with the contents of the fields on the page. Modules implementing this method can change field values by writing back into the fields array.
■ errors — The errors array contain the error strings from validating the form. A null entry means there was no error for the corresponding field. A value of “” (the empty string) means that an error occurred for the corresponding field, but the error message should be taken from the field’s validation error text. (The index into the errors array corresponds with the index into the fields array.)
Returns
For this event, the meaning of eDoNotCall is special. The module should return eDoNotCall if it cannot validate forms of the specified formName. This is important for efficiency reasons.
If more than one module validates the same form and reports an error on the same field, the first error returned will be displayed to the user.
Example
The following example validates form filling step forms, looks for a field named “URL” and lower cases its value.
public override int ValidateForm(string formName,
bool allowChange,
ref FieldValue[] fields,
out string[] errors)
{
errors = null;
if (formName != "FormFilling")
return eDoNotCall;
if (allowChange)
{
foreach (FieldValue f in fields)
{
if (f.fieldName == "URL")
{
f.fieldValue = f.fieldValue.ToLower();
}
}
}
return eSuccess;
}
Since version 5.5
This is called when an administrator is adding a new logon name to the system (or when a user is self-registering and choosing a name), before the user account is created.
Method
int ValidateLogonName(string logonName);
Parameters
■ logonName — Proposed logon name for the user or admin.
Returns
Return eSuccess to allow the logon name. Return eShouldAbort if the given logon name should not be used.
Remarks
This is not called when uploading a user list.
This is called when an administrator is adding a new password to the system or when changing an old password.
Method
int ValidatePassword(string logonName, string newPassword, string context)
Parameters
■ logonName — The logon name of the user (or admin) to which the password applies.
■ newPassword — Proposed new password for this account.
■ context — String indicating what kind of password change is requested:
USER | the user is changing their own password |
ADMIN | the admin is changing a user or admin password |
SELF | the user is creating a password on the self-registration page |
FORGOT | the user is resetting a password via the forgot-my-password page |
SINI | the user is changing the password via a SINI call |
Returns
Return eSuccess to allow the password. Return eShouldAbort if the given password should not be used.
Remarks
This is not called when uploading a user list.