Transaction Rule Engine

Objective

  • This module allows the Venture to set up flexible transactions to be applied based on events, conditions, triggers, and rules.
  • The long-term goal is to have all transactions (fees, commissions, cancellations, tier, etc.) in one centralized module and to be able to apply rules with a high-level of granularity.
  • Currently, fees and commissions are built in Seller Center legacy code.
  • Using the Transaction Rule Engine, transactions will be transparent to everyone and can be dynamically adapted and combined within a transaction rule.

 

Critical KnowledgeIf you want to enable Transaction Rule Engine, please raise a TMLSD ticket. The parameters that need to be enabled are transaction_rule_engine/enabled and  transaction_rule_engine_2/enabled.

Also, when you have already enabled transaction_rule_engine/enabled and would like to switch to the modified Transaction Rule Engine, please have the transaction_rule_engine_2_ui_only/enabled configuration parameter set in order to add new transaction rules. After you have finished creating rules, have transaction_rule_engine_2/enabled enabled.

Tab Overview

The Transaction Rule Engine can be found under Administration > Transaction Rule Management.

Transaction Rule Engine consists of Variable Overview and the Transaction Rules Overview:

  • Variable Overview and Transaction Rules Overview:
    • Maintained by Seller Center.
    • As a mid-term goal, this right will be able to transferred to an admin user on the Venture-side.
  • Variable values:
    • Maintained by Venture (e.g., Account Manager).
  • Macros:
    • Used only by Seller Center maintenance team in order to create additional context for new rules.

Variable Overview

In Variable Overview, a user can create a variable that can be used for multiple calculations.

  • This gives the user the freedom to dynamically set values for commissions or fees on Seller-level.
  • Moreover, this way, VAT and WHT rates can be created individually for each Venture or country and can be applied on Seller-level.
  • As a result, VAT and WHT rate calculations can be shown in the account statement and do not need any manual adjustment with an external tool (e.g., Excel files, etc.).

When adding a variable to the Transaction Rule Engine, the following information is required:

  • “Variable Name”: Variable should have a unique name. Please make sure that this variable can be used by several transaction rules. Therefore, make sure that you are able to identify the variable easily.
  • “Label”:  Generated automatically and used to fetch information with variable values.
  • “Description”: A short explanation of the variable
  • “Type”: Defines if a variable value should be generated as a number or as a percentage.
  • “Inheritance Type”: You can define on which level you would like to manage values.
    • “Global”: One global value is applied.
    • “Global + Seller”: You can set a global value and a Seller-specific value.
    • “Category”: You can set global and Seller-specific values on category-level (same logic as the legacy way to set commissions on a category-level).

After defining all fields and clicking “Save Changes,” the variable will be saved and displayed in both Variable Overview and in variable values.

Variable Overview:

1_variable-overview

Create a variable:

1-1_create-a-variable

Transaction Rules Overview

In Transaction Rules Overview, you can create and search for transaction rules. By clicking on a rule name, you are able to see all of its details.

To enable or disable rules simultaneously, do the following:

  1. Click the “Enable” or “Disable” button. Status will change to “Ready to be enabled” or “Ready to be disabled”
  2. Click “Publish changes” button to save changes.

When adding a transaction rule, the following information is required:

  • “Rule Name”: Rule should have a unique name and be as specific as possible in order to simplify the search.
    • Bad example: “Commissions” (too generic)
    • Good example: “Commission for local Sellers for drop shipping orders”
  • “Account Statement Group”: Linked to transaction type and will be shown in account statements. You can find a list with predefined account statement groups. If you wish to create a custom account statement group, please refer to the Account Statement Groups Overview.
  • “Description”: A short explanation of the transaction rule
  • “Outcome”: Defines which type of transaction should be generated. Please make sure that the outcome name is included in your account statement group.
  • “Enable pre-calculation”: Defines whether or not to specify events for transaction pre-calculation.
  • “Pre-calculated on”: Specifies the events that will trigger the pre-calculation.
  • “Events”: It is possible to choose one or multiple events that the transaction should be triggered by.
  • “Condition”: Defines restrictions that have to be fulfilled for the rule to be applied (e.g., FirstDayofMonth && item.ShippingTypeIsDropshipping).
  • “Net Amount Formula”: Defines the calculation that will be generated with the transaction rule before taxes.
  • “VAT Formula”: Calculates a VAT rate using the outcome from net amount formula amount (will be displayed in account statement).
  • “WHT Formula”: Calculates a WHT rate using the outcome from net amount formula amount (will be displayed in account statement).
  • “Add to the latest closed account statement”: The created transaction will be associated with the previously closed account statement and correct the payout (click the link to read more about the feature).

After defining all fields and clicking “Save Changes,” the transaction rule will be saved and propagated in Transaction Rule Overview.

Transaction Rules Overview:

2_transaction-rule-overview

Enable/disable rules:

2-3_tr-overview-publish-changes

Create a transaction rule:

 

 

 

 

 

 

 

Variable Values

In the “Variable Value” tab, you can see a list with variables and edit values by clicking “Edit.” Depending on the inheritance type, you can set values on global or Seller-level, as well as on category-level.

Variable Values Overview:

3_variable-values

Edit values:

3_variable-values_globalseller

Macros

The following tab is only visible to Seller Center’s maintenance team in order to simplify the context/attribute creation process.

When adding a context/attribute, the following information is needed:

  • “Label”: Define a label that will be shown as an option during transaction rule creation.
  • “Type”: Defines a value of the expression.
  • “Description”: A short explanation of created context
  • “Event”: Multiple events can be shown where macro can be used.
  • “Expression”: Code of the macro

Macros Overview:

4_macros

Create a macro:

4_macros_open

Example Macros

Name & Description Expression (example) Order States Type

areAllItemsShippedOrinFinalState

All items are shipped or in final state

reduce( map( order_items, expr(“status in [‘shipped’, ‘delivered’, ‘canceled’, ‘failed’, ‘returned’]“) ), and, true )
canceled, delivered, failed , returend shipped boolean

orderValue

Amount of money within one order

reduce( map( filter( order_items, expr(“‘shipped’ in statusHistory”) ), expr(“unitPrice”)), sum, 0 )
canceled, delivered, failed , returend shipped numbe

itemIsTheFirstOfThePackage

Item is first hitting the targeted status in the package

item_orderItemId in map( map(order_packages, expr(“items[0]“)), expr(“orderItemId”) )
canceled, delivered boolean

Account Statement Groups Overview

In Account Statement Groups Overview, a user can create account statement groups that will be linked to one of the default transaction types.

  • Account statement groups will allow Ventures to create transaction rules in combinations that were not possible before (e.g., two or more rules generating transactions with the same reference and transaction type).

The only constraint for duplication protection is set regarding the account statement group/reference combination: in no case will the rules generate two transactions for the same account statement group/reference pair.

When adding a new account statement group, the following information is needed:

  • “Account Statement Group Name”: Define a custom account statement group name.
  • “Transaction Type”: Choose the transaction type from the default list.
    • This will be displayed for the Seller in the overview and account statement.
  • “Outcome”: Transaction outcome (Credit / Debit), which gets applied to the Account Statement
    • Will be applied for all rules, which use a certain account statement group

After defining all fields and clicking “Save Changes,” the account statement group will be saved and displayed in the list when creating a transaction rule.

Account Statement Groups Overview:

screen-shot-2016-11-15-at-09-51-53

Create a new account statement group:

 

 

 

 

Please do not create more than one account statement group that is linked to a commission transaction type. Only one commission transaction type is supported.

Available Contexts and Attributes

The following context parameters are available within the Transaction Rule Engine:

  • Item: access all item attributes (e.g., item.unit_price, item.shipmentType.isDropShipping, item.shipping_fee)
  • Seller: access all Seller attributes (e.g., seller.id)

The input fields “Condition” and “Calculation” have auto complete suggestions to help the user easily set up the rule.

Transaction rules on order-level can be created by developing order-specific macros. Please contact your PoC at Seller Center to determine the best way to do this.

Matrix of Available Contexts and Attributes

All mentioned contexts and attributes are available for the following order events:

  • “Shipped”
  • “Delivered”
  • “Canceled”
  • “Returned”
  • “Failed”
  • “Imported”

The following table lists contexts or attributes that are only available for a specific event.

The event for “Day of the month (product)” means that there is daily a check in place, to go through all product of a seller to calculate transactions. This is helpfull in case daily storage fees should be applied for fulfillment products.

Context Attribute Description Applicable in the following events:
Item cancelationDate Date of cancellation “Canceled”
cancelationReason

Name of the reason applied for item cancellation

Example: item.cancelationReason == ‘out_ofstock’

“Canceled”
cancelationSource

Source detection regarding where cancellation has been triggered.

Possible options: “internal” / “external”

Example: item.cancelationSource == CancelationSource.Internal

“Canceled”
creationDate Date when order was created (in Seller Center, which means imported from OMS). Should be used in combination with cancelationDate to calculate difference of days. all
commission Commission applied on item-level based on category all
customerShippingFee Customer shipping fee on order item-level all
extendedPromisedShippingTime all
isFreeShipping

Indicator whether shipping costs need to be calculated or not.

Example: item.isFreeShipping == false

all
returnReason

Reason supplied for item return.

Example: item.returnReason: == ‘error-_wrong_product’

“returned”
revenue Paid price or unit price, depending on Seller commission calculation basis all
orderDate Date of order creation (import to Seller Center) all
paidPrice Price per unit after deductions all
paymentMethod Payment method chosen by customer all
promissedShippingTime Promised time when the order will be shipped all
shipmentType Access shipping types validators all
shipmentType.isCrossDocking Whether the item has been shipped by the Seller to the Venture before final delivery to the customer all
shipmentType.isDropshipping Return true if item shipping type is “Drop Shipping”; otherwise, return false all
shipmentType.isOwnWarehouse Indicates whether the item has been shipped to the customer by the Venture using fulfillment stocks. all
shipmentType.shippingProviderType Choose the name of a specific shipping provider. all
shippingDate Date when package was shipped all
shippingServiceCost Numerical value for shipping service costs that is sent from OMS to Seller Center. Value is received from OMS when feature is enabled.  all
taxPercent Percent of VAT + WHT from unit/paid price all
trackingCode tracking code of an order item
unitPrice Price per unit before deductions all
volumetricSize

 Value of package size that is imported from OMS.

Allowed values: “S”, “M”, “L”, “XL”, “OZ”(over size)

Example: item.volumetricSize != VolumetricSize.XL (as XL any of the other options are possible)

all
voucherAmount  Voucher amount that has been applied to the sales order item.
Value is received from OMS
all
hasPromotionVoucher Based on the voucher code this property is checking if the order item is related to a “Promotion Voucher” and will return true or false response all
promotionVoucher.amountFundedBySeller In case the order item is linked to a Promotion Voucher, this property will calculate the amount of the voucher that should be paid by the seller based on the configured percentage distribution in the promotion setup.
It is a total number and by default, it will return zero.
all
 promotionVoucher.amountFundedByVenture In case the order item is linked to a Promotion Voucher, this property will calculate the amount of the voucher that should be paid by the ventures based on the configured percentage distribution in the promotion setup.
It is a total number and by default, it will return zero.
 all
Seller contractType Associated contract type associated with Seller all
creationDate  Date when a seller was registered in Seller Center all
id Seller identification based on short code all
isActive Indicates whether Seller account is active. First day of the month, Day of the month (product)*
isVerified Indicates whether Seller account is verified. First day of the month, Day of the month (product)*
kpi.CancellationRate Cancellation rate calculates the percentage of orders canceledby the seller all
kpi.operationalScore Operational Score which got configured for a seller within the seller settings. Score is provided by the Venture
rating Current Seller rating of the Seller. Value is between 0-5 all
statistics.itemsSold Sum of ([Order items amount created during the last x days] – [Order items created during last x days (amount configurable) that are now canceled]) all
taxClass Default taxation class on Seller-level all
tier Current tier of the seller all
statistics.lastClosedAccountStatement.sales Sales made within the previous account statement period. Account Statement Closed
statistics.lastClosedAccountStatement.deliveryFailedRate Percentage of the items in status “Failed Delivery” to all order items received within the previous account statement period. Account Statement Closed
statistics.lastClosedAccountStatement.returnedRate Percentage of the items that has been returned to all order items received within the previous account statement period. Account Statement Closed
statistics.lastClosedAccountStatement.pendingToReadyToShipIn48hRate Percentage of the items that has been shipped within 48h to all order items received within the previous account statement period. Account Statement Closed
statistics.lastClosedAccountStatement.failedByCustomReasonsRate

Percentage of the items that has been failed/cancelled for custom reasons to all order items received within the previous account statement period.

Please provide IDs of failure reasons that you would like to be calculated in the configuration parameter “statistic / seller/items_failure_reasons”

Account Statement Closed
statistics.lastClosedAccountStatement.commissionPaid Sum of the commission that needs to be paid by the seller in the previous account statement period. Account Statement Closed
Critical KnowledgeIf you want to use statistics context, please create a TMLSD ticket with a request to start gathering and saving the data to the database.
verificationDate Date when a Seller was initially approved/verified by an Admin. all
Date addBusinessDays

Add (or subtracts) days from a date, skipping any holidays or weekends (which are configured for Seller)

Example for checking that more than two business days have passed between the order date and the cancellation event:

Date.resetTime(Date.addBusinessDays(item.creationDate, 2)) == Date.resetTime(item.cancelationDate)

all, Inventory Status Update (product), Inventory Status Update (order item)
resetTime Resets the time values of a date so that date calculation starts at midnight. all
Product currentPrice Current active product price (either price or sale price, depending on the sale price period of the sale price) all
isInSubsidyPlan Check to determine whether a product is part of a subsidy plan or not in order to trigger the according rules
primaryCategory Product is placed within the configured primaryCategory(s). all
price Product price all
sku Only applies for certain / configured product (Seller) SKUs all
specialPrice Sale or special price of a product all
stock Amount of items available for a product all
volumetricWeight Volumetric weight of a consignment product, which is allocated in the Ventures warehouse all
Vars venture specific list of variables All variables that are configured in Seller Center can be used
VolumneSize Constants for various volumne sizes, e.g. S, M, L,XL, OZ all
Inventory status Status of product in OMS inventory state machine Inventory Status Update (product), Inventory Status Update (order item)
uid Unique identifier of single product in warehouse Inventory Status Update (product), Inventory Status Update (order item)
Payment isPayMeNow The source of payment creation is defining if it was an advance payment desired by seller or an automatic one Payment Paid
* The event “Day of the month (product)” means, that the set rule gets triggered on a daily bases.

There are two additional configuration, which need to be enabled, when the events for “Day of the month (product)” should be used.

Configuration “daily/day_passed_event/enabled”, this configuration executes the rule, but no transaction gets triggered.

Configuration “daily/day_passed_event/process_products/enabled”, this executes the rule and the according transactions get triggered.

Available Operators

The Transaction Rule Engine uses an ExpressionLanguage component that support expressions syntax:

Supported Literals

The component supports:

  • Strings: single and double quotes (e.g., ‘hello’)
  • Numbers (e.g., 103)
  • Arrays: using JSON-like notation (e.g., [1, 2])
  • Booleans: true and false
  • Null: null

Comparison Operators

  • == (equal)
  • === (identical)
  • != (not equal)
  • !== (not identical)
  • < (less than)
  • > (greater than)
  • <= (less than or equal to)
  • >= (greater than or equal to)
  • matches (regex match)

Examples:

  • order.items.count >= 5

Logical Operators

  • not or !
  • and or &&
  • or or ||

Examples:

  • Seller.id == 1234 and item.shipmentType.isDropShipping

Array Operators

  • in (contain)
  • not in (does not contain)

Examples:

  • Seller.id in [1234, 5678, 9101]

Numeric Operators

  • .. (range)

Examples:

  • seller.rating in 4..5

Ternary Operators

  • foo ? ‘yes’ : ‘no’
  • foo ?: ‘no’ (equal to foo ? foo : ‘no’)
  • foo ? ‘yes’ (equal to foo ? ‘yes’ : “)

Examples:

  • item.shipmentType.isDropShipping ? 4 : 5

Checklist to Roll Out Transaction Rule Engine

As a long-term goal, we want to move all transactions from the legacy code to the dynamic mechanism of a Transaction Rule Engine. In doing so, we intend to bring the finance areas of our customers to the next level. In order to make a proper roll out, please take the following steps into consideration:

What are the steps to create a rule in the Transaction Rule Engine?

  1. Consider if a transaction rule is based on Seller or order item-level. Please note: if you need order-level rules, please communicate with your Product Manager regarding the proper way to calculate the transaction rule.
  2. Take your time and write all possible business cases for the transaction rule that you want to apply. Different countries often have different logics and require different contexts for the same rule. Therefore, before sending a request to Seller Center, please send possible business cases and the context that needs to be developed (in order to save time and money).
  3. Once the request is sent, the Product Manager will discuss with you whether any development is required.

How do I roll out a transaction rule within my company?

Currently, rules can be set on Seller Center-side. As a mid-term goal, we are planning to give rights to admin users to set variables and transaction rules. It is recommended to use an Excel table to organize the content that is needed for transaction rules. Please ask your Seller Center Product Manager to provide you with a form.

  1. First, add variables that are needed for a transaction rule (if necessary).
  2. Check with your Seller Center Product Manager if any macros need to be added. If so, they will add macros in order to see the macros’ values in the calculation.
  3. Now you can create a transaction rule.
  4. Edit variable values in a separate tab. As an important part of the roll out, make sure that variable values are added properly by an Account Manager. Only when values are edited, you can enable a rule. Therefore, it is recommended to send an Account Manager an email communicating a deadline to add the values.
  5. Once variable values are added, you can enable the rule.

 

Where to see the applied rules

The transactions tables on the database schema will not change. This means that Sellers and Ventures will see all transactions generated by the rule engine in the same place.

In the “Details” column on the Transaction Overview screen, an extra text will be added to indicate that a transaction rule has been generated by the rule engine.

An Example of a details cell:

“Book: Git for dummies, Generated by Rule: ‘New Rule 1, Reference: 4743′”