Scenario

insight.ready(function () {
 // Get the Insight View.
 var view = insight.getView();

 // Listen to the selected scenario(s).
 // In this case the first scenario in the view selection is listened to.
 var observer = view.withFirstScenario();

 // listen for changes to the data in entities A, B, C
 // also called on view startup
 observer.withEntities('A', 'B', 'C')
    .notify(function (scenario) {
        // when this function is called you have access to the requested scenario(s)

        // an example of how to call a method on a scenario.
        var name = scenario.getName();
    });

 // Start listening to the observed scenarios and render the view.
 view.start();
});

Method summary

Methods

cancel ( ) → {Promise}

Cancel any execution of this scenario.

Returns:

Type	Description
Promise	promise, resolves when the scenario is successfully cancelled, or the scenario is not in the execution queue

Example

var cancelledPromise = scenario.cancel();

cancelledPromise
     .then(function () {
         // at this point scneario has been cancelled.
     })
     .catch(function (err) {
         // scenario failed to cancel
     });

Back to Top

createAttachment ( options ) → {Promise}

Create a new scenario attachment.

Parameters:

Name	Type	Argument	Description
options	NewAttachmentOptions	optional

Returns:

Type	Description
Promise	Resolves when user closes the editor or if attachment create fails

Example

scenario.createAttachment({filename: 'my_file.xml', tag: 'atag'})
        .then(function(data) {
            console.log(data.attachment);
        });

Back to Top

downloadAppAttachments ( attachments ) → {Undefined}

Downloads the attachments specified in the attachments parameter.

Parameters:

Name	Type	Description
attachments	Array.<Attachment> | Array.<String>	Either an array of attachment IDs or an array of attachments

Returns:

Type	Description
Undefined

Example

scenario.downloadAppAttachments([attachment1,attachment2]);
scenario.downloadAppAttachments([attachment1.getId()]);

Back to Top

downloadScenarioAttachments ( attachments ) → {Undefined}

Downloads the attachments specified in the attachments parameter.

Parameters:

Name	Type	Description
attachments	Array.<Attachment> | Array.<String>	Either an array of attachment IDs or an array of attachments

Returns:

Type	Description
Undefined

Example

scenario.downloadScenarioAttachments([attachment1, attachment2]);
scenario.downloadScenarioAttachments([attachment1.getId()]);

Back to Top

execute ( executionMode, options ) → {Promise}

Submits this scenario for execution, either to load the input data of a scenario, or to run it.

Parameters:

Name	Type	Argument	Default	Description
executionMode	string	optional	insight.enums.ExecutionType.RUN	the mode of execution to perform
options	Object	optional		execution options Properties Name Type Argument Description suppressClearPrompt boolean optional  whether, on using an execution mode that clears input data, to suppress the confirmation prompt

Returns:

Type	Description
Promise	promise, resolves when the scenario is successfully queued for execution

Example

var runPromise = scenario.execute(insight.enums.ExecutionType.RUN, 'SLOW');
runPromise
     .then(function () {
         // scenario has been queued for execution
     })
     .catch(function (err) {
         // scenario could not be executed.
     });

Back to Top

findAttachment ( filename ) → {null|Attachment}

Searches for an attachment with the given name on the scenario and the app. If an attachments with the given name is found on the scenario, it is returned without searching the app. If no matching attachment is found on the scenario, the app is searched.

Parameters:

Name	Type	Description
filename	string	the filename of the attachment to return

Returns:

Type	Description
null | Attachment	the found attachment or null if not found

Example

var attachment = scenario.findAttachment('sales-report.txt');

Back to Top

findTaggedAttachments ( tags ) → {Array.<Attachment>}

Searches for tagged attachments on the scenario and the app. If any attachments with the given tag or tags are found on the scenario, they are returned without searching the app. If no matching attachments are found on the scenario, the app is searched.

If no tags are passed in, all scenario attachments with any tag are returned, and if the scenario has no tagged attachments, the app is searched in the same way.

Parameters:

Name	Type	Argument	Description
tags	string | Array.<string>	optional	The tags to search for

Returns:

Type	Description
Array.<Attachment>	An array of Attachment objects

Example

var taggedAttachments = scenario.findTaggedAttachments('tag1');
var taggedAttachments = scenario.findTaggedAttachments(['tag1', 'tag2']);

Back to Top

getAppAttachment ( filename ) → {null|Attachment}

Return a single app attachment that matches the given filename.

Parameters:

Name	Type	Description
filename	string	the filename of the attachment to return

Returns:

Type	Description
null | Attachment	A single attachment object or null if not found

Example

var attachment = scenario.getAppAttachment('sales-report.txt');

Back to Top

getAppAttachments ( ) → {Array.<Attachment>}

Returns all the file attachments on the app.

Returns:

Type	Description
Array.<Attachment>	An array of Attachment objects

Example

var appAttachments = scenario.getAppAttachments();

Back to Top

getAppId ( ) → {string}

The ID of the app this scenario belongs to.

Returns:

Type	Description
string	The ID of the app this scenario belongs to

Example

var appId = scenario.getAppId();

Back to Top

getArray ( entityName ) → {InsightArray}

Get an array from this scenario. Will return an object representing the scenario array, rather than the data itself. If a filter has been applied to the entity by calling ScenarioObserver#filter, this method will return only the array elements which match the filter.

Parameters:

Name	Type	Description
entityName	string	name of the entity

Returns:

Type	Description
InsightArray	the array representation

Example

var insightArray = scenario.getArray('ARRAY_NAME');

Back to Top

getCreationDate ( ) → {Date}

The date this scenario was created.

Returns:

Type	Description
Date	The date this scenario was created

Example

var creationDate = scenario.getCreationDate();

Back to Top

getExecutionStatus ( ) → {ScenarioExecutionStatus}

The ScenarioExecutionStatus for the scenario. Use in conjunction with ScenarioObserver#withExecutionStatus to observe the execution status and call the ScenarioObserver#notify callback on change.

Returns:

Type	Description
ScenarioExecutionStatus

Example

var executionStatus = scenario.getExecutionStatus();

Back to Top

getId ( ) → {string}

The ID for this scenario.

Returns:

Type	Description
string	The ID for this scenario

Example

var scenId = scenario.getId();

Back to Top

getModelSchema ( ) → {ModelSchema}

The model's schema for this scenario.

Returns:

Type	Description
ModelSchema	The model's schema for this scenario

Example

var modelSchema = scenario.getModelSchema();

Back to Top

getName ( ) → {string}

The name of this scenario.

Returns:

Type	Description
string	The name of this scenario

Example

var name = scenario.getName();

Back to Top

getNotes ( ) → {string}

The notes associated with this scenario.

Returns:

Type	Description
string	The notes associated with this scenario

Example

var notesTxt = scenario.getNotes();

Back to Top

getOwnerId ( ) → {string}

The username of the user that owns this scenario.

Returns:

Type	Description
string	The username of the user that owns this scenario

Example

var username = scenario.getOwnerId();

Back to Top

getParameter ( parameterName ) → {string}

Gets the value of a parameter from this scenario.

Parameters:

Name	Type	Description
parameterName	string	the parameter name

Returns:

Type	Description
string	a string representing the parameter value

Example

var parameterString = scenario.getParameter('PARAMETER_NAME');

Back to Top

getPath ( ) → {string}

The path to this scenario in the Insight Repository.

Returns:

Type	Description
string	The path to this scenario in the Insight Repository

Example

var pathString = scenario.getPath();

Back to Top

getScalar ( entityName ) → {PrimitiveType}

Gets the value of a scalar from this scenario.

Parameters:

Name	Type	Description
entityName	string	name of the entity

Returns:

Type	Description
PrimitiveType	entity scalar value

Example

var scalarValue = scenario.getScalar('SCALAR_NAME');

Back to Top

getScenarioAttachment ( filename ) → {null|Attachment}

Return a single scenario attachment that matches the given filename.

Parameters:

Name	Type	Description
filename	string	the filename of the attachment to return

Returns:

Type	Description
null | Attachment	A single attachment object or null if not found

Back to Top

getScenarioAttachments ( ) → {Array.<Attachment>}

Returns all the file attachments on the scenario.

Returns:

Type	Description
Array.<Attachment>	An array of Attachment objects

Example

var scenarioAttachments = scenario.getScenarioAttachments();

Back to Top

getScenarioType ( ) → {insight.enums.ScenarioType}

The type of this scenario.

Returns:

Type	Description
insight.enums.ScenarioType	the type of this scenario

Example

if (scenario.getScenarioType() === insight.enums.ScenarioType.SCENARIO) {
     // do something if this scenario has type 'SCENARIO'
}

Back to Top

getSet ( entityName ) → {Array.<PrimitiveType>}

Gets the elements from a set of this scenario. The set will be ordered alphanumerically by the server and if a set ordering function is defined in the view then it will also be applied.

An Insight Set is represented as a JavaScript array, containing the values in the set.

Parameters:

Name	Type	Description
entityName	string	name of the entity

Returns:

Type	Description
Array.<PrimitiveType>	set elements

Example

var setArray = scenario.getSet('SET_NAME');

Back to Top

getShareStatus ( ) → {insight.enums.ShareStatus}

The share status of this scenario.

Returns:

Type	Description
insight.enums.ShareStatus	The share status of this scenario

Example

if (scenario.getShareStatus() === insight.enums.ShareStatus.FULLACCESS) {
     // do something if share status is 'FULLACCESS'
}

Back to Top

getSummaryData ( ) → {ScenarioSummaryData}

The ScenarioSummaryData for the scenario contains summary information about the scenario and the current solution

Returns:

Type	Description
ScenarioSummaryData

Example

var summaryData = scenario.getSummaryData();

Back to Top

getTaggedAppAttachments ( tags ) → {Array.<Attachment>}

Returns an array of app attachments with the given tags. The argument can be a single tag or an array of tags, or if no tags are passed in, the function returns all attachments with any tag.

Parameters:

Name	Type	Argument	Description
tags	string | Array.<string>	optional	The tags to search for

Returns:

Type	Description
Array.<Attachment>	An array of Attachment objects

Example

var allTaggedScenarioAttachments = scenario.getTaggedScenarioAttachments();
var selectedTaggedAttachments = scenario.getTaggedScenarioAttachments(['tag1', 'tag2'])

Back to Top

getTaggedScenarioAttachments ( tags ) → {Array.<Attachment>}

Returns an array of scenario attachments with the given tags. The argument can be a single tag or an array of tags, or if no tags are passed in, the function returns all attachments with any tag.

Parameters:

Name	Type	Argument	Description
tags	string | Array.<string>	optional	The tags to search for

Returns:

Type	Description
Array.<Attachment>	An array of Attachment objects

Example

var allTaggedScenarioAttachments = scenario.getTaggedScenarioAttachments();
var selectedTaggedAttachments = scenario.getTaggedScenarioAttachments(['tag1', 'tag2'])

Back to Top

isEditable ( ) → {boolean}

Check whether the scenario data is currently in an editable state. When a scenario is reserved for execution (queued, executing, completing) the scenario data cannot be modified.

Returns:

Type	Description
boolean	Whether the scenario data is currently editable

Example

if (scenario.isEditable()) {
    // modify scenario data
}

Back to Top

modify ( ) → {ScenarioDataChange}

Modify data on the scenario within a single transaction.

Returns:

Type	Description
ScenarioDataChange	A new scenario change builder associated with this scenario

Example

scenario
     .modify()
     // Both set commands will be deferred until commit is called. Then they will be executed as a batch update.
     .setScalar( 'SCALAR_NAME', -99 )
     .setArrayElement( 'ARRAY_NAME', [{key: [1], value: 'First'}, {key: [2], value: 'Second'}] )
     .commit();

Back to Top

setNotes ( notes ) → {Promise}

Set notes on this scenario.

Parameters:

Name	Type	Description
notes	string	Notes to set against the scenario

Returns:

Type	Description
Promise	Promise object

Example

scenario
     .setNotes('A short note about this scenario')
     .then(function () {
         // notes have been set.
     })
     .catch(function () {
         // notes could not be set.
     });

Back to Top

setOwnerId ( newOwnerId ) → {Promise}

Change the ownership of this scenario.

Parameters:

Name	Type	Description
newOwnerId	string	the username of the new owner for this scenario

Returns:

Type	Description
Promise	Promise object

Example

scenario
     .setOwnerId('userid')
     .then(function () {
         // ownership has changed.
     })
     .catch(function (err) {
         // ownership could not be changed.
     });

Back to Top