View

Method summary

Methods

addScenarioToShelf ( scenarioId, index ) → {void}

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

Parameters:

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

Returns:

Type	Description
void

Example

// 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

addUnloadHandler ( callback ) → {number}

Register a view unload handler.

Parameters:

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

Returns:

Type	Description
number	The unload handler id

Back to Top

clearShelf ( ) → {void}

Clears the shelf of all its scenarios

Returns:

Type	Description
void

Example

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

Back to Top

configure ( options ) → {View}

Set global configuration options for the view.

Parameters:

Name	Type	Description
options	View~ViewConfiguration	View configuration options

Returns:

Type	Description
View	The instance of the view

Example

var view = insight.getView();
view.configure({
     receivesProgress: true, // Progress updates are only supported in Insight 5
     messageOffset: 50,
     noResultsMessage: 'There are no results.'
});

Back to Top

createAppAttachment ( options ) → {Promise.<CreateAttachmentResult>}

Create a new app attachment.

Parameters:

Name	Type	Description
options	NewAttachmentOptions	The new attachment options

Returns:

Type	Description
Promise.<CreateAttachmentResult>	Resolves when user closes the editor or if attachment create fails

Example

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

Back to Top

createScenarioAttachment ( options, indexOrId ) → {Promise.<CreateAttachmentResult>}

Create a new scenario attachment.

Parameters:

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

Returns:

Type	Description
Promise.<CreateAttachmentResult>	Resolves when user closes the editor or if attachment create fails

Example

// 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

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

Executes the scenario specified by its ID

Parameters:

Name	Type	Argument	Default	Description
scenarioId	string			The scenario ID to execute
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 = 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

getApp ( ) → {App}

The Insight app associated with this View.

Returns:

Type	Description
App	the app associated with the view

Example

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

Back to Top

getAppId ( ) → {string}

The ID of the Insight app associated with this View.

Returns:

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

Example

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

Back to Top

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

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

Parameters:

Name	Type	Argument	Description
key	string	optional	configuration key to fetch

Returns:

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

Example

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

Back to Top

getScenarioCount ( ) → {number}

Gets the number of scenarios in the selection.

Returns:

Type	Description
number	the number of scenarios in the selection

Example

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

Back to Top

getScenarioIds ( ) → {Array.<string>}

Gets the array of scenario IDs in the selection.

Returns:

Type	Description
Array.<string>	the IDs of the selection scenarios

Back to Top

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:

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

Returns:

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

Back to Top

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

Gets the properties of a scenario.

Parameters:

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

Throws:

If the scenario index is out of bounds

Type

Error

Returns:

Type	Description
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

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

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

Back to Top

getUser ( ) → {Promise.<User>}

The current User.

Returns:

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

Example

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

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

Back to Top

getViewProperty ( name ) → {*}

Gets a view property by name.

Parameters:

Name	Type	Description
name	string	the name of the view property

Throws:

Error if the view property has not been set

Returns:

Type	Description
*	the value of the view property

Example

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

Back to Top

hasSingleScenario ( ) → {boolean}

Indicates whether this View represents a single selected scenario.

Returns:

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

Example

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

Back to Top

importFromServer ( locationId, locationType ) → {Promise.<string>}

Open the import from server dialog for the user to interact with. This allows the user to import a previously exported Scenario or Folder of Scenarios only. They will not be able to import an App.

This will return a Promise that will be fulfilled once the server has responded to the request to import an item selected by the end user, or if the user cancels the import dialog.

This is an Insight 5 only feature and will return a rejected Promise if run on an earlier version.

Parameters:

Name	Type	Description
locationId	string	The id of the target FOLDER or APP where the user-selected items will be imported into
locationType	Enums.ObjectType.APP | Enums.ObjectType.FOLDER	The ObjectType of the target location. Must be FOLDER or APP.

Returns:

Type	Description
Promise.<string>	resolves, with the id for the import, if the user picks an item to import and the server accepts. Rejects, with a reason message, if the server rejects the import request or if the user cancels the import dialog.

Example

view.importFromServer('58c7d13d-8467-49c7-b3b0-f549478b30f7', insight.enums.ObjectType.APP)
     .then(function (importId) {
         // import request was accepted by the server. The importId can be used to track the import progress.
     })
     .catch(function (err) {
         // import failed or was cancelled by the end user.
         err.message
     });

Back to Top

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

Indicates whether the view is running in debug mode.

Returns:

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

Example

insight.getView().isDebugEnabled();

Back to Top

modifyScenario ( index ) → {ScenarioDataChange}

Start a scenario modification.

Parameters:

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

Throws:

If the scenario index is out of bounds

Type

Error

Returns:

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

Example

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

openAppAttachmentsDialog ( message )

Opens the app attachments dialog.

A custom message can be 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:

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

Example

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

Back to Top

openFICODrive ( title, resourceType, extensions ) → {Promise.<FICODriveResource>}

Opens the FICO Drive dialog.

It is possible to configure the dialog to have a custom title, filter the file extensions shown and to only allow the selection of either FILE or FOLDER resources.

Parameters:

Name	Type	Description
title	string	Title for the dialog
resourceType	insight.enums.FICODriveResourceType	Resource type to allow the section of. One of FILE or FOLDER.
extensions	Array.<string>	Specifies the filter to be applied to visible files. For example: ["zip", "csv"]

Returns:

Type	Description
Promise.<FICODriveResource>	Resolves when the dialog is closed. The return promise resolves to an object containing the selected file or folder resource.

Back to Top

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:

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

Example

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

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

Parameters:

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

Returns:

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

Back to Top

reload ( ) → {boolean}

Reloads the view.

Returns:

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

Example

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

Back to Top

removeScenarioFromShelf ( scenarioId ) → {void}

Removes a scenario to the shelf specified by its ID

Parameters:

Name	Type	Description
scenarioId	String	the scenario to remove

Returns:

Type	Description
void

Example

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

Back to Top

removeUnloadHandler ( id )

Remove a registered view unload handler.

Parameters:

Name	Type	Description
id	number	The handler id given when registered

Back to Top

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.

Returns:

Type	Description
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

function obtainScenarioIds() {
    return fetch(insight.resolveRestEndpoint('/data/apps/' + insight.getView().getApp().getId() + '/children'), {
        method: 'GET',
        headers: {
            Accept: 'application/vnd.com.fico.xpress.insight.internal.v2+json'
        }
    }).then(r => {
        const responseJson = r.json();
        const ids = responseJson.items.filter(item => {
            return item.objectType === insight.enums.ObjectType.SCENARIO;
        }).map(item => {
            return item.id;
        });

        return ids;
    });
}

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

Back to Top

save ( ) → {Promise.<undefined>}

Save all changes made within this View.

Returns:

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

Example

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

sendJobMessage ( scenarioId, message ) → {Promise}

Send a message to a running scenario.

Parameters:

Name	Type	Description
scenarioId	string	The id of the scenario that should receive the message
message	PrimitiveType | object | array	The message to send. If it is not a string then it will be JSON serialized before sending to the server. It cannot be an empty string.

Returns:

Type	Description
Promise	Resolves when the message is accepted by the server. Rejected if message fails to be sent or the server doesn't accept the message for a specific reason.

Example

insight.getView().sendJobMessage('5cc7bf0a-cc46-414a-99fc-ff40c8bd53f7', {command: 'accept-solution'})

Back to Top

setShelf ( scenario ) → {void}

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

Parameters:

Name	Type	Description
scenario	Array.<string>	scenario ID's as an array

Returns:

Type	Description
void

Example

// 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

setViewProperties ( properties )

Sets multiple view properties in a single operation.

Parameters:

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

Example

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

Back to Top

setViewProperty ( name, value )

Sets a view property.

Parameters:

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

• See:
• View#setViewProperties

Example

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

Back to Top

showErrorMessage ( message ) → {void}

Show an error message in the webclient

Parameters:

Name	Type	Description
message	string	The message to show

Returns:

Type	Description
void

Example

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

Back to Top

showInfoMessage ( message ) → {void}

Show an information message in the webclient

Parameters:

Name	Type	Description
message	string	The message to show

Returns:

Type	Description
void

Example

view.showInfoMessage('Action completed successfully');

Back to Top

showWarningMessage ( message ) → {void}

Show a warning message in the webclient

Parameters:

Name	Type	Description
message	string	The message to show

Returns:

Type	Description
void

Example

view.showWarningMessage('The data you have entered is invalid');

Back to Top

start ( ) → {Promise.<View>}

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

Returns:

Type	Description
Promise.<View>	for chaining

Example

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

Back to Top

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:

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

Returns:

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

Example

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

Back to Top

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:

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

Returns:

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

Example

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

Back to Top

withAllScenarios ( ) → {ScenarioObserver}

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

Returns:

Type	Description
ScenarioObserver

Example

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

Back to Top

withFirstScenario ( ) → {ScenarioObserver}

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

Returns:

Type	Description
ScenarioObserver

Example

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

Back to Top

withMirrorTables ( tableNames ) → {MirrorObserver}

Create a MirrorObserver, specifying which tables should be mirrored.

Parameters:

Name	Type	Description
tableNames	string | Array.<string>	A list of tables to mirror as an array of strings or table names as multiple arguments

Returns:

Type	Description
MirrorObserver	A builder object for defining the mirror operation

Example

insight.getView()
    .withMirrorTables(['my_table_1', 'my_table_2'])
    .withAllScenarios()
    .notify(myNotifyFunc) // Handle progress updates for the mirror operation
    .onError(myErrorFunc) // Handle any error creating the mirror
    .start()

Back to Top

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:

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

Returns:

Type	Description
ScenarioObserver

Example

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

UnloadHandler ( ) → {Promise}

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

Returns:

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

Back to Top

ViewConfiguration - { object }

View configuration data structure.

Properties:

Name	Type	Argument	Default	Description
receivesProgress	boolean	optional	false	Whether the view should receive progress data updates during model execution. Progress updates are only supported in Insight 5.
messageOffset	number	optional	0	The vertical offset for user messages whilst this view is displayed.
noResultsOverlay	boolean	optional	true	Whether to make use of the 'no results' overlay.
noResultsMessage	string	optional	'no results available'	The message displayed in the 'no results' overlay.
notLoadedOverlay	boolean	optional	true	Whether to enable the scenario not loaded overlays
notLoadedMessage	string	optional	'scenario not loaded'	The message to display in the scenario not loaded overlays
executionOverlay	boolean | 'disabled_for_progress'	optional	true	Whether to make use of the 'execution' overlay. 'disabled_for_progress' is only available in Xpress Insight 5 and will disable the default execution overlay only when at least one of the scenarios used in the view runs a job that sends progress.
executionOverlayMessage	string	optional	'Please wait...'	The message displayed in the 'execution' overlay.

Example

var view = insight.getView();
view.configure({
     receivesProgress: true, // Progress updates are only supported in Insight 5
     messageOffset: 50,
     notLoadedOverlay: false,
     executionOverlayMessage: 'Scenario running..'
});