# info.description
# What is Data Workbench?
Data Workbench allows you to:
* Get access to external data from different sources, f.ex. emission data, that can be used in your applications.
* Securely share your data and use data shared by others.
* Monitor who uses your data, limit how long it is available, and revoke access to it.
* Build dashboards and reports on top of the data.
* Work with scalable data streams and self-defined non-time-series data streams.

For details, see [Data Workbench on Marketplace](https://store.veracity.com/b692-2dd3fb6b0225-workbench).

## Tenants and workspaces
Each company or a B2C customer has one tenant in Data Workbench. A tenant can have multiple workspaces. Each workspace has members. Workspace members can be admins or readers.

## Data sets
To see data sets available in your workspace, go to the **Data Catalogue** tab. 

The **Predefined data sets** tab shows data sets that are queried by connections from their corresponding source systems. These data sets are inherited, and you cannot modify them. However, you can use them to create new data sets.

The **Created data sets** tab shows the data sets that workspace members created.

Each data set has:
* Title and description.
* Column picker – show or hide table columns.
* Filters - filter data.
* Save option – save your changes.
* Share option – share a data set with a user, and set for how long you grant them access.

To see data sets you can use, go to [My data](https://data.veracity.com/containers). 
To see how to manage your data on Data Fabric, go [here](https://help-center.veracity.com/en/collections/2429587-managing-your-data-on-data-fabric).

# paths./workspaces/{workspaceId}/datasets/{datasetId}.get.summary
Gets a specific data set by Workspace Id and DataSet Id

# paths./workspaces/{workspaceId}/datasets/{datasetId}.get.description
Gets a specific data set by Workspace Id and DataSet Id

# paths./workspaces/{workspaceId}/datasets/{datasetId}/ledger.get.summary
Gets Dataset Ledger based on workspaceId and datasetId

# paths./workspaces/{workspaceId}/datasets/{datasetId}/ledger.get.description
Gets Dataset Ledger based on workspaceId and datasetId

# paths./workspaces/{workspaceId}/datasets/{datasetId}/query.post.summary
Query for data by Workspace Id and DataSet Id with optional filters

# paths./workspaces/{workspaceId}/datasets/{datasetId}/query.post.description
Query for data by Workspace Id and DataSet Id with optional filters

# paths./workspaces/{workspaceId}/ledger.get.summary
Gets Workspace Ledger based on workspaceId

# paths./workspaces/{workspaceId}/ledger.get.description
Gets Workspace Ledger based on workspaceId

# paths./workspaces/{workspaceId}/schemas.get.summary
Gets a list of workspace schemas for a specific workspace

# paths./workspaces/{workspaceId}/schemas.get.description
Gets a list of workspace schemas for a specific workspace

# paths./workspaces/{workspaceId}/Ingest.post.summary
Get data ingest endpoint for current workspace

# paths./workspaces/{workspaceId}/Ingest.post.description
Get data ingest endpoint for current workspace

# paths./workspaces/{workspaceId}/Ingest.post.responses.200.description
Returns SAS token for created folder, SAS token will be valid for only 15 mins

# paths./workspaces/{workspaceId}/Analysis/executions.post.summary
Execute Python on a dataset, upon completion a notification will be triggered to user

# paths./workspaces/{workspaceId}/Analysis/executions.post.description
Execute Python on a dataset, upon completion a notification will be triggered to user

# paths./tenants/{tenantId}/users/roles.get.summary
Get users with role scopes in specified tenant

# paths./tenants/{tenantId}/users/roles.get.description
Sample response for paginated result of user role scopes info:

    {
    	"result": [
    		{
    			"userId": "ddbf7526-abc3-45e2-bfd9-a2223a431a12",
    			"email": "Jane.Yao@dnv.com",
    			"name": "Jane Yao",
    			"isServicePrincipal": false,
    			"roleScope": {
    				"role": "administrator",
    				"scopeType": "Tenant",
    				"scopeRef": "c39867d7-a4c0-4ae2-8281-7d45936a3bec"
    			}
    		},
    		{
    			"userId": "e574383d-994e-4a3d-9a7d-5d76755552e1",
    			"email": "Jork.Cao@dnv.com",
    			"name": "Jork Cao",
    			"isServicePrincipal": false,
    			"roleScope": {
    				"role": "reader",
    				"scopeType": "Tenant",
    				"scopeRef": "c39867d7-a4c0-4ae2-8281-7d45936a3bec"
    			}
    		}
    	],
    	"pageIndex": 1,
    	"pageSize": 2,
    	"totalCount": 65,
    	"totalPages": 33
    }

# paths./tenants/{tenantId}/users/roles.get.parameters[].description
Format - uuid. The tenant id which you want to get user role scopes

# paths./tenants/{tenantId}/users/roles.get.parameters[].description
Format - int32. Index of the current page (optional)

# paths./tenants/{tenantId}/users/roles.get.parameters[].description
Format - int32. Number of items per page (optional)

# paths./tenants/{tenantId}/users/roles.get.responses.200.description
Returns paginated result of users with role scopes

# paths./tenants/{tenantId}/workspaces.get.description
Sample response for Workspace list info:

    [
        {
            "id": "6113fcaa-a29e-4804-b9a9-dac331676008",
            "name": "Workspace Name1",
            "description": "Workspace created by test1"
        },
        {
            "id": "89a1fcaa-D43e-9802-c879-cad886785129",
            "name": "Workspace Name2",
            "description": "Workspace created by test2"
        }
    ]

# paths./tenants/{tenantId}/workspaces.get.parameters[].description
Format - uuid. The tenant id of the workspaces that you want to get

# paths./tenants/{tenantId}/workspaces.get.responses.200.description
Returns list of workspace in specified tenant

# paths./tenants/{tenantId}/workspaces.post.summary
Add a new workspace to the specified tenant

# paths./tenants/{tenantId}/workspaces.post.description
Sample response for created workspace info:

    {
        "id": "196a8ff4-dfbc-4ee7-ae08-4f38b84d9c86",
        "name": "SHANGHAI",
        "description": "WS SHANGHAI"
    }

# paths./tenants/{tenantId}/workspaces.post.parameters[].description
Format - uuid. The tenant id of the workspace that you want to create

# paths./workspaces/{workspaceId}.get.description
Sample response for Workspace info:

    {
        "id": "6113fcaa-a29e-4804-b9a9-dac331676008",
        "name": "Workspace Name1",
        "description": "Workspace created by test1"
    }

# paths./workspaces/{workspaceId}.get.parameters[].description
Format - uuid. The workspace id of the workspace that you want to get

# paths./workspaces/{workspaceId}/Shares/sharedBy/query.post.description
Sample response for shared owner info:

    [
        {
            "datasetId": "f80b0de1-3b1d-4a64-aa4d-88d6073ff1cd",    // Id of the dataset
            "sharedBy": {
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",   // Id of the shared user
                "sharedByType": "User",
                "name": "User Name"  // Name of the shared user
            }
        },
        {
            "datasetId": "6113fcaa-a29e-4804-b9a9-dac331676ee8",    // Id of the dataset
            "sharedBy": {
                "id": "a1d9ef10-39c3-4d3a-8c33-241a0b1138a1",   // Id of the shared workspace
                "sharedByType": "Workspace",
                "name": "Workspace Name"  // Name of the shared workspace
            }
        }
    ]

# paths./workspaces/{workspaceId}/users/roles.get.summary
Get users with role scopes in specified workspace

# paths./workspaces/{workspaceId}/users/roles.get.description
Sample response for paginated result of user role scopes info:

    {
    	"result": [
    		{
    			"userId": "3e4d0494-0bad-41fb-aa1f-0c2e53516171",
    			"email": "Nana.Ouyang@dnv.com",
    			"name": "Nana Ouyang",
    			"isServicePrincipal": false,
    			"roleScope": {
    				"role": "administrator",
    				"scopeType": "Workspace",
    				"scopeRef": "961a8ff4-dfbc-4ee7-ae08-4f38b84d9c86"
    			}
    		},
    		{
    			"userId": "cc4c079a-5411-6899-8dd4-b8783f9417a8",
    			"email": "Ina.Zhang@dnv.com",
    			"name": "Ina Zhang",
    			"isServicePrincipal": false,
    			"roleScope": {
    				"role": "reader",
    				"scopeType": "Workspace",
    				"scopeRef": "961a8ff4-dfbc-4ee7-ae08-4f38b84d9c86"
    			}
    		}
    	],
    	"pageIndex": 1,
    	"pageSize": 2,
    	"totalCount": 53,
    	"totalPages": 27
    }

# paths./workspaces/{workspaceId}/users/roles.get.parameters[].description
Format - uuid. The workspace id which you want to get user role scopes

# paths./workspaces/{workspaceId}/users/roles.get.parameters[].description
Format - int32. Index of the current page (optional)

# paths./workspaces/{workspaceId}/users/roles.get.parameters[].description
Format - int32. Number of items per page (optional)

# paths./workspaces/{workspaceId}/users/roles.get.responses.200.description
Returns paginated result of users with role scopes

# tags[].description
To get a list of ledgers for a specific workspace, call the https://dwdev.veracity.com/gateway/api/v1/workspaces/{workspaceId}/ledger endpoint. You must provide workspaceId (UUID).
            
A ledger is a log of an event that has happened, such as sharing a dataset, adding a new user or assigning a new role to a user

# tags[].description
You can list all connectors in a workspace by calling the https://dwdev.veracity.com/gateway/api/v1/workspaces/{workspaceId}/connectors endpoint. You must provide workspaceId (UUID) in your call.

You can list all active connections used by a workspace by calling the https://dwdev.veracity.com/gateway/api/v1/workspaces/{workspaceId}/connections endpoint. You must provide workspaceId (UUID) in your call.

# tags[].description
To get all data sets available in a workspace, call the /gateway/api/v1/workspaces/{workspaceId}/datasets endpoint. You must provide workspaceId (UUID).
You can use additional properties in your query parameters:
* isBaseDataset – boolean; by default, no value; you can set it to "true" or "false"
* pageIndex – integer, starts on 1; the index of the page being retrieved 
* pageSize – integer, starts on 1; number of entries in the page being queried
* sortColumn – string; which column to sort the data on
* sortDirection – string; by default, no value; you can set it to "ascending" or "descending"
            
To get a single data set by workspace ID and data set ID, call the /gateway/api/v1/workspaces/{workspaceId}/datasets/{datasetId} endpoint. You must provide the workspaceId (UUID) and the datasetId (UUID).
            
To query for data by workspace ID, data set ID, and some additional properties, call the /gateway/api/v1/workspaces/{workspaceId}/datasets/{datasetId}/query endpoint. You must provide the  workspaceId (UUID) and the {datasetId}(UUID).
You can use additional properties in your query body:
* pageIndex – integer, starts on 1; the index of the page being retrieved 
* pageSize – integer, starts on 1; number of entries in the page being queried
* columnFilter – array of string containing column names
* queryFilters – dictionary containing a column name as key and an array of column values as value

To get a list of ledgers for a specific dataset, call the /gateway/api/v1/workspaces/{workspaceId}/datasets/{datasetId}/ledger endpoint. You must provide workspaceId (UUID) and datasetId (UUID).
            
A ledger is a log of an event that has happened, such as sharing a dataset, adding a new user or assigning a new role to a user

# tags[].description
To get a list of workspace schemas for a specific workspace, call the https://dw.veracity.com/gateway/api/v1/workspaces/{workspaceId}/schemas endpoint. You must provide workspaceId (UUID). If the optional query parameter "includeDefaultSchema (bool)" is set to true, you will get the current default schema version in full as well.
There is also an endpoint for retrieving specific schema versions https://dw.veracity.com/gateway/api/v1/workspaces/{workspaceId}/schemas/schemaversions where you can pass on a list of UUIDs that should represent the IDs of schema versions in your workspace.
            
A schema defines one or multiple schema versions. Each schema version contains which workspace it is connected to, all the columns the data will have while using that schema and some other generic data, such as id, createdBy etc.
            
A predefined schema is a schema that is predefined by the data source, but users\administrators can also create custom schemas if needed.