# Data Sources

The data sources API is responsible for managing data sources in FDPlan.

A **data source** is a versioned input bundle consumed by scenario evaluations. It pairs a
user-facing `source` (a registered data type and its `store`) with one `target` data type
understood by computations, and is discovered and reused across scenarios through `tags`
(usually `StudyId:id`).

Data sources are never created directly. Every data source is produced by an asynchronous
**data source job**: the caller posts the inputs (`source`, `target`, `dataProviders`, `tags`)
and the platform runs the transformation declared on the matching **data source type** in the
background. A data source type is the reusable conversion contract between a domain-native input
format and one or more evaluation-ready data types, and also declares the editors, viewers, and
transformation/copy providers used to author and process the data.

Key resources:

* `data-source-types` - register and manage the conversion contracts (source/target, editors,
viewers, providers).
* `data-source-jobs` - create, reprocess, poll, and complete the asynchronous work that builds
a data source. External transformers report completion via `.../{id}/state`.
* `workflow-input-data-source-jobs` - build all workflow input data sources of a study at once
to create virtual scenarios.
* `data-sources` - read a given `version`, list by `tags`, and delete.


## Client ID

* prod-nam-services-fdplan.slbservice.com
* prod-eu-services-fdplan.slbservice.com
* prod-au-services-fdplan.slbservice.com
* prod-id-services-fdplan.slbservice.com
* production-services-fdplan.slbservice.com


# Table of contents

* [Create a new data source job](#create-a-new-data-source-job)
* [Get a data source job.](#get-a-data-source-job)
* [Patch a data source job.](#patch-a-data-source-job)
* [Create a new data source reprocess job](#create-a-new-data-source-reprocess-job)
* [Set state of data source job.](#set-state-of-data-source-job)
* [Create a new workflow input data source job](#create-a-new-workflow-input-data-source-job)
* [Get list of data sources](#get-list-of-data-sources)
* [Get a data source](#get-a-data-source)
* [Delete a data source.](#delete-a-data-source)
* [Get list of data source types for a given target.](#get-list-of-data-source-types-for-a-given-target)
* [Create new data source type.](#create-new-data-source-type)
* [Get a data source type by ID.](#get-a-data-source-type-by-id)
* [Update a data source type.](#update-a-data-source-type)


# Create a new data source job 

Create a new data source job to trigger the processing of a set of data provider sources

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceJob** The data source processing job that needs to be triggered.


Example
curl -request POST 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-jobs' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '{
"source": {
"type": "demo:data-types:planning-assumption-reference",
"store": "comm-store"
},
"target": {
"type": "price-forecast"
},
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4"
],
"description": "Example of transformation",
"name": "Forecast Q2",
"dataProviders": {
"items": [
{
"name": "Base",
"description": "Base price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base"
]
},
{
"name": "Stress",
"description": "Stress price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress"
]
}
]
}
}'

Response: 202
{
"id": "01JY6YFQ5F7MYPDM3TXCGG02N2",
"dataSourceId": "01JY6YVV4QPRH7W4TY64BXEDB6",
"dataSourceType": "price-forecast",
"dataSourceJobType": "Reprocess",
"dataSourceJobState": "Failed",
"dataSourceJobErrors": [
"scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices",
"scenario 1 of study 2 does not have any attached choices"
]
}

[Back to table of contents](#toc)

# Get a data source job. 

Get a data source job.

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceJobId** The data source job to get.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-jobs/{dataSourceJobId}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"id": "01JY6YFQ5F7MYPDM3TXCGG02N2",
"dataSourceId": "01JY6YVV4QPRH7W4TY64BXEDB6",
"dataSourceType": "price-forecast",
"dataSourceJobType": "Reprocess",
"dataSourceJobState": "Failed",
"dataSourceJobErrors": [
"scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices",
"scenario 1 of study 2 does not have any attached choices"
]
}

[Back to table of contents](#toc)

# Patch a data source job. 

Apply a JSON Patch to a data source job. This is used by an external worker during a custom
copy flow to replace the `dataProviders` of a copy job before writing the target containers,
so the new data source can use different sources in the context of its study. The job is
identified by `dataSourceJobId` (for example the `data.id` from a `copy_transformation_required`
event).

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceJobId** The data source job to patch.
* **patches** The JSON Patch operations to apply to the data source job, for example replacing its `dataProviders`.


Example
curl -request PATCH 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-jobs/{dataSourceJobId}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '[
{
"op": "replace",
"path": "dataProviders",
"value": {
"items": [
{
"name": "Base",
"sources": [
"https://corp.commercials.data-agent.com/reference/01K0F086K8HD3SBMHQ1N0W6J2P/Base"
]
}
]
}
}
]'

Response: 200
{
"id": "01JY6YFQ5F7MYPDM3TXCGG02N2",
"dataSourceId": "01JY6YVV4QPRH7W4TY64BXEDB6",
"dataSourceType": "price-forecast",
"dataSourceJobType": "Reprocess",
"dataSourceJobState": "Failed",
"dataSourceJobErrors": [
"scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices",
"scenario 1 of study 2 does not have any attached choices"
]
}

[Back to table of contents](#toc)

# Create a new data source reprocess job 

Create a new data source reprocess job to trigger the reprocessing of an existing data source.

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceReprocessJob** The data source reprocessing job that needs to be triggered.


Example
curl -request POST 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-reprocess-jobs' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '{
"id": "01JY6YVV4QPRH7W4TY64BXEDB6",
"version": 1,
"dataProviders": {
"items": [
{
"name": "Base",
"description": "Base price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base"
]
},
{
"name": "Stress",
"description": "Stress price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress"
]
}
]
}
}'

Response: 202
{
"id": "01JY6YFQ5F7MYPDM3TXCGG02N2"
}

[Back to table of contents](#toc)

# Set state of data source job. 

Set state of data source job given the data source job ID.

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceJobId** The data source job id to set state.
* **state** The details of the data source job state to be set.


Example
curl -request POST 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-jobs/{dataSourceJobId}/state' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '{
"state": "Failed",
"transformationErrors": {
"items": [
{
"message": "scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices"
},
{
"message": "scenario 1 of study 2 does not have any attached choices"
}
]
}
}'

Response: 200
{
"id": "01JY6YFQ5F7MYPDM3TXCGG02N2",
"dataSourceId": "01JY6YVV4QPRH7W4TY64BXEDB6",
"dataSourceType": "price-forecast",
"dataSourceJobType": "Reprocess",
"dataSourceJobState": "Failed",
"dataSourceJobErrors": [
"scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices",
"scenario 1 of study 2 does not have any attached choices"
]
}

[Back to table of contents](#toc)

# Create a new workflow input data source job 

Create a new workflow input data source job to trigger the processing of a set of data provider sources

**Parameters**

* **slb-partition-id** Data partition id.
* **workflowInputDataSourceJob** The workflow input data source processing job that needs to be triggered.


Example
curl -request POST 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/workflow-input-data-source-jobs' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '{
"dataProviders": {
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0",
"sources": [
"01JY6FMJMY0F6AJFV05V831SB4/files/production-forecast/01JE9MRE22QJH38W0QKF8VZ2DK/Field_Profile_Upside_Base.xlsx"
],
"processAs": {
"type": "ReferenceDataSource",
"value": "01JY6YVV4QPRH7W4TY64BXEDB6:v1"
},
"description": "Production forecast deck"
},
{
"name": "Low",
"nodeAddress": "0:2:2",
"sources": [
"https://corp.commercials.data-agent.com/reference/e92276ec41f84dfb/low"
],
"description": "Low price forecast deck"
},
{
"name": "Base",
"nodeAddress": "0:2:2",
"sources": [
"https://corp.commercials.data-agent.com/reference/e92276ec41f84dfb/base"
],
"description": "Base price forecast deck"
}
]
},
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1"
],
"description": "Standalone economics sensitivity",
"name": "VS_price_sensitivity"
}'

Response: 202
{
"id": "01JY6YFQ5F7MYPDM3TXCGG02N2",
"dataSourceId": "01JY6YVV4QPRH7W4TY64BXEDB6",
"dataSourceType": "price-forecast",
"dataSourceJobType": "Reprocess",
"dataSourceJobState": "Failed",
"dataSourceJobErrors": [
"scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices",
"scenario 1 of study 2 does not have any attached choices"
]
}

[Back to table of contents](#toc)

# Get list of data sources 

Get list of data sources.

**Parameters**

* **slb-partition-id** Data partition id.
* **tags** The tag(s) for data sources v2 to get, e.g. StudyId:ID. Multiple tags can be queried for by using a comma separated list of tags, e.g. StudyId:ID,SourceType:source-type. Only data sources whose tags match every one of the provided tags (AND logic) will be returned. StudyId (or VirtualScenarioStudyId) tag is required. A maximum of 5 tags is allowed.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-sources?tags=value' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"items": [
{
"id": "01JY6YVV4QPRH7W4TY64BXEDB6",
"name": "Forecast Q2",
"description": "Example of transformation",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4"
],
"version": 1,
"source": {
"type": "demo:data-types:planning-assumption-reference",
"store": "comm-store"
},
"target": {
"type": "price-forecast"
},
"details": {
"dataProviders": {
"items": [
{
"name": "Base",
"description": "Base price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base"
]
},
{
"name": "Stress",
"description": "Stress price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress"
]
}
]
},
"containers": [
{
"path": "01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5",
"type": "price-forecast",
"version": 1,
"store": "fdplan",
"description": "Price forecast for Robin field",
"labels": {
"name": "Base"
}
},
{
"path": "01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2TN0YKRF3NQYZJBVF",
"type": "price-forecast",
"version": 1,
"store": "fdplan",
"description": "Price forecast for Robin field",
"labels": {
"name": "Stress"
}
}
]
},
"lastUpdated": {
"atDate": "2025-06-20T15:21:09.000Z",
"byEvent": "9510b57e-835e-9eb0-b544-407aa857226a",
"byUser": "user@example.com"
}
}
]
}

[Back to table of contents](#toc)

# Get a data source 

Get a data source given a data source ID.

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceId** The data source v2 to get.
* **version** The version of data source v2 to get.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-sources/{dataSourceId}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"id": "01JY6YVV4QPRH7W4TY64BXEDB6",
"name": "Forecast Q2",
"description": "Example of transformation",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4"
],
"version": 1,
"source": {
"type": "demo:data-types:planning-assumption-reference",
"store": "comm-store"
},
"target": {
"type": "price-forecast"
},
"details": {
"dataProviders": {
"items": [
{
"name": "Base",
"description": "Base price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base"
]
},
{
"name": "Stress",
"description": "Stress price forecast deck",
"sources": [
"https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress"
]
}
]
},
"containers": [
{
"path": "01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5",
"type": "price-forecast",
"version": 1,
"store": "fdplan",
"description": "Price forecast for Robin field",
"labels": {
"name": "Base"
}
},
{
"path": "01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2TN0YKRF3NQYZJBVF",
"type": "price-forecast",
"version": 1,
"store": "fdplan",
"description": "Price forecast for Robin field",
"labels": {
"name": "Stress"
}
}
]
},
"lastUpdated": {
"atDate": "2025-06-20T15:21:09.000Z",
"byEvent": "9510b57e-835e-9eb0-b544-407aa857226a",
"byUser": "user@example.com"
}
}

[Back to table of contents](#toc)

# Delete a data source. 

Delete a data source.

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceId** The data source to delete.


Example
curl -request DELETE 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-sources/{dataSourceId}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 204

[Back to table of contents](#toc)

# Get list of data source types for a given target. 

Get list of data source types for a given target.

**Parameters**

* **slb-partition-id** Data partition id.
* **target** The data type (target) to get data source types.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-types' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"items": [
{
"id": "production-forecast-fdplan-workbook:fdplan",
"editors": [
{
"editorURL": "",
"name": "fdplan-file-selector",
"type": "Both"
}
],
"isSystem": true,
"source": {
"store": "fdplan",
"type": "production-forecast-fdplan-workbook"
},
"targets": [
"production-forecast"
],
"copyProvider": {
"name": "system"
},
"transformationProvider": {
"name": "system"
},
"viewers": [
]
}
]
}

[Back to table of contents](#toc)

# Create new data source type. 

Create new data source type.

**Parameters**

* **slb-partition-id** Data partition id.
* **createDataSourceType** The data source type that needs to be created.


Example
curl -request POST 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-types' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '{
"source": {
"store": "fdplan",
"type": "production-forecast-fdplan-workbook"
},
"targets": [
"production-forecast"
]
}'

Response: 200
{
"id": "production-forecast-fdplan-workbook:fdplan",
"editors": [
{
"editorURL": "",
"name": "fdplan-file-selector",
"type": "Both"
}
],
"isSystem": true,
"source": {
"store": "fdplan",
"type": "production-forecast-fdplan-workbook"
},
"targets": [
"production-forecast"
],
"copyProvider": {
"name": "system"
},
"transformationProvider": {
"name": "system"
},
"viewers": [
]
}

[Back to table of contents](#toc)

# Get a data source type by ID. 

Get a data source type by ID.

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceTypeId** The data source type id to get.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-types/{dataSourceTypeId}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"id": "production-forecast-fdplan-workbook:fdplan",
"editors": [
{
"editorURL": "",
"name": "fdplan-file-selector",
"type": "Both"
}
],
"isSystem": true,
"source": {
"store": "fdplan",
"type": "production-forecast-fdplan-workbook"
},
"targets": [
"production-forecast"
],
"copyProvider": {
"name": "system"
},
"transformationProvider": {
"name": "system"
},
"viewers": [
]
}

[Back to table of contents](#toc)

# Update a data source type. 

Update a data source type.

**Parameters**

* **slb-partition-id** Data partition id.
* **dataSourceTypeId** The data source type id to update.
* **patch** The update to apply to the given data source type id.


Example
curl -request PATCH 
--url 'https://api.delfi.slb.com/fdplan/data-sources/v2/data-source-types/{dataSourceTypeId}' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '{
"targets": [
"production-forecast"
]
}'

Response: 200
{
"id": "production-forecast-fdplan-workbook:fdplan",
"editors": [
{
"editorURL": "",
"name": "fdplan-file-selector",
"type": "Both"
}
],
"isSystem": true,
"source": {
"store": "fdplan",
"type": "production-forecast-fdplan-workbook"
},
"targets": [
"production-forecast"
],
"copyProvider": {
"name": "system"
},
"transformationProvider": {
"name": "system"
},
"viewers": [
]
}

[Back to table of contents](#toc)