RSL Reference
Revenium Scripting Language (HSL) provides a Low Code environment for Business Analysts, Knowledge Workers, and Developers to author Dynamic Pricing Rules for the Revenium Platform.
Last updated
Revenium Scripting Language (HSL) provides a Low Code environment for Business Analysts, Knowledge Workers, and Developers to author Dynamic Pricing Rules for the Revenium Platform.
Last updated
© Revenium - www.revenium.io
RSL supports 3 main types that drive Dynamic Pricing Rule operations on API transaction data. The following table lists some of the common types encountered when writing Dynamic Pricing Rules:
String
A sequence of characters
“Retail”, “Finance”, “Central IT”
Number / BigDecimal
A decimal number with suitable precision for financial calculations. Note fractional value must start with 0 (ie, 0.10)
1, 1.0, 0.25
Date
A timestamp with a timezone
“Sun Sep 19 18:25:27 EDT 2021”
The Revenium Platform makes it easy to expose API-driven sources as Products that can be modified and charged back within a customer. These concepts are important because they are surfaced as Objects in RSL. Objects are API Monetization specific extensions augmenting Basic Types.
The following is a review of important objects on the platform:
Source: Sources are resources that can be bundled into products. APIs contain the following fields:
name: The name of the Source
type: the type of the Source, which can be one of the following:
Source: The URL of an Source to be metered
API Resource: The full URL of an API along with optional HTTP verbs to be metered.
Stream: An event stream
description: A description of the asset
version: The version of the asset
Customers and Revenium Organizations: The organization of which the source belongs to
**Product: **A collection of sources and, optionally, other products which can be metered. Products contain the following fields:
name: The name of the Product
description: A description of the Product
version: The version of the Product
Customers and Revenium Organizations: : The organization of which the Product belongs to
invoicingPeriod: How often subscribers are invoiced for utilization of the Product.
transactionType: How the product is metered, referred to as Billing Model in the UI. The transaction type can be one of the following values:
Transactional: pay-per-use metering
Subscription: recurring charge for unlimited or quota-based usage for a Product
One-Time Charge: non-recurring charge for unlimited or quota-based usage for a Product
Note that subscriptions were previously known as product keys. The name was changed make their purpose more clear, though they are still referred to as Keys in the API specification.
ProductKey: An entitlement issued to a consumer to gain access to a product. ProductKeys contain the following fields:
name: The ProductKey’s name
description: A description of the ProductKey
key: The unique identifier associated with the ProductKey
owner: The User who owns the ProductKey
organization: The organization of which the ProductKey belongs to
expiration: The expiration date
quota: The quota associated with the ProductKey
quotaConsumed: The amount of the quota consumed by this ProductKey
applications: The ProductKey applications
LineItem: API transactions are recorded as line items which are invoiced based on the product’s invoicing period. A Line Item contains the following fields:
product: The Product associated with the API request
type: The transaction type (transactional, subscription or one-time charge.)
source: The Source associated with the API request
callCount: The amount of times the Source has been called in the interval
timestamp: The time the asset was called
Subscriber: A person or group of people who use the Revenium Platform. Subscribers in Revenium have the following fields:
name: The Subscriber's name
emailAddress: The Subscriber's email address
Customers and Revenium Organizations: An Organization represents a group of subscribers and associated sources, Products, subscription, etc. Organizations can align with Business Units, Teams or other kinds of organizational groupings within a business. Organizations have the following fields:
name: the Organization’s name
description: the Organization’s_ description
Tag: One or more Tags can be added to assets and products. They can be useful for grouping and filtering:
name: the Tag's name
PricingRule: One or more p_ricing rules_ can be added to products and productKeys. They are the other rules already present when the demo rule is being tested.
name: the Pricing Rule name
script: The pricing rule script, a string.
defaultExecutionNote: The pricing rule default execution note.
Application: One or more applications can be added productKeys.
name: the Application name
externalId: The external ID of the application.
productLicenses: The product Licenses of the application.
Dynamic Pricing Rules are RSL scripts that are edited within the Revenium platform. A Dynamic Pricing Rule has one simple requirement, it must return a Number.
Here is an example of a Dynamic Pricing Rule that returns a cost of 0 for an API invoked outside of business hours:
You can begin authoring your own Dynamic Pricing Rules by navigating to “Manage” and then “Pricing Rules”:
Clicking the “+” icon will bring up the RSL editor: From here you can give the Pricing Rule a name, optionally select the Organization it's associated with and finally click on the “Next” button to proceed.
Now you can begin to write a rule and test it by clicking on the “Test” button:
Dynamic Pricing Rules are RSL Scripts that are evaluated when a LineItem is processed. The Dynamic Pricing Context contains the LineItem being evaluated. From this object you can navigate to all of the Objects covered above.
The RSL Editor supplies a Dynamic Pricing Context with Test Data. You can edit this Test Data to experiment how scripts behave within different Dynamic Pricing Contexts:
Objects in the Dynamic Pricing Context can be considered immutable / read-only. Dynamic Pricing Rules only need to return a Number for Revenium to determine the charge.
You can make use of “if..else” and “switch” expressions to conditionally vary pricing for a LineItem.
The following RSL rule will vary pricing based on the name of the Organization owning the Product being invoked
Switch statements can be used for more complicated evaluations:
Revenium Scripting Language has a series of functions that simplify common operations when dynamically pricing API requests.
Function
Description
Target
Example
isBusinessHours()
Evaluated the timestamp of a lineItem and returns true if it’s within business hours or false if not
lineItem
if (lineItem.timestamp.isBusinessHours()) {
return lineItem.product.baseCost * .80
} else {
return lineItem.product.baseCost
}
isOutsideBusinessHours()
Evaluated the timestamp of a lineItem and returns true if it’s outside business hours or false if not
lineItem.timestamp
if (lineItem.timestamp.isOutsideBusinessHours()) {
return lineItem.product.baseCost * .80
} else {
return lineItem.product.baseCost
}
contains()
Checks if a string contains the supplied series of characters.
Any String Field, e.g. name, description.
if (lineItem.api.version.contains("demo")) {
return 0.0
} else {
return lineItem.product.baseCost
}
Date Comparisons
Checks if a date is before or after another date
Any date field such, e.g. timestamp, expiration.
if (lineItem.timestamp > lineItem.productKey.expiration) { return lineItem.product.baseCost * 1.25 } else { return lineItem.product.baseCost }
containsPricingRule( <pricing rule name>)
Checks if the target contains a pricing rule with this name. Returns true if it does, or false if not.
product,
productKey
if (lineItem.product.containsPricingRule("foo")) {
return 0.0
} else {
return lineItem.product.baseCost
}
containsTag(<tag name> )
Checks if the target contains a tag with this name. Returns true if it does, or false if not.
source,
product
if (lineItem.product.containsTag("foo")) {
return 0.0
} else {
return lineItem.product.baseCost
}
containsProduct(<product name>)
Checks if the target contains a product with this name. Returns true if it does, or false if not.
product
if (lineItem.product.containsProduct("foo")) {
return 0.0
} else {
return lineItem.product.baseCost
}
containsAsset(<asset name>)
Checks if the target contains an asset with this name. Returns true if it does, or false if not.
product
if (lineItem.product.containsAsset("foo")) {
return 0.0
} else {
return lineItem.product.baseCost
}
containsApplication(<asset name>)
Checks if the target contains an application with this name. Returns true if it does, or false if not.
productKey
if (lineItem.productKey.containsApplication("foo")) {
return 0.0
} else {
return lineItem.product.baseCost
}
executionNote = "New Execution Note"
Override the default execution note. This note will be recorded with the charge resulting from the pricing rule execution. Later it can be used in invoices to give better context for lineItem charges.
if (lineItem.timestamp.isBusinessHours()) {
executionNote = "Business Hours"
return lineItem.product.baseCost * .80
} else {
executionNote = "Outside Business Hours"
return lineItem.product.baseCost
}
