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.

Basic Types

RSL Basic Types

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:

Type	Description	Example
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”

Objects

The Revenium Platform makes it easy to expose API-driven assets as Products that can be modified and charged back within an organization. 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:

• Asset: Asset resources that can be bundled into products. APIs contain the following fields:

  • name: The name of the Asset

  • type: the type of the Asset, which can be one of the following:

    • Asset: The URL of an Asset 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

  • organization: The organization of which the asset belongs to

• **Product: **A collection of assets 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

  • organization: The organization of which the Product belongs to

  • settlementPeriod: How often consumers 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 product licenses 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 settlement 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.)

  • asset: The Asset associated with the API request

  • callCount: The amount of times the Asset has been called in the interval

  • timestamp: The time the asset was called

• User: A person or group of people who use the Revenium Platform. Users in Revenium have the following fields:

  • name: The User's name

  • emailAddress: The user’s email address

• Organization: An Organization represents a group of users and associated assets, Products, Product Licenses, 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.

Authoring Dynamic Pricing Rules

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:

if (lineItem.timestamp.isOutsideBusinessHours()) {
  return 0.0
} else {
  return lineItem.product.baseCost
}code

You can begin authoring your own Dynamic Pricing Rules by navigating to “Manage” and then “Pricing Rules”:

Figure 1.,

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.

Figure 2.

Now you can begin to write a rule and test it by clicking on the “Test” button:

Figure 3.

The Dynamic Pricing Context

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:

The Dynamic Pricing Context

Pricing Rule Test Data

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.

Conditional Expressions

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

if (lineItem.product.organization.name == "AcmeSoft") {
  return lineItem.product.baseCost * 0.80
} else {
  return lineItem.product.baseCost
}

Switch statements can be used for more complicated evaluations:

switch (lineItem.product.organization.name) {
  case "AcmeSoft":
    return lineItem.product.baseCost * 0.80
    break
  case "FooSoft":
    return lineItem.product.baseCost * 0.75
    break
  default:
    return lineItem.product.baseCost
}

Using RSL Convenience Functions

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.	asset, 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 }