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

method

cancel ( ) → {Promise}

Cancel any execution of this scenario.

details

Returns:

returns table

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

Example

examples

var cancelledPromise = scenario.cancel();

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

Back to Top

method

createAttachment ( options ) → {Promise}

Create a new scenario attachment.

Parameters:

params

Name	Type	Argument	Description
options	type NewAttachmentOptions	optional

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

downloadAppAttachments ( attachments ) → {Undefined}

Downloads the attachments specified in the attachments parameter.

Parameters:

params

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

details

Returns:

returns table

Type	Description
type Undefined

Example

examples

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

Back to Top

method

downloadProjectAttachments ( )

Use Scenario#downloadAppAttachments instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

downloadScenarioAttachments ( attachments ) → {Undefined}

Downloads the attachments specified in the attachments parameter.

Parameters:

params

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

details

Returns:

returns table

Type	Description
type Undefined

Example

examples

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

Back to Top

method

execute ( executionMode, options ) → {Promise}

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

Parameters:

params

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

details

Returns:

returns table

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

Example

examples

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

method

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:

params

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

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

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:

params

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

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

getAppAttachment ( filename ) → {null|Attachment}

Return a single app attachment that matches the given filename.

Parameters:

params

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

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

getAppAttachments ( ) → {Array.<Attachment>}

Returns all the file attachments on the app.

details

Returns:

returns table

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

Example

examples

var appAttachments = scenario.getAppAttachments();

Back to Top

method

getAppId ( ) → {string}

The ID of the app this scenario belongs to.

details

Returns:

returns table

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

Example

examples

var appId = scenario.getAppId();

Back to Top

method

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:

params

Name	Type	Description
entityName	type string	name of the entity

details

Returns:

returns table

Type	Description
type InsightArray	the array representation

Example

examples

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

Back to Top

method

getCreationDate ( ) → {Date}

The date this scenario was created.

details

Returns:

returns table

Type	Description
type Date	The date this scenario was created

Example

examples

var creationDate = scenario.getCreationDate();

Back to Top

method

getCurrentExecutionStatus ( ) → {Promise.<ScenarioExecutionStatus>}

Gets the current execution status of this scenario.

details

Returns:

returns table

Type	Description
type Promise.<ScenarioExecutionStatus>	promise containing the current execution status

Example

examples

var statusPromise = scenario.getCurrentExecutionStatus();
statusPromise
     .then(function (status) {
             // status available here
         });

Back to Top

method

getId ( ) → {string}

The ID for this scenario.

details

Returns:

returns table

Type	Description
type string	The ID for this scenario

Example

examples

var scenId = scenario.getId();

Back to Top

method

getModelSchema ( ) → {ModelSchema}

The model's schema for this scenario.

details

Returns:

returns table

Type	Description
type ModelSchema	The model's schema for this scenario

Example

examples

var modelSchema = scenario.getModelSchema();

Back to Top

method

getName ( ) → {string}

The name of this scenario.

details

Returns:

returns table

Type	Description
type string	The name of this scenario

Example

examples

var name = scenario.getName();

Back to Top

method

getNotes ( ) → {string}

The notes associated with this scenario.

details

Returns:

returns table

Type	Description
type string	The notes associated with this scenario

Example

examples

var notesTxt = scenario.getNotes();

Back to Top

method

getOwnerId ( ) → {string}

The username of the user that owns this scenario.

details

Returns:

returns table

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

Example

examples

var username = scenario.getOwnerId();

Back to Top

method

getParameter ( parameterName ) → {string}

Gets the value of a parameter from this scenario.

Parameters:

params

Name	Type	Description
parameterName	type string	the parameter name

details

Returns:

returns table

Type	Description
type string	a string representing the parameter value

Example

examples

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

Back to Top

method

getPath ( ) → {string}

The path to this scenario in the Insight Repository.

details

Returns:

returns table

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

Example

examples

var pathString = scenario.getPath();

Back to Top

method

getProjectAttachment ( )

Use Scenario#getAppAttachment instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

getProjectAttachments ( )

Use Scenario#getAppAttachments instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

getProjectId ( )

Use ScenarioProperties#getAppId instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

getScalar ( entityName ) → {PrimitiveType}

Gets the value of a scalar from this scenario.

Parameters:

params

Name	Type	Description
entityName	type string	name of the entity

details

Returns:

returns table

Type	Description
type PrimitiveType	entity scalar value

Example

examples

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

Back to Top

method

getScenarioAttachment ( filename ) → {null|Attachment}

Return a single scenario attachment that matches the given filename.

Parameters:

params

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

details

Returns:

returns table

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

Back to Top

method

getScenarioAttachments ( ) → {Array.<Attachment>}

Returns all the file attachments on the scenario.

details

Returns:

returns table

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

Example

examples

var scenarioAttachments = scenario.getScenarioAttachments();

Back to Top

method

getScenarioType ( ) → {insight.enums.ScenarioType}

The type of this scenario.

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

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:

params

Name	Type	Description
entityName	type string	name of the entity

details

Returns:

returns table

Type	Description
type Array.<PrimitiveType>	set elements

Example

examples

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

Back to Top

method

getShareStatus ( ) → {insight.enums.ShareStatus}

The share status of this scenario.

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

getSummaryData ( ) → {ScenarioSummaryData}

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

details

Returns:

returns table

Type	Description
type ScenarioSummaryData

Example

examples

var summaryData = scenario.getSummaryData();

Back to Top

method

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:

params

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

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

getTaggedProjectAttachments ( )

Use Scenario#getTaggedAppAttachments instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

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:

params

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

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

modify ( ) → {ScenarioDataChange}

Modify data on the scenario within a single transaction.

details

Returns:

returns table

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

Example

examples

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

method

setNotes ( notes ) → {Promise}

Set notes on this scenario.

Parameters:

params

Name	Type	Description
notes	type string	Notes to set against the scenario

details

Returns:

returns table

Type	Description
type Promise	Promise object

Example

examples

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

Back to Top

method

setOwnerId ( newOwnerId ) → {Promise}

Change the ownership of this scenario.

Parameters:

params

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

details

Returns:

returns table

Type	Description
type Promise	Promise object

Example

examples

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

Back to Top