Insight Scenario Access Package

Topics covered in this chapter:

Introduction

The Insight scenario access package mminsightscenario offers a high-level client for interacting with an Insight v5 server using the REST webservice interfaces. You can use mminsightscenario to create/update/delete apps, folders and scenarios; to read and write entity data, to access and update scenario and app attachments, as well as execute scenarios.

mminsightscenario can be used both inside and outside of Insight apps. When used within an Insight scenario, there is no relationship between the calls made through mminsightscenario and the currently running scenario (any reads/writes behave as though they came from outside of the scenario).

Relationship to mminsightrestapi

The mminsightscenario and mminsightrestapi packages both offer ways to interact with the Insight v5 REST webservice interface. mminsightscenario aims to offer a user-friendly API targeting the most commonly used functionality, whereas mminsightrestapi is a direct implementation of the webservice operations as Mosel subroutines. As mminsightrestapi can be more difficult to call, it is recommended developers use mminsightscenario where possible, and only use mminsightrestapi to perform tasks not supported by mminsightscenario.

If necessary, both packages can be used within the same model.

Getting Started with mminsightscenario

To use the package, import it at the top of your model, e.g.:

model mymodel
  imports 'mminsightscenario'
  namespace ins

When using the package from an Insight app, it is important to reference the package using imports and not uses, as mminsightscenario is not supplied with the Insight 5 worker and thus the app must have imported it at build-time.

All the subroutines and records defined in this package are within the ins namespace.

Before you can communicate with the Insight server, you must call the ins~login procedure to tell the package the URL of the Insight v5 server, and the client ID and secret values that will be used to authenticate your session. Where you are running Mosel without restrictions on your local account, it's recommended that you pass just the Insight URL and allow the client ID and secret to be read from the local secure storage (such as the Windows Credential Manager or Mac keychain; see the section Providing REST API credentials for instructions on configuring this).

ins~login('http://localhost:8080/')
if ins~haserror then
  writeln_('error during login: ',ins~getlasterror)
  exit(1)
end-if

But if this is not suitable for your use case, you can pass the client ID and secret using the insightscenario_clientid and insightscenario_secret package parameters, e.g.:

setparam('insightscenario_clientid', 'NWFiNmYxYjctYTE2Ny00YmY1LTk5J#111')
setparam('insightscenario_secret', 'dPrqZo4QVx84LPJ5wczJWn9chknNbN8t')
ins~login('http://localhost:8080/')
if ins~haserror then
  writeln_('error during login: ',ins~getlasterror)
  exit(1)
end-if

You can pass the server URL as a parameter as well:

setparam('insightscenario_url', 'http://localhost:8080/')
setparam('insightscenario_clientid', 'NWFiNmYxYjctYTE2Ny00YmY1LTk5J#111')
setparam('insightscenario_secret', 'dPrqZo4QVx84LPJ5wczJWn9chknNbN8t')
ins~login
if ins~haserror then
  writeln_('error during login: ',ins~getlasterror)
  exit(1)
end-if

Or as a final alternative, all three values can be passed as subroutine arguments, e.g.:

ins~login('http://localhost:8080/',
    'NWFiNmYxYjctYTE2Ny00YmY1LTk5J#111',
    'dPrqZo4QVx84LPJ5wczJWn9chknNbN8t')
if ins~haserror then
  writeln_('error during login: ',ins~getlasterror)
  exit(1)
end-if

The client ID and secret are credentials giving access to your Insight 5 account - you should never hard-code them in a Mosel source file. Requests you make throught the mminsightscenario package will be performed as the user that generated the client ID and secret, and the operations that can be performed will be restricted by the authorities granted to that account.

Once you've called ins~login, you can call any of the other subroutines to send requests to the Insight server. For example, to list all the apps that are visible to your user account:

declarations
  apps: list of ins~app
end-declarations
apps := ins~getapps
if ins~haserror then
  writeln_('error fetching apps list: ',ins~getlasterror)
  exit(1)
end-if
forall(app in apps)
  writeln('Found app: ', app.name)

After every call to an mminsightscenario subroutine, you should check ins~haserror to see if it succeeded. An error could be anything from a network issue interrupting communication with Insight, to the account not having the rights to access the resource requested, to someone else having deleted the resource while we were using it. If you don't want to have to handle these errors, you can set the insightscenario_failonerror parameter and your model will automatically exit when an error is encountered:

setparam('insightscenario_failonerror', true)
declarations
  apps: list of ins~app
end-declarations
apps := ins~getapps
! Will not get this far if ins~getapp fails for any reason
forall(app in apps)
  writeln('Found app: ', app.name)

Some failed requests to the Insight server will automatically be retried before an error is returned. Sometimes, this will result in a delay before you see an error message; if you want requests to fail faster, you can control the number of retries using the dmp_max_retries parameter:

setparam('dmp_max_retries', 2)  ! Retry each failure twice

Reading Entity Values

When reading scenario data, you fetch all the entities you want in a single call, rather than making a separate call for each entity — this is both more efficient and ensures you are reading consistent data (i.e. the scenario isn't updated between fetches of two entities). To do this, you pass ins~getscendata a list of ins~entityfetch values created by the following functions:

• ins~getscalar
• ins~getscalars
• ins~getset
• ins~getarrayelt
• ins~getarray

Consult the individual function documentation for details on how to use each one, but they are all passed the name of the entity and a reference to a Mosel variable in the local model into which the entity will be read. So for example, to fetch the values of a scalar maxProfit and an array Prices:

declarations
  SCENARIO_ID='2926e9a1-9568-4116-84ed-2e75190bc651'
  Regions: set of string
  Months: set of integer
  Prices: dynamic array(regions, months) of real
  profitLimit: real
end-declarations
ins~getscendata(SCENARIO_ID, [ ins~getscalar('maxProfit', ->profitLimit),
    ins~getarray('Prices', Prices) ] )
if ins~haserror then
  writeln_('Error: ',ins~getlasterror)
else
  writeln('Maximum profit: ', profitLimit)
  forall (region in Regions, month in Months | exists(Prices(region,month))) do
    writeln('Price in ', region, ' for month #', month, ': ', Prices(region,month))
  end-do
end-if

The ins~getscendata will convert between the value types returned by the Insight REST API, and the types of the variables in your model. The supported value types are:

• boolean
• integer
• real
• string
• text
• constant text – for sets
• any – to use the type returned by the Insight REST API

Updating Entity Values

When updating scenario data, you update all the entities you want in a single call, rather than making a separate call for each entity - this is both more efficient and ensures the scenario always has consistent data (i.e. nobody can read the scenario data between the updates of two entities). To do this, you pass ins~updatescendata a list of ins~entityupdate values created by the following functions:

• ins~setscalar
• ins~setscalars
• ins~addsetelts
• ins~delsetelts
• ins~addarrayelt
• ins~addarrayelts
• ins~delarrayelt
• ins~delarrayelts

Consult the individual function documentation for details on how to use each one, but they are all passed the name of the entity and a reference to a Mosel variable in the local model into which the entity will be read. So for example, to fetch the values of a scalar maxProfit and an array prices:

declarations
  SCENARIO_ID='2926e9a1-9568-4116-84ed-2e75190bc651'
  regions: set of string
  months: set of integer
  prices: dynamic array(regions, months) of real
  profitLimit: real
end-declarations
ins~getscendata(SCENARIO_ID, [ ins~getscalar('maxProfit', ->profitLimit),
    ins~getarray('prices', prices) ] )
if ins~haserror then
  writeln_('Error: ',ins~getlasterror)
else
  writeln('Maximum profit: ', profitLimit)
  forall (region in regions, month in months | exists(prices(region,month))) do
    writeln('Price in ', region, ' for month #', month, ': ', prices(region,month))
  end-do
end-if

Error handling

Authentication

User Management

Data Types

ins~user  : record

Information about a user on the Insight server
id  : text
	The ID of this user
username  : text
	This user's username
name  : text
	This user's full name
firstname  : text
	This user's first name
lastname  : text
	This user's last name
email  : text
	The email address of this user
status  : string
	The status of this user's account (Value should be one of: ACTIVE,DELETED,DISABLED,LOCKED)
See also	ins~getuser

Subroutines

Apps

Data Types

ins~app  : record

Information about an app on the Insight server.
id  : text
	The ID of this app
name  : text
	The name of this app
path  : text
	The path within the repository
appver  : text
	The model version
dataver  : integer
	The model data version
See also	ins~getapp, ins~getapps

ins~appmember  : record

Information about a member of an app on the Insight server.
id  : text
	The ID of this user
name  : text
	This user's full name
firstname  : text
	This user's first name
lastname  : text
	This user's last name
See also	ins~getappmembers ins~user

Subroutines

App Attachments

Data Types

ins~attachment  : record

Information about a label/tag which can be applied to one or more attachments depending on its properties.
id  : text
	The ID of this attachment
filename  : text
	The file name of this attachment
description  : text
	A description of this attachment
hidden  : boolean
	Whether the attachment is hidden. This indicates the attachment is not for general user interaction
lastmod  : text
	When the attachment contents were last modified
lastmodby  : text
	The ID of the user who last modified this attachment
appid  : text
	The ID of the app that this attachment belongs to
parentid  : text
	The ID of the app or scenario that is the parent of this attachment. For app attachments, this will be the same as the appid value.
parenttype  : string
	The type of the parent of this attachment, either APP or SCENARIO
tags  : list of text
	The tags that are present on this attachment
size  : real
	The size of this attachment in bytes
See also	ins~getappattachinfo, ins~setappattachinfo, ins~getallappattachinfo, ins~getscenattachinfo, ins~setscenattachinfo, ins~getallscenattachinfo

ins~attachtag  : record

Information about a label/tag which can be applied to one or more attachments depending on its properties.
name  : text
	Unique name of the tag
description  : text
	A human-readable description for this tag
mandatory  : boolean
	Whether this tag must be present on at least one attachment belonging to the app or scenario
multifile  : boolean
	Whether this tag can be present on multiple attachments
See also	ins~getattachtags

Subroutines

Scenario Attachments

Subroutines

Scenarios

Data Types

ins~scenario  : record

Information about a scenario.
id  : text
	The ID of this scenario
created  : text
	The timestamp this scenario was created
ownerid  : text
	The ID of the user that owns this scenario
ownername  : text
	The full name of the user that owns this scenario
appid  : text
	The ID of the app that owns this scenario
parentid  : text
	The ID of the app or folder that is the parent of this scenario. For top-level scenarios this will be the same as the appid value.
parenttype  : string
	The type of the parent of this attachment, either APP or FOLDER
name  : text
	The name of this scenario
path  : text
	The path within the repository
type  : text
	The scenario's custom type if it has one, otherwise SCENARIO.
sharestatus  : string
	The share status of this scenario (one of: FULLACCESS, PRIVATE, READONLY)
datastate  : string
	The current state of this scenario's data (one of: LOADED, RESULTS,, RESULTS_DIRTY, UNLOADED)
execduration  : real
	The duration of the last execution of this scenario in milliseconds
execmode  : text
	The execution mode for the last execution
execusername  : text
	The full name of the user that last executed this scenario
execuserid  : text
	The ID of the user that last executed this scenario
dataver  : integer
	The version number of the model data
status  : string
	The model status for this scenario (one of: OK, BREAK, ERROR, EXIT, INSTR, IOERR, LICERR , MATHERR, NA, NIFCT, NULL, PROB, STOP, UNKNOWN, UNKN_PF, UNKN_SYS)
probstatus  : string
	The problem status for this scenario (one of: INFEASIBLE, NA, OPTIMAL, OTHER, SOLUTION, UNBOUNDED, UNFINISHED, UNKNOWN)
execstart  : text
	Timestamp when this scenario last started loading or executing
execfinish  : text
	Timestamp when this scenario last finished loading or executing
See also	ins~getscen

Subroutines

Reading Scenario Data

Data Types

ins~entityfetch  : record

Information about an entity that is to be fetched from the Insight scenario.
Note	Use the supplied functions to create a list of ins~entityfetch values and then pass to ins~getscendata to fetch atomically fetch all the entities.
See also	ins~getscalar ins~getscalars ins~getset ins~getarrayelt ins~getarray ins~getscendata

Subroutines

Updating Scenario Data

Data Types

ins~entityupdate  : record

Information about an entity that is to be updated on the Insight scenario.
Note	Use the supplied functions to create a list of ins~entityupdate values and then pass to ins~updatescendata to fetch atomically update all the entities.
See also	ins~setscalar, ins~setscalars, ins~addsetelts, ins~delsetelts, ins~addarrayelt, ins~addarrayelts, ins~delarrayelt, ins~delarrayelts

Subroutines

Folders

Data Types

ins~folder  : record

Information about a folder within an app.
id  : text
	The ID of this folder
appid  : text
	The ID of the app that this folder belongs to
parentid  : text
	The ID of the app or folder that is the parent of this folder. For top-level folders, this will be the same as the appid value.
parenttype  : string
	The type of the parent of this folder, either APP or FOLDER
name  : text
	The name of this folder
path  : text
	The path within the repository
ownerid  : text
	The ID of the user that owns this folder
ownername  : text
	The full name of the user that owns this folder
sharestatus  : string
	The share status of this folder (one of: FULLACCESS, PRIVATE, READONLY)
See also	ins~getappchildren, ins~getfolder

Subroutines

Control Parameters