Output data for Decision Optimization deployment jobs

Last updated: Dec 05, 2024

When your submit a job, you can define what output data you want to use and how you collect it (as either inline or referenced data).

Inline Data

You can define how to collect your output data as inline data.

This example collects solution.csv output as inline data.

"output_data": [{
      "id":"solution.csv"
}]

Referenced data

When using data or connection assets for tabular data, use .csv as the data-identifier extension in the id field, regardless of the asset type. The data-connector makes the necessary transformations, so that you can save data in the target format without needing to change the format of the data. You can thus use the same Decision Optimization model with many different data-source types and formats by using a data-connector to reference your data. If you use other data-identifier extensions, the data is saved as a raw-data binary-file without any transformation.

To use referenced data in your request, you can adapt and use the following code examples.

Data assets

You can use data asset references to locate any data asset present in your space and benefit from the data-connector integration capabilities.

You can specify the location for the output by using an href, if the asset already exists in the space, and the asset is updated. For example,

      "location": {
           "href": "/v2/assets/<ASSET_ID>?space_id=<SPACE_ID>"
      }

You can also create an asset by specifying the asset name and a description. This example creates the asset solution.csv.

      "location": {
            "name": "solution.csv",
            "description": "solution description"
      }

This example defines output-data references to update a data asset in a space.

output_data_references": [{
      "type": "data_asset",
      "id" : "solution.csv",
      "connection": {},
      "location": {
            "href": "/v2/assets/<ASSET_ID>?space_id=<SPACE_ID>"
      }
}]

You can also save your output data as an asset with a different name by using the name field. This example creates an output asset named my_solution.csv in the current space.

"output_data_references": [{
      "type" : "data_asset",
      "id" : "solution.csv",
      "connection": {},
      "location": {
            "name": "my_solution.csv"
      }
}]

This example shows you how to save a Microsoft Excel file asset to a space.

"output_data_references": [{
      "type": "data_asset",
      "id": "kpis.csv",
      "connection": {},
      "location": {
            "id": "<SPACE_ID>"
            "name": "kpis.xlsx"
      }
}]

You can also use a regular expression as an identifier. For more information, see Regexp.

Connection assets

You can use connection assets to reference any data and then refer to the connection without having to specify credentials each time. Referencing a secure connection without having to use inline credentials in the payload also offers you better security. You can use the id to identify connections. For example,

"output_data_references": [{
      "type": "connection_asset",
      "id": "solution.csv",
      "connection": {
              "id" : "<CONNECTION_ID>",
      }
      "location": {  
              <data-connector interaction properties depending on connection type>
      }
}]

The <CONNECTION_ID> is the globally unique identifier for a connection. You can find this identifier when you have created a connection and you then edit the connection in your project. The identifier is visible in the Edit connection window's URL.

For information about job definitions, see Deployment job definitions.

You can specify the interaction properties that are required for the connection in the location field.

This example connects to a COS/S3 bucket. The interaction properties are provided in the location field.

      "location": {
            "file_name" : "<FILENAME>",
            "bucket" : "<BUCKET_NAME>"
      }

This example connects to a Db2 asset. The interaction properties are provided in the location field.

      "location": {
            "table_name" : "<TABLE_NAME>",
            "schema_name" : "<SCHEMA_NAME>"
      }

This example connects to a COS/S3 bucket. The connection reference is provided in the id field.

"output_data_references": [{
      "type": "connection_asset",
      "id": "diet_food.csv",
      "connection": {
            "id" : "<CONNECTION_ID>"
      },
      "location": {
            "file_name" : "<FILENAME>",
            "bucket" : "<BUCKET_NAME>"
      }
}]

This example shows you how to save a Microsoft Excel file to a COS/S3 bucket.

"output_data_references": [{
      "type": "kpis.csv",
      "id": "kpis.csv",
      "connection": {
            "id" : "<CONNECTION_ID>"
      },
      "location": {
            "file_name" : "<kpis.xlsx>",
            "bucket" : "<BUCKET_NAME>"
      }
}]

This example shows you how to connect to a Db2 asset. The connection reference is are provided in the id field.

"output_data_references": [{
      "type" : "connection_asset",
      "id" : "solution.csv",
      "connection" : {
            "id" : "<CONNECTION_ID>"
      },
      "location" : {
            "table_name" : "<TABLE_NAME>",
            "schema_name" : "<SCHEMA_NAME>"
      }
}]

For more information about the interaction properties that you can use in the location field, see Platform connections in the main menu. On the Connections page, select Connection resources > Connection properties. Then select the Interaction properties > As a target tab for the relevant connector. You might need to create a Platform assets catalog.

For more information about the different connections available for Decision Optimization, see Supported data sources in Decision Optimization.

URL-referenced data

You can use URL-referenced data to store data at a particular URL.

This example uses the PUT command to place the solution.csv output file on the server.

"output_data_references": {
      "type": "url",
      "id": "solution.csv",
      "connection": {
            "verb": "PUT",
            "url": "https://myserver.com/diet_food.csv",
            "headers": {
                  "Content-Type": "application/x-www-form-urlencoded"
            }
      },
      "location": {}
}

Regexp

You can use a Regexp as an identifier for all types of outputs. For example to collect all .csv output files:

"id":".*\\.csv"

Or all output files of any kind:

"id":".*"

You can use a Regexp as an identifier, and combine it with ${oaas_job_id} and ${oaas_attachment_name} place holders in the name, to create an output asset each time the job is run.

"output_data_references": [{
      "type" : "data_asset",
      "id" : ".*",
      "connection": {
            "href" : "/v2/connections/<CONNECTION_ID>?space_id=><SPACE_ID>"
      },
      "location": {
            "name" : "${oaas_job_id}_${oaas_attachment_name}"
      }
}]

This example creates a file in a job-specific COS/S3 folder for each output returned by the model. If, for example, a solution.csv file is generated as output, this file is saved in a folder that has the same name as the job number.

"output_data_references": [{
      "type" : "connection_asset",
      "id" : ".*",
      "connection": {
            "id" : "<CONNECTION_ID>"
      },
      "location": {
            "bucket" : "<BUCKET_NAME>",
            "file_name": "${oaas_job_id}/${oaas_attachment_name}"
      }
}]

You can combine different types of data in the same request. For more information about data definitions, see Adding data to an analytics project.