Initializing help system before first use

# ScenarioObserver

Provides a way to register for data and state changes for scenarios and entities.

### Method summary

name | description
--- | ---
bindAutoForm | Bind an AutoForm DOM element that matches the formId property in the options argument.
bindAutoTable | Bind AutoTable configuration to a specified DOM table element and update the AutoTable whenever there are data changes.
bindAutoText | Bind AutoText elements from the DOM that match the selector property in the options argument.
bindImageAttachments | Bind IMG elements marked with the 'data-attachment-filename' attribute, to display image attachments in the page.
dispose | This stops the event listener for the configured scenarios and entities.
filter | Apply a filter to an InsightArray. The filtering is done on the server-side and the client will only have access to elements matching the specified index filters.
isDisposed | Check if the scenario observer is disposed.
notify | Add a function to be called with the requested data whenever there are changes to that data.
once | Add a function to be called once with the requested data and then dispose this observer.
start | This tells the system to go and fetch the configured scenarios and entities and return their values. Also it starts listening for change events on those scenarios and entities.
withAttachments | Registers this observer to be notified whenever the scenario attachments change.
withEntities | Specify the entities this scenario observer is interested in.
withExecutionStatus | Registers this observer to be notified whenever the scenario execution status changes.
withSummaryData | Registers this observer to be notified whenever the scenario summary data changes.
withViewProperties | Specify the view properties this scenario observer is interested in.

### Methods

bindAutoForm ( options ) → {ScenarioObserver}

  Bind an AutoForm DOM element that matches the formId property in the options argument.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  options | ScenarioObserver~BindAutoFormOptions | AutoForm binding options

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
bindAutoTable ( options ) → {ScenarioObserver}

  Bind an AutoTable DOM element that matches the tableId property in the options argument. The options and overrides objects passed in should match the AutoTable constructor arguments except where it is expecting Scenario objects you can pass scenario id and they will get resolved.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  options | ScenarioObserver~BindAutoTableOptions | AutoTable binding options

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
bindAutoText ( options ) → {ScenarioObserver}

  Bind AutoText elements from the DOM that match the selector property in the options argument. Alternatively, if a string arguments is passed in the this acts as the selector.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  options | ScenarioObserver~BindAutoTextOptions | string | AutoText binding options object or the the selector is a string

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
bindImageAttachments ( options ) → {ScenarioObserver}

  Bind IMG elements marked with the 'data-attachment-filename' attribute, to display image attachments in the page.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  options | ScenarioObserver~BindImageAttachmentOptions | jQuery | string | an image attachment binding options object, a jQuery selector or a CSS selector string

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
dispose ( )

  This stops the event listener for the configured scenarios and entities. The notify callback or bound auto components related to this scenario observer will not receive any further updates.

  Back to Top
filter ( entity, callback ) → {ScenarioObserver}

  Apply a filter to an InsightArray. The filtering is done on the server-side and the client will only have access to elements matching the specified index filters.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  entity | string | the entity name to filter on
  callback | ScenarioObserver~FilterCallback | the filter to apply

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  ##### Example

      insight.getView()
          .withFirstScenario()
          .withViewProperties('selectedDay')
          .withEntities('SUPPLY')
          .filter('SUPPLY', function (viewProperties) {
              // Array filter: filters the 'DAY' index of the array by the value of a view property called
              // 'selectedDay' and filters the 'REGION' index of the array by hard-coded values.
              return {
                  'DAY': [viewProperties.get('selectedDay')],
                  'REGION': ['SOUTH', 'WEST']
              }
          })
          .notify(function (scenario) {})
          .start();

  Back to Top
isDisposed ( ) → {boolean}

  Check if the scenario observer is disposed.

  Returns:

  Type | Description
  --- | ---
  boolean | Whether this scenario observer is disposed

  Back to Top
notify ( callback ) → {ScenarioObserver}

  Add a function to be called when there are data changes, depending on what has been subscribed to.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  callback | NotifyCallback | the callback to invoke

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
once ( callback ) → {ScenarioObserver}

  Add a function to be called once with the requested data and then dispose this observer. once() and notify() are mutually exclusive.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  callback | NotifyCallback | the callback to invoke

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
start ( ) → {ScenarioObserver}

  This tells the system to go and fetch the configured scenarios and entities and return their values. Also it starts listening for change events on those scenarios and entities.

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
withAttachments ( options ) → {ScenarioObserver}

  Registers this observer to be notified whenever the scenario or app attachments change.

  The argument to this function can be one of the following:
  - An array of tags to observe.
  - A single tag to observe.
  - A configuration object (of type WithAttachmentsOptions) indicating which tags to observe and whether to observe scenario or app attachments.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  options | ScenarioObserver~WithAttachmentsOptions |

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  ##### Example

      insight.ready(function () {
           var view = insight.getView();
           view
                   .withFirstScenario()
                   .withAttachments({tags: ['tagA', 'tagB'], app: true, scenario: true})
                   .notify(function (scenario) {
                       // code to access attachments here...
                   });
                  });

  Back to Top
withEntities ( entities ) → {ScenarioObserver}

  Specify the entities this scenario observer is interested in.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  entities | string | Array.<string> | the entities to observe

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
withExecutionStatus ( ) → {ScenarioObserver}

  Registers this observer to be notified whenever the scenario execution status changes. Retrieve the execution status from the scenario(s) using Scenario#getExecutionStatus.

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  ##### Example

      insight.getView()
        .withFirstScenario()
        .withExecutionStatus()
        .notify(function (scenario) {
          // Retrieve the current ScenarioExecutionStatus from a Scenario.
          scenario.getExecutionStatus().getJobId();
        });

  Back to Top
withSummaryData ( ) → {ScenarioObserver}

  Registers this observer to be notified whenever the scenario summary changes. Can be used in combination with `ScenarioObserver#withEntities` to get notified when either the summary data or entity data change.

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top
withViewProperties ( viewProperties ) → {ScenarioObserver}

  Specify the view properties this scenario observer is interested in.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  viewProperties | string | Array.<string> | the view properties to observe

  Returns:

  Type | Description
  --- | ---
  ScenarioObserver |

  Back to Top

### Type Definitions

BindAutoFormOptions - { object }

  ##### Properties:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  formId | string |  | id of the DOM element to bind to
  scenario | string | number | optional | the scenario id or index to use, defaults to the first scenario in the selection
  loadButton | string | optional | id of the DOM element to bind the load action to
  runButton | string | optional | id of the DOM element to bind the run action to
  saveButton | string | optional | id of the DOM element to bind the save action to
  cancelButton | string | optional | id of the DOM element to bind the cancel action to
  additionalBindings | object | optional | additional binding information passed in to the AutoForm. See the AutoForm#bindForm inputs argument

BindAutoTableError ( error )

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  error | Error | The error encountered

  Back to Top
BindAutoTableOptions - { object }

  ##### Properties:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  tableId | string |  |  | id of the DOM table element to bind to
  scenario | string | number | optional |  | scenario id or index to use, defaults to the first scenario in the selection
  columnOptions | Array.<AutoTable~ColumnOptions> | optional |  | list of column options for AutoTable. The scenario properties on columns can be specified as a scenario index or id and they will automatically be transposed into Scenario objects
  indicesOptions | Object.<string, (AutoTable~IndicesOptions|Array.<AutoTable~IndicesOptions>)> | optional |  | map of indices options for AutoTable
  overrides | object | optional |  | map of DataTables overrides for AutoTable
  addRemoveRow | boolean | optional | false | enable the add/remove row functionality. See the AutoTable constructor
  onError | ScenarioObserver~BindAutoTableError | optional |  | Callback if Autotable creation leads to error

BindAutoTextOptions - { object }

  ##### Properties:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  selector | string |  | a jQuery selector defining the DOM elements to bind to
  scenario | string | number | optional | the scenario id or index to use, defaults to the first scenario in the selection

BindImageAttachmentOptions - { object }

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  selector | string | a jQuery selector or CSS selector string defining the IMG elements to bind to within the DOM

FilterCallback ( viewProperties ) → {Object.<(string|number), *>}

  Filter callback to apply to the entity.

  At times it is desirable to only retrieve a slice of an array, i.e. only retrieve the elements for a subset of the array's index values. This callback should return an object containing an array of values to use for each index set. If the index set is not included in the object then all values in the index set are used. The index set can either be specified by name or by ordinal. (The first index set of the array has ordinal 0.)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  viewProperties | MaskedViewProperties | Only allows access to the view properties that this scenario observer is listening to

  Returns:

  Type | Description
  --- | ---
  Object.<(string|number), *> | the filter; a map from index set name (or ordinal) to array of filter values

  ##### Example

      // Array filter: filters the second index of the array by the value of a view property called 'selectedDay'
      function (viewProperties) {
          return {
              1: [viewProperties.get('selectedDay')]
          }
      }

      // Array filter: filters the 'DAY' index of the array by the value of a view property called 'selectedDay' and
      // filters the 'REGION' index of the array by hard-coded values.
      function (viewProperties) {
          return {
              'DAY': [viewProperties.get('selectedDay')],
              'REGION': ['SOUTH', 'WEST']
          }
      }

  Back to Top
ScenarioObserverOptions - { object }

  ##### Properties:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  disposeCallback | function | optional | to be called when the observer is disposed
  startCallback | function | optional | to be called when the observer is started

WithAttachmentsOptions - { object }

  ##### Properties:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  tags | string | Array.<string> | optional |  | List of tags to observe (if not provided, all attachments will be observed)
  filenames | string | Array.<string> | optional |  | List of filenames to observe (if not provided, all attachments will be observed)
  scenario | boolean | optional | true | Whether to notify the callback when scenario attachments are changed
  app | boolean | optional | true | Whether to notify the callback when app attachments are changed ScenarioObserver#withAttachments argument

Parent Topic Classes

© 2001-2026 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.