Understanding Optimization Server Statements

Optimization Server tasks, also referred to as worker tasks, are executed remotely on an Optimization Server worker service. Their implementation is described in Chapter Implementing Worker Tasks. Once you have implemented a worker task, you can include its execution in the script of one of your tasks.

The ExecuteOptimizationServerTaskStatement.forTaskId(Expression taskId) method creates a statement that, when executed, executes the worker task with the provided ID on the Optimization Server. Additional information can be given for the execution of the worker task with the following methods.

  • usingOnDemandContext(Expression onDemandExecutionContext) provides a value for configuring the On-Demand job Execution Context. The On-Demand feature is only available on optimization servers deployed on Kubernetes. The worker and the different On-Demand Execution Contexts available are defined using a ConfigMap. For more details on the deployment of an "on demand" worker, please refer to the Optimization Server documentation, Chapter Workers .

    Note:

    Note that, if the On-Demand Context value is defined for a job that is run on an Optimization Server instance that is not deployed on Kubernetes (e.g. Docker), the specified value for onDemandExecutionContext is ignored.

  • withJobDescription(Expression description) provides a free-text description of the purpose of the worker task execution.

  • withInput(String name, Expression value) provides a value for the worker task input with the specified name, in accordance with the description of the worker task in the worker.yml file associated with the worker that implements the task.

  • withOutput(String outputName, String variableName) will store the value of the specified worker task output into the script memory under the specified variable name. This method is to be used for numeric, text, and binary outputs, which are mapped to the NUMBER, TEXT, and BLOB expression types, respectively.

  • withOutputScenario(String outputName, Expression scenarioId, Expression... filterTables) is to be used when the worker task output contains scenario data. The method will associate the output data with the scenario having the provided ID. Table names can be provided to restrict a subsequent save operation. The resulting scenario data will be stored in the script memory under the specified variable name, and saved to the database. Schema checkers will be run, and the schema status of the scenario updated. The variant withOutputScenarioCheckSchema(String outputName, Expression scenarioId, Expression checkSchema, Expression... filterTables) has an additional argument that must evaluate to a Boolean value; this value controls whether the schema checkers should be run on the scenario or not.

  • withFileOutput(String outputName, String variableName, Expression filename [, Expression mimeType]) is to be used when the worker task output is the content of a file. This method will associate the output data with a file having the provided name. A MIME type (used by web browsers to know how to handle the file as a task output) can be specified. The resulting file value will be stored in the script memory under the specified variable name.

  • withTaskGroupLabel(Expression label, Expression value) is used when the worker task belongs to a group on which limits have been defined based on job labels, to provide a value for the specified label. The label argument receives an expression that must evaluate to a string. The value argument receives an expression that can evaluate to any type that can be converted to a string. Note that if the worker task belongs to a group on which limits have been defined, this method must be called once for each of the labels included in the limits definition.

Except for the withJobDescription method, the methods above are typically repeated as many times as needed to address all the inputs, outputs, and task group limits of the worker task.

When a worker task is launched by executing an ExecuteOptimizationServerTaskStatement, the Optimization Server master process looks for a worker to execute the task. For more details, please refer to the Optimization Server documentation, Chapter Workers .

If all eligible workers are busy, the master process waits for certain amount of time. This amount can be configured in the Execution Service extension through the services.execution.dbos.scheduled-job-max-waiting-time Spring property, or the SERVICES_EXECUTION_DBOS_SCHEDULED_JOB_MAX_WAITING_TIME environment variable. Its default value is 30 minutes.

If the worker task emits a numeric output named com.decisionbrain.gene.exitCode, the value of this output is used as the exit code of the statement. Otherwise, the statement has exit code zero.

A worker task can receive an interruption signal as a result of user interaction, in two possible forms.

  • When the user selects the Stop Job command in the web client while the current step executes an Optimization Server task, the task is required to abort with the TERMINATE_WITH_NO_SOLUTION policy. It should then stop execution as soon as possible, with no requirement to emit any output. The job will then be stopped. For more details, please refer to Section Understanding Job Termination Statements

  • When the user presses the next step button in the job details view, while the current step executes an Optimization Server task. In this case, the task is required to abort with the TERMINATE_WITH_CURRENT_SOLUTION policy. The intent for this action is that the user considers (for example by looking at the task KPIs in the Optimization Server console) that the task computation has reached an acceptable state. It should then stop execution as soon as possible, but is required to emit its current solution as output. The job execution will then proceed to the next statement in the task script.