Key Points When Writing Code

This page provides supplementary information you need when writing code for use in a template.

The SAMRunContext Object

The scenario analysis module passes the SAMRunContext object to your code. This object contains information about the scenario analysis run, and is meant for use in logging.

Within Python, this object is a JSON object with the following properties:

scenarioAnalysisId—Contains the unique ID of this analysis run.
userId—Contains the ID of the username under which the analysis was running.
startTime—Indicates the date and time when the analysis was started.
contexts—A copy of the context object that was passed into the analysis run. This is an array of objects, each of which has the properties parameterName and value. This is the input data needed to analyze the scenario.

Within ObjectScript, this object is a %DynamicObjectOpens in a new tab that has the same structure.

Where available: All code that accepts parameters, except for SQL.

The Snapshot Object

The scenario analysis module also passes the snapshot object to your code. This object is an instance of SC.Core.Analytics.SAM.Data.Internal.Snapshot and contains a snapshot of the data for a specific scenario. Rather than updating the Supply Chain tables directly, use the interface provided by this object to modify the snapshot. Similarly, throughout the scenario analysis, use this object to obtain values from the tables where needed.

Where available: All code that accepts parameters, except for SQL and except for preprocessor code of any kind.

This class provides two methods you can call.

Using the Snapshot to Run Queries

Within the scenario analysis, do not query the database directly. Instead use the Query() method of the snapshot object, which accepts an SQL query and parameters, and which returns the results. Internally, this method rewrites the query so that it runs on the snapshot equivalent, which is how the scenario analysis module keeps each scenario strictly contained.

For example:

   set sql="SELECT quantity FROM SC_Data.ProductInventory WHERE siteLocationId = ? AND productId = ?"
   set params = ##class(%DynamicArray).%New()
   do params.%Push(warehouseId)
   do params.%Push(productId)
   set result = snapshot.Query(sql,params)

Adding Parameters to the Snapshot

Sometimes, additional contextual information is only known during execution, especially when using preprocessors, and is needed in downstream operations. In such cases, you can add parameters by calling the the AddContext() method of the snapshot object. For example:

 do snapshot.AddContext(parameterName, value)

This enables downstream operations to have access to the value.

Logging

The scenario analysis module automatically logs basic activity for every scenario analysis, writing the details to the interoperability Event Log.

Your code should write additional log entries so that you can understand unexpected behavior, debug and troubleshoot your code, and see the actual behavior within transformations and validations. To add custom log entries, use methods of the the SC.Core.Analytics.SAM.Util.SAMLogger class, which provides three class methods:

LogInfo()

ClassMethod LogInfo(SAMRunContext, snapShotId, message)

This method logs an informational message. The arguments are as follows:

SAMRunContext is a %DynamicObjectOpens in a new tab containing information about the context of the scenario analysis run.
snapShotId is the optional ID of the snapshot. This ID is available as the uid property of the snapshot object.
message is the message to write to the log.

LogWarning()

ClassMethod LogWarning(SAMRunContext, snapShotId, message)

This method logs a warning. The arguments are the same as for LogInfo().

LogError()

ClassMethod LogError(SAMRunContext, snapShotId, message)

This method logs an error. The arguments are the same as for LogInfo().

The following shows an ObjectScript example, with an artificial line break for readability:

 do ##class(SC.Core.Analytics.SAM.Util.SAMLogger).LogInfo(SAMRunContext, 
    snapshot.uid, "Starting transformation for warehouse A")

Location of Code

The scenario analysis module expects to find code in specific locations, based on type:

InterSystems IRIS class definitions must be saved and compiled directly in the IRIS instance, and must be available in the same namespace as the Supply Chain production.
BPL business processes, which are class definitions, must follow the above rule. They must also be added to the Supply Chain production and must be enabled.
Python scripts must be in the directory install-dir/mgr/user/SAM/python/namespaceName
SQL files must be in the directory install-dir/mgr/user/SAM/SQL/namespaceName

Create these directories if needed.