View

Method summary

Methods

method

addScenarioToShelf ( scenarioId, index ) → {void}

Adds a scenario to the shelf specified by its ID and optionally pos index (0 based)

Parameters:

params

Name	Type	Argument	Description
scenarioId	type String		the scenario to add
index	type Integer	optional	add the scenario to this position on the shelf

details

Returns:

returns table

Type	Description
type void

Example

examples

// adds the scenario matching the ID to the end of the shelf
view.addScenarioToShelf('5cc7bf0a-cc46-414a-99fc-ff40c8bd53f7')

// adds the scenario matching the ID to index position 1
view.addScenarioToShelf('5cc7bf0a-cc46-414a-99fc-ff40c8bd53f7', 1)

Back to Top

method

addUnloadHandler ( callback ) → {number}

Register a view unload handler.

Parameters:

params

Name	Type	Description
callback	type View~UnloadHandler	Called before the view is unloaded

details

Returns:

returns table

Type	Description
type number	The unload handler id

Back to Top

method

clearShelf ( ) → {void}

Clears the shelf of all its scenarios

details

Returns:

returns table

Type	Description
type void

Example

examples

// clears all of the scenarios from the shelf
view.clearShelf()

Back to Top

method

configure ( options ) → {View}

Set global configuration options for the view.

Parameters:

params

Name	Type	Description
options	type View~ViewConfiguration	View configuration options

details

Returns:

returns table

Type	Description
type View	The instance of the view

Example

examples

var view = insight.getView();
view.configure({
     messageOffset: 50,
     noResultsMessage: 'There are no results.'
});

Back to Top

method

createAppAttachment ( options ) → {Promise}

Create a new app attachment.

Parameters:

params

Name	Type	Description
options	type NewAttachmentOptions	The new attachment options

details

Returns:

returns table

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

Example

examples

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

Back to Top

method

createProjectAttachment ( )

Use View#createAppAttachment instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

createScenarioAttachment ( options, indexOrId ) → {Promise}

Create a new scenario attachment.

Parameters:

params

Name	Type	Argument	Default	Description
options	type NewAttachmentOptions			The new attachment options
indexOrId	type number | string	optional	0	The scenario index on shelf or scenario id

details

Returns:

returns table

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

Example

examples

// Create attachment for seconf scenario on the shelf (index = 1).
view.createScenarioAttachment({filename: 'my_file.xml', tag: 'atag'}, 1)
    .then(function(data) {
        console.log(data.attachment);
    });

Back to Top

method

executeScenario ( scenarioId, executionMode, options ) → {Promise}

Executes the scenario specified by its ID

Parameters:

params

Name	Type	Argument	Default	Description
scenarioId	type string			The scenario ID to execute
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 = view.executeScenario('58c7d13d-8467-49c7-b3b0-f549478b30f7', "RUNFAST");
runPromise
     .then(function () {
         // scenario has been queued for execution
     })
     .catch(function (err) {
         // scenario could not be executed.
     });

Back to Top

method

getApp ( ) → {App}

The Insight app associated with this View.

details

Returns:

returns table

Type	Description
type App	the app associated with the view

Example

examples

var view = insight.getView();
view.getApp();

Back to Top

method

getAppId ( ) → {string}

The ID of the Insight app associated with this View.

details

Returns:

returns table

Type	Description
type string	the ID of the app associated with the view

Example

examples

var view = insight.getView();
view.getAppId();

Back to Top

method

getConfiguration ( key ) → {string|undefined|View~ViewConfiguration}

Get the entire view configuration or a single configuration option if a key is provided.

Parameters:

params

Name	Type	Argument	Description
key	type string	optional	configuration key to fetch

details

Returns:

returns table

Type	Description
type string | undefined | View~ViewConfiguration	whole configuration object or, if key is specified, a single configuration value. Returns undefined if key does not exist.

Example

examples

insight.getView().getConfiguration('notLoadedMessage'); // returns 'scenario not loaded' by default.

Back to Top

method

getProject ( )

Use View#getApp instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

getProjectId ( )

Use View#getAppId instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

getScenarioCount ( ) → {number}

Gets the number of scenarios in the selection.

details

Returns:

returns table

Type	Description
type number	the number of scenarios in the selection

Example

examples

var view = insight.getView();
view.getScenarioCount();

Back to Top

method

getScenarioIndex ( id ) → {number}

Returns the index of a scenario by id.

If the id is a number, or validly represents one as a string, it will be treated as an index, and returned as a number if the index is valid.

Parameters:

params

Name	Type	Description
id	type number | string	The id or index to look up

details

Returns:

returns table

Type	Description
type number	the index of scenario, or -1 if not found

Back to Top

method

getScenarioProperties ( index ) → {Promise.<ScenarioProperties>}

Gets the properties of a scenario.

Parameters:

params

Name	Type	Argument	Default	Description
index	type number	optional	0	The index of the scenario from the selection. Indexed from 0. Defaults to the first scenario.

details

Throws:

exceptions

If the scenario index is out of bounds

Type

type

Error

Returns:

returns table

Type	Description
type Promise.<ScenarioProperties>	Resolves once the scenario has been fetched from the server. Rejected with an error object if an error is encountered whilst fetching the data.

Example

examples

var view = insight.getView();
var propsPromise = view.getScenarioProperties(0); // zero is first scenario

propsPromise
     .then(function (props) {
         var scenarioName = props.getName();
     });

Back to Top

method

getUser ( ) → {Promise.<User>}

The current User.

details

Returns:

returns table

Type	Description
type Promise.<User>	User object within the promise response

Example

examples

var view = insight.getView();
var userPromise = view.getUser();

userPromise
     .then(function(user) {
         // user is available at this point.
     });

Back to Top

method

getViewProperty ( name ) → {*}

Gets a view property by name.

Parameters:

params

Name	Type	Description
name	type string	the name of the view property

details

Throws:

exceptions

Error if the view property has not been set

Returns:

returns table

Type	Description
type *	the value of the view property

Example

examples

var view = insight.getView();
view.getViewProperty('Custom Property');

Back to Top

method

hasSingleScenario ( ) → {boolean}

Indicates whether this View represents a single selected scenario.

details

Returns:

returns table

Type	Description
type boolean	true if this View contains a single selection and that selection is a scenario, otherwise false

Example

examples

var view = insight.getView();
if (view.hasSingleScenario() {
     // this code is only for single scenarios.
}

Back to Top

method

isDebugEnabled ( ) → {View.isDebugEnabled|Insight.isDebugEnabled|boolean|*}

Indicates whether the view is running in debug mode.

details

Returns:

returns table

Type	Description
type View.isDebugEnabled | Insight.isDebugEnabled | boolean | *

Example

examples

insight.getView().isDebugEnabled();

Back to Top

method

isModified ( )

Indicates whether there are pending changes in this View.

details

Returns:

returns table

Type	Description
	True if changes are pending, otherwise false

Example

examples

insight.getView().isModified();

Back to Top

method

isReadOnly ( ) → {boolean}

Indicates whether this view is read only.

details

Returns:

returns table

Type	Description
type boolean	true if the view is read only, false if not

Example

examples

insight.getView().isReadOnly();

Back to Top

method

modifyScenario ( index ) → {ScenarioDataChange}

Start a scenario modification.

Parameters:

params

Name	Type	Argument	Default	Description
index	type number	optional	0	The index of the scenario from the selection. Indexed from 0. Defaults to the first scenario.

details

Throws:

exceptions

If the scenario index is out of bounds

Type

type

Error

Returns:

returns table

Type	Description
type ScenarioDataChange	The scenario modification object on which to commit changes

Example

examples

var view = insight.getView();
var modifyPromise = view.modifyScenario(0) // modify first scenario.
                         .setScalar('numAccounts', 15000)
                         .commit();
modifyPromise
     .then(function() {
         // data change saved
     }).catch(function(err) {
         // failed to save data change
     });

Back to Top

method

openAppAttachmentsDialog ( message )

Opens the app attachments dialog.

A custom message can shown within the dialog in order to guide the user in what they are expected to achieve using the dialog (e.g., uploading a particular type of attachment, adding a tag, etc.)

Parameters:

params

Name	Type	Argument	Description
message	type string	optional	A custom message to show within the dialog

details

Example

examples

insight.getView().openAppAttachmentsDialog('Upload an attachment');

Back to Top

method

openProjectAttachmentsDialog ( )

Use View#openAppAttachmentsDialog instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

openScenarioAttachmentsDialog ( message, indexOrId )

Opens the scenario attachments dialog.

A custom message can shown within the dialog in order to guide the user in what they are expected to achieve using the dialog (e.g., uploading a particular type of attachment, adding a tag, etc.)

By default, the attachments of the first scenario on the shelf will be shown in the dialog. An alternative scenario can be specified using either its id or its selection index.

Parameters:

params

Name	Type	Argument	Default	Description
message	type string	optional		A custom message to show within the dialog
indexOrId	type string | number	optional	0	The index or id of the scenario whose attachments to show in the dialog

details

Example

examples

insight.getView().openScenarioAttachmentsDialog('Upload an attachment'); // First scenario on the shelf
insight.getView().openScenarioAttachmentsDialog('Upload an attachment', 1); // Second scenario on the shelf
insight.getView().openScenarioAttachmentsDialog('Upload an attachment', scenario.getId());

Back to Top

method

promptToClearInputData ( scenarioId, options ) → {Promise.<boolean>}

Parameters:

params

Name	Type	Argument	Description
scenarioId	type string
options	type Object	optional	Properties params Name Type Argument Description force type boolean optional  Whether to force the prompt to appear even if not normally merited executionMode type string optional  The name of the execution mode to be used

details

Returns:

returns table

Type	Description
type Promise.<boolean>	A promise that resolves to whether the load should proceed

Back to Top

method

reload ( ) → {boolean}

Reloads the view.

details

Returns:

returns table

Type	Description
type boolean	true if the view has been reloaded, false if not

Example

examples

if (insight.getView().reload()) {
     // view was reloaded
}

Back to Top

method

removeScenarioFromShelf ( scenarioId ) → {void}

Removes a scenario to the shelf specified by its ID

Parameters:

params

Name	Type	Description
scenarioId	type String	the scenario to remove

details

Returns:

returns table

Type	Description
type void

Example

examples

// removes the scenario matching the ID from the shelf
view.removeScenarioToShelf('5cc7bf0a-cc46-414a-99fc-ff40c8bd53f7')

Back to Top

method

removeUnloadHandler ( id )

Remove a registered view unload handler.

Parameters:

params

Name	Type	Description
id	type number	The handler id given when registered

details

Back to Top

method

replaceSelection ( ) → {Promise.<Array.<string>>}

Replace the scenario selection for the view. Specify a list of scenarios (or a Promise that resolves to a list of scenarios) that can be used by the view. This will result in the user-selected scenarios that appear on the shelf being ignored.

details

Returns:

returns table

Type	Description
type Promise.<Array.<string>>	Resolves with a list of scenario ids if successfully applied the new selection. Rejected with an Error if failed to apply new selection

Example

examples

function getSomeScenarioIds() {
    return new Promise(function (resolve, reject) {
        $.get(document.location.origin + '/insightservices/rest/v1/data/project/' + insight.getView().getApp().getId() + '/children?maxResults=9999', function (result) {
            var ids = result.items
                .filter(function (item) {
                    return item.objectType === 'SCENARIO';
                })
                .map(function (item) {
                    return item.id;
                });
            resolve(ids);
        });
    });
}

insight.getView().replaceSelection(getSomeScenarioIds())
    .then(function (selection) {
        console.log('Successfully applied the replacement selection', selection);
    });

Back to Top

method

save ( ) → {Promise.<undefined>}

Save all changes made within this View.

details

Returns:

returns table

Type	Description
type Promise.<undefined>	Resolves when the view is saved successfully

Example

examples

var view = insight.getView();
var savePromise = view.save();

savePromise
     .then(function () {
         // view was saved
     }).catch(function (err) {
         // view was not able to save
     });

Back to Top

method

setShelf ( scenarios ) → {void}

Sets the shelf to contain the array of scenario's specified in the array

Parameters:

params

Name	Type	Description
scenarios	type Array	scenario ID's as an array

details

Returns:

returns table

Type	Description
type void

Example

examples

// sets the state of the shelf to contain only the scenarios specified
view.setShelf(['5cc7bf0a-cc46-414a-99fc-ff40c8bd53f7', '5cc7bf0a-cc46-3454-99fc-ff40c8bd5444'])

Back to Top

method

setViewProperties ( properties )

Sets multiple view properties in a single operation.

Parameters:

params

Name	Type	Description
properties	type Object.<string, *>	the name value pairs of properties to set

details

Example

examples

var view = insight.getView();
view.setViewProperties({
     propertyNumber: 1888,
     propertyName: 'Leap Year'
});

Back to Top

method

setViewProperty ( name, value )

Sets a view property.

Parameters:

params

Name	Type	Description
name	type string	the name of the property
value	type *	the value of the property

details

• See:
• View#setViewProperties

Example

examples

var view = insight.getView();
view.setViewProperty('Custom Property', 999);

Back to Top

method

showErrorMessage ( message ) → {void}

Show an error message in the webclient

Parameters:

params

Name	Type	Description
message	type string	The message to show

details

Returns:

returns table

Type	Description
type void

Example

examples

view.showErrorMessage('An error has occurred and your request could not be completed');

Back to Top

method

showInfoMessage ( message ) → {void}

Show an information message in the webclient

Parameters:

params

Name	Type	Description
message	type string	The message to show

details

Returns:

returns table

Type	Description
type void

Example

examples

view.showInfoMessage('Action completed successfully');

Back to Top

method

start ( ) → {Promise.<View>}

Start ScenarioObservers and add no-results and execution overlays to the view.

details

Returns:

returns table

Type	Description
type Promise.<View>	for chaining

Example

examples

var view = insight.getView();
view.start();

Back to Top

method

uploadAppAttachment ( tagName, message ) → {Promise.<undefined>}

Opens the app attachments dialog in a mode where any file uploaded will be automatically tagged with the given tag.

Parameters:

params

Name	Type	Description
tagName	type string	the tag to assign when uploading
message	type string	optional custom message to show in the upload dialog

details

Returns:

returns table

Type	Description
type Promise.<undefined>	Resolves when the dialog is opened successfully

Example

examples

view.uploadAppAttachment('input-sheet', 'Custom message', 0);

Back to Top

method

uploadProjectAttachment ( )

Use View#uploadAppAttachment instead.

details

• Deprecated since Js Api 4.5

Back to Top

method

uploadScenarioAttachment ( tagName, message, indexOrId ) → {Promise.<undefined>}

Opens the scenario attachments dialog in a mode where any file uploaded will be automatically tagged with the given tag.

Parameters:

params

Name	Type	Argument	Default	Description
tagName	type string			The tag to assign when uploading
message	type string	optional		Custom message to show in the upload dialog
indexOrId	type integer | string	optional	0	Scenario selection index or scenario id

details

Returns:

returns table

Type	Description
type Promise.<undefined>	Resolves when the dialog is opened successfully

Example

examples

view.uploadScenarioAttachment('input-sheet', 'Custom message', 0);

Back to Top

method

withAllScenarios ( ) → {ScenarioObserver}

Create a new ScenarioObserver that listens to all scenarios in the view selection.

details

Returns:

returns table

Type	Description
type ScenarioObserver

Example

examples

insight.getView()
         .withAllScenarios()
         .withEntities('ENTITY_NAME')
         .notify(myNotifyFunc); // notify callback for entity data updates.

Back to Top

method

withFirstScenario ( ) → {ScenarioObserver}

Create a new ScenarioObserver that listens to the first scenario in the view selection.

details

Returns:

returns table

Type	Description
type ScenarioObserver

Example

examples

insight.getView()
         .withFirstScenarios()
         .withEntities('ENTITY_NAME')
         .notify(myNotifyFunc); // notify callback for entity data updates.

Back to Top

method

withScenarios ( arguments ) → {ScenarioObserver}

Create a new ScenarioObserver that listens to list of scenarios from the view selection. Provide either a number, list of numbers or an array of numbers, or the scenario ids.

Parameters:

params

Name	Type	Description
arguments	type number | string | Array.<number> | Array.<string>	the selection indices or scenario ids

details

Returns:

returns table

Type	Description
type ScenarioObserver

Example

examples

insight.getView()
         .withScenarios(0, 2) // observes the first and third scenarios
         .withEntities('ENTITY_NAME')
         .notify(myNotifyFunc); // notify callback for entity data updates.

Back to Top

Type Definitions

method

UnloadHandler ( ) → {Promise}

Called before the view is unloaded, giving your custom code chance to save or cleanup.

details

Returns:

returns table

Type	Description
type Promise	Resolves or rejects when view shutdown tasks have been completed.

Back to Top

members

ViewConfiguration - {

type

object }

View configuration data structure.

details

Properties:

properties

Name	Type	Argument	Default	Description
messageOffset	type number	optional	0	The vertical offset for user messages whilst this view is displayed.
noResultsOverlay	type boolean	optional	true	Whether to make use of the 'no results' overlay.
noResultsMessage	type string	optional	'no results available'	The message displayed in the 'no results' overlay.
notLoadedOverlay	type boolean	optional	true	Whether to enable the scenario not loaded overlays
notLoadedMessage	type string	optional	'scenario not loaded'	The message to display in the scenario not loaded overlays
executionOverlay	type boolean	optional	true	Whether to make use of the 'execution' overlay.
executionOverlayMessage	type string	optional	'Please wait...'	The message displayed in the 'execution' overlay.

Example

examples

var view = insight.getView();
view.configure({
     messageOffset: 50,
     notLoadedOverlay: false,
     executionOverlayMessage: 'Scenario running..'
});