Insight Scenario REST API client

Topics covered in this chapter:

Introduction

The subpackage xpressinsight.scenario can be used to interact with an Insight v5 server using the REST web service interface. You can use the xpressinsight.scenario package to create, update and delete apps, folders and scenarios; to read and write entity data; to access and update scenario and app attachments, and to execute scenarios.

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

Your Python script file should import the xpressinsight.scenario package in the usual way:

import xpressinsight.scenario as ins

Thereafter, all xpressinsight.scenario types can be accessed by prepending "ins.". This is the standard way of importing the xpressinsight.scenario package. Many example fragments given in this document will assume that the package has been imported in this way.

After importing, you must instantiate an ins.InsightRestClient object, passing in the URL of the Insight server. Authentication information (client-id and secret values, generated from the Insight UI) are read from the Windows credential manager or Mac keychain entry named "ficoxpress:<insight_server_url>" (where <insight_server_url> is the URL of the Insight server); consult the Insight 5 documentation for detailed instructions on how to configure this. For example:

client = ins.InsightRestClient('http://localhost:8080/')

When running on Mac, the client ID must be passed to the InsightRestClient constructor to enable the keychain entry to be found:

client = ins.InsightRestClient('http://localhost:8080/',
    client_id='<replace-this-with-client-id>')

Alternately, on any platform, the credentials can be passed explicitly as arguments in the Python script:

client = ins.InsightRestClient('http://localhost:8080/',
    client_id='<replace-this-with-client-id>',
    secret='<replace-this-with-secret>')

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

When you want to use the InsightRestClient from within an Insight app, you can instantiate it from the AppInterface.get_rest_client function, which avoids passing the insight URL, e.g.:

client = self.insight.get_rest_client(
    client_id='<replace-this-with-client-id>',
    secret='<replace-this-with-secret>')

Finally, if your Insight app is running within DMP, you can omit the client_id and secret entirely. When you do this, InsightRestClient automatically makes requests under an Insight user named "solutionclient", and must add this user to any apps you want to access, using the Insight administration UI. Depending on which actions you want to perform, you might also need to grant additional authorities to the "solutionclient" user.

client = self.insight.get_rest_client()
#  client authorized using 'solutionclient' user

By whatever method you create your InsightRestClient instance, you can then use it to perform operations using the Insight 5 REST API. For example, to create a new scenario within an app:

my_scenario = client.create_scenario(
    name='My New Scenario',
    parent=ins.reference.to_app('570b9100-46e3-4643-baee--2e24aa538f25'))

Or to read the 'factories' frame from a scenario:

@xi.ScenarioData()
class FactoriesInfo:
    factories: xi.data.DataFrame(columns=[
        xi.data.Column('costs'),
        xi.data.Column('units_manufactured')
    ])

my_factories_info = client.get_scenario_data(
    scenario_id='bfc697fb-53e7-435b-ade0-0b4b632134b4',
    scenario_data_class=FactoryInfo)

Full details on the functions supported can be found in xpressinsight.scenario.InsightRestClient.

The InsightRestClient classes

xpressinsight.scenario.InsightRestClient

xpressinsight.scenario.App

xpressinsight.scenario.AppCreationResponse

xpressinsight.scenario.AppMember

xpressinsight.scenario.AppUpgradeResponse

xpressinsight.scenario.ArrayUpdate

xpressinsight.scenario.Attachment

xpressinsight.scenario.AttachmentTag

xpressinsight.scenario.AttachmentUpdate

xpressinsight.scenario.BearerToken

xpressinsight.scenario.EntityUpdate

xpressinsight.scenario.Folder

xpressinsight.scenario.IndexUpdate

xpressinsight.scenario.ModelStatus

xpressinsight.scenario.ObjectType

xpressinsight.scenario.ProblemStatus

xpressinsight.scenario.Reference

xpressinsight.scenario.ScalarUpdate

xpressinsight.scenario.Scenario

xpressinsight.scenario.ScenarioDataState

xpressinsight.scenario.ScenarioSummary

xpressinsight.scenario.ShareStatus

xpressinsight.scenario.User

xpressinsight.scenario.UserStatus