Authenticating

Topics covered in this chapter:

Using Executor Properties

This section assumes you have an Executor component available in your active FICO DMP Solution. Open the Library and select your Solution containing your Executor component.

The simplest way to specify the Executor component URL and authorization credentials is to define the corresponding properties of your Executor entity, for example:

model DirectInitExample
  uses "executor"
  declarations
    myexecutor: Executor
  end-declarations

  myexecutor.componenturl := "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/"
  myexecutor.bearertokenurl := "https://iam-svc.dms.usw2.ficoanalyticcloud.com/registration/rest/client/token"
  myexecutor.clientid := "vm5qh0y37c"
  myexecutor.secret := "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"
  ! myexecutor now initialized and can be used
end-model

To find the component URL, navigate to your DMP Solution and open the drop-down menu by clicking the chevron beside the component name and select "View Links". Use the value from the 'REST' field but remove everything after the domain name. For example, if the link displayed is:

https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/rest/runtime/execution?solutionID=vm5qh0y37c

then use

https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/

The clientid and secret values for your solution can be found on the "Client Apps" page of the solution screen in DMP. Finally, the bearertokenurl will be the URL from where we will obtain DMP authentication tokens - consult the "Requesting a Bearer Token" page of the DMP documentation for more details.

If you prefer to manage the authentication with DMP yourself, you can alternately initialize the Executor with the component URL and a DMP bearer token, e.g.:

model DirectInitExample
  uses "executor"
  declarations
    myexecutor: Executor
  end-declarations

  myexecutor.componenturl := "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/"
  myexecutor.bearertoken := "xyfuehdsoguihUGHifsihf7hi"
  ! myexecutor now initialized and can be used
end-model

However, note you will need to refresh the 'bearertoken' value periodically as the tokens will expire. If you initialize with clientid and secret, the 'executor' module will request new bearer tokens when it needs to.

Using a JSON Configuration File

As an alternative to setting credentials in the model, you can specify them in a JSON document, the contents of which you assign to the executor_components parameter. The document should be in the following format:

{
  "<component-id>": {
    "componentUrl": "<URL of component>",
    "bearerTokenUrl": "<URL of DMP authentication service, optional>",
    "clientId": "<clientId of DMP solution, optional>",
    "secret": "<secret of DMP solution, optional>",
    "bearerToken": "<DMP bearer token, optional>"
  }
}

The "<component-id>" string is a key that you use to refer to the component in the JSON and has no other meaning. You can specify multiple components in the same JSON file so long as they have different "<component-id>" strings, e.g.:

{
  "main": {
    "componentUrl": "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/",
    "bearerTokenUrl": "https://iam-svc.dms.usw2.ficoanalyticcloud.com/registration/rest/client/token",
    "clientId": "vm5qh0y37c",
    "secret": "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"
  },
  "dev": {
    "componentUrl": "https://6tk0a8qheb-6tk0a8qheb.dms.usw2.ficoanalyticcloud.com/",
    "bearerTokenUrl": "https://iam-svc.dms.usw2.ficoanalyticcloud.com/registration/rest/client/token",
    "clientId": "vm5qh0y37c",
    "secret": "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"
  }
}

The JSON document must always specify the componentUrl, and either the bearerToken or all of the bearerTokenUrl, clientId and secret values. If you do specify your own bearer token, be aware that it will eventually expire.

Then you can initialize an Executor in the model with the credentials from the JSON by calling the executorinit procedure. For example, if you've saved the above sample JSON in a file called "executors.json", then you can do:

model InitExample
  uses "executor","mmsystem"
  declarations
    public jsoncfg: text
    myexecutor: Executor
  end-declarations

  ! Load executors.json into a variable so it can be passed to a parameter
  fcopy("executors.json","text:jsoncfg")
  setparam("executor_components",string(jsoncfg))

  ! Initialize myexecutor using the 'main' set of credentials
  executorinit(myexecutor, "main")
  if myexecutor.status<>EXECUTOR_OK then
    writeln("Executor initialization error: ", myexecutor.lasterror)
    exit(1)
  end-if
  ! myexecutor now initialized and can be used
end-model

The executor_components parameter is special in that it has a single value shared by all models within the Mosel instance - this means that if, for example, you set it for your master model, then the same value will be used for all submodels that you start in the same Mosel process.

Using from Xpress Insight in DMP

When using Xpress Insight within DMP, the Mosel instance will automatically be configured to access any Xpress Executor components in the same solution. To use this, call executorinit, passing the name of your Xpress Executor component:

model DmpInitExample
  uses "executor"
  declarations
    myexecutor: Executor
  end-declarations

  ! Initialize myexecutor for the component called "My Executor"
  executorinit(myexecutor, "My Executor")
  if myexecutor.status<>EXECUTOR_OK then
    writeln("Executor initialization error: ", myexecutor.lasterror)
    exit(1)
  end-if
  ! myexecutor now initialized and can be used
end-model

Alternatively, if you call executorinit without a name, it will access the Xpress Executor component it finds in your solution:

model DmpInitExample
  uses "executor"
  declarations
    myexecutor: Executor
  end-declarations

  ! Initialize myexecutor for the an Xpress Executor component we find
  executorinit(myexecutor)
  if myexecutor.status<>EXECUTOR_OK then
    writeln("Executor initialization error: ", myexecutor.lasterror)
    exit(1)
  end-if
  ! myexecutor now initialized and can be used
end-model

The Insight component instance will access Executor instances in the same lifecycle stage (for example, an Insight in the staging environment will access the staging environment of Executor, not production or design). You can override this by specifying the environment on the 'executorinit' line, for example:

model DmpInitExample
  uses "executor"
  declarations
    myexecutor: Executor
  end-declarations

  ! Initialize myexecutor for the an Xpress Executor component we find
  executorinit(myexecutor,"My Executor","STAGING")
  if myexecutor.status<>EXECUTOR_OK then
    writeln("Executor initialization error: ", myexecutor.lasterror)
    exit(1)
  end-if
  ! myexecutor now initialized and can be used
end-model

This method cannot be used to access the Executor component from Xpress Insight 5. Instead, an Insight 5 app should call DMP Manager webservices to find the Executor component URL, and set the componenturl and bearertoken properties as described in the section Using Executor Properties.

Using local development mode

An Executor can also be initialized in a 'local' mode that does not require a DMP component. In this configuration, Executor will run any submitted executions locally using Mosel submodels. This can be configured as follows:

model LocalInitExample
  uses "executor"
  declarations
    myexecutor: Executor
  end-declarations

  ! Initialize myexecutor to simulate a Xpress Executor component using local submodels
  executorinitlocal(myexecutor)
  if myexecutor.status<>EXECUTOR_OK then
    writeln("Executor initialization error: ", myexecutor.lasterror)
    exit(1)
  end-if
  ! myexecutor now initialized and can be used
end-model

After initialization, the 'local' executor will always have an empty configuration, so you should call executorsetmodelfile and executorsetexecmode to configure it.

Once configured, you can interact with the local execution using the same functions as you would use for a true Xpress Executor component (e.g. executorexecute, executorwaitfor, executorfetchresult, ...). Local execution is supplied as an aid in developing your model and there may be small differences between how your model reacts to errors locally and how it behaves in a real Xpress Executor.

Note that the local Xpress Executor does not support the MPS or LP file execution mode, and the progress field of the ModelExecution record will always contain 0 regardless of the progress events emitted by your models.