Authenticating

Using Executor Properties

The simplest way 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.dmpmanagerurl := "https://manager.dms.usw2.ficoanalyticcloud.com/"
  myexecutor.clientid := "vm5qh0y37c"
  myexecutor.secret := "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"
  ! myexecutor now initialized and can be used
end-model

To find the component URL, bring up the drop-down menu beside the component name in DMP 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 DMP Manager URL will be the URL for the DMP instance in which your component lives.

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>",
    "dmpManagerUrl": "<URL of DMP manager, 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/",
    "dmpManagerUrl": "https://manager.dms.usw2.ficoanalyticcloud.com/",
    "clientId": "vm5qh0y37c",
    "secret": "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"
  },
  "dev": {
    "componentUrl": "https://6tk0a8qheb-6tk0a8qheb.dms.usw2.ficoanalyticcloud.com/",
    "dmpManagerUrl": "https://manager.dms.usw2.ficoanalyticcloud.com/",
    "clientId": "vm5qh0y37c",
    "secret": "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"
  }
}

The JSON document must always specify the componentUrl, and either the bearerToken or all of the dmpManagerUrl, 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 save the above sample JSON in a file called "executors.json":

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, simply 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 first Xpress Executor component it finds in your solution:

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

  ! Initialize myexecutor for the first 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).

Note that within DMP, the Executor can only be accessed within the first 30 minutes of the Insight scenario execution - if you attempt to call any 'executor' functions after this, you may receive an EXECUTOR_ACCESS_DENIED error response.

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 LocalnitExample
  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 being initialized, 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.