REST API for Oracle Analytics Server

Run a data flow

post

/api/20210901/catalog/dataflows/{dataflowId}/actions/run

Run an existing data flow with a given id. If the request body includes parameters, the data flow runs with the given parameters. If no request body is provided, the data flow runs as-is. Returns an oa-work-request-id so you can monitor progress.

Request

Path Parameters

dataflowId(required): string(byte)

The object ID of the data flow with Base64URL encoding. For example, if your data flow has the object ID 'User1'.'dataflow1', enter the Base64URL encoded value, J1VzZXIxJy4nZGF0YWZsb3cxJw==.

Supported Media Types

application/json

Root Schema : schema

Type: object

Show Source

appName: string

Value of an application to be replaced and run.
appParameterName: string

Identifier of an application to be replaced.
cubeName: string

Value of a cube to be replaced and run.
cubeParameterName: string

Identifier of a cube to be replaced.
datasetName: string

Display name of a dataset to be replaced and run.
parameterName: string

Identifier of a source or target dataset to be replaced.
type: string

Type of parameter, there are 3 values:\ source, target, and cube.

{
    "properties":{
        "parameterName":{
            "type":"string",
            "description":"Identifier of a source or target dataset to be replaced."
        },
        "datasetName":{
            "type":"string",
            "description":"Display name of a dataset to be replaced and run."
        },
        "type":{
            "type":"string",
            "description":"Type of parameter, there are 3 values:\\ source, target, and cube."
        },
        "appParameterName":{
            "type":"string",
            "description":"Identifier of an application to be replaced."
        },
        "appName":{
            "type":"string",
            "description":"Value of an application to be replaced and run."
        },
        "cubeParameterName":{
            "type":"string",
            "description":"Identifier of a cube to be replaced."
        },
        "cubeName":{
            "type":"string",
            "description":"Value of a cube to be replaced and run."
        }
    }
}

Response

202 Response

Asynchronous operation started.

Headers

oa-work-request-id:

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

403 Response

Forbidden (missing permissions for operation, request denied for unspecified reason, and so on).

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

404 Response

Not Found. The requested resource was not found.

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

409 Response

Conflict (operation results in constraint violation, the operation is incompatible with the current state, and so on).

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

Examples

These examples show you how to run a data flow with a given dataflowID with or without parameters.

Example 1 - Run a data flow without parameters
Example 2 - Run a data flow with parameters
Example 3 - Run a data flow with parameters defined in a JSON file (multiple dataset targets)
Example 4 - Run a data flow with parameters in a JSON file (Essbase cube target)

When you run a data flow, you can specify several, optional parameters in the request body. Parameters allow you to specify inputs and outputs for the data flow at runtime.

parameterName - Identifier for a source dataset or a target dataset to be replaced.
datasetName - Name of the dataset. The dataset must exist and you must have permission to use the dataset in the data flow.
type - Type of data flow parameter. Valid values: source, target, cube
appParameterName - Identifier for the target Essbase application.
appName - Name of the target Essbase application.
cubeParameterName - Identifier for the target Essbase cube.
cubeName - Name of the target Essbase cube.

Example 1 Run a data flow without parameters

In this example, you run a data flow job with a given dataflowID. The object ID of the data flow is 'adminuser'.'mySalesDataFlow2024' which has the Base64URL-safe encoded dataflowID value: J2FkbWludXNlcicuJ215U2FsZXNEYXRhRmxvdzIwMjQn

cURL Example:

First, obtain the object ID of the data flow you want to run and Base64URL-safe encode this value to determine the dataflowID. You can obtain the Object ID value from the Inspect dialog for data flow in Oracle Analytics Server.

Run the cURL command with the required dataflowID:

curl -i \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request POST 'https://<hostname>/api/20210901/catalog/dataflows/J2FkbWludXNlcicuJ215U2FsZXNEYXRhRmxvdzIwMjQn/actions/run' \

Example of Request Body

None required

Example of Response Header

Not applicable.

Example of Response Body

Status 200:

Example 2 Run a data flow with parameters

In this example, you run a data flow with source and target parameters. The object ID of the data flow is 'adminuser'.'myOrdersDataFlow2024' which has the Base64URL-safe encoded dataflowID value: J2FkbWludXNlcicuJ215T3JkZXJzRGF0YUZsb3cyMDI0Jw

Source parameters - Identify one or more dataset sources for the data flow. In this example, the input to the data flow is a single dataset, SalesDataset.
Target parameters - Identify one or more datasets output from the data flow. In this example, the output from the data flow is a single dataset, mySalesDataset2024.

cURL Example:

Run the cURL command with the required dataflowID:

curl -i \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request POST 'https://<hostname>/api/20210901/catalog/dataflows/J2FkbWludXNlcicuJ215T3JkZXJzRGF0YUZsb3cyMDI0Jw/actions/run' \
     --data '{ "parameters": [ \
               { "parameterName": Source Input", "datasetName": "SalesDataset", "type": "source" },
               { "parameterName": "Target Output", "datasetName": "mySalesDataset2024", "type": "target" }]}'

Example of Request Body

{"parameters":       
      [
            {
               "parameterName":"Source Input",
               "datasetName":"SalesDataset",
               "type":"source"
             },            
             {
               "parameterName": "Target Output",
               "datasetName": "mySalesDataset2024",  
               "type": "target"
            }
       ]
}

Example of Response Header

Not applicable.

Example of Response Body

Status 200:

Example 3 Run a data flow with parameters defined in a JSON file (multiple dataset targets)

In this example, you run a data flow with multiple source and target parameters defined in a JSON file (mydataflowparameters.json). The object ID of the data flow is 'adminuser'.'myProductSalesDataFlow2024' which has the Base64URL-safe encoded dataflowID value: J2FkbWludXNlcicuJ215UHJvZHVjdFNhbGVzRGF0YUZsb3cyMDI0Jw

Source parameters - Identify one or more dataset sources for the data flow. In this example, there are two inputs to the data flow: Product1Dataset and Product2Dataset.
Target parameters - Identify one or more datasets output from the data flow. In this example, there are two outputs from the data flow: myProduct1Dataset2024 and myProduct2Dataset2024.

cURL Example:

Next, create a JSON file that contains the parameters required to run the data flow. For example, create a JSON file called mydataflowparameters.json with a payload that looks like this.

{"parameters":       
      [
            {
               "parameterName":"Source Input - Product1",
               "datasetName":"Product1Dataset",
               "type":"source"
             },            
             {
               "parameterName": "Source Input - Product2",
               "datasetName": "Product2Dataset",  
               "type": "source"
            },          
            {
               "parameterName": "Target Output - newDatasetProduct1",     
               "datasetName": "myProduct1Dataset2024",
               "type":"target"
            },
            {
               "parameterName": "Target Output - newDatasetProduct2",
               "datasetName": "myProduct2Dataset2024",
               "type": "target"       
            }
       ]
}

Run the cURL command with the required dataflowID:

curl -i \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request POST 'https://<hostname>/api/20210901/catalog/dataflows/J2FkbWludXNlcicuJ215UHJvZHVjdFNhbGVzRGF0YUZsb3cyMDI0Jw/actions/run' \
     --data @mydataflowparameters.json

Example of Response Header

Not applicable.

Example of Response Body

Status 200:

Example 3 Run a data flow with parameters defined in a JSON file (Essbase cube target)

In this example, you run a data flow with source and target parameters defined in a JSON file (mydataflowcubeparameters.json). The object ID of the data flow is 'adminuser'.'mySalesDataFlow' which has the Base64URL-safe encoded dataflowID value: J2FkbWludXNlcicuJ215U2FsZXNEYXRhRmxvdyc=

Source parameters - Identify one or more dataset sources for the data flow. In this example, there is one input to the data flow: SalesDataset.
Target parameters - Identify a target Essbase application and cube output from the data flow. In this example: MyEssbaseApp and MySalesCube.

cURL Example:

Next, create a JSON file that contains the parameters required to run the data flow. For example, create a JSON file called mydataflowcubeparameters.json with a payload that looks like this.

{
         "parameters":
         [
            {
               "parameterName": "Source Input",
               "datasetName": "SalesDataset",
               "type": "source"
             },
             {
               "appParameterName": "Target - MyEssbaseApp",
               "appName": "MyEssbaseApp",
               "cubeParameterName": "Target - MySalesCube",
               "cubeName": "MySalesCube",
               "type": "cube"
            }
         ]
}

Run the cURL command with the required dataflowID:

curl -i \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request POST 'https://<hostname>/api/20210901/catalog/dataflows/J2FkbWludXNlcicuJ215U2FsZXNEYXRhRmxvdyc=/actions/run' \
     --data @mydataflowcubeparameters.json

Example of Response Header

Not applicable.

Example of Response Body

Status 200: