Defining a Template
This page describes, at a high level, how to define a scenario analysis template.
In practice, you can divide the work so that template developers design and create the template documents, and other coders write the pieces of code used by the templates.
Overview
To define a scenario analysis template, use the following general process:
-
Identify the general issue that you want to address. For example, this documentation uses an example template that is designed for the scenario in which there is an out-of-stock event.
-
Determine what input data is needed. In our example, we will need the product ID, the ID of the warehouse where the item is out of stock (let’s call this Warehouse A), and the quantity needed for replenishment.
This means that the template will need to receive those three pieces of information as input. When calling the scenario analysis API, your code will pass this information within the context object.
-
Identify the possible general approaches to address the issue. The example template considers two possible approaches to address an out-of-stock event:
-
Moving inventory from another warehouse
-
Placing a purchase order from a supplier
This means that the template has two kinds of transformations: one that adjusts inventory levels and one that places purchase orders.
-
-
For each possible approach, determine the transformation logic. The goal is to create snapshot data that can be validated and then evaluated. This snapshot data simulates a possibility. Later steps will rule out scenarios and evaluate the actual impacts of the remaining ones.
This is best explained by example. For moving inventory from another warehouse:
-
The first step is to identify the warehouses to consider: this should be only the warehouses that have the needed product. The template needs a function that returns a list of warehouses, given a product ID.
-
Then for the actual transformation, the template needs a function that increases the inventory in Warehouse A and decreases it in the other warehouse. The transformation function is applied to each of the warehouses from the previous step. This simulates a transfer of the product.
Similarly, for the approach of ordering from a supplier:
-
The first step is to identify suppliers that sell this product. The template needs a function that returns a list of suppliers, given a product ID.
-
Then for the actual transformation, the template needs a function that creates a PO record for that supplier. The transformation function is applied to each of the suppliers from the previous step.
At the end of the transformation phase, there are multiple scenarios, each with its own snapshot of data.
-
-
Determine all the validation rules that need to be applied for each approach. These validation rules are applied to the snapshot data for the scenarios. In our example, there are two simple validation rules:
-
For warehouses, the warehouse must have enough inventory to satisfy the applicable safety stock requirement for the product. The template needs a function that accepts a warehouse ID and that returns a Boolean value indicating if that warehouse has enough stock to satisfy the applicable safety stock requirement for the product.
-
For suppliers, the supplier must be an active supplier. The template needs a function that accepts a supplier ID and that returns a Boolean value indicating if that supplier is active. A real life-example would also could also check that a supplier is not blocked for some reason.
At the end of the validation phase, there are still multiple scenarios, but not necessarily as many as before.
-
-
Determine the logic needed to compute values (typically, cost impact and time impact) that you can use to compare the scenarios.
-
Determine the rules to use to choose the best scenario. Specifically, given two scenarios with different impacts, how do you determine which is better?
-
Write all the necessary pieces of code.
-
Create the JSON template definition that refers to these pieces of code.
Context Object
When you invoke scenario analysis, you provide the name of the template to use and a context object that contains parameters for the template code to use. The following shows a context object that is suitable as input for the example template presented in this documentation:
[
{ "parameterName": "productId", "value": "Aurora-Protein-Bar-001" },
{ "parameterName": "warehouseId", "value": "ChicagoDC-001" },
{ "parameterName": "requiredQuantity", "value": 120 }
]
Formally, this object is a JSON array of objects. Each object in this array has the following properties:
-
parameterName — Name of this parameter. The example above uses three parameters named productId, warehouseId, and requiredQuantity, but the number and names of the parameters depend upon the business case.
-
value — Value to use for this parameter, within this scenario analysis.
Your solution is responsible for creating this context object, as part of starting the scenario analysis. For example, your code would detect a shortfall of a product at a specific warehouse and would use those specific values to populate the context object.
Template Example
The following shows the example, with artificial line breaks for readability:
{
"name": "Out Of Inventory",
"transformation": {
"name": "Replenishment Strategies",
"rules": [
{
"description": "Move Inventory from Another Warehouse",
"name": "Move Inventory",
"type": "ObjectScript",
"expression": "##class(Transformations.MoveInventory).MoveInventoryFromAtoB()",
"parameters": [
"quantity",
"productId",
"destinationLocationId"
],
"preprocessor": {
"expression": "WarehousePreprocessor.sql",
"type": "SQL",
"parameters": [
"productId"
],
"transformationParameterIdx": 3,
"transformationParameter": "warehouseId"
},
"callAction": "CallActionForMoveInventoryBPL"
},
{
"description": "Order the Product from a Supplier",
"name": "Order Product",
"type": "ObjectScript",
"expression": "##class(Transformations.OrderProduct).PurchaseProductFromSupplier()",
"parameters": [
"destinationLocationId",
"productId",
"quantity"
],
"preprocessor": {
"expression": "##class(Transformations.OrderProduct).GetListOfSuppliers()",
"type": "ObjectScript",
"parameters": [
"productId"
],
"transformationParameterIdx": 1,
"transformationParameter": "supplierId"
},
"callAction": "CallActionForOrderProductFromSupplierBPL"
}
]
},
"validation": {
"name": "Replenishment Strategies Validations",
"rules": [
{
"description": "Check if it has enough inventory to supply and still maintain its own safety stock.",
"name": "Warehouse safety stock check",
"type": "Python",
"expression": "WarehouseValidation.py.CheckWarehouseSafetyStock",
"parameters": [
"warehouseId"
]
},
{
"description": "Check if supplier is approved to buy from.",
"name": "Supplier Check",
"type": "SQL",
"expression": "SupplierValidation.sql",
"parameters": [
"supplierId"
]
}
]
},
"impact": {
"name": "KPIs for out of stock scenarios",
"rules": [
{
"description": "Time to get the inventory",
"name": "Time impact",
"type": "Python",
"expression": "TimeImpact.py.calculateTimeImpact",
"parameters": [
"supplierId",
"productId"
]
},
{
"description": "Cost to get the inventory",
"name": "Cost impact",
"type": "ObjectScript",
"expression": "##class(Impacts.Cost).CalculateCostImpact()",
"parameters": [
"supplierId",
"destinationLocationId",
"productId",
"quantity"
]
}
]
},
"recommendation": "RecommendationOutOfStockRule",
"transformationValidationRulesMapping": [
{
"transformationRuleName": "Move Inventory",
"validationRuleNames": [
"Warehouse safety stock check"
]
},
{
"transformationRuleName": "Order Product",
"validationRuleNames": [
"Supplier Check"
]
}
]
}
Formally, a template is a JSON document that has the following top level elements:
-
name — This is the unique name of the template, to be used when running a scenario analysis.
-
transformation — This is a JSON object that contains an array of transformation rules, each with a callAction.
-
validation — This is a JSON object that contains an array of validation rules.
-
impact — This is a JSON object that contains an array of impact rules.
-
recommendation — This is a string that refers to a BPL business process that will evaluate the scenarios and select one as the recommendation.
-
transformationValidationRulesMapping — This is a JSON object that contains an array of objects, each of which associates one transformation rule with one or more validation rules.
Developing and Deploying a Template
At a high-level, the process of developing and deploying a template is as follows:
-
On your development system, define the template and all code used by the template. Initially the template is just a JSON document.
-
Via the Scenario Analysis API, post the template JSON to your development system, which makes it available for use in the development system. Now you can use it and test it.
-
When the template and all code is ready for use on a production system, export the template, which generates a ZIP file containing the template JSON and all code that it uses.
-
Import the exported template into the production system (or into a intermediate test system, as you prefer).
The Scenario Analysis API includes calls to manage templates, and import and export templates.
