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', '<replace-this-with-client-id>')
setparam('insightscenario_secret', '<replace-this-with-secret>')
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', '<replace-this-with-client-id>')
setparam('insightscenario_secret', '<replace-this-with-secret>')
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/',
    '<replace-this-with-client-id>',
    '<replace-this-with-secret>')
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.

If your code is executing within an Insight 5 app on DMP, you can call ins~login with no parameters to log into the current Insight 5 component:

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

This logs in using the Insight user named "solutionclient" which will be different from the user executing the scenario - you will need to add the "solutionclient" user to any apps you want to access using "mminsightscenario" from the administration UI in Insight. Depending on what actions you want to perform, you may also need to grant additional authorities to the "solutionclient" user.

You can pass a dmpresource initialized for another component in the same solution:

declarations
  res:dmpresource
end-declarations
dmpinitcomp(res, "", "Xpress Insight", "My Simulation Component", "")
if res.status<>DMP_OK then
  writeln_('error finding component: ',res.lasterror)
  exit(1)
end-if

ins~login(res)
if ins~haserror then
  writeln_('error during login: ',ins~getlasterror)
  exit(1)
end-if

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

Model parameter values can be accessed as an array named 'parameters'; for example, a parameter 'DB_CONNECTION_STRING' can be read as follows:

public declarations
  dbConnectionString: string
end-declarations
ins~getscendata(SCENARIO_ID, [
    ins~getarrayelt('parameters', ['DB_CONNECTION_STRING'], ->dbConnectionString) ] )
if ins~haserror then
  writeln_('Error: ',ins~getlasterror)
end-if

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 value or Mosel variable in the local model from which which the new entity data will be read. So for example, to update the values of a scalar maxProfit and four entries of 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
end-declarations
prices('EU', 1) := 12.5
prices('EU', 2) := 13.0
prices('US', 1) := 10.0
prices('US', 2) := 10.0
ins~updatescendata(SCENARIO_ID, [ ins~setscalar('maxProfit', 98.1),
    ins~addarrayelts('prices', prices) ] )
if ins~haserror then
  writeln_('Error: ',ins~getlasterror)
else
  writeln('Entity values updated')
end-if