Skip to main content

Extension points for Scripting

Under construction

The scripting engine is a work in progress and updates are being introduced regularly. If you've somehow ended up on this page (possibly through a direct link sent to you or a search result) then congratulations, you are now in on one of our roadmap secrets. Let's keep it that way, and we'll make sure to announce it with a bang once it's fully up and running.

On this page we showcase the currently available and supported extension points for scripting.

note

Extesnion points are being added on a regular basis.

Restrict product sales unless elevated

Extension point name: CheckOrderLineValidation

This extension point adds an extra checkout step where a store supervisor/manager approval is prompted on sales of a specific item (OrderLine). The script would be an extension to CheckOrderLineValidation that would script an OrderRequirement and in turn require an employee verification.

The scripted behavior is as follows:

  • POS and Companion will respond to an Employee Verification step needed on a specified OrderLine and initiate an elevation flow.
  • There are two methods to verify an order, either by a QR code scan or a PIN code entry by a user with VerifyOrder rights. After a verification is performed, the regular output of the extension point continues as usual. In our example here, it's the "validate" output.

Sample script

{ Name = "Verify orderline",
Dialect = "Extension",
IsActive = true,
Source = "extend CheckOrderLineValidation

set validate to false

if OrderLine.Product.BackendID = 'PRODUCT_1' then
set validate to true
end

if OrderLine.IsVerified then
set validate to false
end

output validate"
}

Whereas,

Name is string,
Dialiect is the “extension”,
IsActive is a boolean,
Source is as shown above.

Things to consider for this scenario

If you want the VerifyOrder elevation to be via Pin code then the setting Security:ElevatedFunctionalityProvider should be set with a value TemporaryElevationCode. In POS App a user can find the pin code in Generate elevation code and on Companion App it's under the information chapter. Further, you can specify the validity period of such Pin code using the setting Security:TemporaryElevationCode:ExpireInMinutes (default validity period is 20 hours if setting left untouched).

Restrict order returns unless elevated

Extension point name: CheckOrderLineValidation

This extension point adds an extra checkout step where a store supervisor/manager approval is prompted on return of a specific item (OrderLine). The script would be an extension to CheckOrderLineValidation that would script an OrderRequirement and in turn require an employee verification.

Sample script

{ Name = "Verify orderline",
Dialect = "Extension",
IsActive = true,
Source = "extend CheckOrderLineValidation

set validate to false

if Order.HasReturnLines then
set validate to true
end

if Order.IsVerified then
set validate to false
end

output validate"
}

Incentive upon subscription

Extension point name: GenerateUserDiscountCoupon

This extension point adds an extra step to a coupon discount action where a newly subscribed/added user (in this scenario a customer) would receive a welcome gift in the form of a discount coupon if certain custom user field requirements are met.

The scripted behavior would be an extension to GenerateUserDiscountCoupon and would script a discount BackendID that would pertain to the coupon.

note

A discount with a trigger type Coupon should already be configured on the organization unit in order for this to work. The BackendID of which should be used here as your input.

The script can expose the following variables:

  • FirstName
  • LastName
  • EmailAdddress
  • Nickname
  • Username
  • CustomField (generic, allows access to all custom fields of the user)

Sample script

{ Name = "Generate user discount coupon",
Dialect = "Extension",
IsActive = true,
Source: "extend GenerateUserDiscountCoupon

set discountBackendID to ''

if User.CustomFields = 'ExpectedValue' then
set discountBackendID to 'DiscountABC123'
end

output discountBackendID"
}

Here is a filled sample:

 {  "Name": "Generate user discount coupon",
"Dialect": "Extension",
"IsActive": true,
"Source": "extend GenerateUserDiscountCoupon set Generate_a_coupon to 'false' if User.CustomFields.CatsDogs = 'Dogs' then set Generate_a_coupon to 'true' end output Generate_a_coupon"}

If you want the script to check if a coupon was already generated, then it would look like this:

{ Name = "Generate user discount coupon",
Dialect = "Extension",
IsActive = true,
Source: "extend GenerateUserDiscountCoupon

set discountBackendID to ''

if User.CustomFields = 'ExpectedValue' then
set discountBackendID to 'DiscountABC123'
end

if ExtensionInformation.GeneratedCouponCount > 0 then
set discountBackendID to ''
end

output discountBackendID"
}

Discount financial implications

Extension point name: DiscountFinancialDispersion

note

This script has no impact on discount actions Get a product, Other costs, Pick a product, Custom field discount (except for value determined ones), and Generate a coupon, since financial implications are not applicable to such actions.

This Extension Point allows you to create a customized discount financial dispersion behavior. One that is different from the default inputs made under the Discount actions Financial implications card. Namely, the inputs made under the fields Distribution type and Products to consider (if applicable to the chosen action).

For the sake of terminology clarity:

  • Distribution type: Will be referred to as FinancialDispersionType.
  • Products to consider: will be referred to as ProductActionFinancialDispersionType.

By opting to use a script for this (ticking the Use script when applicable box found under the Financial implications card), you're basically empowered to customize the behavior of those two fields if certain variables apply. The extension point currently supports the following variables only:

  • User custom fields
  • Order custom fields
  • DefaultFinancialDispersionType: this is the configured input on the discount.
  • DefaultProductSetFinancialDispersionType: this is the configured input on the discount that is applicable for Discount action Product sets only.

Once ticked, you will be presented with a dropdown list of created/existing DiscountFinancialDispersion scripts. In other words, the dropdown list will display the ListScripts response, filtered on dialect extensions with a name DiscountFinancialDispersion, which is the underlying extension point for this scripting scenario.

Sample script

 {  "Name": "DiscountFinancialDispersion",
"Dialect": "Extension",
"IsActive": true,
"Source": "extend DiscountFinancialDispersion set financialDispersion to DefaultFinancialDispersion set productDispersion to DefaultProductSetFinancialDispersion if User.CustomFields.InputHere = 'ExpectedValue' then set financialDispersion to 0 set productDispersion to 0 end output financialDispersion, productDispersion"}

What is being attempted from the above script is that if a user custom field "X" is = to an 'Expectedvalue', then default FinancialDispersion and default ProductActionFinancialDispersionType would be overridden to 0 and 0 instead of their respective default inputs. The available enum values for FinancialDispersion and ProductActionFinancialDispersionType can be found here.

note

A valid script return would always override the default dispersion input(s).

We can also derive from the above sample script that the service return would be an integer array. This corresponds well to action(s) that support both financial and product dispersion, as the case is with the Product sets action. The return however, can also be a single integer. This corresponds well to action(s) that only support a financial dispersion, as the case is with the Order discounts action.

Script returns validation

Some discount actions expect an integer array return and some single. But what if an integer array is returned by the script while only a single integer was expected?

Single integer returns


Discount actions that only require a single integer return from the script, will not fail if an integer array is returned. The extra integer will be ignored.

Let's assume that an underlying discount action required only a FinancialDispersionType to be defined, and that the default input for it was set to 0:

  • Script returns 1

Implication:

FinancialDispersion is set to MostExpensiveToCheapest 1 (Name on frontend: Most expensive first) instead of the default input value of 0.

  • Script returns 1.1

Implication:

FinancialDispersion is set to MostExpensiveToCheapest 1 (Name on frontend: Most expensive first) instead of the default input value of 0
Second value is ignored.

  • Script returns 9.1

Implication:

FinancialDispersion will remain 0 (the default input value) because the returned script value is invalid (9).
Second value is ignored

  • Script returns 1.9

Implication:

FinancialDispersion is set to MostExpensiveToCheapest 1 (Name on frontend: Most expensive first) instead of the default input value of 0
Second value is ignored

Array integer returns


Discount actions that require an integer array return from the script (both a financial and a product dispersion), will not fail if a single integer is returned (financial dispersion only). The missing integer pertaining to ProductActionFinancialDispersionType will revert to the default configured input.

Let's assume that an underlying discount action required both a FinancialDispersion and a ProductActionFinancialDispersionType configured, and that the default inputs were set to 0 for both.

  • Script returns 1

Implication:

FinancialDispersion is set to MostExpensiveToCheapest 1 (Name on frontend: Most expensive first)
ProductActionFinancialDispersion remains unchanged. The default value configured on the discount action applies (in this example it would mean AllProductsInSet 0 (Name on frontend: All products in action)

  • Script returns 1,1

Implication:

FinancialDispersion is set to MostExpensiveToCheapest 1 (Name on frontend: Most expensive first)
ProductActionFinancialDispersion is set to AllDiscountableProductsInSet 1 (Name on frontend: All discountable order lines)

  • Script returns 9,1

Implication:

Both FinancialDispersion and ProductActionFinancialDispersion remain unchanged since the FinancialDispersion return value of 9 is invalid. In this example it would mean that both would remain at their default values configured of 0.

Financial and Product Dispersion enum values


The following table represents the enum values pertaining to FinancialDispersionType and ProductActionFinancialDispersionType. Those values are used when creating a discount financial implications script under the `Source` property.
FinancialDispersionType
{
DivideInProportionToProductPrice = 0,
MostExpensiveToCheapest = 1,
CheapestToMostExpensive = 2,
HighestToLowestTaxRate = 3,
LowestToHighestTaxRate = 4
}
ProductActionFinancialDispersionType
{
AllProductsInAction = 0,
AllDiscountableProducts = 1,
AllNonDiscountableProducts = 2,
AllDiscountableOrderLines = 3
}
note

ProductActionFinancialDispersionType naming on frontend may slightly differ.

Event export

Extension point name: EventExport.

note

This script currently only supports event exports with target Order.

This Extension Point allows you to create a customized event export that would only perform an export if certain filter(s) are matched. This basically means that you can now create filter(s) which you can then specify within the script, and only if that is matched, would the event export be performed and sent to an endpoint of your choice based your event export configuration.

  • The script which will filter your event export configurations, is fed to the event properties, and in case of an event with Target Order, then it would be fed to order properties as well.
  • The script returns a boolean if an event should be exported. So, a return true if you want this exported, and false if not. It's as simple as that.

The script is only executed if all other filter parameters match, and thus making it an additional compounded requirement before exporting. Returning nothing or something else from this script, will skip the requirement, and thus end up exporting.

Sample script

{
"Name": "EventExport",
"Dialect": "Extension",
"IsActive": true,
"Source": "extend EventExport set export to false if Order.Type = 'Sales' then set export to true end output export"}

Your last step to link this script to your event export would be to take the response ScriptID and place it in the ScriptID property of CreateEventExportConfiguration service or UpdateEventExportConfiguration.

User Task Priority

Extension point name: UserTaskPriority.

This Extension Point allows you to create a dynamic user task priority which means that you can take in a user task or a user task model as input(s), and return a new priority for that task. The returned priority is a number and would be based on your existing user task priorities scale setup.

note

The script runs after a user task has been created.

Sample script

    "Name": "UserTaskPriority",
"Dialect": "Extension",
"IsActive": true,
"Source": "set priority to null if StartTime has value `` then set priority to 1234 end output priority"}

Generate Order line Cancellation Discount Coupon

Extension point name: GenerateOrderlineCancellationDiscountCoupon

This Extension Point allows you to send a coupon when customer order lines have been cancelled for whatever reason (ex: out-of-stock, delivery issues, etc...). It is a promotion that is mainly built as a sort of compensation to the incident of having cancelled line(s) on a customers order.

The extension point has the following data available:

  • Order

  • Orderlines

  • User

  • FullOrderCancellation

  • CancelledLines

    • OrderLineID
    • AlreadyCancelledQuantity
    • CurrentCancelledQuantity
    • FullLineCancellation

    Outcome of the script is a DiscountBackendID on which two things are generated:

    • A discount coupon - sample script and details below
    • A discount coupon event - more on this can be found under Event Exports namely, EventExportTarget 19 "Coupon".

Sample script

{
"Name": "GenerateOrderlineCancellationDiscountCoupon",
"Dialect": "Extension",
"IsActive": true,
"Source": "extend GenerateOrderlineCancellationDiscountCoupon set DiscountID to '' for each CancelledLine in CancelledLineStates do if CancelledLine.CancellationQuantity > 0 then set DiscountID to 'coupon_cancel' end end output DiscountID"}
}

DiscountID "coupon_cancel" specified in the above sample, is the DiscountBackendID for a discount with trigger type Coupon we have set up. This should of course be adjusted based on your respective DiscountBackendID with trigger type Coupon.

Settings
  • It is possible that cancellation of lines happen at various moments of an order flow therefore, a setting called OrderLineCancelled:CustomerInteraction:Timeout can be used to determine the waiting time before a count starts to determine the quantity of cancelled orders. This setting is mainly used to avoid having multiple coupons issued for an order where multiple order lines become cancelled at different moments. The value of this setting is by default set to 10 minutes. The values specified should be in seconds.
  • A setting called OrderLineCancelled:GenerateCoupon needs to be set to true in order for the script to work and actually generate the desired coupon.
  • The CouponCode is then included as a string that is exposed in the root of the OrderLineCancelled stencil.

Orders Monitor

Extension point name: OrdersMonitor

This Extension Point allows you to create advanced order monitors where the script verifies if an order is applicable for monitoring or not.

It can be set up by specifying the desired order property that you would then wish to monitor.

Below are two sample order monitor scripts. These scripts include order returns that were returned using cash as payment method and a script which shows refunds which failed in your orders monitor results on Admin Suite:

Sample scripts

{
"Name": "OrdersMonitor",
"Dialect": "Extension",
"IsActive": true,
"Source": "extend OrdersMonitor set includeInResult to false if HasReturnLines = true then for each item in PaymentTransactions do if item.Description = 'Cash' then set includeInResult to true end end end output includeInResult"}
}