1 Innoslate Simulators
Innoslate’s discrete event and Monte Carlo simulators require little scripting for most applications. The logic execution uses the decision points and Input/Output (I/O) triggers for basic problems, but for more complex simulations you will want to learn how to add scripts, which will range from minimal to complex.
For adding to Innoslate scripts, note the use of “let” to define a variable. Innoslate script allows either “let” or “var” to define variables. Comments can also be added using two backslashes (//). Also “print()” statements can easily be added. These statements print to the Innoslate simulator console.
The OR and LOOP decision points (special cases of the Action) already come with pre-built scripts (Probability and Resource for both and Iterations for the Loop). These can be used without any scripting on your part. Just select the script type you want, adjust the values, and submit the script, then we generate the script automatically. The code behind each decision point’s script type can be accessed by selecting ‘Script’ from the drop-down menu. An example of each is shown in the later sections below.
3 Pre-Built Scripts
3.1 OR Script
3.1.1 OR Probability
The user selects “Or Probability” from the drop-down menu, as seen in Figure.2, then the user can adjust the branch probabilities, in this case making Yes be 70% of the time and No being 30%.
The script that is generated is shown in Figure 3. Note that the comment line at the top contains the information shown in the user interface above. The comment list each branches ID number with its corresponding assigned percentages. If changes are made it is recommend to either update assigned percentages or delete it.
3.1.2 OR Resource Script
The Or Resource script will use Resource entity attributes such as its Amount to be set and used as a condition for the Or Resource script. A Resource entity must be created first and available in the database. The branch options include logical constructs and values. Figure 4 shows the user interface for the Or Resource script.
These options will be used to compare to the Resource amount at the time the script is executed. Figure 5 shows the resulting script from this selection. Note that the Global ID is usedfor getting the Resource from the database (using the Rest API: Sim.getAmountByGlobalId()). More on this provided in the Advanced Simulator Scripting section.
3.2 Loop Script
3.2.1 Loop Probability
Loop Probability will be based on the percentages set by the user. In Figure 6, we changed the default probabilities from 50/50 to 80/20 between the Continue and Exit branches.
Figure 7 shows the generated script. The script in Figure 7 allows simulator to stay in the Continue branch because of the condition, “r <= 80”. If the condition is not met the simulator will leave on the Exit branch.
3.2.2 Loop Resource
The Loop Resource is similar to the Or Resource except the condition is based on the Resource except condition is based on the Resource is based on the Resource's amount value. Figure 8 shows the user interface for the Loop Resource.
Figure 9 references the Resource construct in the script by using the REST API, “ Sim.getAmountByGlobalId()”, and Resource’s Global ID.
3.2.3 Loop Iteration
The Loop Iteration script allows to user to tell the simulator amount of times the loop should run. Figure 10 shows the Loop Iterations user interface. We changed the number of iterations from the default value of 3 to 10.
Figure 11 shows the resulting script. Note that the “i” variable is initialized to zero outside the function and then “i” is incremented each time this function is called.
It is recommended to start with these if you are building a new script, as it will often be easier to get the exit branch identifier automatically. Note that the branch identifier is not essential for the script and if you want to reuse (copy and paste) the script into other Actions/Decision Points, then you will want to eliminate them.
One more common situation is the need to make sure that decision points are synchronized with other decision points. The next section discusses this situation.
4 Synchronizing OR Decision
Often we need to make sure that when a decision is made by one Asset that another Asset uses that decision to go down a particular path. We can see this in the example below in Figure 12.
In this diagram, the first asset makes a decision using a standard probability script. We want the second asset to respond to that decision and go down a similar path. For this to execute properly, we need to trigger the second decision point from the first, i.e. to ensure that the second decision point does not try to execute at the same time as the first one (which it would do without the “Decision” Input/Output entity.
Figure 13 shows the first decision point [Decide? (Asset #1)], where it starts with the standard probability script. Then we added the “globals.set” and “print” lines.
For Asset #2’s OR script (Figure 14), then we get the global variable and use it instead of the probability to make the decision. We also added print statements to show it went down the correct path.
The results for a yes decision are shown in Figure 15.
The results for a no decision are shown in Figure 16.
5 Advance Simulator Script using API
The simulator has a scripting API (Sim) to allow user to gain access to data contained in the model being executed. To use many of these APIs, you need to provide the Global ID or project-level ID. These IDs can be found when selecting an entity in the Metadata tab on the sidebar.
Sim is a utility class that references methods used to access simulation objects during simulation. Table 1 identifies each of the functions available in the Sim API and what they return.
Note that the table below is missing two methods:
These objects include:
- Entities (Actions, Resources, I/Os, Conduits, Assets, Cost)
- Current Time
- http Request
You can use these functions to get the names, numbers, descriptions, and any other related attributes of any of the entities available within the simulation. The entities are limited as the simulator only loads information on the entity classes listed above. The example below shows how to use these functions for Cost and Time. Figure 17 shows Actions that incur Costs. The picture shows a simple Action Diagram with two Actions.
The Action Diagram in Figure 17 shows the incurs relationship and Cost entities for each Action. If you add the script in Figure 18 into the Action diagram and then execute it, you will see the results in Figure 19.
5.1 Using Resources in Simulators
Figures 4&5 and 8&9 showed the predefined scripting capabilities in the OR and LOOP actions. These figures show how the pre-built scripts access the current amount of Resources identified by their GlobalIDs. These IDs are found in the Metadata tab of the entity view on the Action Diagram side bar for the Resource, as seen in Figure 20. The scripts are able to be manipulated via user defined scripts of an action and then plotted during the simulation.
Important information about attributes of a Resource:
Figure 20. Resource Entity View
Value of Resource not being between Minimum and Maximum Amount will cause simulation to dead lock (break).
Relationships created between Actions and Resources allow for Pre-Defined Scripting to:
- produces Resources
- consumes Resources
- seizes Resources
Either the produces or seizes relationship can be selected when you drag from a green circle on a highlighted Resource onto an Action, an overlay of the two options will be provided. If you select seizes the Resource icon will turn a lighter purple and the lines will have a “seizes” label. Figure 21 shows an example of the produces relationship. Click on each Action Entity and go to ‘Relationships’ on side panel, find ‘produces’ relationship and define amount to produce.
Figure 23 shows the results from the simulation. The consumed amount of the Resource is permanently taken away from the Resource, while seized amount only takes away from Resource during an Action’s duration.
Scripts can also be developed to change resources, with or without the Resource being directly associated with the Action. Figure 24 shows an example of this capability.
For this example, we had the Action produce 20 units (remember units are arbitrary and must be consistently set) of the Resource using the attribute on the produces/produced by relationship. The scripts for the Actions are shown in Figure 25.
The resulting simulation output is shown in Figure 26. Note that the produces relationship incrementing of the Resource occurs before the execution of the onEnd() script. So the net effect of the first script is to reduce the amount to 10 units from the original 20. The second script reduces the amount of the Resource by another 5 units.
5.2 Using Scripts Prompts
The Innoslate simulator can help conduct tabletop exercises, develop standard operating procedures, and Concepts of Operations. These applications simulate how users may respond to different events and how the system reacts to the user’s input. As such, scripts to prompt the user for input have also been provided. Table 2 shows the prompt script methods and their purpose.
Note these prompts may only be used with the discrete event simulator. If these prompt are enabled during a Monte Carlo simulation the user will receive an error message.
An example of using this prompt is shown in Figure 27. The prompt method automatically returns the “response” variable to the script, so that the user only needs to use the onEnd(response) function call.
6 Advance Simulator Scripting Using 'Inno' API
The “Inno” APIs consist of the following methods: InnoObject, InnoEntity, InnoAttributes, InnoSimulation, InnoRelationships, and InnoLabels. These methods can only be used with the entity classes directly related to the instances included in the simulation. They cannot manipulate other classes within the database, such as Risk, Time, Measures, etc. Any changes to the attributes, relationships, and labels are only temporary and contained within the simulation. This limitation is a security feature that makes database corruption impossible. It also is essential for cyber security in a cloud environment. To make database changes, you can use the general JavaAPIs with the Enterprise version of Innoslate.
The following subsections discuss each of these methods and usage.
6.1 InnoObject Methods
InnoObject methods enable the user to get and set most of common attributes of any object (Name, Description, Created and Modified Dates, etc.). Table 4 shows these methods and their return values.
Table 4. InnoObject Methods
|getCreated()||Creation time in milliseconds|
|getCreatedBy()||User that created the object|
|getDatabase()||Database for current entity|
|getDescription()||Description text of object|
|getDescriptionAsText()||Strips out special characters and formatting|
|getGlobalID()||Global ID of the entity|
|getId()||ID of the entity|
|getModified()||Modified time in millliseconds|
|getModifiedBy()||User that last modified the object|
|getName()||Name of the object|
|isHidden()||Determines if object is a hidden object|
|isLocked()||Determines if object is locked|
|setDescription( text)||Updated entity description|
|setHidden( hidden )||Sets object as hidden|
|setLocked( locked )||Sets the locked state of object|
|setName( name )||Updated entity name|
An example of using some of these methods is shown in Figure 28. The results of the simulation are shown in the Console panel in the figure.
6.2 InnoEntity Methods
InnoEntity methods enable the user to get and set most of common attributes and properties of any class entity (Number). Table 5 shows these methods and their return values.
Table 5. InnoAttribute Methods
|setInnoClass( name ),|
setInnoClassByName( name )
|setInnoClassById( id )||Entity Object|
|hasChanged()||Boolean: true || false|
|instanceOf( name ), |
instanceOfByName( name )
|Boolean: true || false|
|instanceOfById( id )|
|setNumber( number )||Entity|
An example of using some of these methods is shown in Figure 29. The Console panel shown in this diagram shows the simulation results for the first three actions.
6.3 InnoAttributes Methods
InnoAttributes methods enable the user to get and set any attributes of any object. Table 6 shows these methods and their return values.
Table 6. InnoAttribute Methods
|all()||id: attribute value of all attributes|
|get( name ),|
getByName( name )
|String||id: attribute value|
|getById( id )||Integer||id: attribute value|
|getByProperty( property )||InnoProperty||id: attribute value|
|set( name,value ), |
setByName( name,value )
|setById( i d,value )||Integer, String||InnoEntity|
|setByProperty( property,value )||InnoProperty, String|
An example of using some of these methods is shown in Figure 30. The Console panel shown in this diagram shows the simulation results for these actions.
6.4 InnoSimulation Methods
InnoSimulation methods enable the user to get and set simulation scripts. This capability would enable the user to create different scripts for execution within the simulation. Table 7 shows these methods and their return values.
Table 7. InnoSimulation Methods
|getScript()||String of the script|
|getScript( script )||String|
An example of using some of these methods is shown in Figure 31. The Console panel shown in this diagram shows the simulation results for these actions.
6.5 InnoRelationship Methods
InnoRelationship methods enable the user to get and set relationships between entities. Table 8 shows these methods and their return values.
Table 8. InnoRelationship Methods
|add( relationName, target ), addByName( relationName, target )||Entity|
|addById( relationId, target )||Entity|
|addByRelation( relation,target )|
|allLazy()||Array of all InnoEntity related to Entity|
|allTargetIds()||all IDs of related Entities|
|allTargetIdsMap()||Map of IDs|
|allTargets()||Array of InnoEntity objects|
|get( name, target ),|
getByName( name, target )
|EntityRelationship object if exist, or false|
|getById( id,target )||EntityRelationship object if exist, or false|
|getAndRemove( name,target )||EntityRelationship object if exist, or false|
|remove( relationship )||True if successful|
|anyByIdLazy( id )||Array of InnoRelations|
|anyLazy( name ),|
anyByNameLazy( name )
|Array of InnoRelations|
|anyTargetIds( name )||IDs of related Entities|
|anyTargetIdsById( relationId )||IDs that have given relationship with|
|contains( relationship )||Boolean|
|containsAnyById( id )||Boolean|
|containsById( relationId, target )||Boolean|
|containsByName( relationName, target )||Boolean|
|countAny( relationName ),|
countAnyByName( relationName )
|countAnyById( id )||Integer|
An example of using some of these methods is shown in Figure 33. The Console panel shown in this diagram shows the simulation results for these actions.
6.6 InnoLabel Methods
InnoLabel methods enable the user to operations to add, remove, and check for labels. Table 9 shows these methods and their return values.
Table 9. InnoLabel Methods
|add( label )||InnoLabel||InnoEntity|
|addByName( id )||Integer||InnoEntity|
|addByName( name )||String||InnoEntity|
|all()||label id: InnoLabel pairs|
|contains( label )||InnoLabel||Boolean|
|containsById( id )||Integer||Boolean|
|containsByName( name )||String||Boolean|
|ids()||array of label IDs|
|remove( InnoLabel )||InnoLabel|
An example of using some of these methods is shown in Figure 34. The Console panel shown in this diagram shows the simulation results for these actions.
7 Using I/Os
We have already seen how Input/Output entities are used to control the sequencing of the Actions as a trigger. With version 4.5, a “Value” attribute was added to act as a variable in the simulation. This attribute allows information transfer to be more visual in the simulation, instead of just using global variables in the script. The value attribute is a text string and can be encoded with any data type. To access the Value attribute, you can use the Sim.getIOValueByNumber(), Sim.getIOValueById(), and Sim.getIOValueByGlobalId() methods for the “Sim” API. To set the I/O value, you will still need to use the InnoEntity methods discussed above. An example is provided below.
7.1 Using Basic I/O API
I/O can be used to store and retrieve values using the I/O construct. The I/O construct uses following "Sim" API found in the Table 10.
Table 10. I/O Sim APIs
|Method||Input Value||Input Type||Return|
|Sim.getIOValueByNumber()||Entity's Number Attribute||String||Entity Attribute Value|
|Sim.getIOValueById()||Entity's ID||Integer||Entity Attribute Value|
|Sim.getIOValueBYGlobalId()||Entity's Global ID||integer||Entity Attribute Value|
There is two ways to retrieve the I/O value and it's based on whether the entity has a trigger or not.
If an I/O has the following relationship used:
- "generated by"
- "received by"
The I/O will be a trigger for the entity with the "received by" relationship. An example of using some of these methods is shown in Figure 35. The Console panel shown in this diagram shows the simulation results for these actions.
If an I/O has only one relationship used :
- "received by"
The I/O will need to set to 'optional' and these can be done by going to I/O "received by" relationship and turning the trigger field into "No" as seen in Figure 36. By doing this it will avoid a deadlock when the simulation runs.
An example of using some of these methods is shown in Figure 37. The Console panel shown in this diagram shows the simulation results for these actions.
Another use of the I/O is to set value and retrieve it for later use. To set a value for an IO is to assign a variable using the API and storing a new value using "attributes().set()". An example of using some of these methods is shown in Figure 38. The Console panel shown in this diagram shows the simulation results for these actions.
7.2 Using Advanced I/O API
In section 7.1, provides the basic for setting and getting the IO entity value. These section will show how a user can set and get IO values from a decomposed parent diagram. This done by making the I/O entity traced to the action entity prior to decomposing that entity. It will ensure the same IO is passed to its child entity.
To set the IO value, the user will need to handle that script in the child entity. An example of using some of these methods is shown in Figure 39. The Console panel shown in this diagram shows the simulation results for these actions.
Once the IO value is set by the child entity that IO value can be passed and used in the parent diagram. The user will need to make sure the IO is a trigger in the parent diagram to allow the value to be used. An example of using some of these methods is shown in Figure 40. The Console panel shown in this diagram shows the simulation results for these actions.