Custom Form is an action in the Workflow for Transactions, Activities, and Accounts that allows you to run any HTML or JavaScript, and either display it to the user, or run it in the background.

The purpose of the form is to allow calculations that can't be done in the Rule Engine in Pepperi, such as those which don't rely only on data that is available in the Transaction itself (for example data from another transaction, or activity done previously).

Custom Forms should be written by programmers with knowledge of Java Script.

NOTE: If you are running a custom form in the background, you cannot pop up alerts or notification actions. They won't be displayed properly to the user. You can add these as separate workflow actions after the custom form.

For example:

• Track the travel time of a merchandiser between visits.

Use the API to access the previous Visit report and calculate the amount of time that has passed since the previous visit that day. Add this time to the travel time between customers.

• Loop through the cart line by line, and reduce prices according to a discount rule - if you purchased specific items, you get other ones for free.

The eligibility for the free items is checked using the rule engine, however the reduction of the prices of the free items is done by the custom form.

This is a good example that shows how the transaction is built as an object, and then its elements are accessed and modified, such as unit price of each item.

To add a Custom Form action, select it from the list of Actions in the Workflow Transition you require. For example, if you want it to run when the user tries to submit an order in the shopping cart, add it after the "In Creation" Status.

Click on the + Available Fields, to add the fields you require in the JS object.

Let's say you added to the custom form the fields: WrntyID, ActionDateTime, UnitPrice, ItemExternalID (last two are from the Transaction Line fields) and you added 3 items to the cart:

Your Workflow object will look like this:
workflowObject= 
{
WrntyID:11111111,
ActionDateTime:"121231231231231"
TransactionLines:[
{ID:21,"ItemExternalID":"WA50440","UnitPrice":20},          {ID:22,"ItemExternalID":"WA50332","UnitPrice":100},
{ID:23,"ItemExternalID":"WA50295","UnitPrice":90} ]
}

And now you will loop over the cart in the code that was inserted to the custom form, in order to change the prices. The full code for this specific example is attached at the bottom of this article in an html file.

The Custom Form has some built it methods:

• HttpRequest – enables you to call an external data source from the form
• onSaveAndClose() - updated the fields data, close the form and continue with the workflow
• onClose() - close form, continue with the workflow but do not updated the fields data.
• onCancel() - do not continue with the workflow and do not updated the activity fields data (act as when closing the window via Close/Back button).

In the example above, since we want to save the changes to the Pepperi fields, the onSaveAndClose() method is executed after the data is changed.

If things aren't working the way you expected, and you need to troubleshoot your Custom Form use these guidelines: Troubleshooting Custom Forms

Save as File

To use the custom form in another transaction you can save it as a Configuration file. 

Click File

Use existing file - select from files you have already loaded to the Configuration files section as a "Custom Client Form".

Add new file - will automatically create a "Custom Client Form" configuration file and save it in the Configuration Files section. You may then use it again in future forms.

Click Load