Introduction
You can use a collection of Watson Data REST APIs associated with Watson Studio and IBM Knowledge Catalog to manage data-related assets and connections in analytics projects and catalogs on IBM Cloud Pak for Data.
Catalog data Use the catalog and asset APIs to create catalogs to administer your assets, associate properties with those assets, and organize the users who use the assets. Assets can be notebooks or connections to files, database sources, or data assets from a connection.
Govern data Use the governance and workflows APIs to implement data policies and a business glossary that fits to your organization to control user access rights to assets and to uncover data quality and data lineage.
Add and find data Use the discovery, search, and connections APIs to add and find data within your projects and catalogs.
API Endpoint
https://{cpd_cluster_host}
Creating an CPD bearer token
A bearer token from IBM Cloud Pak for Data is required to use any of the Watson Data APIs.
Visit the authorization section on Cloud Pak for Data for more information.
Use the value of the access_token property from the curl command on the right. Set the access_token value as the authorization header parameter for requests to the Watson Data APIs. The format is Authorization: Bearer <access_token_value_here>. For example:
Authorization: Bearer eyJraWQiOiIyMDE3MDgwOS0wMDowMDowMCIsImFsZyI6IlJTMjU2In0...
Curl command with API key to retrieve token
curl -k -X POST https://cpd_cluster_host/icp4d-api/v1/authorize -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{"username":"admin","password":"password"}'
Response
{
"_messageCode_": "200",
"message": "Success",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwicm9sZSI6IkFkbWluIiwicGVybWlzc2lvbnMiOlsiYWNjZXNzX2FkdmFuY2VkX2dvdmVybmFuY2VfY2FwYWJpbGl0aWVzIiwic2lnbl9pbl9vbmx5IiwiYWNjZXNzX2NhdGFsb2ciLCJhY2Nlc3NfaW5mb3JtYXRpb25fYXNzZXRzIiwiYWRtaW5pc3RyYXRvciIsIm1hbmFnZV9xdWFsaXR5IiwiY2FuX3Byb3Zpc2lvbiIsIm1hbmFnZV9kaXNjb3ZlcnkiLCJtYW5hZ2VfbWV0YWRhdGFfaW1wb3J0IiwidmlydHVhbGl6ZV90cmFuc2Zvcm0iLCJtYW5hZ2VfY2F0YWxvZyIsImF1dGhvcl9nb3Zlcm5hbmNlX2FydGlmYWN0cyIsIm1hbmFnZV9jYXRlZ29yaWVzIiwibWFuYWdlX2dvdmVybmFuY2Vfd29ya2Zsb3ciLCJtYW5hZ2VfaW5mb3JtYXRpb25fYXNzZXRzIiwidmlld19xdWFsaXR5Iiwidmlld19nb3Zlcm5hbmNlX2FydGlmYWN0cyJdLCJzdWIiOiJhZG1pbiIsImlzcyI6IktOT1hTU08iLCJhdWQiOiJEU1giLCJ1aWQiOiIxMDAwMzMwOTk5IiwiYXV0aGVudGljYXRvciI6ImRlZmF1bHQiLCJpYXQiOjE2MDQwMjI0NTQsImV4cCI6MTYwNDA2NTYxOH0.xtBNYtShcFO51Ja1AEN_hkGwEcq00bshXwZ_rTTGzJu1BHzATpE6JlI5ssBky8ojoJH1PH_hvceCO2UBDwvv2bWIk3efvznADr0FjM_GZSMDd-sxoNkLoUGucdAxEQs80jVAN7OPnPrqDbRqE4D191TRubmtb22ys3H7adgTWrX0dLOQ-sW4zHa-rOEHi7yKvQyl-Jqs7IYpPXlNMnmezoMGfAzrtx9pAGABSVnFQItA3TVf-64jDtMWoDXyHllU3XsYMQKaRSAQnzSYX4WaQ5U6utsT1uTpQ6ViPId7LhYJz_lbwzo8I6CDRlfYRDsXTczQBTHG9vLhC25w6OexvA"
}
The bss_account_id parameter
Some APIs make use of bss_account_id parameter, also referred to as tenant id.
Even though the system is designed to support multiple tenants, there is currently one and only one account (tenant) in CloudPak for Data with a static value of 999. Always use 999 if a bss_account_id parameter needs to be specified.
Versioning
Watson Data API has a major, minor, and patch version, following industry conventions on semantic versioning: Using the version number format MAJOR.MINOR.PATCH, the MAJOR version is incremented when incompatible API changes are made, the MINOR version is incremented when functionality is added in a backwards-compatible manner, and the PATCH version is incremented when backwards-compatible bug fixes are made. The service major version is represented in the URL path.
Error Handling
Responses with 400-series or 500-series status codes are returned when a request cannot be completed. The body of these responses follows the error model, which contains a code field to identify the problem and a message field to explain how to solve the problem. Each individual endpoint has specific error messages. All responses with 500 or 503 status codes are logged and treated as a critical failure requiring an emergency fix.
Catalogs
IBM Knowledge Catalog helps you easily organize, find and share data assets, analytical assets, etc. for many data science projects and for the users who need to use those assets.
You can use the Catalog API to create catalogs which are rich metadata repositories for organizing and exploring metadata.
There are two phrases that will be used repeatedly throughout this (and the "Assets" and "Asset Types") documentation:
-
asset resource: The primary content of the asset. Many assets have a resource that is stored in an external repository: a data file, connected data set, notebook file, dashboard definition, or model definition. -
asset metadata: The information about the asset resource. Each asset has a primary metadata document in a project or catalog and might have additional metadata documents.
See the Asset Terminology section for more information about those two phrases.
This section describes some of the individual Catalog APIs.
Get a Catalog
You can get metadata about a catalog using the get Catalog API. (Note: you aren't retrieving the actual data catalog with the GET Catalog API - you're just retrieving metadata that describes the catalog.)
Get Catalog - Request URL:
GET {service_URL}/v2/catalogs/{catalog_id}
Get Catalog - Response Body:
{
"metadata": {
"guid": "c6f3cbd8-2b7f-42fb-aa60-___",
"url": "https://api.dataplatform.cloud.ibm.com/v2/catalogs/c6f3cbd8-2b7f-42fb-aa60-___",
"creator_id": "IBMid-___",
"create_time": "2018-11-06T17:40:32Z"
},
"entity": {
"name": "CatalogForGettingStartedDoc",
"description": "Catalog created for Getting Started doc",
"generator": "Your catalog generator",
"bss_account_id": "12345___",
"capacity_limit": 0,
"is_governed": false,
"saml_instance_name": "IBM w3id"
}
}
Get Catalogs
To obtain the metadata for all the catalogs that you have access to (ie, are a collaborator of), you can call the GET Catalogs API.
Get Catalogs - Request URL:
GET {service_URL}/v2/catalogs
Note: the above URL is the simplest URL for getting catalogs because it doesn't contain any parameters. There are a number of optional parameters (limit, bookmark, skip, include, bss_account_id) to the above URL that you can make use of to limit the number of catalogs for which metadata is returned.
Get Catalogs - Response Body:
{
"catalogs": [
{
"metadata": {
"guid": "c6f3cbd8-2b7f-42fb-aa60-___",
"creator_id": "IBMid-___",
"create_time": "2018-11-06T17:40:32Z"
},
"entity": {
"name": "CatalogForGettingStartedDoc",
"description": "Catalog created for Getting Started doc",
"generator": "Your catalog generator",
"bss_account_id": "12345___",
"capacity_limit": 0,
"is_governed": false,
"saml_instance_name": "IBM w3id"
}
}
],
"nextBookmark": "g1AAAAFCeJzLYWBgYMlgTmHQSklKzi9KdUhJMjT___",
"nextSkip": 0
}
In the above example, metadata for only one catalog is returned - the catalog created above. An advantage of calling the GET Catalogs API is you don't have to remember the ID of any particular catalog in order to get the metadata for that catalog.
Assets
From a high level, an asset is an item of data or data analysis in a project or catalog. Most of these assets consist of two parts:
-
Asset resource: The primary content of the asset. Many assets have a resource that is stored in an external repository: a data file (eg. text file, image, video, etc.), connected data set (eg. database table), notebook file, dashboard definition, or model definition. The Assets API does not affect this part of the asset. Think of this as the object that's being described by asset metadata (ie, an asset resource is a "decribee").
-
Asset metadata: The information about the asset resource. Each asset has a primary metadata document in a project or catalog and might have additional metadata documents. This is the part of the asset that you can get, create, or operate on with the Assets API. Think of this as the object that's doing the describing of an asset resource (ie, asset metadata is a "describer").
A library is a useful analogy for understanding the scope of the Assets API. A library contains a set of books and an index. The index, or card catalog, contains a card about each book. A card has information about the book, including the location of the book. A project or catalog contains only the card catalog part of the library. The books, or asset resources, are elsewhere. Consequently, the Assets API can return the location of an asset resource, but not affect the asset resource in any way.
The term asset encapsulates the following:
- [1] asset resource: the primary / initial resource that a user wants described by a primary metadata document.
- [2] primary metadata document: a document added to a catalog to describe an asset resource.
- [3] attributes: chunks of data inside a primary metadata document that describe either the asset resource or a secondary / extended metadata document.
- [4] secondary / extended metadata documents: additional documents containing information related to the asset resource. Attached to the primary metadata document. Can be generated by catalog processes, such as profiling.
- [5] a combination of all of the above: the IBM Knowledge Catalog UI presents information from each of the above on a single page and calls all that information an "asset".
For example, when you call the Get Assets API, you receive asset metadata (in a primary metadata document). The asset metadata might point to the location of the asset resource, but the Get Assets API does not return the asset resource. Similarly, when you run the Create Assets API, you create a primary metadata document that can, eventually, include the location of an existing asset resource.
This overview section provides a picture of the parts of a "primary metadata document" and then explains the parts of that picture. The picture provides a kind of "map" of a primary metadata document, so it's recommended to spend a few minutes studying it. Readers who prefer API examples can skip over the explanation of that picture that follows, and go straight to the Assets API Examples section. However, the Assets API Examples section will often refer back to the terms and explanations discussed in this Assets API Overview section.
Note: when calling any of the endpoints in the Assets API you must specify either a catalog ID or a project ID to indicate whether the metadata for an asset is (to be) in a catalog or a project. Because the Assets API endpoints can be applied to either a catalog or a project, rather than repeating the phrase "either a catalog or a project" over and over throughout the rest of this documentation, only the term "catalog" will be used. The possibility of instead using a "project" will be implied.
Asset Primary Metadata Document (or Card)
A primary metadata document is a document that contains the primary metadata for an asset resource. Once a primary metadata document has been created and stored in the catalog, it's often informally said that that asset resource has been "cataloged", or "added to the catalog". Note: being cataloged, or added to the catalog, does not mean the asset resource has been moved or copied and is now physically stored inside the catalog - it just means a primary metadata document has been created for that asset resource, and that primary metadata document is now stored in the catalog.
Almost every Assets API endpoint revolves around creating, reading, modifying or deleting a primary metadata document. JSON is natively used to store primary metadata documents in a catalog, and to transfer those documents in Assets API REST calls. So, JSON examples of primary metadata documents will be used throughout this documentation.
In this documentation, the term card (as in, an index card in a library's catalog) will often be used as a short nickname for the phrase "primary metadata document". In this documentation, "card" and "primary metadata document" mean exactly the same thing. The term "card" just saves us from reading and writing the lengthier phrase "primary metadata document" over and over.
A primary metadata document (ie, card) is a JSON object that's composed of up to three top-level fields, named as follows:
1. [**metadata**](#Section_Assets__Overview_and_Terminology__Asset_Metadata_Document__metadata_group): a JSON object containing metadata _common to all_ [asset types](#Section_Assets__Overview_and_Terminology__Asset_Type)
2. [**entity**](#Section_Assets__Overview_and_Terminology__Asset_Metadata_Document__entity_group): a JSON object containing [attributes](#Section_Assets__Overview_and_Terminology__Attributes), each containing metadata _specific to one_ asset type
3. [**attachments**](#Section_Assets__Overview_and_Terminology__Asset_Metadata_Document__attachments_group): an optional JSON array, each item of which is a JSON object containing _metadata for_ an attached (ie, externally stored) [asset resource](#Section_Asset__Terminology_Overview__definition__Asset_Resource) or [extended metadata document](#Section_Assets__Overview_and_Terminology__Asset_Metadata_Document_Overview__attachment__extended_metadata)
For a pictorial representation of a primary metadata document (ie, card) and its associated asset resource and extended metadata documents, see the Parts of a Primary Metadata Document figure below:
In particular, note that:
- red rectangles are used in the figure to highlight the [three top-level fields of a card](#Section_Assets__Overview_and_Terminology__Asset_Metadata_Document_Overview__three_top_level_fields_of_a_card).
- the green rectangles illustrate how important the _name_ of the [primary asset type](#Section_Assets__Overview_and_Terminology__Asset_Type__Primary_Asset_Type_definition) is in relating various parts of the card, and the attached [asset resource](#Section_Asset__Terminology_Overview__definition__Asset_Resource), to each other. In the example figure, the value of `"metadata.asset_type"` is "data\_asset". The value you'll see in your card depends on the "asset_type" you've specified for your asset.
"metadata" field of a Primary Metadata Document
The "metadata" field of a primary metadata document (ie, of a card) is a JSON object that contains metadata fields that are common across all types of assets. (See the top red rectangle in the parts figure.) The Assets API specifies the names of the fields that go into the "metadata" part of the card. The user must supply values for some of the fields in "metadata"; the values of other fields in "metadata" will be filled in by the Assets API during the life of the card. Here's a list of some of the fields inside "metadata" (see example cards in the Get Asset section for more extensive lists):
- "asset_id":
- The ID of the card (ie, primary metadata document) rather than of the asset resource described by the card.
- Created internally by the Assets API at the time the card is created. That is, you do not supply this value.
- "asset_type":
- You must supply this value.
- Declares the primary asset type of this card.
- Describes the type of the asset resource attached (if any) to this card.
- Specifies the name of the primary attribute in this card.
- See Asset Types for more details on asset types.
- "asset_attributes":
- You must not supply any value for this field when creating a primary metadata document. The Assets APIs maintain the contents of this field.
- An array of attribute names (only the names, not the actual attributes).
- Each attribute / asset type name listed in this array will have a correspondingly named attribute in the "entity" field of the card.
- The name of each attribute must match the name of an existing asset type, so this is also an array of the names of the primary and secondary / extended asset types used by this card.
- "name": the name of the asset resource this card describes
- "description": a description of the asset resource
- "origin_country": the originating country for the asset resource
- "tags": an array of terms that users want to associate with the asset resource
- "rov": Rules Of Visibility.
- "mode": -1 - this is the default, which corresponds to "mode" : 0, public (see below)
- "mode": 0 - indicates public visibility, in which everybody can view and search the values of the asset's primary metadata document (card), and preview the asset's data. Note: access can still be denied based on actionable governance policy rules.
"rov": {
"mode": 0,
"collaborator_ids": []
}
-
- "mode": 8 - indicates private visibility, which allows users listed as members of the asset (as denoted by
collaborator_idslist) to view and search all fields (includingmetadata,entity, andattachments) of the asset's primary metadata document (card), and preview the asset's data. Non-members are allowed to only view and search themetadatafield, and cannot preview the asset's data. This mode is only available through the API, and is not exposed in the IKC UI. Note: access can still be denied based on actionable governance policy rules.
- "mode": 8 - indicates private visibility, which allows users listed as members of the asset (as denoted by
"rov": {
"mode": 8,
"collaborator_ids": [
{
"IBMid-06___": {
"user_iam_id": "IBMid-06___"
}
},
{
"IBMid-27___": {
"user_iam_id": "IBMid-27___"
}
}
]
}
-
- "mode": 16 - indicates hidden visibility, in which only users listed as members of the asset (as denoted by
collaborator_idslist) have any access to fields in the asset, and non-members have no access to the asset. Note: access can still be denied based on actionable governance policy rules.
- "mode": 16 - indicates hidden visibility, in which only users listed as members of the asset (as denoted by
"rov": {
"mode": 16,
"collaborator_ids": [
{
"IBMid-06___": {
"user_iam_id": "IBMid-06___"
}
},
{
"IBMid-27___": {
"user_iam_id": "IBMid-27___"
}
}
]
}
"entity" field of a Primary Metadata Document
The "entity" field of a card (ie, primary metadata document) is a JSON object that contains additional JSON objects called attributes, each of which contains metadata fields that are specific to one asset type. (See the middle red rectangle in the parts figure.) The only contents of the "entity" field are attributes, which are discussed in the next section.
Note: the fact that the "entity" section contains attributes for more than one asset type does not mean that a single card contains metadata for more than one asset resource. A card always contains metadata for exactly one asset resource, and that asset resource will have exactly one attribute associated with it (see primary attribute below). All the other attributes in the "entity" field contain extended metadata describing the single asset resource that the card was created for. Really, asset types ought to be thought of as attribute types because asset types literally define (some of) the fields that will appear in attributes.
Attributes
- is contained directly inside the ["entity"](#Section_Assets__Overview_and_Terminology__Asset_Metadata_Document__entity_group) field of the [primary metadata document](#Section_Assets__Overview_and_Terminology__definition__primary_metadata_document).
- is identically named with, and has fields that are partially defined by, an [Asset Type](#Section_Assets__Overview_and_Terminology__Asset_Type)
- describes an [asset resource](#Section_Asset__Terminology_Overview__definition__Asset_Resource) or something related to that asset resource, such as an [extended metadata document](#Section_Assets__Overview_and_Terminology__Asset_Metadata_Document_Overview__attachment__extended_metadata)
There is one attribute in the "entity" field for each attribute name that appears in the "metadata.asset_attributes" array. So, for example, if the "metadata.asset_attributes" array contains these two attribute names:
"metadata": {
...
"asset_attributes": [
"data_asset",
"data_profile"
],
}
then the "entity" field will contain these two correspondingly named attributes:
"entity": {
"data_asset": { // attribute name matches "data_asset" in "metadata.asset_attributes"
...attribute contents...
},
"data_profile": { // attribute name matches "data_profile" in "metadata.asset_attributes"
...attribute contents...
}
}
The name of each attribute in "entity" must also match the name of an existing asset type. That is, an attribute named "X" will contain metadata related to an asset type also named "X". So, an attribute's name can be thought of as simultaneously telling us that attribute's "type". For example, in this asset metadata document example, both the attribute names "data_asset" and "data_profile" refer to asset types with those same names.
There is one special attribute that will be referred to as the primary attribute. The primary attribute is the main attribute used to describe an asset resource. Every primary metadata document will have exactly one primary attribute. The name of the primary attribute is the same as the name that appears in the "metadata.asset_type" field.
Any attribute other than the primary attribute is a "secondary" / "extended" attribute whose name must match the name of a secondary / extended asset type. A common example of an attribute for extended metadata is named "data_profile", which is created by the Profiling API. For example, see the underlined names in the Parts of a Primary Metadata Document figure, or the "entity.data_profile" field in this asset metadata document.
Although the Assets API restricts the names of attribute objects to match the names of asset types, the Assets API does not (in general) specify what the contents of those attributes should be. So, in some sense, the fields within an attribute are the opposite of the fields within the "metadata" field:
- the Assets API "owns" (or, specifies) which fields go inside "metadata"
- the user "owns" (or, specifies) which fields go inside the attributes (except for some fields of already available asset types)
The following example shows two attributes, whose names must match asset types, but whose contents are (for the most part) up to the user:
"entity": {
"data_asset": { // attribute name must match some asset type's name
...
data_asset *type creator* and
data_asset *attribute creator*
decide what fields go here
...
},
"data_profile": { // attribute name must match some asset type's name
...
data_profile *type creator* and
data_profile *attribute creator*
decide what fields go here
...
}
}
Because the Asset Types API is itself the creator of some already available asset types, the Asset Types API specifies some of the fields for any attribute whose name corresponds to one of those already available asset types. For example, see the discussion of the already available asset type called "data_asset".
Note: there is a GET attribute API that can be used to retrieve just the attributes in the "entity" section of the primary metadata document, instead of the entire primary metadata document as returned by the GET asset API.
"attachments" (optional) field of a Primary Metadata Document
The "attachments" field of a card (ie, primary metadata document) is a JSON array, each item of which contains metadata for one attachment. (See the bottom red rectangle in the parts figure.)
-
the "attachments" array in the primary metadata document
-
an attachment item in the "attachments" array
-
a metadata document that will be returned from a call to the GET Attachment API. That metadata document will contain information that points to, and can be used to retrieve, either...
-
the asset resource being described by the primary metadata document
-
an extended metadata document stored containing extended metadata for the asset resource
Each attribute in the "entity" field can have a corresponding attachment item in the "attachments" array. An attribute and its corresponding attachment item are related to each other by using the name of the attribute as the value for the attachment item's "asset_type" field. For example, notice in the following card snippet how the attribute name "data_asset" is used to link that "data_asset" attribute to its attachment item in the "attachments" array:
"entity": {
...other attributes
"data_asset": { // <-- attribute's name matches its...
...
},
...other attributes
},
"attachments": [
...other attachment items
{
...
"asset_type": "data_asset", // <-- ...attachment's asset_type
...
"connection_id": "...", // connection_ fields are one way
"connection_path": "...", // that item points to attached object
...
},
...other attachment items
]
Notice also in the above card snippet that, in this case, the attachment item contains two "connection_..." fields that point to the attachment object located in external storage. So, an attribute has an attachment item which points to an attachment object.
Like the fields of "metadata", the fields of an attachment item are specified by the Assets API. Some of the most important fields in an attachment item are:
- "asset_type":
- describes the type of the attachment
- figuratively connects the attachment item to the attribute with the same name
- "connection_id" and "connection_path" (optional):
- this pair of fields specify the ID of a
WDP Connectionand a path in the associated data repository that points to the attached object - always used for an attached asset like a database table
- can also be used for an attached asset resource (eg, spreadsheet) that can be stored in the catalog
- the presence of these two fields means the attachment will be known as a remote attachment
- this pair of fields specify the ID of a
- "object_key" and "handle" (optional):
For any attachment, only one of the following two pairs of fields will be used:
"connection_id"and"connection_path"(ie, remote attachment), or"object_key"and"handle"(ie, referenced attachment).
Interestingly, being remote does not tell you whether or not an attachment is in the catalog. Remote only tells you how the attached object can be retrieved: by using a connection.
An attachment item (in the card) points to one of two kinds of attached object (in external storage):
-
an asset, or
-
and extended metadata document.
Those are briefly discussed in the next 2 sections.
Asset Resource Attachment
The most typical attachment object is the asset resource being described by the card.
Follow the green arrows in the Parts of a Primary Metadata Document figure to see how:
- the asset's type name leads to
- an attribute name, which leads to
- a primary attribute, which leads to
- an attachment metadata item for that attribute, which finally leads to
- the attached asset resource.
For a full example that shows an attachment metadata item for an attached csv file, see the (only) item in the "attachments" array in Get Asset - CSV File - Response Body - Before Profiling.
Extended Metadata Document Attachment(s)
The other kind of attachment objects are extended metadata documents. A card can have 0, 1, or many attached extended metadata documents. These documents each contain a related set of (additional) metadata describing the asset resource.
See the underlined "data_profile" type name in the Parts of a Primary Metadata Document figure for a visualization of how, for one extended metadata document, the three parts ("metadata", "entity", "attachments") of a card are related to each other.
See the second item in the "attachments" array in Get Asset - CSV File - Response Body - After Profiling for an example showing an attachment item for a "data_profile" extended metadata document.
Uses of "asset_type" value
From the previous sections, you can see that the "asset_type" value shows up in:
- the "metadata.asset_type" field
- the "metadata.asset_attributes" array
- a field (ie, object) in the "entity" field. This object is the primary attribute.
- the asset_type field of the primary attribute's attachment (if such an attachment exists, which it typically does). This (primary) attachment will be the asset resource (eg, database table, spreadsheet, csv file, etc.).
For example, see the Parts of a Primary Metadata Document figure above, where the name of the primary attribute is, in this case, "data_asset" and is highlighted with green rectangles in all the places it's used. The path shown by the green arrows in the figure starts at the "metadata.asset_type" field and ends at the asset resource, in this case a file called Sample.csv.
Other Assets API Objects
Finally, here is a brief list of some of the remaining objects that can be manipulated with the Assets APIs:
- owner
- the owner of the asset
- collaborators
- users who are allowed to see and possibly edit (some parts of) the asset
- perms
- permissions for viewing / editing an asset
- ratings
- indications of how popular or useful the asset is
- stats
- statistics on how often and when the asset was viewed or edited, and who did that viewing or editing.
Getting an Asset
It's important to understand that the GET Asset API does not return an asset resource like a database table, a spreadsheet, a csv file, etc. Instead, it returns a primary metadata document (ie, card) that describes an asset resource.
Obviously, a primary metadata document (ie, card) must have been created before it can be retrieved. Still, it's instructive to see actual examples of a card and its parts before attempting to create those things. After all, many users will retrieve cards that were previously created by someone else.
This and the following sections show how to retrieve asset metadata and attachments (eg, an asset resource and extended metadata documents).
Getting an Asset - for a Connection
We'll start by retrieving a common primary metadata document (ie, card): one for a "connection" asset type. This is a simple card because it has no attachments. That makes it an easy example to start with, even though many of the other cards you'll encounter do have attachments.
Use the following GET Asset API to retrieve the primary metadata document for a connection. Note that this requires that you know and supply the IDs of both the primary metadata document (ie, card) and of the catalog that contains the card. Either someone has given you both of those IDs or you can browse to the asset's page using the IBM Knowledge Catalog UI and then extract both the catalog ID and the primary metadata document ID from within the URL in the browser's address bar.
Getting an Asset - Request URL:
GET {service_URL}/v2/assets/{asset_id}?catalog_id={catalog_id}
The following is the primary metadata document (ie, card) that's returned.
Note: you may find it helpful to look at the Parts of a Primary Metadata Document Figure before looking at the following Response Body.
Getting an Asset - Connection - Response Body:
{
"metadata": {
"rov": {
"mode": 0,
"collaborator_ids": {}
},
"usage": {
"last_updated_at": "2018-11-06T17:40:37Z",
"last_updater_id": "IBMid-___",
"last_update_time": 1541526037227,
"last_accessed_at": "2018-11-06T17:40:37Z",
"last_access_time": 1541526037227,
"last_accessor_id": "IBMid-___",
"access_count": 0
},
"name": "ConnectionForCSVFile",
"description": "Connection for CSV file",
"tags": [],
"asset_type": "connection",
"origin_country": "us",
"rating": 0,
"total_ratings": 0,
"catalog_id": "c6f3cbd8-2b7f-42fb-aa60-___",
"created": 1541526037227,
"created_at": "2018-11-06T17:40:37Z",
"owner_id": "IBMid-___",
"size": 0,
"version": 2,
"asset_state": "available",
"asset_attributes": [
"connection"
],
"asset_id": "070e9be2-40a8-4e0e-___",
"asset_category": "SYSTEM"
},
"entity": {
"connection": {
"datasource_type": "193a97c1-4475-4a19-b90c-295c4fdc6517",
"context": "source,target",
"properties": {
"bucket": "catalogforgettingsta___",
"secret_key": "{wdpaes}12345___=",
"api_key": "{wdpaes}eo/12345_=",
"resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/12345c___:7240b198-b0f6-___::",
"access_key": "12345___",
"region": "us-geo",
"url": "https://s3.us-south.objectstorage.softlayer.net"
},
"flags": []
}
}
}
The above response has two of the three primary groups of metadata that were described in the Primary Metadata Document section: "metadata" and "entity".
As discussed in Assets API Overview section, the contents of the "metadata" field are common to all primary metadata documents (ie, cards). The set of fields in "metadata" is completely defined by the Assets API. The values for some of those fields must be provided by the creator of the card, while other fields' values will be populated by various Assets APIs during the life of the card. Note the following fields' values in particular:
-
"metadata"fields whose values are provided by the creator of the card:-
"name": "ConnectionForCSVFile" -
"description": "Connection for CSV file" -
"asset_type": "connection" -
"asset_attributes": [ "connection"]
-
-
"metadata"fields whose values are set by various Assets APIs during the life of the card:"usage": contains various statistics describing usage of the card/asset"catalog_id": the ID of the catalog that contains the card"created_at": the time and date at which the card was created"asset_id": the ID of the card (not the asset resource)
For more info about the "metadata" fields, see the discussion on "metadata" in the Assets API Overview section above.
The contents of the "entity" field are only partially defined by the Assets API. In particular, the "entity" field shown in the above card contains a field whose name must match the value in "metadata.asset_type", in this case, "connection". That field is the primary attribute.
On the other hand, both the names and the values of all the fields inside the primary attribute "entity.connection" are completely determined by the creator of the "connection" asset type and the creator of the "connection" attribute. The Assets API does not, in general, decide what fields go inside the primary attribute (or any other attribute). In the example "connection" attribute above, some of the more interesting fields are:
"datasource_type"- specifies the ID of the type of the data source to which a connection will be formed."properties"- specifies connection metadata specific to the type of the datasource. The exact contents of this field will change according to the type of the datasource.
For more info on the contents of "entity" in general, see the discussion on "entity" in the Assets API Overview section.
Notice the above card contains no "attachments" array. That means there is no attached asset resource associated with this card. A natural question is: how can "connection" asset metadata exist for, or describe, a non-existent "connection" asset resource? Actually, a "connection" asset resource does exist, but only when the metadata in the connection's primary metadata document is used to create a client-server connection at runtime.
Getting an Asset - for a CSV File
This section shows a far more typical example in which the primary metadata document (ie, card) does have an attached asset resource - in this case, a csv file named Sample.csv. Here's the very simple contents of the Sample.csv file:
Sample.csv file contents
Name,Number
abc,123
def,456
Use the GET Asset API to retrieve the asset metadata for the Sample.csv asset resource. Note: the GET Asset API only returns a primary metadata document (ie, card) that describes the Sample.csv file - it does not return the actual Sample.csv file.
Getting an Asset - Request URL:
GET {service_URL}/v2/assets/{asset_id}?catalog_id={catalog_id}
It's instructive to show two different versions of the primary metadata document for the Sample.csv asset:
- Before profiling (which returns a small metadata document - without extended metadata)
- After profiling (which returns a much larger metadata document - with extended metadata)
Note: you may find it helpful to look at the Parts of a Primary Metadata Document Figure before looking at either of the following two Get Asset Response Bodies.
Here is the smaller primary metadata document that exists before the Profile API is invoked on the Sample.csv file.
Getting an Asset - CSV File - Response Body - Before Profiling:
{
"metadata": {
"name": "Sample.csv",
"description": "A simple csv file.",
"asset_type": "data_asset",
"rov": {
"mode": 0,
"collaborator_ids": {}
},
"usage": {
"last_updated_at": "2018-11-06T17:45:23Z",
"last_updater_id": "IBMid-___",
"last_update_time": 1541526323713,
"last_accessed_at": "2018-11-06T17:45:23Z",
"last_access_time": 1541526323713,
"last_accessor_id": "IBMid-___",
"access_count": 0
},
"origin_country": "united states",
"rating": 0,
"total_ratings": 0,
"catalog_id": "c6f3cbd8-2b7f-42fb-aa60-___",
"created": 1541526321437,
"created_at": "2018-11-06T17:45:21Z",
"owner_id": "IBMid-___",
"size": 0,
"version": 2,
"asset_state": "available",
"asset_attributes": [
"data_asset"
],
"asset_id": "45f4ab8c-37d5-45a1-8adf-___",
"asset_category": "USER"
},
"entity": {
"data_asset": {
"mime_type": "text/csv",
"dataset": false
}
},
"attachments": [
{
"id": "b8c7a390-e857-4c34-add8-___",
"version": 2,
"asset_type": "data_asset",
"name": "remote",
"description": "remote",
"connection_id": "070e9be2-40a8-4e0e-___",
"connection_path": "catalogforgettingsta-datacatalog-r1s___/data_asset/Sample_SyjEQUy6m.csv",
"create_time": 1541526323713,
"size": 0,
"is_remote": true,
"is_managed": false,
"is_referenced": false,
"is_object_key_read_only": false,
"is_user_provided_path_key": true,
"transfer_complete": true,
"is_partitioned": false,
"complete_time_ticks": 1541526323713,
"user_data": {},
"test_doc": 0,
"usage": {
"access_count": 0,
"last_accessor_id": "IBMid-___",
"last_access_time": 1541526323713
}
}
]
}
The above primary metadata document has all three primary groups of metadata ("metadata", "entity", and "attachments") that were described in the Assets API Overview section.
The contents of the "metadata" field are very similar to those shown above for the Connection card example. The most important difference is the value that the user specified as the "asset type" for the Sample.csv asset, namely "data_asset". That asset type name shows up in two places inside the "metadata" section of the primary metadata document:
"metadata":"asset_type": "data_asset""asset_attributes": [ "data_asset" ]
As discussed in the Attributes section, the fact that "metadata.asset_type" has the value "data_asset" means the "entity" field of the card must contain a primary attribute called "data_asset". The Asset Types API provides the predefined asset type "data_asset". That "data_asset" type definition declares that there are two mandatory fields in a "data_asset" attribute: "mime_type" and "dataset", as can be seen in the card above and repeated here:
"entity":"data_asset":"mime_type": "text/csv"- specifies the mime type of the asset resource. Here, the mime type indicates that the asset resource is a text csv file.
"dataset": false- false because there is no "columns" field in this primary attribute.
- Note: false does not mean there are no columns in the asset resource. Clearly, our Sample.csv file does have columns. The problem here is that no one has (yet) told the card that the asset resource has columns. Compare this "data_set" attribute to the one shown in the next example Get Asset - CSV File - Response Body - After Profiling, where the value of "dataset" has been changed to true, and the primary attribute does have a "columns" field.
Unlike in the Connection card example above, the card for the Sample.csv file does have an "attachments" field. In this case, the "attachments" array has one item in it. That item contains metadata that points to the attached asset resource (ie, the Sample.csv file). Some of the more interesting fields in that attachment item are:
"id": "b8c7a390-e857-4c34-add8-___"- identifies the metadata document that points to the attached asset resource
"asset_type": "data_asset"- matches the name of the primary attribute in "entity", so linking the primary attribute to this attachment item and designating this item as the item that points to the asset resource.
"connection_id": "070e9be2-40a8-4e0e-___"- identifies a connection primary metadata document (ie, card) which contains credentials and other info that can be use to connect to the external repository that contains the attached asset resource (ie, the "Sample.csv" file)
- not coincidentally, the particular connection card referred to by "070e9be2-40a8-4e0e-___" is the exact same connection card shown above in Get Asset - Connection Primary Metadata Document
"connection_path": "catalogforgettingsta-datacatalog-r1s___/data_asset/Sample_SyjEQUy6m.csv",- identifies the path in the external repository that contains the attached asset (ie, the "Sample.csv" file)
"is_remote": true- as discussed in the "attachments" overview section, is_remote is true because "connection_id" and "connection_path" are being used to describe how to get the Sample.csv asset resource.
"is_referenced": false (at most one of "is_referenced" and "is_remote" will be true)
Getting an Asset - CSV File - Response Body - After Profiling:
Now, let's compare what GET {service_URL}/v2/assets/{asset_id}?catalog_id={catalog_id} returns for the same asset after the Profile API has been invoked on the Sample.csv file:
{
"metadata": {
"rov": {
"mode": 0,
"collaborator_ids": {}
},
"name": "Sample.csv",
"description": "Simple csv file for experiment for getting started document.",
"tags": [],
"asset_type": "data_asset",
"origin_country": "united states",
"rating": 0,
"total_ratings": 0,
"catalog_id": "c6f3cbd8-2b7f-42fb-aa60-___",
"created": 1541526321437,
"created_at": "2018-11-06T17:45:21Z",
"owner_id": "IBMid-___",
"size": 9238,
"version": 2,
"asset_state": "available",
"asset_attributes": [
"data_asset",
"data_profile"
],
"asset_id": "45f4ab8c-37d5-45a1-8adf-___",
"asset_category": "USER"
},
"entity": {
"data_asset": {
"mime_type": "text/csv",
"dataset": true,
"columns": [
{
"name": "Name",
"type": {
"type": "varchar",
"length": 1024,
"scale": 0,
"nullable": true,
"signed": false
}
},
{
"name": "Number",
"type": {
"type": "varchar",
"length": 1024,
"scale": 0,
"nullable": true,
"signed": false
}
}
]
},
"data_profile": {
"971e9c66-be4c-44b4-91f3-___": {
"metadata": {
"guid": "971e9c66-be4c-44b4-91f3-___",
"asset_id": "971e9c66-be4c-44b4-91f3-___",
"dataset_id": "45f4ab8c-37d5-45a1-8adf-___",
"catalog_id": "c6f3cbd8-2b7f-42fb-aa60-___",
"created_at": "2018-11-12T15:32:53.902Z",
"accessed_at": "2018-11-12T15:32:53.902Z",
"owner_id": "IBMid-___",
"last_updater_id": "IBMid-___"
},
"entity": {
"data_profile": {
"options": {
"disable_profiling": false,
"max_row_count": 5000,
"max_distribution_size": 100,
"max_numeric_stats_bins": 200,
"classification_options": {
"disabled": false,
"use_all_ibm_classes": true,
"ibm_class_codes": [],
"custom_class_codes": []
}
},
"execution": {
"status": "finished",
"is_supported": true,
"dataflow_id": "3f1ace02-4d40-451d-9bc7-___",
"dataflow_run_id": "f774f92f-5a61-49ca-8a68-___"
},
"columns": [],
"attachment_id": "8d614be0-6900-403b-ab50-___"
}
}
},
"attribute_classes": [
"NoClassDetected",
"Organization Name"
]
}
},
"attachments": [
{
"id": "b8c7a390-e857-4c34-add8-___",
"version": 2,
"asset_type": "data_asset",
"name": "remote",
"description": "remote",
"connection_id": "070e9be2-40a8-4e0e-___",
"connection_path": "catalogforgettingsta-datacatalog-r1s___/data_asset/Sample_SyjEQUy6m.csv",
"create_time": 1541526323713,
"size": 0,
"is_remote": true,
"is_managed": false,
"is_referenced": false,
"is_object_key_read_only": false,
"is_user_provided_path_key": true,
"transfer_complete": true,
"is_partitioned": false,
"complete_time_ticks": 1541526323713,
"user_data": {},
"test_doc": 0,
"usage": {
"access_count": 0,
"last_accessor_id": "IBMid-___",
"last_access_time": 1541526323713
}
},
{
"id": "8d614be0-6900-403b-ab50-___",
"version": 2,
"asset_type": "data_profile",
"name": "data_profile_971e9c66-be4c-44b4-91f3-___",
"object_key": "data_profile_971e9c66-be4c-44b4-91f3-___",
"create_time": 1542036813627,
"size": 9238,
"is_remote": false,
"is_managed": false,
"is_referenced": true,
"is_object_key_read_only": false,
"is_user_provided_path_key": true,
"transfer_complete": true,
"is_partitioned": false,
"complete_time_ticks": 1542036813627,
"user_data": {},
"test_doc": 0,
"handle": {
"bucket": "catalogforgettingsta-datacatalog-r1s___",
"location": "us-geo",
"key": "data_profile_971e9c66-be4c-44b4-91f3-___",
"upload_id": "done",
"max_part_num": 1
},
"usage": {
"access_count": 0,
"last_accessor_id": "iam-ServiceId-12345___",
"last_access_time": 1542036813627
}
}
]
}
Let's look at a few of the most important differences between the primary metadata document for the Sample.csv file before and after profiling:
-
"metadata":"asset_attributes": [ "data_asset", "data_profile" ]- Note the "data_profile" attribute name has been added
-
"entity":-
"data_asset":"columns": the Profile API has added the"columns"field to thedata_assetattribute,"dataset": the Profile API caused this to change from false to true because of the newly added"columns"field
-
"data_profile":- this
"data_profile"attribute is entirely new, and was added by the Profile API. - the name of this secondary attribute matches the name of the secondary asset type "data_profile", which was (previously) created by the Profile API.
- the contents of this
"data_profile"attribute was entirely decided by the Profile API, not by the Assets API. - this attribute contains a lot of extended metadata about the "data_profile" run that produced a
"data_profile"extended metadata document.
- this
-
-
"attachments":- a new item has been added to the
"attachments"array - that new item contains the following
metadataabout an extended metadata document:"id": "8d614be0-6900-403b-ab50-___""asset_type": "data_profile"- note that the value "data_profile" matches the name of the "data_profile" attribute that this attachment item belongs to, so linking the attachment item and the attribute.
"handle": contains various fields pointing to the actual attached extended metadata document which is located in some external repository. That extended metadata document will contain a great deal more metadata about the asset resource, that is, about the "Sample.csv" file.
- a new item has been added to the
The next section shows how to retrieve the Extended Metadata Document that's referred to by the new "data_profile" "attachments" item just described above.
Get Attachment - Extended Metadata Document:
The following example builds on the GET Asset example from the previous section and shows how to retrieve an attachment that is an extended metadata document.
An attachment can be retrieved in 4 steps.
The only choices you have for asset_type in a given primary metadata document are listed in that document's "metadata.asset_attributes" field. In the example above those values are:
- "data_asset"
- "data_profile"
The asset_type of the extended metadata document we want is "data_profile".
Step 2: Get the "id" of the "attachments" item whose "asset_type" field has the value you chose in Step 1.
In the primary metadata document, look for the only "attachments" item whose "asset_type" field has the value you chose in Step 1, namely "data_profile". In our example primary metadata document above, that "attachments" item has the "id" value "8d614be0-6900-403b-ab50-___".
Step 3: Invoke the Get Attachment API to get attachment metadata for the attached extended metadata document.
Get Asset Attachment - Request URL
GET /v2/assets/{asset_id}/attachments/{attachment_id}
The values for the above URL parameters are obtained as follows:
-
{asset_id}: is the same as what appears in the"metadata.asset_id"field of the above primary metadata document, namely "45f4ab8c-37d5-45a1-8adf-___" -
{attachment_id}is the of"id"that was obtained in Step 2, namely "8d614be0-6900-403b-ab50-___".
Invoke the above GET Attachment API with the above values, which will return an attachment metadata document as shown in the following response body:
Get Asset Attachment - Response Body:
{
"attachment_id": "8d614be0-6900-403b-ab50-___",
"asset_type": "data_profile",
"is_partitioned": false,
"name": "data_profile_971e9c66-be4c-44b4-91f3-___",
"created_at": "2018-11-12T15:33:33Z",
"object_key": "data_profile_971e9c66-be4c-44b4-91f3-___",
"object_key_is_read_only": false,
"bucket": {
"bucket_name": "catalogforgettingsta-datacatalog-r1s___",
"bluemix_cos_connection": {
"viewer": {
"bucket_connection_id": "5b6bc03d-577d-4609-b3a4-___"
},
"editor": {
"bucket_connection_id": "070e9be2-40a8-4e0e-a468-___"
}
}
},
"url": "https://s3.us-south.objectstorage.softlayer.net/catalogforgettingsta-datacatalog-r1s___/data_profile_971e9c66-be4c-44b4-91f3-___?response-content-disposition=attachment%3B%20filename%3D%22data_profile_971e9c66-be4c-44b4-91f3-___%22&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190423T162446Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=d2d518b66ac64de___%2F2019___%2Fus-geo%2Fs3%2Faws4_request&X-Amz-Signature=ce7322d7291396c511a6df38635df4e85b7c78c173___",
"transfer_complete": true,
"size": 9238,
"user_data": {},
"creator_id": "iam-ServiceId-12345___",
"usage": {
"access_count": 1,
"last_accessor_id": "IBMid-___",
"last_access_time": 1556036686480
}
}
It's important to understand that the GET Attachment API only returns a metadata document that describes where, or how, an attached asset resource or extended metadata document can be accessed or retrieved.
The most important field in the above response is "url" which contains a signed URL that can be used to retrieve the actual extended metadata document. Note that the "url" points to a completely different server than the server that responds to "Assets API" calls! Extended metadata documents are not stored in the catalog.
Step 4: Use the "url" in the response from Step 3 to call the relevant server to get the extended metadata document.
The simplest way to use that "url" value is to paste it into the address bar of a browser, and let the browser retrieve the extended metadata document. Here's a peek at some of the contents of the large extended metadata document that can be retrieved using that "url" value. That large extended metadata document was created by the Profile API and contains a great deal of extended metadata about our small Sample.csv file:
{
"summary": {
"version": "1.9.3",
"row_count": 2,
"score": 1,
"score_stats": {
"n": 2,
"mean": 1.0,
"variance": 0.0,
"stddev": 0.0,
"min": 1.0,
"max": 1.0,
"sum": 2.0
},
...
},
"columns": [{
"name": "Name",
"value_analysis": {
"distinct_count": 2,
"null_count": 0,
"empty_count": 0,
"unique_count": 2,
"max_value_frequency": 1,
"min_string": "abc",
"max_string": "def",
"inferred_type": {
"type": {
"length": 3,
"precision": 0,
"scale": 0,
"type": "STRING"
}
},
...
}, {
"name": "Number",
"value_analysis": {
"distinct_count": 2,
"null_count": 0,
"empty_count": 0,
"unique_count": 2,
"max_value_frequency": 1,
"min_string": "123",
"max_string": "456",
"min_number": 123.0,
"max_number": 456.0,
"inferred_type": {
"type": {
"length": 3,
"precision": 3,
"scale": 0,
"type": "INT16"
}
},
...
]
}
Get Attachment - Asset Resource:
The 4 steps given above to retrieve an extended metadata document can also be used to retrieve an asset resource like the Sample.csv file example.
The main difference is that in Step 1 you would choose the asset_type "data_asset" because that is the primary asset type of the primary metadata document, ie. the asset_type that identifies both the primary attribute and the primary attachment, ie, the asset resource.
Create Asset: book
Before you can create a primary metadata document (ie, card) the asset type that you want to use for that card must already exist. You can use one of the already available asset types, or you can use an asset type that you have created.
The Create Asset Type: book section shows how to create an asset type named book. In this section, that asset type will be used to create a primary metadata document for a book asset resource. That primary metadata document will have:
- a
"metadata.asset_type"field with the value"book" - a primary attribute called
"book".
Use the following endpoint to create a primary metadata document for a book asset resource:
Create Asset: book - Request URL:
POST {service_URL}/v2/assets?catalog_id={catalog_id}
Create Asset: book - Request Body:
{
"metadata": {
"name": "Getting Started with Assets",
"description": "Describes how to create and use metadata for assets",
"tags": ["getting", "started", "documentation"],
"asset_type": "book",
"origin_country": "us",
"rov": {
"mode": 0
}
},
"entity": {
"book": {
"author": {
"first_name": "Tracy",
"last_name": "Smith"
},
"price": 29.95
}
}
}
The above request body specifies the preliminary contents for the primary metadata document about to be created. Most of the fields have been described previously in the Asset's Primary Metadata Document section. However, there are a few things to note in particular about the above request:
"metadata": you supply the values of only some of the fields that will end up appearing inside the"metadata"field of the primary metadata document about to be created, including:"asset_type": the value"book"matches the name of the asset type for this document"name": the name to use for the asset being described by this document"description": a description for the asset
Notice that you do not supply a "metadata.asset_attributes" field in the request body. If you include a "metadata.asset_attributes" field in your Create Asset request body then the request will be rejected because it tried to supply a reserved value. The Assets API reserves control of the contents of the "metadata.asset_attributes" field.
"entity": you supply the entire contents of the"entity"field"book":- this is the primary attribute of the primary metadata document
- the name of this attribute matches the name of the corresponding primary asset type "book"
- contains metadata describing a book (does not contain the actual book asset resource)
Notice the above "book" attribute doesn't contain a field called "title" - a field which might be expected in an attribute for a book. In this case, we've chosen to put the title of the book in the "metadata.name" field of the card. However, the creator of the "book" attribute is free to include whatever fields they want in that attribute, including a field called "title" if desired.
Create Asset: book - Response Body:
{
"metadata": {
"rov": {
"mode": 0,
"collaborator_ids": {}
},
"usage": {
"last_updated_at": "2019-04-30T14:37:57Z",
"last_updater_id": "IBMid-___",
"last_update_time": 1556635077746,
"last_accessed_at": "2019-04-30T14:37:57Z",
"last_access_time": 1556635077746,
"last_accessor_id": "IBMid-___",
"access_count": 0
},
"name": "Getting Started with Assets",
"description": "Describes how to create and use metadata for assets",
"tags": [
"getting",
"started",
"documentation"
],
"asset_type": "book",
"origin_country": "us",
"rating": 0,
"total_ratings": 0,
"catalog_id": "c6f3cbd8-___",
"created": 1556635077746,
"created_at": "2019-04-30T14:37:57Z",
"owner_id": "IBMid-___",
"size": 0,
"version": 2,
"asset_state": "available",
"asset_attributes": [
"book"
],
"asset_id": "3da5389d-d4a4-43da-be1f-___",
"asset_category": "USER"
},
"entity": {
"book": {
"author": {
"first_name": "Tracy",
"last_name": "Smith"
},
"price": 29.95
}
}
"asset_id": "3da5389d-d4a4-43da-be1f-___"
}
Notice that the card returned in the Create Asset Response Body has many more fields than were present in the Request Body. The Create Asset API has added a lot of information to the "metadata" part of the primary metadata document:
"asset_id": most importantly, the Create Asset API has given your primary metadata document an id"owner_id": the API has made the caller of the API be the owner of the asset"created_at": the API has recorded the time at which the metadata document was created. In general, this is not the same as the time at which an attached asset resource was created (although in this case there is no attached asset resource)."total_ratings": contains the number of ratings this asset has recieved. 0 for now because the primary metadata document is brand new."usage": usage statistics. Since this is a brand new card these statistics don't yet contain much interesting data."asset_attributes": notice that the Create Asset API has added the name of the primary attribute to this array.
On other hand, notice that the Create Asset API did not modify the contents of the "entity" field in any way. In particular, the Create Asset API did not modify the contents of the primary attribute "book".
Your catalog now contains a primary metadata document for a "book" asset resource.
Associate a Term with an Asset
You can associate one or more terms with an asset. Within the asset's primary metadata document a pre-defined attribute called "asset_terms" (one of the global asset_types) is used to contain the array of terms associated with the asset.
The first time any term is associated with an asset, the Create Asset Attribute API must be used to create and populate an instance of the "asset_terms" attribute inside the asset's primary metadata document. In the following example, we're only associating a single term with an asset, so the "list" value in the request body is an array with a single element containing info related to that single term.
POST {service_URL}/v2/assets/{asset_id}/attributes?catalog_id={catalog_id}
Body:
{
"name": "asset_terms",
"entity": {
"list": [
{
"term_id": "--insert your term's id here--",
"term_display_name": "first_term"
}
]
}
}
Note: the field named "term_display_name" is not strictly mandatory, but is highly recommended because its value is what will be used when searching for assets by term. Its value is also the term name that users will see in the Catalog UI.
The response should look like:
{
"asset_id": "--your asset id--",
"asset_terms": {
"list": [
{
"term_id": "--your term id--",
"term_display_name": "first_term"
}
]
},
"href": ".../v2/{asset_id}/attributes/asset_terms?catalog_id={catalog_id}"
}
The next time you GET the asset you should see the "asset_terms" attribute you just created:
{
"metadata": {
...
},
"entity": {
...
"asset_terms": {
"list": [
{
"term_id": "--your term id--",
"term_display_name": "first_term"
}
]
}
},
"attachments": [
...
]
}
If you want to associate additional terms with an asset, or remove existing terms, then use the Update Asset Attribute API. For example, the following adds an additional term to the already existing "asset_terms" attribute of the asset used in the above example:
PATCH {service_URL}/v2/assets/{asset_id}/attributes/asset_terms?catalog_id={catalog_id}
Body:
[
{
"op": "replace",
"path": "/list",
"value": [
{
"term_id": "--insert your term's id here--",
"term_display_name": "first_term"
},
{
"term_id": "--insert your second term's id here--",
"term_display_name": "second_term"
}
]
}
]
You can use GET the asset to see the new collection of terms in the asset_terms attribute of the asset.
Associate a Classification with an Asset
You can associate one or more classifications with an asset. The classifications associated with the asset reside within the "data_profile" attribute of the asset. When user runs asset profiling, then the profiling job will add the suitable classifications. However, users can manually add classifications to an asset also.
If profile has not run on the asset, then the "data_profile" attribute will not exist. In such a scenario, the Create Asset Attribute API must be used to create and populate an instance of the "data_profile" attribute inside the asset's primary metadata document. Since the classification is added manually, the property added will be "data_classification_manual".
In the example below, we are adding a single classification to an asset in a catalog. If you don't know the id and global id of the classification, you can run the API GET artifact of a given type. If you know the id of the classification, you can obtain the global_id of the classification by running the GET classification API.
POST {service_URL}/v2/assets/{asset_id}/attributes?catalog_id={catalog_id}
Body:
{
"name": "data_profile",
"entity": {
"data_classification_manual": [
{
"id": "--insert your classification's id here--",
"name": "your_classification_name",
"global_id": "--insert your classification's global id here--"
}
]
}
}
The response should look like:
{
"asset_id": "{asset_id}",
"data_profile": {
"data_classification_manual": [
{
"id": "{classification id}",
"name": "your_classification_name",
"global_id": "{classification global id}"
}
]
},
"href": "/v2/assets/{asset_id}/attributes/data_profile?catalog_id={catalog_id}"
}
You can use GET the asset to see the new collection of classifications in the data_profile attribute of the asset.
{
"metadata": {
...
},
"entity": {
...
"data_profile": {
"data_classification_manual": [
{
"id": "{classification id}",
"name": "your_classification_name",
"global_id": "{classification global id}"
}
]
}
},
"attachments": [
...
]
}
If you want to associate additional classifications with an asset, or remove existing classifications, then use the Update Asset Attribute API. For example, the following adds an additional classification, to the existing "data_profile" attribute of the asset, without replacing the classification added in the previous example:
PATCH /v2/assets/{asset_id}/attributes/data_profile?catalog_id={catalog_id}
Body:
[
{
"op": "add",
"path": "/data_classification_manual/1",
"value":
{
"id":"--insert your second classification's id here--",
"name":"your_second_classification_name",
"global_id":"--insert your second classification's global id here--"
}
}
]
The response should look like:
{
"data_classification_manual": [
{
"id": "{classification id}",
"name": "your_classification_name",
"global_id": "{classification global id}"
},
{
"id": "{second classification id}",
"name": "your_second_classification_name",
"global_id": "{second classification global id}"
}
]
}
The following example replaces all the classifications associated with the asset and replaces with a new list
PATCH /v2/assets/{asset_id}/attributes/data_profile?catalog_id={catalog_id}
Body:
[
{
"op": "replace",
"path": "/data_classification_manual",
"value":
[
{
"id":"--insert your classification's id here--",
"name":"your_classification_name",
"global_id":"--insert your classification's global id here--"
}
]
}
]
The response should look like:
{
"data_classification_manual": [
{
"id": "{classification id}",
"name": "your_classification_name",
"global_id": "{classification global id}"
}
]
}
Duplicate Asset
Duplicate Asset Overview
When a CAMS call tries to create an asset (e.g. create a new asset, promote/publish/clone an asset, etc.), CAMS can optionally detect pre-existing duplicate assets and take appropriate actions based on configurations and query parameters, e.g., ignoring the duplicates and create a new asset, or failing the call and returning an error saying duplicates were found, or updating the existing duplicate.
Planned from CPD 4.7, when a CAMS call tries to update an asset, CAMS will also optionally detect if the asset with the incoming change would have any duplicates if the change were persisted and take appropriate actions based on configurations and query parameters, e.g., ignoring the duplicates and update the asset, or failing the call and returning an error saying the change would result in duplicates.
This process is called duplicate asset processing. This section describes how the duplicate asset processing works in CAMS and how you can make it work in the ways you desire.
What is a duplicate
An asset is considered a duplicate if it fits any of the following scenarios:
- Original asset - the asset that the incoming asset was originally cloned/published from.
For instance, if you cloned/published an asset A to a project/catalog and resulted in asset B, and then try to publish/clone the asset B back to the original catalog/project, the asset A will be seen as the original asset and considered as a duplicate.
- Copies of the same asset - an asset is cloned/published/promoted from the same asset as the incoming asset
For example, if you cloned/published/promoted an asset A to a project/catalog/space and resulted in asset B, and then try to clone/publish/promote the asset A again to the same target project/catalog/space, the asset B will be seen as the copy of the same asset and considered as a duplicate.
- Asset with the same values - an asset has the same values as the incoming asset based on the effective duplicate detection strategy of the asset type. See Duplicate Detection Strategy section for more details about duplicate detection strategy.
Let's say that the effective duplicate detection strategy of the asset type data_asset in a project is DUPLICATE_DETECTION_BY_NAME (i.e., the duplicate detection will base on the metadata.name field). If you try to create an asset of type data_asset with the name KPIReport2021 in this project, and there is an existing asset A of type data_asset with the same name, then the asset A will be considered as a duplicate.
What to do with a duplicate
Users can set the configuration duplicate_action of the asset containers and/or specify the query parameter duplicate_action while calling endpoints to control how the service handles duplicate assets. The valid values of duplicate_action for calls creating a new asset are:
IGNORE- ignore the duplicates and create a new assetREJECT- fail the call and return an error response similar to the one below (no asset will be created):
{
"trace": "290c281c-4adc-4e40-aa49-aaf7cd2dbf6a",
"errors": [
{
"code": "already_exists",
"message": "ASTSV3040E: Duplicate assets exist. '[cc5f7412-5c96-4d66-9c14-40b3c944ad79, 244a3612-63a8-4140-9423-f40841be33ee]'"
}
]
}
UPDATE- update the duplicate with the incoming changes. See Multiple duplicates for how to choose the duplicate for updating if more than one duplicate is found. See here on how the duplicate asset is updated.REPLACE- overwrite the duplicate with the input values. See Multiple duplicates for how to choose the duplicate for overwriting if more than one duplicate is found. See here on how the duplicate asset is overwritten.
The valid values of duplicate_action for calls making changes to an existing asset (including restoring a deleted asset) are:
IGNORE- ignore the duplicates and update the assetREJECT- fail the call and return an error response similar to the one below. The asset will not be updated or restored.
{
"trace": "8ea27315-c958-435a-b415-e3632a664dbc",
"errors": [
{
"code": "already_exists",
"message": "ASTSV3128E: The asset will have duplicate assets with IDs '[a0a54f65-8a3d-4f22-95b7-5456d8e43a71]' after saving the change."
}
]
}
Or the below for restoring an asset. Note that the reason that the id of the asset that will have duplicates is also in the message is that restoring an asset may potentially restore multiple related assets and it is possible that some of these related assets will have duplicates.
{
"trace": "7b2668a4-c794-4720-83dd-f4f16e9d0a04",
"errors": [
{
"code": "already_exists",
"message": "ASTSV3128E: The asset '8c740814-5fc0-4294-a2be-f042f15098f1' will have duplicate assets with IDs '[a0a54f65-8a3d-4f22-95b7-5456d8e43a71]' after being restored."
}
]
}
UPDATEandREPLACEare not allowed to be used for the query parameterduplicate_actionfor calls updating assets. However, if the query parameterduplicate_actionis not supplied and the configurationduplicate_actionis set to one of these values in the asset container level, they will be the effective value of theduplicate_action. In which case, they will be treated the same asREJECT.
The configuration duplicate_action can be set in the asset container level during the creation of a container and can be modified later by using the endpoint PUT /v2/asset_containers/configurations. If the configuration duplicate_action is not specified in an asset container, it will be equivalent to IGNORE.
The following example shows how to supply the configuration duplicate_action (along with other duplicate asset processing related configurations) while creating a catalog:
{
"name": "my catalog",
...
"configurations": {
"duplicate_action": "REJECT",
...
}
}
The following example shows how to update the configuration by using the endpoint PUT /v2/asset_containers/configurations:
{
"duplicate_action": "REPLACE",
...
}
The configuration duplicate_action can be overwritten by a query parameter duplicate_action for individual calls to control how CAMS handles duplicates for these particular calls. The endpoints that support the query parameter are listed below. Note that the allowed options may differ from endpoint to endpoint depending on if the endpoint supports all available options.
POST /v2/assetsPOST /v2/data_assetsPOST /v2/assets/{asset_id}/publishPOST /v2/assets/{asset_id}/clonePOST /v2/assets/{asset_id}/promotePOST /v2/assets/{asset_id}/deepcopyPOST /v2/assets/bulk_createPOST /v2/assets/bulk_patchPATCH /v2/assets/{asset_id}POST /v2/assets/{asset_id}/attributesPATCH /v2/assets/{asset_id}/attributes/{attribute_key}DELETE /v2/assets/{asset_id}/attributes/{attribute_key}POST /v2/assets/{asset_id}/attachmentsDELETE /v2/assets/{asset_id}/attachments/{attachment_id}POST /v2/trashed_assets/{asset_id}/restore
Duplicate Detection Strategy
The duplicate detection strategy defines what fields to be used for determining if assets of a particular asset type are duplicates. The available duplicate detection strategies are:
DUPLICATE_DETECTION_BY_NAME- themetadata.namefieldDUPLICATE_DETECTION_BY_RESOURCE_KEY- themetadata.resource_keyfieldDUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY- themetadata.nameand themetadata.resource_keyfieldsDUPLICATE_DETECTION_NOT_APPLICABLE- no duplicate will be determined. If this strategy is used, no duplicate will be determined by the strategy. At the same time, it also disables the duplicate detection fororiginal assetandcopies of the same asset. In other words, it disables duplicate detection for assets of the asset type completely.
The duplicate detection strategy can be set in several levels as shown below (from the highest priority to the lowest priority). Setting with a higher priority will take precedence over the setting with a lower priority.
- Strategy of the asset type defined in the asset container configuration, e.g.,
{
"duplicate_strategies": [
{
"asset_type": "data_asset",
"strategy": "DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY"
}
]
}
- Strategy specified in the asset type definition, e.g.,
{
"description": "Job Run",
"fields": [],
"identity": {
"strategy": "DUPLICATE_DETECTION_NOT_APPLICABLE"
}
}
-
System default strategy of the asset type in the residing asset container. i.e.,
- Project/Space:
connection:DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY- Catalog:
connection:DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEYdata_asset:DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY
-
The
default_duplicate_strategyspecified in the asset container configuration (which applies to all asset types), i.e.,
{
"default_duplicate_strategy": "DUPLICATE_DETECTION_BY_NAME"
}
- System default strategy
DUPLICATE_DETECTION_BY_NAME(which applies to all asset types)
Multiple duplicates
It is possible that a call may find more than one duplicate for a given asset. It could be that the duplicates were created before CAMS started processing duplicate assets, or the duplicates were created because multiple calls were creating the same asset at the same time.
If the effective value for duplicate_action is REJECT, CAMS will fail the call and return the asset ids of all the duplicates in the error response. If the effective value for duplicate_action is UPDATE or REPLACE, CAMS will rank the duplicates based on the following order and choose the duplicate that has the highest score and the caller has permission to update as the target for updating or overwriting. When all things are equal, the duplicates will be ranked by the created time (i.e., the metadata.created field) from the earliest to the most recent.
- Original asset
- Copies of the same asset
- Asset with the same values
How the duplicate asset is updated or overwritten
If the effective value of duplicate_action is UPDATE or REPLACE, the following information of the duplicate asset that has the highest score and the caller has permission to update will be updated or overwritten with the values from the incoming asset based on the rules. Any other aspects of the duplicate asset will not be updated or overwritten, e.g., privacy settings, collaborators, owners, source asset, ratings, revisions, non-inline relationships, related assets, etc.
- metadata
metadata.namemetadata.descriptionmetadata.resource_keymetadata.origin_countrymetadata.tags
- attributes (e.g.,
entity.data_asset,entity.data_profile,entity.column_info, etc.) - attachments (i.e.,
attachments[*])
If duplicate_action is UPDATE, the chosen duplicate asset will be updated as described below. The result will look the same as the duplicate asset but with the incoming changes.
- The listed metadata fields will be replaced with the values from the incoming asset if the value from the incoming asset is not
null - All attributes in the incoming asset will be copied over and any existing attribute will be replaced. Some exceptions may apply, e.g.,
- If the existing or incoming attribute
connectionrepresents a reference connection, the existing attributeconnectionwill not be replaced. - Reference copy terms are preserved
- If the existing or incoming attribute
- All attachments in the incoming asset will be copied over. Any existing attachments with the same
asset_typeas the attachments in the incoming asset will be removed.
If duplicate_action is REPLACE, the chosen duplicate asset will be updated as described below. The result will look the same as the incoming asset with some exceptions.
- All listed metadata fields will be replaced with the values from the incoming asset (even if the value from the incoming asset is
null) - All existing attributes will be removed and all attributes in the incoming asset will be copied over with the exception of the attribute
connection. If the existing or incoming attributeconnectionrepresents a reference connection, the existing attributeconnectionwill remain unchanged. - All existing attachments will be removed and all attachments in the incoming asset will be copied over
Let's say you have an existing asset that looks like below
{
"metadata": {
"name":"B",
"description":"C",
"tags":[
"confidential"
]
},
"entity": {
"data_asset": {
"mime_type": "binary"
},
"something": {}
},
"attachments":[
{
"asset_type": "data_asset",
"name": "attachment 1"
},
{
"asset_type": "something",
"name": "attachment 2"
}
]
}
and you try to add the following asset
{
"metadata": {
"name":"A",
},
"entity": {
"data_asset": {
"mime_type": "text/csv"
}
},
"attachments":[
{
"asset_type": "data_asset",
"name": "attachment 3"
}
]
}
If the effective duplicate_action is UPDATE, the existing asset will be modified to be the following
{
"metadata": {
"name":"A",
"description":"C",
"tags":[
"confidential"
]
},
"entity": {
"data_asset": {
"mime_type": "text/csv"
},
"something": {}
},
"attachments":[
{
"asset_type": "something",
"name": "attachment 2"
},
{
"asset_type": "data_asset",
"name": "attachment 3"
}
]
}
If the effective duplicate_action is REPLACE, the existing asset will be modified to be the following
{
"metadata": {
"name":"A"
},
"entity": {
"data_asset": {
"mime_type": "text/csv"
}
},
"attachments":[
{
"asset_type": "data_asset",
"name": "attachment 3"
}
]
}
Backup revision
When the best duplicate is updated as a result of asset duplicate processing, a revision is created in case we want to go back or review what was changed. The revision will contain commit information similar to below:
{
"committed_at": "2020-11-17T08:13:39.103Z",
"commit_message": "Backup prior to update the best duplicate",
"reason": "update_duplicate",
"duplicate_source": {
"operation": "clone",
"asset_id": "ca0007d9-051d-478f-b87f-82f38fc6997c",
"catalog_id": "c548b021-e026-49a6-aa60-35fe478afdb5"
}
}
The asset in the response will contain the previous_revision field in such a case. Which can be used to determine if the call indeed created a new asset or updated an existing asset.
{
"metadata": {
...,
"commit_info": {
"previous_revision": 1
}
},
"entity": {
...
},
"asset_id": "c1bf6686-836c-4f93-b173-c2ed52da8e76"
}
Check duplicates before creating an asset
The duplicate asset processing automatically kicks in when a CAMS call tries to create an asset. However, in some cases, you may want to check possible duplicates before creating an asset or before publish/clone/promote/deepcopy an asset. CAMS provides an endpoint POST /v2/assets/duplicates/search to help you do this. You can either supply an existing asset or an asset payload to check the duplicates. The endpoint will list all the potential duplicates and why they were considered duplicates.
Lineage and Activity event messages change
If the query parameter duplicate_action is UPDATE or REPLACE and duplicate assets are found, the calls will change from creating a new asset to updating an existing asset. As a result, the corresponding Lineage and Activity event messages will also change from creating an asset to updating an asset.
Known issues/limitations
Duplicate assets may be created due to race condition
When a call is made to create an asset, CAMS searches for potential duplicates and creates the asset only if no duplicate is found. If multiple calls are made at the exact same time to create the same asset, it is possible to result in a duplicate. For example, two calls try to create the same asset at the same time, and both calls search for potential duplicates and do not find any duplicates; both calls think there is no duplicate and create the asset. As the result, the same asset will be created twice and each asset is a duplicate of the other.
There is currently no way to prevent such cases from happening. If this happened, the user would have to choose one of these assets and delete others. Internally, CAMS always favours the asset that has the earliest value in the metadata.created field and chooses it for future duplicate updating/overwriting operations.
Troubleshooting
Duplicate assets are not detected
Sometimes you may see assets that look like duplicates but are not detected as duplicates. You can call the GET /v2/assets/{asset_id} API to get the JSON representation of these assets and compare the fields that are used for identifying duplicates. If the fields are not the same, then the assets are not duplicates. Otherwise, it may fall into one of the situations where real duplicates are not detected. Please see the Known issues/limitations section for more details.
For instance, if the effective duplicate detection strategy is DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY, you can compare the metadata.name and the metadata.resource_key fields of these assets and see if they are indeed the same; if the effective duplicate detection strategy is DUPLICATE_DETECTION_BY_NAME, you can compare the metadata.name field of these assets. For details about what fields are used for a strategy, please see Duplicate detection strategy section.
Asset Types
Asset Types serve multiple purposes in the Assets API. Asset types fall into two categories:
-
Primary asset type:
- describes the primary type of an asset
- every primary metadata document (ie, card) will have exactly one primary asset type, whose name will be stored in the card's
"metadata.asset_type"field - every card will have exactly one primary attribute whose name matches the name of the primary asset type
- a very common example of a primary asset type is the "data_asset" type, examples of which are shown throughout this documentation
-
Secondary / Extended asset type:
- a secondary / extended asset type describes an inter-related group of additional metadata for an asset resource
- a primary metadata document can have 0, 1, or many secondary / extended asset types
- information for a secondary / extended asset type is stored in a secondary / extended attribute in a primary metadata document
- a very common example of a secondary / extended asset type is "data_profile". See Get Asset - CSV File - Response Body - After Profiling for an example "data_profile" attribute.
- secondary / extended / decorator asset types can be used to simulate type inheritance
The names of various asset types are used in the following ways, all at once, within a single primary metadata document:
- describe the type of an asset resource, via the
"metadata.asset_type"field - describe the type of an object that contains extended information for an asset resource. For example, the type of an extended metadata document via an
"attachments[_].asset_type"field. - assign names and types to attributes in the "entity" field of a primary metadata document
- implicitly tie various related parts of a primary metadata document to each other. For example, see the green rectangles and arrows in the Parts of a Primary Metadata Document Figure.
The content, or definition, of an asset type serves the following purposes:
- tell the catalog what fields of an attribute should be indexed for searching
- specify search paths and cross attribute searching
- specify additional features like relationships and external asset previews (both of which are beyond the scope of this document)
An asset type must exist in the catalog before it can be used for any of the above purposes.
As of this writing there are several asset types available, including the following:
- data_asset
- folder_asset
- policy_transform
- asset_terms
- column_info
- connection
- ai_training_definition
- data_flow
- activity
- notebook
- machine-learning-stream
- dashboard
- data_profile_nlu
You are free to use any of the above asset types. You do not have to, nor are you allowed to, create or over-write any of the above asset types.
Use the Create Asset Type API to create your own asset type. See Asset Type Fields for an overview of the specification of an asset type. See Create Asset Type: book for an example of creating an asset type.
Asset Type Fields
Here is a description for each of the fields in the definition of an asset type. You supply values for these fields when creating an asset type. You will see those same values returned when you get a list of asset types or get a specific asset type.
"name":- the name and identifier for the asset type
- should contain only lowercase letters
- will be used in various places in primary metadata documents, including:
- can be used in catalog searches of attribute contents
"description": a description for this asset type"fields":- an array that contains information for the fields in the corresponding attribute that should be indexed for subsequent searches.
- does not (necessarily) describe all the fields in attributes of this asset type.
- there must be at least one item in this array. In other words, there must be at least one index for an asset type.
- see the following Fields Table for a description of the contents of an item in the
"fields"array - see "fields" and "properties" Note below
"properties":- an object that contains "non-index" information for the fields in the corresponding attribute. This information is typically used by UIs that display/edit assets.
- does not (necessarily) describe all the fields in attributes of this asset type.
- see the following Properties Table for a description of the contents of an item in the
"properties"object - see "fields" and "properties" Note below
"external_asset_preview": beyond the scope of this document"relationships": beyond the scope of this document"localized_metadata_attributes": a description for this asset type"decorates": list of pointers to types this type can decorate"identity": identity definition of the assets of the type"global_search_searchable": list of fields made searchable through Global Search functionality- The fields correspond the the
"key"defined in the field
- The fields correspond the the
"attribute_behavior": define the behavior only if this asset type is used as an attribute- it contains a field
"remove_on_copy". This field can take boolean values true or false. - when
"remove_on_copy"is true, then during cloning, publishing or promoting the asset, the attribute is removed from the asset
- it contains a field
"attribute_only": takes boolean values true or false. When true, then this attribute will be used as custom attributes"data_protection": asset type properties and attachments that should be removed when user who does not have access is trying to view the data"is_column_custom_attribute": takes boolean values true or false. When true, then this attribute can be applied as a column level attribute. See Columns and Column Level Attributes"can_have_image": takes boolean values true or false. Set to true if asset type is expected to support uploading of images"icon_id": name or id of the svg image to be used as the icon for the asset type"allow_decorators": takes boolean value true or false. When true, custom attributes can decorate this asset type
Note: "fields" and "properties" can, optionally, both be used to describe the exact same field in an attribute. Whether you use "fields" and/or "properties" depends on what you want to specify for a field. For example, if you're creating an asset type named "person" and a person has a field called "birthdate" (resulting in "entity.person.birthdate" being present in the primary metadata document) then:
- if you want
birthdateto be indexed (for searching) then you would include an entry in the"fields"array forbirthdate - if you want a UI to understand/display the
birthdateproperly then you would include an entry in the"properties"object for that samebirthdatefield
See this example which shows both an example "fields" array and an example "properties" object.
| Key | Description | Example | Required |
|---|---|---|---|
| key | the name of both the field that will appear in an attribute for this asset type, and the name of the corresponding index for that attribute field | data_asset.mime_type | Yes |
| type | the data type of the field being indexed | boolean, or number, or string | Yes |
| facets | beyond the scope of this document | true or false | No. Defaults to false. |
| search_path | a json path that locates a field in the attribute | See Search Path Examples below. | Yes |
| is_searchable_across_types | specifies whether this field can be used in a query without specifying the asset type | true or false | No. Defaults to false. |
| Name | Type | Description |
|---|---|---|
| type | String | Specifies the data type for the property. This value is required. Possible types are: string, number |
| description | String | A displayable string to describe the property. |
| is_array | boolean | true if the property value is multi-valued (json array). |
| required | boolean | true if the property requires a value to be set. |
| hidden | boolean | true if the application UI should not display the property or value. |
| readonly | boolean | true if the property should not be changed once set. |
| default_value | matches the "type" | A value that should be set if no value is provided when the asset attribute is created. |
| placeholder | string | A string an application UI can use as a prompt before a value is entered. |
| values | array, elements matching "type" | An array of allowed values for the property. Used to describe a limited enumeration or "choice list". |
| minimum | integer/number | For an integer or number property, the minimum allowed value. |
| maximum | integer/number | For an integer or number property, the maximum allowed value. If both minimum and maximum are specified, minimum must be less than or equal to maximum. |
| min_length | integer | For a string property, the minimum allowed length. If specified, must be greater than or equal to zero. |
| max_length | integer | For a string property, the maximum allowed length. If specified, must be greater than or equal to zero. If both min_length and max_length are specified, min_length must be less than or equal to max_length. |
| properties | object | For a property of type 'object', the recursive definition of the properties, described as in this table. This allows describing nested object-valued properties. |
Search Path Examples
-
See the request body in Create Asset Type: book for an example of where a search path is used in the definition of an asset type.
- Note: when you specify a search path in the definition of an asset type's
"field", you only specify the path within the correspondingly named attribute. You needn't specify the attribute name. For example if you have an attribute called"book"that has a field called"author.last_name"within it, you only need to specify"author.last_name"as the search path - not"book.author.last_name".
- Note: when you specify a search path in the definition of an asset type's
-
See Search Asset Type: attribute - book for an example of where a search path is used in the body of a search.
- Note: when you specify a search path in the body of search you must specify the name of the attribute being searched. For example if you have an attribute called
"book"that has a field called"author.last_name"within it, you would include the name of the attribute in the search path:"book.author.last_name".
- Note: when you specify a search path in the body of search you must specify the name of the attribute being searched. For example if you have an attribute called
-
"price": a simple path contains just the name of the field to be searched. In this case the attribute being searched should have a simple field called"price". -
"tags[]": traverse a json array called"tags". Because tags[] is not followed by any further names it must be a basic type (e.g. string, boolean, or number), and so its elements will be indexed directly. -
"asset_terms[].name": this search path indicates a path starting with a json object named"term_assignments"at the top, traversing through a json array named asset_terms (you use the [] at the end of the field name to indicate it's an array), landing on another json object that has a field called"name". The"name"field will be indexed. -
"asset_terms[0].name": same as above but only the first element in the"asset_terms"array will be traversed. -
"columns.*.tags[]": traverse an object called"columns"followed by any column name (the '*' indicates a wildcard), followed by a json array called"tags". Because tags[] is not followed by any further names it must be a basic type (e.g. string, boolean, or number), and so its elements will indexed directly. -
"column_tags.*[]": the json object"column_tags"contains a series of arrays indicated by *[]. The name of the array object doesn't matter - we want to index it.
Global Search searchable custom attributes
Fields that have been identified as Global Search searchable by being included in global_search_searchable array by their key, will be synchronized as custom attributes to Global Search microservice, and will become searchable via Global Search. Note that field will only be synchronized to Global Search if field definition contains a valid search_path. Values found at that search_path will be synchronized to Global Search, otherwise field will be ignored. Any values provided in global_search_searchable array which do not correspond to any existing fields of the type will be ignored.
An example of valid configuration of global_search_searchable attributes would be:
{
"name": "book",
"description": "Book asset type",
"fields": [
{
"key": "last_name",
"type": "string",
"facet": false,
"is_array": false,
"search_path": "author.last_name",
"is_searchable_across_types": true
}
],
"global_search_searchable": [
"last_name"
],
"properties": {
"price" : {
"type": "number",
"description": "Suggested retail price",
}
}
}
Following are key characteristics of a valid definition:
- Key of a field
last_nameis included inglobal_search_searchablearray. - Field
last_namehas a properly definedsearch_pathwhich contains a valid json path.
Common pitfalls:
- Not including
search_pathinto the field definition will cause the field to be ignored and prevent it from indexing. Similarly, an invalid json path definition withinsearch_pathwhich either is not formatted correctly, or points to a wrong location will prevent field value from being indexed asglobal_search_searchable. - Make sure that only the key value of the field is used inside
global_search_searchable. In the above examplelast_nameis the name of the field, so theglobal_search_searchablearray contains anlast_name.
data_asset Type
"data_asset" is by far the most commonly used already available asset type. It can be seen in:
- the Parts of a Primary Metadata Document Figure
- many of the examples in the Assets API Examples and Asset Types API Examples sections
- the default asset type used when you drag an asset resource file onto the Create Asset page.
The reason "data_asset" is so popular is that it is a generic asset type that allows you to declare a specific type for a given asset resource without explicitly creating an asset type named after that specific type. For example, say you want to create a primary metadata document for a csv file. You could first create a specific asset type named, say, "csv_file", and then create a primary metadata document (for that csv file) and specify "csv_file" as the value for "metadata.asset_type". However, you can avoid creating a specific "csv_file" asset type by instead using the generic "data_asset" asset type and then use the "mime_type" field of the "data_asset" attribute to declare that the specific type of your asset resource is a csv file. To do so, the primary metadata document for the csv file would have:
- a
"metatada.asset_type"value of the generic type"data_asset" - a
"entity.data_asset.mime_type"value of the specific type"text/csv".
The fields "asset_type" and "mime_type" both describe the "type" of the asset resource. However:
- the type specified by the
"metatada.asset_type"field (ie,"data_asset") is generic - the type specified by the
"entity.data_asset.mime_type"field (ie,"text/csv") is specific
It is the "mime_type" field of the data_asset type that allows you to declare a specific type for an asset without creating that specific type(!).
So, in its most basic use, the "data_asset" asset type is a very "lite" asset type. It's used to avoid creating many other "heavier" asset types. However, if you need to create more complex attributes with indexes for specific fields in your attribute then you will have to create your own asset type (see Create Asset Type: book for an example).
The other two fields of the type "data_asset" are "dataset" and "columns".
"dataset"value offalsemeans that the"columns"field is absent in a"data_asset"attribute"dataset"value oftruemeans that the"columns"field is present in a"data_asset"attribute
The "columns" field of a "data_asset" attribute is optionally used to specify metadata for columns of assets that have columns, like csv files, spreadsheets, database tables, etc.
The full definition of the "data_asset" type is shown in Get Asset Type: data_asset - Response Body.
See Get Asset - CSV File - Response Body - Before Profiling and Get Asset - CSV File - Response Body - After Profiling for examples where a "data_asset" is used for a csv asset resource.
Using Secondary / Extended / Decorator Asset Types to Simulate Type Inheritance
Asset type inheritance/subclassing is not supported by the Asset Type API. Asset types can be combined through the use of Secondary / Extended / Decorator Asset Types, to simulate inheritance through composition of multiple types. A "decorator" can combine a common set of properties that under a traditional inheritance model would be part of the super class and "decorate" those types that would traditionally be the child class. The asset type decorates field specifies the child asset types that are decorated. Note that type decoration is not enforced by the API, i.e. there is no checking that the contents of an asset has fields which match what is declared in any asset type. However, the IKC UI honors the type decorator setting by presenting the fields in decorator types as custom attributes in the Asset Overview screen UI under "Details" section. For more details on using the asset type decorator feature, see Tailor your Data Catalog with custom asset attributes.
Get Asset Types
You can get a list of the asset types in a catalog using the following Asset Types API:
Get Asset Types - Request URL:
GET {service_URL}/v2/asset_types?catalog_id={catalog_id}
Get Asset Types - Response Body:
{
"resources": [
{
"description": "Data Asset Type",
"fields": [
{
"key": "dataset",
"type": "boolean",
"facet": true,
"is_array": false,
"is_searchable_across_types": false
},
{
"key": "mime_type",
"type": "string",
"facet": true,
"is_array": false,
"is_searchable_across_types": false
},
{
"key": "columns",
"type": "string",
"facet": true,
"is_array": true,
"search_path": "columns[].name",
"is_searchable_across_types": true
}
],
"external_asset_preview": {},
"relationships": [],
"name": "data_asset",
"version": 3
},
"global_search_searchable": [
"mime_type"
],
{
"description": "An asset type you can use to describe the columns of a data asset. Normally attached as a property to an existing data asset.",
"fields": [
{
"key": "column_info_term_display_name",
"type": "string",
"facet": true,
"is_array": false,
"search_path": "*.column_terms[].term_display_name",
"is_searchable_across_types": true
},
{
"key": "column_info_term_id",
"type": "string",
"facet": true,
"is_array": false,
"search_path": "*.column_terms[].term_id",
"is_searchable_across_types": false
},
{
"key": "column_info_tag",
"type": "string",
"facet": true,
"is_array": false,
"search_path": "*.column_tags[]",
"is_searchable_across_types": true
},
{
"key": "column_info_description",
"type": "string",
"facet": false,
"is_array": false,
"search_path": "*.column_description",
"is_searchable_across_types": true
},
{
"key": "column_info_omrs_guid",
"type": "string",
"facet": true,
"is_array": false,
"search_path": "*.omrs_guid",
"is_searchable_across_types": true
}
],
"external_asset_preview": {},
"relationships": [],
"name": "column_info",
"version": 4
},
{
"description": "An asset type that you can use to assign terms from a business glossary to any asset. Attach items of this type as attributes to other assets.",
"fields": [
{
"key": "asset_term_display_name",
"type": "string",
"facet": true,
"is_array": false,
"search_path": "list[].term_display_name",
"is_searchable_across_types": true
},
{
"key": "asset_term_id",
"type": "string",
"facet": true,
"is_array": false,
"search_path": "list[].term_id",
"is_searchable_across_types": false
}
],
"external_asset_preview": {},
"relationships": [],
"name": "asset_terms",
"version": 1
},
...
]
}
See Asset Type Fields for descriptions of the fields in each of the above asset types.
In a scenario in which the user has not yet created any of their own asset types, the result will contain only the pre-existing, global, asset types. For brevity, the actual sample result shown above includes only a subset of those asset types. Try the GET Asset Types API on your catalog to see the complete set of pre-existing, global, asset types.
Get Asset Type: data_asset
You can get an individual asset type in a catalog using the following Asset Types API:
Get Asset Type: data_asset - Request URL:
GET {service_URL}/v2/asset_types/{type_name}?catalog_id={catalog_id}
Supplying "data_asset" as the value for the {type_name} parameter in the above url will produce a response like the following:
Get Asset Type: data_asset - Response Body:
{
"description": "Data Asset Type",
"fields": [
{
"key": "mime_type",
"type": "string",
"facet": true,
"is_array": false,
"is_searchable_across_types": false
},
{
"key": "dataset",
"type": "boolean",
"facet": true,
"is_array": false,
"is_searchable_across_types": false
},
{
"key": "columns",
"type": "string",
"facet": true,
"is_array": true,
"search_path": "columns[].name",
"is_searchable_across_types": true
}
],
"global_search_searchable": [
"mime_type"
],
"external_asset_preview": {},
"relationships": [],
"name": "data_asset",
"version": 3
}
See Asset Type Fields for descriptions of the fields in the above asset type definition.
Since an asset type called "data_asset" exists, you can create a primary metadata document (ie, card) with a "metadata.asset_type" value of "data_asset". That card must then also have a primary attribute called "data_asset".
The most interesting item in the "fields" array in the above "data_asset" asset type definition is the item with "key" value "mime_type". That item means that a primary attribute named "data_asset" will have a field called "mime_type". The value of that "mime_type" attribute field will declare the specific type of the asset resource represented by the primary metadata document. For example, see the field "entity.data_asset.mime_type" in Get Asset - CSV File - Response Body - Before Profiling where the "mime_type" value is "text/csv".
Notice the "data_asset" attribute in Get Asset - CSV File - Response Body - Before Profiling only contains two fields - "mime_type" and dataset. The columns field specified in the definition of the "data_asset" asset type is not present in the "data_asset" attribute.
Now compare all the items in the "fields" array in the above "data_asset" asset type definition with the "entity.data_asset" attribute fields as shown, for example, in Get Asset - CSV File - Response Body - After Profiling. Notice that now all the fields described in the "fields" array of the "data_asset" type are present as fields in the "entity.data_asset" attribute. In particular, profiling has added the "columns" field to the "data_asset" attribute.
The Before Profiling and After Profiling examples illustrate that not all the fields defined in an asset type need be present in a corresponding attribute.
Lastly, note that asset type definition includes a global_search_searchable list of field keys, including the value mime_type. That indicates that mime_type value of every instance of this asset type will be seachable via Global Search microservice.
Create Asset Type: book
Say you have a book asset resource and you want to create a primary metadata document to describe that book. You will first need to create an asset type called "book" (as shown below) so you can then:
- use the name of that asset type as the value for the
"metadata.asset_type"field in the primary metadata document - create a primary attribute named "book" that will contain data about your book.
Say you want that primary attribute to look like the following:
"book": {
"author": {
"first_name": "Tracy",
"last_name": "Smith"
},
"price": 29.95
}
}
The above "book" attribute has:
- one complex field called "author" (complex fields are allowed in attributes)
- one simple field called "price".
For this example, assume you'll want to be able to search inside the "author.last_name" field of "book" attributes.
In addition to that, lets assume that you would like to use value of "author.last_name" field to search for "books" via Global Search microservice.
To create an asset type named "book" that will allow you to do all of the above, use a request like the following:
Create Asset Type: book - Request URL:
POST {service_URL}/v2/asset_types?catalog_id={catalog_id}
Create Asset Type: book - Request Body:
{
"name": "book",
"description": "Book asset type",
"fields": [
{
"key": "author.last_name",
"type": "string",
"facet": false,
"is_array": false,
"search_path": "author.last_name",
"is_searchable_across_types": true
}
],
"global_search_searchable": [
"author.last_name"
],
"properties": {
"price" : {
"type": "number",
"description": "Suggested retail price",
}
}
}
The purpose of most of the fields used in the above request was described in the Asset Type Fields section. Here are some things to note specifically in the above request:
"name": uses only lowercase letters, ie, "book""fields": even though our goal attribute has multiple fields in it, there is only one item in the asset type's"fields"array. That is because the"fields"array should only contain items for the fields of an attribute that we want the catalog to create an index for. In this case, we only want an index for the"author.last_name"field of "book" attributes."key": the name of the attribute field that we want indexed, and the name for that index. In this case,"author.last_name"."type": the type of the"author.last_name"field is "string""facet": an explanation of this field is beyond the scope of this document"is_array": false because"author.last_name"is not an array"search_path": this is the path inside the attribute to the value that we want indexed"is_searchable_across_types": an explanation of this field is beyond the scope of this document
"global_search_searchable"since we would like to be able to search forauthor.last_namevalue using Global Search - we include correspondingfield.keyvalue.
Create Asset Type: book - Response Body:
{
"description": "Book asset type",
"fields": [
{
"key": "author.last_name",
"type": "string",
"facet": false,
"is_array": false,
"search_path": "author.last_name",
"is_searchable_across_types": true
}
],
"global_search_searchable": [
"author.last_name"
],
"relationships": [],
"name": "book",
"version": 1
}
The response to the POST /v2/asset_types API echoes the input, with two additional fields:
- `relationships`: an explanation of the contents of this field is beyond the scope of this document
- `version`: the version of the newly created asset type
You now have an asset type called "book" that specifies one indexed, search-able, field called "author.last_name". See Create Asset: book for an example of the ways in which that "book" asset type can be used when creating a primary metadata document.
Search Asset Type: attribute - book
The Search Asset Type API can be used to search inside a catalog for all the primary metadata documents that satisfy both of the following conditions:
- have a
"metadata.asset_type"value that matches the asset type name specified in the {type_name} URL parameter - have an attribute whose fields' values match those specified in the request body.
Recall that one of the primary reasons for creating an asset type is to specify fields in attributes (named after that asset type) that will be indexed for searching. The Create Asset Type: book section showed how to create an asset type named "book". The Create Asset: book section showed how to create a primary metadata document whose "metadata.asset_type" value and primary attribute name are both "book". So, if you use the value "book" for the ``{type_name}` parameter in the URL below, and if you supply the following request body, then you'll get back matching metadata for books.
Search Asset Type: attribute - book - Request URL
POST {service_URL}/v2/asset_types/{type_name}/search?catalog_id={catalog_id}
Search Asset Type: attribute - book - Request Body:
{
"query":"book.author.last_name:Smith"
}
Notice how the query specifies both the attribute (book) to be searched and the search path (author.last_name) within that attribute. The value to match is specified after the colon (:). In this case, the value is Smith.
The following is the result of the above search:
Search Asset Type: attribute - book - Response Body:
{
"total_rows": 1,
"results": [
{
"metadata": {
"rov": {
"mode": 0,
"collaborator_ids": {}
},
"usage": {
"last_updated_at": "2019-05-01T18:58:51Z",
"last_updater_id": "IBMid-___",
"last_update_time": 1556737131140,
"last_accessed_at": "2019-05-01T18:58:51Z",
"last_access_time": 1556737131140,
"last_accessor_id": "IBMid-___",
"access_count": 0
},
"name": "Getting Started with Assets",
"description": "Describes how to create and use metadata for assets",
"tags": [
"getting",
"started",
"documentation"
],
"asset_type": "book",
"origin_country": "us",
"rating": 0,
"total_ratings": 0,
"catalog_id": "c6f3cbd8-___",
"created": 1556635077746,
"created_at": "2019-04-30T14:37:57Z",
"owner_id": "IBMid-___",
"size": 0,
"version": 0,
"asset_state": "available",
"asset_attributes": [
"book"
],
"asset_id": "3da5389d-d4a4-43da-be1f-___",
"asset_category": "USER"
},
"href": "https://api.dataplatform.cloud.ibm.com/v2/assets/3da5389d-d4a4-43da-be1f-___?catalog_id=c6f3cbd8-___"
}
]
}
In this case, there is only one primary metadata document returned in the "results" array (namely, the primary metadata document that was created in the Create Asset: book section). In general, there can be many matching documents in the "results" array.
Notice the results of an Asset Type Search, as shown above, only contain the "metadata" section of a primary metadata document. In particular, the "entity" section that contains the attributes is not returned. That is done to reduce the size of the response because, in general, the "entity" section of a primary metadata document can be much larger than the "metadata" section. Use the value of the "metadata.asset_id" in one of the items in "results" to retrieve either:
- the entire primary metadata document (using the GET Asset API), or
- just the attributes of the primary metadata document (using the GET Attributes API).
Notes:
- searching is not limited to just primary attributes (like
bookabove). Searches may also be performed on:- Secondary, or extended, attributes
- the "metadata" field of a primary metadata document, as shown in the next section.
- other parameters available for searches are:
- limit (number): limit number of search results
- sort (string): sort columns for search results
- counts: beyond the scope of this document
- drilldown: beyond the scope of this document
Search Asset Type: metadata - name
You're not limited to searching within attributes (like the attribute search shown in the previous section). You can also search within the "metadata" section of a primary metadata document.
Search Asset Type: metadata - name - Request URL:
POST {service_URL}/v2/asset_types/{type_name}/search?catalog_id={catalog_id}
Search Asset Type: metadata - name - Request Body:
{
"query":"asset.name:Getting Started with Assets"
}
Notice the query signifies that the search should take place in the "metadata" section of the primary metadata document by using the term asset at the beginning of the search path. Then the field to be searched within "metadata" is specified - name in the example above. The value to match is specified after the colon (:), in this case the value is Getting Started with Assets.
The following is the result of the above search:
Search Asset Type: metadata - name - Response Body:
{
"total_rows": 1,
"results": [
{
"metadata": {
"rov": {
"mode": 0,
"collaborator_ids": {}
},
"usage": {
"last_updated_at": "2019-04-30T17:27:56Z",
"last_updater_id": "IBMid___",
"last_update_time": 1556645276827,
"last_accessed_at": "2019-04-30T17:27:56Z",
"last_access_time": 1556645276827,
"last_accessor_id": "IBMid___",
"access_count": 0
},
"name": "Getting Started with Assets",
"description": "Describes how to create and use metadata for assets",
"tags": [
"getting",
"started",
"documentation"
],
"asset_type": "book",
"origin_country": "us",
"rating": 0,
"total_ratings": 0,
"catalog_id": "c6f3cbd8-___",
"created": 1556635077746,
"created_at": "2019-04-30T14:37:57Z",
"owner_id": "IBMid-___",
"size": 0,
"version": 0,
"asset_state": "available",
"asset_attributes": [
"book"
],
"asset_id": "3da5389d-d4a4-43da-be1f-___",
"asset_category": "USER"
},
"href": "https://api.dataplatform.cloud.ibm.com/v2/assets/3da5389d-d4a4-43da-be1f-___?catalog_id=c6f3cbd8-___"
}
]
}
In this case, the result is the same as was described in Search Asset Type: attribute - book - Response Body. See that section for more details.
Data Assets and Columns
Data assets represent tables or files from a connection to a data source (ex. tables) or files uploaded into cloud object storage associated with Projects or Catalog. Data assets extend the generic asset service and attachments functionality. This means that like generic assets, data assets also have name, description, visibility, members, tags, classifications and asset_type. In addition, data assets have mime type, column related attributes and properties. The asset type for data asset is data_asset and it is one of the asset types already available.
Like other assets, we can add or update attributes on data assets also. Given below is a simple format of a data asset, which has attributes associated with columns.
{
"metadata": {
...
...
"name": "Name of the data asset",
"asset_type": "data_asset",
"asset_attributes": [
"data_asset",
"column_info",
... other attributes
],
"asset_id": "id of the data asset"
},
"entity": {
"data_asset": {
"mime_type": "text/csv",
"dataset": false,
"columns": [
{
"name": "NameOfColumn", // Name of the column
"type": {
"type": "varchar",
"length": 1024,
"scale": 0,
"nullable": true,
"signed": false
}
}
]
},
"column_info": {
"NameOfColumn": { // we are listing the column_info attributes associated with each column
"column_description": "description of the column",
"column_terms": [
{
"term_display_name": "test_term",
"term_id": "d3d667e1-____"
}
]
}
},
... other attributes
},
"attachments": [
...
...
]
}
All asset APIs listed in Assets API Overview apply to data assets as well. In additions, data assets have special APIs.
Creating a Data Asset
Creating a data asset is similar to creating any other asset. In here,
- a
"metadata.asset_type"field will hold value"data_asset" - a primary attribute called
"data_asset".
In the first example, we will create a connected data asset. It represents a table or a file from an exisitng connection. The sample request body and the corresponding response is given below.
Create Data Asset: Request URL:
POST {service_URL}/v2/data_assets
Create Data Asset: -Sample Request Body:
{
"metadata": {
"name": "CUSTOMER", // Name of table
"description": "customer table", // description
"tags": [
"public"
],
"asset_type": "data_asset",
"origin_country": "us",
"rov": {
"mode": 0
}
},
"entity": {
"data_asset": {
"mime_type": "application/x-ibm-rel-table",
"dataset": true,
"properties": [
{
"name": "schema_name",
"value": "DB2INST1"
},
{
"name": "table_name",
"value": "CUSTOMER"
}
],
"columns": [ // list of columns in the data asset
{
"name": "CID",
"type": {
"type": "bigint",
"length": 19,
"scale": 0,
"nullable": false,
"signed": true,
"native_type": "BIGINT"
}
},
{
"name": "INFO",
"type": {
"type": "sqlxml",
"length": 0,
"scale": 0,
"nullable": true,
"signed": false,
"native_type": "XML"
}
},
{
"name": "HISTORY",
"type": {
"type": "sqlxml",
"length": 0,
"scale": 0,
"nullable": true,
"signed": false,
"native_type": "XML"
}
}
]
}
},
"attachments": [ // details of the connection
{
"asset_type": "data_asset",
"name": "CUSTOMER",
"description": "customer table",
"mime": "application/x-ibm-rel-table",
"connection_id": "3a______",
"connection_path": "/DB2_path_/CUSTOMER_table_path",
"is_partitioned": false
}
]
}
Create Data Asset: - Response Body:
{
"metadata": {
"usage": {
"last_updated_at": "2023-04-20T20:13:39Z",
"last_updater_id": "-- creator id--",
"last_update_time": 1682021619570,
"last_accessed_at": "2023-04-20T20:13:39Z",
"last_access_time": 1682021619570,
"last_accessor_id": "-- creator id--",
"access_count": 0
},
"rov": {
"mode": 0,
"collaborator_ids": {},
"member_roles": {
"-- creator id--": {
"user_iam_id": "-- creator id--",
"roles": [
"OWNER"
]
}
}
},
"name": "CUSTOMER",
"description": "customer table",
"tags": [
"public"
],
"asset_type": "data_asset",
"origin_country": "us",
"resource_key": "0000:0000:0000:0000:0000:FFFF:0914:9C3E|50000|sample:/DB2INST1/CUSTOMER",
"rating": 0,
"total_ratings": 0,
"catalog_id": "e1____",
"created": 1682021619570,
"created_at": "2023-04-20T20:13:39Z",
"owner_id": "-- creator id--",
"size": 0,
"version": 2,
"asset_state": "available",
"asset_attributes": [
"data_asset"
],
"asset_id": "12____",
"asset_category": "USER",
"creator_id": "-- creator id--"
},
"entity": {
"data_asset": {
"mime_type": "application/x-ibm-rel-table",
"dataset": true,
"properties": [
{
"name": "schema_name",
"value": "DB2INST1"
},
{
"name": "table_name",
"value": "CUSTOMER"
}
],
"columns": [
{
"name": "CID",
"type": {
"type": "bigint",
"length": 19,
"scale": 0,
"nullable": false,
"signed": true,
"native_type": "BIGINT"
}
},
{
"name": "INFO",
"type": {
"type": "sqlxml",
"length": 0,
"scale": 0,
"nullable": true,
"signed": false,
"native_type": "XML"
}
},
{
"name": "HISTORY",
"type": {
"type": "sqlxml",
"length": 0,
"scale": 0,
"nullable": true,
"signed": false,
"native_type": "XML"
}
}
]
}
},
"href": "/v2/assets/12____?catalog_id=e1____",
"asset_id": "12____",
"attachments": [
{
"attachment_id": "2a____",
"asset_type": "data_asset",
"attachment_type": "remote",
"datasource_type": "8c____",
"is_partitioned": false,
"name": "CUSTOMER",
"description": "customer table",
"mime": "application/x-ibm-rel-table",
"connection_id": "3a____",
"connection_path": "/DB2INST1/CUSTOMER",
"user_data": {},
"href": "/v2/assets/12____/attachments/2a____?catalog_id=e1____",
"asset_category": "USER"
}
]
}
In the next example, we will create a data asset which represents a local file uploaded to catalog. The URL for the API remains same. The sample request body and the corresponding response are given below.
Create Data Asset for Local File: -Sample Request Body:
{
"metadata": {
"name": "New data Asset",
"description": "data table",
"tags": [
"public"
],
"asset_type": "data_asset",
"origin_country": "us",
"rov": {
"mode": 0
}
},
"entity": {
"data_asset": {
"mime_type": "application/octet-stream",
"dataset": true,
"columns": [
{
"name": "COLUMN1",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN2",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN3",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN4",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN5",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN6",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN7",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN8",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
}
],
"properties": [
{
"name": "bucket",
"value": "--bucket name--"
},
{
"name": "file_name",
"value": "file_path/file_name-csv"
},
{
"name": "first_line_header",
"value": "false"
},
{
"name": "encoding",
"value": "UTF-8"
},
{
"name": "invalid_data_handling",
"value": "fail"
},
{
"name": "file_format",
"value": "csv"
}
]
}
},
"attachments": [
{
"asset_type": "data_asset",
"name": "remote",
"description": "remote",
"mime": "text/csv",
"connection_id": "26____",
"connection_path": "Cloud_object_storage_path/file_name-csv.csv",
"is_partitioned": false
}
]
}
Create Data Asset For Local File: - Response Body:
For the above request, the expected response is given below.
{
"metadata": {
"usage": {
"last_updated_at": "2023-04-20T20:23:21Z",
"last_updater_id": "-- creator id--",
"last_update_time": 1682022201699,
"last_accessed_at": "2023-04-20T20:23:21Z",
"last_access_time": 1682022201699,
"last_accessor_id": "-- creator id--",
"access_count": 0
},
"rov": {
"mode": 0,
"collaborator_ids": {},
"member_roles": {
"-- creator id--": {
"user_iam_id": "-- creator id--",
"roles": [
"OWNER"
]
}
}
},
"name": "New data Asset",
"description": "data table",
"tags": [
"public"
],
"asset_type": "data_asset",
"origin_country": "us",
"resource_key": "New data Asset",
"rating": 0,
"total_ratings": 0,
"catalog_id": "e1______",
"created": 1682022201699,
"created_at": "2023-04-20T20:23:21Z",
"owner_id": "-- creator id--",
"size": 0,
"version": 2,
"asset_state": "available",
"asset_attributes": [
"data_asset"
],
"asset_id": "80___",
"asset_category": "USER",
"creator_id": "-- creator id--"
},
"entity": {
"data_asset": {
"mime_type": "application/octet-stream",
"dataset": true,
"columns": [
{
"name": "COLUMN1",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN2",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN3",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN4",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN5",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN6",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN7",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
},
{
"name": "COLUMN8",
"type": {
"length": 1024,
"nullable": true,
"type": "varchar",
"scale": 0,
"signed": false
}
}
],
"properties": [
{
"name": "bucket",
"value": "--bucket name--"
},
{
"name": "file_name",
"value": "file_path/file_name-csv"
},
{
"name": "first_line_header",
"value": "false"
},
{
"name": "encoding",
"value": "UTF-8"
},
{
"name": "invalid_data_handling",
"value": "fail"
},
{
"name": "file_format",
"value": "csv"
}
]
}
},
"href": "/v2/assets/80__?catalog_id=e1____",
"asset_id": "805e24e6-2473-41d4-9e2a-679df9a40e7b",
"attachments": [
{
"attachment_id": "2b____",
"asset_type": "data_asset",
"attachment_type": "remote",
"is_partitioned": false,
"name": "remote",
"description": "remote",
"mime": "text/csv",
"connection_id": "26____",
"connection_path": "Cloud_object_storage_path/file_name-csv.csv",
"user_data": {},
"href": "/v2/assets/80____/attachments/2b____?catalog_id=e1____",
"asset_category": "USER"
}
]
}
Retrieving a Data Asset
Retrieving a data asset can be achieved by calling APIs for retrieving any other asset. Since data assets are also uploaded locally we can retrieve csv files also. However, we have special APIs designed specifically to retrieve data assets.
If we retrieve the data asset created in the previous section
Retrieve a Data Asset: Request URL:
GET {service_URL}/v2/data_assets/{asset_id}?catalog_id={catalog_id}
Retrieve Data Asset: - Response Body:
{
"metadata": {
"usage": {
"last_updated_at": "2023-04-17T20:20:56Z",
"last_updater_id": "--id--",
"last_update_time": 1681762856921,
"last_accessed_at": "2023-04-17T20:20:56Z",
"last_access_time": 1681762856921,
"last_accessor_id": "--id--",
"access_count": 0
},
"rov": {
"mode": 0,
"collaborator_ids": {},
"member_roles": {
"--id--": {
"user_iam_id": "--id--",
"roles": [
"OWNER"
]
}
}
},
"name": "CUSTOMER",
"description": "customer table",
"tags": [
"public"
],
"asset_type": "data_asset",
"origin_country": "us",
"resource_key": "string",
"rating": 0,
"total_ratings": 0,
"catalog_id": "e12____",
"created": 1681762856921,
"created_at": "2023-04-17T20:20:56Z",
"owner_id": "--id--",
"size": 0,
"version": 2,
"asset_state": "available",
"asset_attributes": [
"data_asset"
],
"asset_id": "75____",
"asset_category": "USER",
"creator_id": "--id--"
},
"entity": {
"data_asset": {
"mime_type": "application/x-ibm-rel-table",
"dataset": true,
"columns": [
{
"name": "CID",
"type": {
"length": 19,
"nullable": false,
"type": "bigint",
"scale": 0,
"signed": true
}
},
{
"name": "INFO",
"type": {
"length": 0,
"nullable": true,
"type": "sqlxml",
"scale": 0,
"signed": false
}
},
{
"name": "HISTORY",
"type": {
"length": 0,
"nullable": true,
"type": "sqlxml",
"scale": 0,
"signed": false
}
}
],
"properties": [
{
"name": "schema_name",
"value": "DB2INST1"
},
{
"name": "table_name",
"value": "CUSTOMER"
}
]
}
},
"attachments": [
{
"id": "51d____",
"version": 2,
"asset_type": "data_asset",
"name": "CUSTOMER",
"description": "customer table",
"mime": "application/x-ibm-rel-table",
"connection_id": "3a____",
"connection_path": "/DB2_path_/CUSTOMER_table_path",
"datasource_type": "8c____",
"creator_id": "--id--",
"create_time": 1681762856936,
"size": 0,
"is_remote": true,
"is_managed": false,
"is_referenced": false,
"is_object_key_read_only": false,
"is_user_provided_path_key": true,
"transfer_complete": true,
"is_partitioned": false,
"complete_time_ticks": 1681762856936,
"user_data": {},
"test_doc": 0,
"usage": {
"access_count": 0,
"last_accessor_id": "--id--",
"last_access_time": 1681762856936
}
}
],
"href": "/v2/data_assets/75__?catalog_id=e1____"
}
Retrieving Columns from a Data Asset
Data assets often contain information regarding the columns in the table or file. Use the GET columns API to retrieve the column related information, such as the terms, column description etc.
Retrieve Columns from a Data Asset: Request URL:
GET {service_URL}/v2/data_assets/{asset_id}/columns?catalog_id={catalog_id}
Retrieve Columns from a Data Asset: - Response Body:
{
"total_rows": 1, // Total number of columns
"resources": [
{
"data_asset": {
"columns": [
{
"name": "NameOfColumn",
"type": {
"type": "varchar",
"length": 1024,
"scale": 0,
"nullable": true,
"signed": false
},
"position": 1
}
]
},
"column_info": {
"NameOfColumn": {
"column_description": "column description",
"column_terms": [
{
"term_display_name": "test_term",
"term_id": "d3d______"
}
],
"name": "NameOfColumn"
}
}
}
]
}
Data assets can hold information about the columns of the data. It is important to note that they do not hold the actual column and the column values. The information it can stores can be the terms and data class assigned after profiling or manually, data quality score of the column, the type of the column, tags associated with the column and the description of the column.
Among the already available asset types, asset types "data_asset" and "column_info" contain attributes for columns.
Column Related Information Present in data_asset Asset Type
The basic structure of data_asset asset type is described in section data_asset Type. Here we will elaborate on the "columns" field of the data_asset.
The "columns" field consists of a list of elements. Each element represents a column. It is populated after profiling. Example of a single column element is given below
{
"name": "MARITAL_STATUS", // Name of the column
"type": {
"type": "varchar",
"length": 1024,
"scale": 0,
"nullable": true,
"signed": false
}
}
Column Related Information Present in column_info Asset Type
The column_info attribute in a data asset represents information about each column. The informations is added manually, or after running profiling or metadata enrichment. The "column_info" field consists of a map. Each key-value pair represents an individual column. Each key is the name of the column. The value of the key represents attributes assigned to the column.
Example of a single column element's column_info is given below
"MARITAL_STATUS": { // name of the column
"data_class": {
"selected_data_class": {
"id": "7a8e___",
"name": "status",
"setByUser": false
}
},
"inferred_type": {
"length": 10,
"precision": 0,
"scale": 0,
"type": "STRING",
"display_name": "varchar(10)"
},
"quality": {
"score": 98
},
"column_terms": [
{
"term_id": "7a8e____",
"term_display_name": "TestTerm",
"confidence": 0.984,
"specification": "Data class based assignment"
}
],
"suggested_terms": [],
"rejected_terms": [],
"name": "MARITAL_STATUS"
}
}
Assigning Terms and Data Class to a Column
We can assign terms and data class to a column manually also. The terms associated with individual columns reside as an array inside the column_info attribute.
In the first scenario we will add a single term and data class to a file which does not have the "column_info" attribute. This can happen if a csv file has been uploaded locally. In this case, we need to use the Create Asset API to create and populate an instance of "column_info" attribute inside the asset's primary metadata document.
POST {service_URL}/v2/assets/{asset_id}/attributes?catalog_id={catalog_id}
Body:
{
"name": "column_info",
"entity": {
"BUSINESS_NAME": {
"column_terms": [
{
"term_id": "--your term id--",
"term_display_name": "term_name"
}
],
"data_class": {
"selected_data_class": {
"id": "--your data class id--",
"name": "data_class_name"
}
}
}
}
}
The response should look like:
{
"asset_id": "--your asset id--",
"column_info": {
"BUSINESS_NAME": { // Name of your column
"column_terms": [
{
"term_id": "--your term id--",
"term_display_name": "term_name"
}
],
"data_class": {
"selected_data_class": {
"id": "--your data class id--",
"name": "data_class_name"
}
}
}
},
"href": "/v2/assets/b8____/attributes/column_info?catalog_id=e1____"
}
If you want to associate additional terms or data class to a column, or add terms or data class to a column which does not have terms or data class, or remove existing terms or data class from a column, then use the Update Asset Attribute API. In the following example, we will replace terms assigned to the column BUSINESS_NAME and add terms to a column which does not have any terms yet.
PATCH {service_URL}/v2/assets/{asset_id}/attributes/column_info?catalog_id={catalog_id}
Body:
[
{
"op": "replace",
"path": "/BUSINESS_NAME/column_terms", // column to which we already have terms and data class
"value": [
{
"term_id": "--your term id--",
"term_display_name": "new_term_name"
}
]
},
{
"op": "add",
"path": "/ADDRESS", // column to which no terms are data classes are assigned
"value": {
"column_terms": [
{
"term_id": "--your term id--",
"term_display_name": "term_name_2"
}
]
}
}
]
The response should look like:
{
"BUSINESS_NAME": {
"column_terms": [
{
"term_id": "--your term id--",
"term_display_name": "new_term_name"
}
],
"data_class": {
"selected_data_class": {
"id": "--your data class id--",
"name": "data_class_name"
}
}
},
"ADDRESS": {
"column_terms": [
{
"term_id": "--your term id--",
"term_display_name": "term_name_2"
}
]
}
}
Connections
A connection is the information necessary to create a connection to a data source or a repository. You create a connection asset by providing the connection information.
List data source types
Data sources are where data can be written or read and might include relational database systems, file systems, object storage systems and others.
To list supported data source types, call the following GET method:
GET /v2/datasource_types
The response to the GET method includes information about each of the sources and targets that are currently supported. The response includes a unique ID property value metadata.asset_id, name, and a label. The metadata.asset_id property value should be used for the data source in other APIs that reference a data source type. Additional useful information such as whether that data source can be used as a source or target (or both) is also included.
Use the connection_properties=true query parameter to return a set of properties for each data source type that is used to define a connection to it. Use the interaction_properties=true query parameter to return a set of properties for each data source type that is used to interact with a created connection. Interaction properties for a relational database might include the table name and schema from which to retrieve data.
Use the _sort query parameter to order the list of data source type returned in the response.
A default maximum of 100 data source type entries are returned per page of results. Use the _limit query parameter with an integer value to specify a lower limit.
More data source types than those on the first page of results might be available. Additional properties generated from the page size initially specified with _limit are returned in the response. Call a GET method using the value of the next.href property to retrieve the next page of results. Call a GET method using the value in the prev.href property to retrieve the previous page of results. Call a GET method using the value in the last.href property to retrieve the last page of results.
These URIs use the _offset and _limit query parameters to retrieve a specific block of data source types from the full list. Alternatively, you can use a combination of the _offset and _limit query parameters to retrieve a custom block of results.
Create a connection
Connections to any of the supported data source types returned by the previous method can be created and persisted in a catalog or project.
To create a connection, call the following POST method:
POST /v2/connections
A new connection can be created in a catalog or project. Use the catalog_id or project_id query parameter to specify where to create the connection asset. Either catalog_id or project_id is required.
The request body for the method is a UTF-8 encoded JSON document and includes the data source type ID (obtained in the List data source types section), its unique name in the catalog or project space, and a set of connection properties specific to the data source. Some connection properties are required.
The following example shows the request body used for creating a connection to IBM dashDB:
{
"datasource_type": "cfdcb449-1204-44ba-baa6-9a8a878e6aa7",
"name":"My-DashDB-Connection",
"properties": {
"host":"dashDBhost.com",
"port":"50001",
"database":"MYDASHDB",
"password": "mypassword",
"username": "myusername"
}
}
By default, the physical connection to the data source is tested when the connection is created. Use the test=false query parameter to disable the connection test.
A response payload containing a connection ID and other metadata is returned when a connection is successfully created. Use the connection ID as path parameter in other REST APIs when a connection resource must be referenced.
Discover connection assets
Data sources contain data and metadata describing the data they contain.
To discover or browse the data or metadata in a data source, call the following GET method:
GET /v2/connections/{connection_id}/assets?path=
Use the catalog_id or project_id query parameter to specify where the connection asset was created. Either catalog_id or project_id is required.
connection_id is the ID of the connection asset returned from the POST https://{service_URL}/v2/connections method, which created the connection asset.
The path query parameter is required and is used to specify the hierarchical path of the asset within the data source to be browsed. In a relational database, for example, the path might represent a schema and table. For a file object, the path might represent a folder hierarchy.
Each asset in the assets array returned by this method includes a property containing its path in the hierarchy to facilitate the next call to drill down deeper in the hierarchy.
For example, starting at the root path in an RDBMS will return a list of schemas:
{
"path": "/",
"asset_types": [
{
"type": "schema",
"dataset": false,
"dataset_container": true
}
],
"assets": [
{
"id": "GOSALES",
"type": "schema",
"name": "GOSALES",
"path": "/GOSALES"
},
],
"fields": [],
"first": {
"href": "https://wdp-dataconnect-ys1dev.stage1.mybluemix.net/v2/connections/4b28b5c1-d818-4ad2-bcf9-7de08e776fde/assets?catalog_id=75a3062b-e40f-4bc4-9519-308ee1b5b251&_offset=0&_limit=100"
},
"prev": {
"href": "https://wdp-dataconnect-ys1dev.stage1.mybluemix.net/v2/connections/4b28b5c1-d818-4ad2-bcf9-7de08e776fde/assets?catalog_id=75a3062b-e40f-4bc4-9519-308ee1b5b251&_offset=0&_limit=100"
},
"next": {
"href": "https://wdp-dataconnect-ys1dev.stage1.mybluemix.net/v2/connections/4b28b5c1-d818-4ad2-bcf9-7de08e776fde/assets?catalog_id=75a3062b-e40f-4bc4-9519-308ee1b5b251&_offset=100&_limit=100"
}
}
Drill down into the GOSALES schema using the path property for the GOSALES schema asset to discover the list of table assets in the schema.
GET /v2/connections/{connection_id}/assets?catalog_id={catalog_id}&path=/GOSALES
The list of table type assets is returned in the response.
{
"path": "/GOSALES",
"asset_types": [
{
"type": "table",
"dataset": true,
"dataset_container": false
}
],
"assets": [
{
"id": "BRANCH",
"type": "table",
"name": "BRANCH",
"description": "BRANCH contains address information for corporate offices and distribution centers.",
"path": "/GOSALES/BRANCH"
},
{
"id": "CONVERSION_RATE",
"type": "table",
"name": "CONVERSION_RATE",
"description": "CONVERSION_RATE contains currency exchange values.",
"path": "/GOSALES/CONVERSION_RATE"
}
],
"fields": [],
"first": {
"href": "https://wdp-dataconnect-ys1dev.stage1.mybluemix.net/v2/connections/4b28b5c1-d818-4ad2-bcf9-7de08e776fde/assets?catalog_id=75a3062b-e40f-4bc4-9519-308ee1b5b251&_offset=0&_limit=100"
},
"prev": {
"href": "https://wdp-dataconnect-ys1dev.stage1.mybluemix.net/v2/connections/4b28b5c1-d818-4ad2-bcf9-7de08e776fde/assets?catalog_id=75a3062b-e40f-4bc4-9519-308ee1b5b251&_offset=0&_limit=100"
},
"next": {
"href": "https://wdp-dataconnect-ys1dev.stage1.mybluemix.net/v2/connections/4b28b5c1-d818-4ad2-bcf9-7de08e776fde/assets?catalog_id=75a3062b-e40f-4bc4-9519-308ee1b5b251&_offset=100&_limit=100"
}
}
Use the fetch query parameter with a value of either data, metadata, or both. Data can only be fetched for data set assets. In the response above, note the asset_type has the property type value of table. Its dataset property value is true. This means that data can be fetched from table type assets. However, if you fetched assets from the connection root, the response would contain schema asset types, which are not data sets and thus fetching this data is not relevant.
A default maximum of 100 metadata assets are returned per page of results. Use the _limit query parameter with an integer value to specify a lower limit. More assets than those on the first page of results might be available.
Additional properties generated from the page size initially specified with _limit are returned in the response. Call a GET method using the value of the next.href property to retrieve the next page of results. Call a GET method using the value in the prev.href property to retrieve the previous page of results. Call a GET method using the value in the last.href property to retrieve the last page of results.
These URIs use the _offset and _limit query parameters to retrieve a specific block of assets from the full list. Alternatively, use a combination of the _offset and _limit query parameters to retrieve a custom block of results.
Specify properties for reading delimited files
When reading a delimited file using this method, specify property values to correctly parse the file based on its format. These properties are passed to the method as a JSON object using the properties query parameter. The default file format (property file_format) is a CSV file. If the file is a CSV, the following property values are set by default:
| Property Name | Property Description | Default Value | Value Description |
|---|---|---|---|
quote_character |
quote character | double_quote |
double quotation mark |
field_delimiter |
field delimiter | comma |
comma |
row_delimiter |
row delimiter | carriage_return_linefeed |
carriage return followed by line feed |
escape_character |
escape character | double_quote |
double quotation mark |
For CSV file formats, these property values can not be overwritten. If it is necessary to modify these properties to properly read a delimited file, set the file_format property to delimited. For generic delimited files, these properties have the following values:
| Property Name | Property Description | Default Value | Value Description |
|---|---|---|---|
quote_character |
quote character | none |
no character is used for a quote |
field_delimiter |
field delimiter | null | no field delimiter value is set by default |
row_delimiter |
row delimiter | new_line |
Any new line representation |
escape_character |
escape character | none |
no character is used for an escape |
This example sets file format properties for a generic delimited file:
GET https://{service_URL}/v2/connections/{connection_id}/assets?catalog_id={catalog_id}&path=/myFolder/myFile.txt&fetch=data&properties={"file_format":"delimited", "quote_character":"single_quote","field_delimiter":"colon","escape_character":"backslash"}
For more information about this method see the REST API Reference.
Discover assets using a transient connection
A data source's assets can be discovered without creating a persistent connection.
To browse assets without first creating a persistent connection, call the following POST method:
POST https://{service_URL}/v2/connections/assets?path=
This method is identical in behavior to the GET method in the Discover connection assetssection except for two differences:
- You define the connection properties in the request body of the REST API. You do not reference the connection ID of a persistent connection with a query parameter. The same JSON object used to create a persistent connection is used in the request body.
- You do not specify a catalog or project ID with a query parameter.
See the previous section to learn how to set properties used to read delimited files.
For more information about this method see the REST API Reference.
Update a connection
To modify the properties of a connection, call the following PATCH method:
PATCH /v2/connections/{connection_id}
connection_id is the ID of the connection asset returned from the POST https://{service_URL}/v2/connections method, which created the connection asset.
Use the catalog_id or project_id query parameter to specify where the connection asset was created. Either catalog_id or project_id is required.
Set the Content-Type header to application/json-patch+json. The request body contains the connection properties to update using a JSON object in JSON Patch format.
Change the port number of the connection and add a description using this JSON Patch:
[
{
"op": "add",
"path": "/description",
"value": "My new PATCHed description"
},
{
"op":"replace",
"path":"/properties/port",
"value":"40001"
}
]
By default, the physical connection to the data source is tested when the connection is modified. Use the test=false query parameter to disable the connection test.
For more information about this method see the REST API Reference.
Delete a connection
To delete a persistent connection, call the following DELETE method:
DELETE /v2/connections/{connection_id}
connection_id is the ID of the connection asset returned from the POST https://{service_URL}/v2/connections method, which created the connection asset.
Use the catalog_id or project_id query parameter to specify where the connection asset was created. Either catalog_id or project_id is required.
Business Lineage
Introduction
Business Lineage in IKC is designed to parse a new attribute, data_lineage, which is defined on the asset level in Common Assets Managed Services. This attribute is used as primary API between components that provide data sources for Business Lineage and IKC Lineage Service.
General structure of data_lineage attribute:
- List of assets.
- List of flows defined in lineage_relationships section, mapping source assets to target assets.
(Note: All assets referenced as source or target in
lineage_relationshipssection, must be defined in assets section, including their context assets, recursively)
Recommendations for representing data flow:
- Describe data flow on the finest-grained level possible, for example on the level of database columns, data file attributes, or fields. If you don't have access to this level of metadata, describe data flow for table-level flows.
- Do not mix hierarchies. Map columns to fields and tables to stages. Do not map, for example, fields to databases.
- Add
data_lineageattribute to an asset that owns the logic from which lineage information is derived. For example: Database View, Job or Data Transformation.
Types of grouped flows:
- DESIGN: Flows are predicted based on default value parameterization. For some tools, default parameterisation may not exist and DESIGN flows may not be applicable.
- OPERATIONAL: Flows were reported by operational metadata (OMD) - 'what actually happened' for a particular run.
- USER: Flows are relayed by user, not determined automatically.
- SYSTEM: Flows will happen in every run, independent of parameter values or external circumstances. For example, inner job flow.
- OTHER_IMPACT: Flows are not related to data flow. Other forms of impact flows are, for example, bob sequencing or model dependencies
Asset can be referenced in three ways:
- Asset Identity
{
"provider_name": "catalog:e96a4824-ab56-4bad-8176-4d98c313af3d",
"internal_id": "a3",
"lookup": {
"producer_properties": {
"id": "7a84b47f-1891-496c-b225-27602acd8128"
}
}
}
Note: Asset to which data_lineage is added, can be referenced through word self intead of asset ID.
Note: internal_id is internal identifier used for referencing asset only in data_lineage attribute in lineage_relationship section.
- Resource Key is a global idenifier for CAMS assets. It can be used for referencing asset for lineage flows. For example:
{
"provider_name": "catalog:e5887d45-6c6a-44b6-82ec-8cd953ff2765",
"internal_id": "a1",
"lookup": {
"producer_properties": {
"resource_key": "192.168.1.10/SAMPLE/DB2INST1/EMPLOYEE_TBL"
}
}
}
In case column or member of the asset needs to be referenced and it does not own its ID, then resource key can be extended in the form resourceKey:Column_Name. For example:
{
"provider_name": "catalog:e5887d45-6c6a-44b6-82ec-8cd953ff2765",
"internal_id": "a1",
"lookup": {
"producer_properties": {
"resource_key": "192.168.1.10/SAMPLE/DB2INST1/EMPLOYEE_TBL:EMP_ID_COL"
}
}
}
- Context information
{
"provider_name": "catalog:e5887d45-6c6a-44b6-82ec-8cd953ff2765",
"internal_id": "a3",
"lookup": {
"fqrn": [
{
"database_column": "ID"
},
{
"database_table": "EMP"
},
{
"database_schema": "XYZ"
},
{
"database": "db2"
},
{
"host": "my.abc.com"
}
]
}
}
The following example shows data_lineage attribute:
{
"name": "data_lineage",
"entity": {
"assets": [
{
"provider_name": "catalog:e5887d45-6c6a-44b6-82ec-8cd953ff2765",
"internal_id": "a1",
"lookup": {
"producer_properties": {
"resource_key": "192.168.1.10/SAMPLE/DB2INST1/EMP_ACT:EMENDATE"
}
}
},
{
"provider_name": "catalog:e5887d45-6c6a-44b6-82ec-8cd953ff2765",
"internal_id": "a2",
"lookup": {
"producer_properties": {
"resource_key": "192.168.1.10/SAMPLE/DB2INST1/EMPACT:EMENDATE"
}
}
}
],
"lineage_relationships": [
{
"flow_type": "flow_design",
"flows": [
{
"sources": [
"a1"
],
"targets": [
"a2"
]
}
]
}
]
}
}
Note: provider_name field is optional. When not specified, asset container to which this data_lineage attribute is added, is used as default.
Lineage
Introduction
The lineage of an asset includes information about all events, and other assets, that have led to its current state and its further usage. Asset and Event are the two main entities that are part of the lineage data model. An asset can either be generated from or used in subsequent events. An event can be any of:
- asset-generation-events
- asset-modification-events
- asset-usage-events.
Use the Lineage API to publish events on an asset or to query the lineage of an asset.
Publish a lineage event
The following example shows a sample lineage event that can be posted when a data set is published from a project to a catalog:
Request URL
POST /v2/lineage_events
Request Body
{
"message_version": "v1",
"user_id": "IAM-Id_of_User",
"account_id": "e86f2b06b0b267d559e7c387ceefb089",
"event_details": {
"event_id": "sample-event1",
"event_type": "DATASET_PUBLISHED",
"event_category": [
"additions"
],
"event_time": "2018-04-03T14:01:08.603Z",
"event_source_service": "Watson Knowledge Catalog"
},
"generates_assets": [
{
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset03",
"asset_type": "DataSet",
"relation": {
"name": "Created"
},
"properties": {
"dataset": {
"type": "dataset",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset03",
"name": "Asset Name in Catalog XX",
"catalog_id": "9f9c961a-78d1-4c06-a601-4b589catalog"
}
},
"catalog": {
"type": "catalog",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b589catalog"
}
}
}
}
],
"uses_assets": [
{
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset02",
"asset_type": "DataSet",
"relation": {
"name": "Used"
},
"properties": {
"dataset": {
"type": "dataset",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset02",
"name": "2017_sales_data",
"project_id": "9f9c961a-78d1-4c06-a601-4b589project"
}
},
"project": {
"type": "project",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b589project"
}
}
}
}
]
}
Response Body
{
"metadata": {
"id": "01014d1f-31cf-4956-bd41-7a77ba14004c",
"source_event_id": "sample-event1"
}
}
The id generated in the response can be used to query the details of the published event with the following request:
Request URL
GET v2/lineage_events/01014d1f-31cf-4956-bd41-7a77ba14004c
For more details on each field in the lineage event JSON payload, refer to the Lineage Events section of API documentation.
Query lineage of an asset
The lineage of an asset involved in the sample event can be queried using the following request:
Request URL
GET v2/asset_lineages/9f9c961a-78d1-4c06-a601-4b5890fdataset03
Response Body
{
"resources": [
{
"metadata": {
"id": "01014d1f-31cf-4956-bd41-7a77ba14004c",
"source_event_id": "sample-event1",
"created_at": "2018-04-03T14:01:08.603Z",
"created_by": "IAM-Id_of_User"
},
"entity": {
"type": "DATASET_PUBLISHED",
"generates_assets": [
{
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset03",
"type": "DataSet",
"relation": {
"name": "Created"
},
"properties": {
"catalog": {
"type": "catalog",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b589catalog"
}
},
"dataset": {
"type": "dataset",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset03",
"name": "Asset Name in Catalog XX",
"catalog_id": "9f9c961a-78d1-4c06-a601-4b589catalog"
}
}
}
}
],
"uses_assets": [
{
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset02",
"type": "DataSet",
"relation": {
"name": "Used"
},
"properties": {
"dataset": {
"type": "dataset",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b5890fdataset02",
"name": "2017_sales_data",
"project_id": "9f9c961a-78d1-4c06-a601-4b589project"
}
},
"project": {
"type": "project",
"value": {
"id": "9f9c961a-78d1-4c06-a601-4b589project"
}
}
}
}
],
"properties": {
"event_time": "2018-04-03T14:01:08.603Z",
"event_category": [
"additions"
],
"event_source_service": "Watson Knowledge Catalog"
}
}
}
],
"limit": 50,
"offset": 0,
"first": {
"href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lineages/9f9c961a-78d1-4c06-a601-4b5890fdataset03?offset=0&_=1528182675331"
}
}
Simple Query
The simple query can be invoked like this:
GET /v3/search?query='fred flintstone'&limit=100
With the simple query you can peform simple textual searches using the Lucene syntax. The above query will return items containing fred, flintstone, or both.
Advanced Query
You can use the Global Search api to issue queries using the full capabilities of the Elasticsearch Query Language to search for Catalog assets and Governance artifacts. For details on the structure of an item indexed in global search see below. The advanced query can look something like this:
POST /v3/search -d '
{
"_source":["provider_type_id", "artifact_id", "metadata.name"],
"query": {
"query_string" : { "query" : "flintstone" }
}
}'
The above query returns any items containg the string "flintstone".
Searching with authorization cache
Global search searches across the Cloud Pak for Data platform and restricts search results to content that a user is authorized to view. For faster search results, you can use cached authorization information by setting the auth_cache parameter to true. The auth_cache parameter is set to false by default to use the most current authorization information.
A simple query using cached authorization information:
GET /v3/search?query='fred flintstone'&limit=100&auth_cache=true
An advanced query using cached authorization information:
POST /v3/search?auth_cache=true -d '
{
"_source":["provider_type_id", "artifact_id", "metadata.name"],
"query": {
"query_string" : { "query" : "flintstone" }
}
}'
Searching with limited authorization scope
Global Search searches across the Cloud Pak for Data platform. For a faster search, you can limit your search scope to certain platform components using the auth_scope parameter.
For example, to limit the scope of your search to assets within catalogs, you can use auth_scope=catalog, or to limit your search to assets within projects, you can use auth_scope=project.
Valid values for the auth_scope parameter are catalog, project, space, category, ibm_watsonx_governance_catalog, ibm_data_product_catalog and all (default).
A simple query limiting the scope of the search to catalog only:
GET /v3/search?query='fred flintstone'&limit=100&auth_scope=catalog
An advanced query limiting the scope of the search to catalogs only:
POST /v3/search?auth_scope=catalog -d '
{
"_source":["provider_type_id", "artifact_id", "metadata.name"],
"query": {
"query_string" : { "query" : "flintstone" }
}
}'
Searching for terms in specific fields
The above query searched for the word flintstone anywhere in an indexed artifact. You can specify which fields to search in, instead of searching throughout the document using the following example:
{
"_source":["provider_type_id", "artifact_id", "metadata.name"],
"query": {
"match" : { "metadata.name" : "flintstone" }
}
}
In the above example, the query is searching for the term flintstone but only in the metadata.name field.
Key-Value Search
Use key-value pairs to restrict search within specific properties such as the name, description, tags, column names, terms, custom properties and more
key:value: This matchesvaluein the key property.key:"value here": This matchesvalue herein the key property. Quoted value is treated as a whole phrase.key1:value1 key2:value2 key3:value3: Multiple key value pairs implies an AND between all pairs. The above matches (value1in thekey1property) AND (value2in thekey2property) AND (value3in thekey3property).text before key1:value1 in-between key2:value2 key3:value3 after: Key-value pairs mixed with regular strings. The above matches (textORbeforeORin-betweenORafterin any property) AND (value1in thekey1property) AND (value2in thekey2property) AND (value3in thekey3property)
The following properties can be specified as the key.
name: Search within the name of an asset or artifact
desc: Search within the description of an asset or artifact
type: Search by the type of an asset (asset_type) or artifact (artifact_type)
owner: Search by the user ID of the owner of an asset
term: Search in assets and artifacts with the specified business term assigned
tag: Search in assets and artifacts with the specified tag
category: Search for artifacts with the specified primary category
category2: Search for artifacts with the specified secondary category
abbr: Search by the abbreviation of a business term
syn: Search by the synonym of a business term
classification: Search by the classification of an asset or artifact
column: Search with the name of a column in a data asset
columnDesc: Search within the description of a column in a data asset
columnTerm: Search with a business term assigned to a column in a data asset
columnTag: Search with a tag on a column in a data asset
columnDataclass: Search with a data class of a column in a data asset
columnClassification: Search with a classification on a column in a data asset
connection: Search with a connection path of an asset
schema: Search for data assets with the specified schema name
table: Search for data assets with the specified table name
resourceKey: Search with a resource key of an asset
steward: Search by the user ID of the steward of an artifact
Global Search searchable custom attribute names can also be used as a key to restrict search to the specified custom attribute.
Restrictions for keys:
For key-value search by type:, the value must be an asset_type such as data_asset (as referenced by GET /v2/asset_types) or artifact_type such as data_class (as referenced by GET /v3/governance_artifact_types). The value is case-sensitive.
For key-value search by owner: or steward:, the value must be the user ID and not the user name or display name. The value is case-sensitive.
Sample query to restrict search to few properties
{
"query":{
"bool":{
"must":[
{
"gs_user_query":{
"search_string":" name:job tag:Toronto",
"nlq_analyzer_enabled": true}
}
]
}
}
}
In this sample query, we want to query on any asset or artifact having job in the name property AND Toronto in the tags property.
Sample query to restrict search to a custom attribute
{
"query":{
"bool":{
“must”:[
"nested": {
"path": "custom_attributes",
"query": {
"gs_user_query":{
“search_string” : "book.author.last_name:Smith”,
"nlq_analyzer_enabled": true,
"nested": true
}
}
}
]
}
}
In this sample query, we want to query on assets of type book, having a Global Search searchable ("global_search_searchable") field called author.last_name with a value of Smith.
Sample Query with Sort
{
"_source":["provider_type_id", "artifact_id", "metadata.name"],
"query": {
"query_string" : {
"query" : "flintstone"
}
},
"sort": [
{"metadata.modified_on": {"order": "desc","unmapped_type": "date"}}
]
}
The above query will sort the search results based on the date the item was modified.
Sample Query with Aggregation
Here is a sample query of a search for the word flintstone with an aggregation (a count) of the words that people put in their tags fields and their terms fields. See the below for the fields that exist documents indexed in Global Search.
{
"query": {
"query_string" : {
"query" : "flintstone"
}
},
"aggregations" : {
"num_tags" : {"terms" : { "field" : "metadata.tags.keyword" }},
"num_terms" : {"terms" : { "field" : "metadata.terms.keyword" }}
}
}
Nested Queries and Custom Attributes
You can add any number of custom attributes to an item you index with Global Search, and each custom attribute consists of combinations of a name field, and a value field.
"custom_attributes": [
{
"last_updated_at": 0,
"attribute_name": "string",
"attribute_value": "string"
}
Because custom attributes normally consist of two fields acting as one, they are nested objects and you must use nested queries to query on those nested objects.
The custom_attributes fields will be included in the response for any result which has custom_attributes. Nested queries are only required to query properties of the custom_attributes, such as custom_attributes.attribute_name or custom_attributes.attribute_value.
Sample Nested Query
In this sample query, we want to query on any asset having a custom attribute named city having a value of ottawa, and a second custom attribute named colour having a value red. In this example, the city attribute is treated as a text field, while the colour attribute will simulate an enumerated list of colours having exact values (i.e. red, blue, green, etc).
{
"_source":["metadata.name", "custom_attributes"],
"query": {
"bool": {
"must": [
{
"nested": {
"path": "custom_attributes",
"query": {
"bool": {
"must": [
{"term": {"custom_attributes.attribute_name": "city"}},
{"match": {"custom_attributes.attribute_value": "Ottawa"}}
]
}
}
}
},
{
"nested": {
"path": "custom_attributes",
"query": {
"bool": {
"must": [
{"term": {"custom_attributes.attribute_name": "colour"}},
{"term": {"custom_attributes.attribute_value.keyword": "red"}}
]
}
}
}
}
]
}
},
"aggs": {
"custom_attr_count": {
"nested": {
"path": "custom_attributes"
},
"aggs": {
"city_count": {
"filter": {
"term": {"custom_attributes.attribute_name": "city"}
},
"aggs": {
"city_count": {
"terms": {
"field": "custom_attributes.attribute_value.keyword",
"size": 20
}
}
}
}
}
}
}
}
In the query body illustrated above, there's a query portion, and an aggregations (aggs) portion. There can be any number of custom attributes. Because we only want counts of city we must include a filter in the aggregation so that only attributes whose name is city are counted. Notice that the count is returned for custom_attribute.attribute_value.keyword, not custom_attribute.attribute_value. This is important to note. You cannot sort or aggregate on text fields. You can only do so on keyword fields. Every text field in global search has a corresponding keyword field with a .keyword extension. Use the .keyword field for things you want to count or sort on. Finally, the size parameter restricts the number of counts to return to the top 20.
Caution The key-value search is not supported inside a nested clause.
General Purpose Search Function
Global Search provides a general purpose search function that is tailored to the requirements of CloudPak For Data users. You can invoke it using Global Search's Advanced API (see the Methods section below). It is this function that CloudPak for Data uses when a user enters a search term at the top search bar of the CloudPak for Data user interface. You can invoke it anywhere you would normally invoke a normal ElasticSearch search function. For example it can be the main function of your query:
{
"query":{
"gs_user_query":{
"search_string":"The quick red fox jumped over the lazy brown dog"
}
}
}
The search_string field is required and specifies the search query string.
The following optional parameters can be specified as part of the gs_user_query:
search_fields- List of fields that the search will be restricted to. If not specified, the search will run across all fields in the configuration.nlq_analyzer_enabled- Specifytrueto enable the natural language analyzer. The default value isfalse.semantic_expansion_enabled- Specifytrueto enable semantic query expansion. The default value isfalse.nested- Specifytrueto optimize nested queries. The default value isfalse.
{
"query":{
"gs_user_query":{
"search_string": "The quick red fox jumped over the lazy brown dog",
"search_fields": ["metadata.name", "metadata.description"],
"nlq_analyzer_enabled": true,
"semantic_expansion_enabled": true,
"nested": false
}
}
}
This search function will find:
- a single phrase
- multiple individual words
- partial words (within words or at the beginning of words)
- the first letter of a word
If no search fields are specified, the function will search the entire document, including the name fields, the description field, tags, synonyms, custom attribute values, column names, and column descriptions, etc. It will give the highest priority to the name field of the document.
You can embed gs_user_query within a compound query:
{
"query":{
"bool":{
"must":[
{"gs_user_query":{"search_string": "the quick red fox jumped over the lazy brown dog"}}
],
"filter":[
{"term":{"provider_type_id":"cams"}}
]
}
},
"sort": [
{"metadata.modified_on": {"order": "desc","unmapped_type": "date"}}
]
}
You can include gs_user_query with complex queries that include aggregations along with sorts:
{
"query": {
"gs_user_query" : {
"search_string": "fred flintstone"
}
},
"sort" : [
{"metadata.modified_on": {"order": "desc", "unmapped_type": "date"}}
],
"aggregations": {
"first_letter": {
"terms": {
"script": "doc['metadata.name.keyword'].getValue().substring(0,1)",
"order": {
"_key": "asc"
}
},
"aggs": {
"first_letter_group": {
"terms": {
"field": "metadata.name.keyword",
"order": {
"_key": "asc"
}
}
}
}
}
}
}
You can use gs_user_query in a nested query to search for custom attributes:
{
"query": {
"bool": {
"should": [
{
"gs_user_query": {
"search_string": "quick red fox",
"nlq_analyzer_enabled": true
}
},
{
"nested": {
"path": "custom_attributes",
"query": {
"gs_user_query": {
"search_string": "lazy brown dog",
"nlq_analyzer_enabled": true,
"nested": true
}
}
}
}
]
}
}
Searching for a quoted phrase
Wrap the phrase in quotes within your query as follows:
{
"query":{
"gs_user_query":{
"search_string":"\"The quick red fox jumped over the lazy brown dog\""
}
}
}
The above query will search for exactly the phrase "The quick red fox jumped over the lazy brown dog".
A quoted phrase can also be included in a longer string:
{
"query":{
"gs_user_query":{
"search_string":"The \"quick red fox\" jumped over the \"lazy brown dog\"",
"nlq_analyzer_enabled": true
}
}
}
The above query will search for the phrases quick red fox and lazy brown dog, and will not return results containing only quick, red, fox, lazy, brown, or dog. The query will, however, return results matching the individual words jumped or over.
Searching for words starting with ...
To search for words starting with a letter or letters, enter only the first 1 to 3 letters of the word.
{
"query":{
"gs_user_query":{
"search_string":"in"
}
}
}
The above query will return documents with words like infinite and invitation, but not words like definitive.
Searching for parts of words
If your search terms include more than three letters, then Global Search will search for any partial word matches. For example
{
"query":{
"gs_user_query":{
"search_string":"init"
}
}
}
The above query will find documents with words like initialize (i.e. at the beginning of the word) and trinitoluene (i.e. within the word).
Note: The metadata.description and entity.assets.column_descriptions fields are excluded from partial word matching.
Searching with natural language
Natural language analysis can be applied to English search strings to optimize search results in the following ways:
- Words that are not important to the search intent are removed from the search query.
- Phrases in the search string that are common in English are automatically ranked higher than results for individual words.
{
"query": {
"gs_user_query": {
"search_string": "credit card interest in United States",
"nlq_analyzer_enabled": true
}
}
}
The above query will find documents with:
- Matches for the phrases credit card interest and United States ranked highest
- Matches for individual words credit, card, interest, United, and States ranked lower
The above query will not return documents containing only the word in.
Searching with business term semantics
Business terms can be used to express semantic meaning of words and phrases of a business vocabulary. Semantic search leverages this knowledge by expanding search to follow term relationships, making it easier to find semantically similar assets on the platform.
The query below illustrates how to structure a query which uses both natural language analysis and semantic expansion:
{
"query": {
"gs_user_query": {
"search_string": "contact methods for clients",
"nlq_analyzer_enabled": true,
"semantic_expansion_enabled": true
}
}
}
With both natural language analysis and semantic expansion enabled, the search will find business terms matching any of the following:
contact methods for clientscontact methodsclients
Business terms are matched based on their names or abbreviations. For example, CTM may be defined as an abbreviation of the term contact methods. If the search string includes CTM the business term contact methods will match.
For any matching business terms, free-text search results will be expanded to also include the following business terms as well as any assets associated the following business terms:
- Synonyms of the business term
- For example,
customermay be defined as a synonym ofclient
- For example,
- Business terms which are a type of the business term or its synonyms.
- For example,
phone numberwith typeshome phoneandcell phonemay be defined as a type ofcontact methods
- For example,
- Business terms which are related to the business term
- For example,
preferred method of contactmay be defined as being related tocontact method
- For example,
The expanded search results are driven entirely by the definition of business terms and their relationships.
Result scoring
Results are prioritized using a combination of field priority and type of match as follows:
Type of match:
- Matches for entire phrases will score highest.
- Exact matches of complete words will score next highest.
- If the search term is 3 characters or less results that contain words STARTING with that search term will score next highest.
- Partial matches of complete words will score next highest.
- Fuzzy matches (i.e.
adidasvsadadas) will match, but will score lowest.
Field:
- Name
- Synonyms, Abbreviation, Terms, Tags or Classifications
- Description, Primary or Secondary Category
- Column Descriptions, Column Terms, Column Tags or Column Data Class Names
Documents in Global Search
You can query on any of the fields within the document by including the field name in a flattened json structure. For example the field:
{
"entity":{
"artifacts":{
"artifact_id":"<id>"
}
}
}
is queried for by using the following
entity.artifacts.artifact_id
Documents indexed in global search have the following structure:
{
"provider_type_id": "string",
"tenant_id": "string",
"artifact_id": "string",
"last_updated_at": 0,
"metadata": {
"name": "string",
"description": "string",
"artifact_type": "string",
"tags": [
"string"
],
"modified_on": "2021-02-11T11:25:59.384Z",
"modified_by": "string",
"terms": [
"string"
],
"term_global_ids": [
"string"
],
"steward_ids": [
"string"
],
"steward_group_ids": [
"string"
]
"state": "string",
"classifications": [
"string"
],
"classification_global_ids": [
"string"
]
},
"entity": {
"artifacts": {
"global_id": "string",
"version_id": "string",
"artifact_id": "string",
"rule_type": "string",
"effective_start_date": "2021-02-11T11:25:59.384Z",
"effective_end_date": "2021-02-11T11:25:59.384Z",
"abbreviation": [
"string"
],
"synonyms": [
"string"
],
"synonym_global_ids": [
"string"
],
"enabled": true
},
"assets": {
"asset_id": "string",
"asset_name": "string",
"attribute_quality_score": 0,
"catalog_id": "string",
"project_id": "string",
"space_id": "string",
"column_names": [
"string"
],
"column_terms": [
"string"
],
"column_term_global_ids": [
"string"
],
"column_descriptions": [
"string"
],
"connection_paths": [
"string"
],
"column_tags": [
"string"
],
"connection_ids": [
"string"
],
"column_data_class_names": [
"string"
],
"data_quality_score": 0,
"data_quality_score_dbl": 0,
"data_quality_delta": 0,
"data_quality_delta_dbl": 0,
"metadata_enrichment_area_id": "string",
"metadata_enrichment_review_date": 0,
"resource_key": "string",
"asset_id": "string",
"suggested_column_term_global_ids": [
"string"
],
"suggested_column_terms": [
"string"
],
"schema_name": "string",
"table_name": "string",
"structured_profiling_completed_date": "2021-02-11T11:25:59.384Z",
"structured_profiling_status": "string",
"term_assignment_completed_date": "2021-02-11T11:25:59.384Z",
"metadata_import_id": "string",
"first_imported_timestamp": "2021-02-11T11:25:59.384Z",
"last_imported_timestamp": "2021-02-11T11:25:59.384Z",
"outdated_timestamp": "2021-02-11T11:25:59.384Z",
"last_discovered_timestamp": "2021-02-11T11:25:59.384Z",
"outdated_reason": "string"
},
"data_asset_column": {
"data_class_name": "string",
"data_class_id": "string",
"data_class_set_by_user": true,
"data_quality_score": 0,
"data_quality_score_dbl": 0,
"metadata_enrichment_review_date": "2021-02-11T11:25:59.384Z",
"data_quality_delta": 0,
"data_quality_delta_dbl": 0,
"column_order": 0,
"suggested_class_ids": ["string", "string", "string"],
"suggested_class_names": ["string", "string", "string"]
},
"ref_data_value": {
"value": "string",
"value_long": 0,
"value_dbl": 0,
"ref_data_set_artifact_id": "string",
"ref_data_set_version_id": "string",
"parent_ref_data_value_artifact_id": "string"
}
},
"custom_attributes": [
{
"last_updated_at": 0,
"attribute_name": "string",
"attribute_value": "string"
}
],
"categories": [
{
"last_updated_at": 0,
"primary_category_id": "string",
"primary_category_global_id": "string",
"primary_category_name": "string",
"secondary_category_ids": [
"string"
],
"secondary_category_global_ids": [
"string"
],
"secondary_category_names": [
"string"
]
}
]
}
Methods
Get a list of file paths.
Returns a list of file paths (similar to S3 listObjects) for the provided project, catalog, space or account. Requires viewer or higher permission. Assets for a catalog are not retrievable by external users.
GET /v2/asset_files
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000Pagination param, limit number of resources returned.
Pagination param, resources returned wil be offset by this value.
If true folder structures are recursively flattened and the response is a list of files of all files in parent and child directories. The 'path' will show the resource full path from starting directory.
Whether or not to resturn hidden files. If false, hidden files files will be left out of the response object. Only works when the path being retrieved is a directory. Default is true.
(Internal use only) If '&root=true' is supplied in request URL the api will return relative to target container's root directory instead of standard assets directory. Note, there is one exception. If '&root=true' is supplied along with 'userfs' param targetting a project where the user has correct permissions standard auth will work.'
The content will be streamed out instead of being fully contructed and sent out all at once. Used mainly when there are a large number of files are expected.
Response
The total number of resource for the query.
The limit used for the request.
The offset used for the request.
- first
URL to indicated pagination result.
- last
URL to indicated pagination result.
- next
URL to indicated pagination result.
- previous
URL to indicated pagination result.
- resources
The path of the file.
ETAG for the resource. Not returned when streaming responses.
The size in bytes for files. The number of resource for folders.
Either folder or file.
If the resource is a file this will be the mime type of the file. If the mime_type cannot be determined it will not be returned.
Time when the asset was last modified, defaults to create date. Returned in json timestamp format.
Status Code
OK
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space or account does not exist.
Internal server error.
No Sample Response
Create project, catalog, space or account root folder.
Before files can be uploaded, project/catalog/account/space root folder needs to be created. If the folder already exists the call will fail. Project folder can be created with additional content required for internal Git. Requires Bearer auth with admin permission for project or space. Creating folder for a catalog is not available to external users.
PUT /v2/asset_files
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000Optional param for project containers.
Response
Status Code
The folder was created.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space or account does not exist.
Conflict. The directory already exists.
Internal server error.
No Sample Response
Batch delete or delete project/catalog/account/space folder.
Delete either files in batch or a project/catalog/account/space folder. If request body is present it should be a list of filenames/filepaths to be deleted in the provided project, catalog, space or account. Files are deleted asyncronously so some files may be deleted and others skipped. If there is no request body the project/catalog/account/space folder will be deleted but will fail if the project/catalog/account/space folder is not empty. For projects and spaces a batch delete requires editor permission. For accounts, batch delete requires the user to be the account admin. Deletion of the project/catalog/account/space folder requires admin permission. Catalog assets are cannot be deleted by external users (internal only). Please note the 'assets' dir and its subdir 'data_asset' cannot be deleted.
DELETE /v2/asset_files
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000(Internal use only) If '&root=true' is supplied in request URL the api will return relative to target container's root directory instead of standard assets directory. Note, there is one exception. If '&root=true' is supplied along with 'userfs' param targetting a project where the user has correct permissions standard auth will work.'
If '&force_delete=true' all safeguards regarding non-empty directory will be bypassed. Only works for projects, catalogs and spaces.
Asset files to delete
Response
Status Code
The delete partially successful. Response body will be a list of files.
The delete operation was completely successful.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space or account does not exist.
Internal server error.
No Sample Response
Get Asset File
Streams the content of the specified file, with the appropriate HTTP headers for etag, file size, mime type etc. If the asset file is a directory, response will be JSON listing the content of the directory. If the asset is a file, response will be contents of the file. Requires viewer permission or higher. Assets for a catalog are not available to external users. This endpoint supports authentication via signature paramater. See 'Get auth signature' call for more info.
GET /v2/asset_files/{path}Request
Custom Headers
Similar to byte_range query param. Currently only supports bytes. See https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35 for more info. Can be used to limit the bytes of a file being returned. Ranges are inclusive. If set will take precedence over anything in byte_limit or byte_range.
Default:
Range 0-100
Path Parameters
Asset file path
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000If passed, indicates how many bytes of data is to be returned.
If passed, indicates the bytes that should be returned. Must be in format ('x-y': bytes x to y inclusive, '-y': the last y bytes, 'x-': everything from and including the xth byte). Does not support mulitiple ranges.
Returns 400 bad request if asset is larger than the value provided here. In MB.
Additional auth method. Signed string obtained by making presigned API request.
If true, folder structures are recursively flattened and the response is a list of files of all files in parent and child directories. The 'path' will show the resource full path from starting directory. Only works for directories.
If true, the response will contain less info. (ex// no etag) Only works with flat param set to true.
Whether or not to resturn hidden files. If false, hidden files files will be left out of the response object. Only works when the path being retrieved is a directory. Default is true.
(Internal use only) If '&root=true' is supplied in request URL the api will return relative to target container's root directory instead of standard assets directory. Note, there is one exception. If '&root=true' is supplied along with 'userfs' param targetting a project where the user has correct permissions standard auth will work.'
If '&inflate=true' ALL other query params except the target are ignored. The file being retrieved must be an archive. If all checks pass the archive will be expanded to a temp location and the results will be returned as if flat=true was supplied. If the target archive has perviously be inflated any existing inflate preview will be overwritten if the zip is newer. Otherwise the previous preview will be returned.
Only used when &inflate=true. Tells asset files to skip validation on wheter the target is a zip. Inflate will be run regardless.
Only works for directories. The content will be streamed out instead of being fully contructed and sent out all at once. Used mainly for when there are a large number of files are expected.
Response
Status Code
If the requested asset is a file, the file is returned. If it is a directory, a JSON object will be returned. The JSON format for a folder will match that of GET /v2/asset_files/path
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space, account or asset does not exist.
Internal server error.
No Sample Response
Get Asset File Headers
Returns ONLY the HTTP headers for etag, file size, mime type etc. without streaming the file content. Requires viewer permission. Assets for a catalog are not available to external users. This endpoint supports authentication via signature paramater. See 'Get auth signature' call for more info.
HEAD /v2/asset_files/{path}Request
Path Parameters
Asset file path
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000Additional auth method. Signed URL obtained by making presigned API request.
Response
Status Code
Headers for the requested file are returned in response.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space, account or asset does not exist.
Internal server error.
Put New Asset File
Uploads the bytes into the file with the provided file name using HTTP multi-part format, creating a new file if missing, overriding if existing (unless override=false). Assets cannot be uploaded to a catalog by external users. Adding project or space assets accepts all formats that grant editor access or higher. Adding to accounts requires a user with account admin access. This endpoint supports authentication via signature paramater. See 'Get auth signature' call for more info on signed urls.
PUT /v2/asset_files/{path}Request
Path Parameters
Asset file path
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000Default true. If set to false will not overwrite file.
Additional auth method. Signed string obtained by making API request to signing endpoint.
Root dir must be created. Will take supplied file and decompress into target directory tree. Inflate is only acceptable for project, space and catalog targets. If inflate is selected it will take precedence over any and all other params.
Override functionality. If true will ensure the directory specified by 'path' exists (instead of uploading any file provided). 201 will be returned ig created, 200 if already exists and 409 if it is present and not a directory. Will take precedence over other query params except 'inflate'
(Internal use only) If '&root=true' is supplied in request URL the api will return relative to target container's root directory instead of standard assets directory. Note, there is one exception. If '&root=true' is supplied along with 'userfs' param targetting a project where the user has correct permissions standard auth will work.'
Form Parameters
File to upload.
Response
Status Code
Asset file/folder created. The asset was successfully uploaded.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space or account does not exist.
Internal server error.
No Sample Response
Delete Single Asset File/Folder
Deletes a file in a project, space or a catalog. Requires minimum editor permission for projects and spaces. Assets in a catalog cannot be deleted by external users. Account requires users to have account admin privelege or internal auth. Please note the 'assets' dir and its subdir 'data_asset' cannot be deleted.
DELETE /v2/asset_files/{path}Request
Path Parameters
Asset file path
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000(Internal use only) If '&root=true' is supplied in request URL the api will return relative to target container's root directory instead of standard assets directory. Note, there is one exception. If '&root=true' is supplied along with 'userfs' param targetting a project where the user has correct permissions standard auth will work.'
If '&force_delete=true' is supplied, non-empty directories will be deleted.
Response
Status Code
Asset file/folder was deleted.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space or account does not exist.
Internal server error.
No Sample Response
Get auth signature
(Internal use only) Generate a signed URL that can be used to access specific API calls. A signed URL will be returned in the response body as plain text. A fully encoded version of the same url will be sent in the 'Location' header.
POST /v2/asset_files/{path}/signedRequest
Custom Headers
(Internal use only) Authorization value should use Basic [token] format where [token] is an opaque access token obtained by authenticating with appropriate auth service.
Default:
Basic tokenAllowable values: [
application/json,text/html,text/plain]
Path Parameters
The path to asset you wish to make signed url for. Must be encoded
Query Parameters
TTL in seconds.
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified catalog.
Example:
3edb984f-df1e-4017-ae30-c1ca42fac19cMake request relative to the specified account.
Example:
999Make request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000Optional content type (to override the defaults of asset being requested)
Optional (to override the defaults) - must be URIEncoded as it can contain spaces if filename is used.
Wheter to access the path from root.
Only useful for put. Will allow signed url to act as inflat request.
Accepts 'get' or 'put'. (Defaults to 'get' if not supplied)
Response
Status Code
A signed URL that can be used to access other endpoints. The same value will be returned in 'Location' header. The value return in the body can be used as is. The value returned in the location header is url encoded and should be decoded before use.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space or asset does not exist.
Internal server error.
/v2/asset_files/data_asset%2Fmyfile.csv?project_id=f0bf39f4-8eb9-4a64-9408-4132f850eeac&signature=2YQspmvQndoU%2FvjbzLACUA%3D%3D%3Al%2Bxzj4Z0zeI%2FdjjuxU16IBR03EvA%2FIhAqfKGCMJkcl1fPxMt22GObAW6X%2F8FcbL7s3KxoiI%2BCNICH%2B67m6xGaOUQnI0ZRuJ8NiH8c%2BbUiHTO9Fo6lA59O3XsL7pUNah5HM6ByYXUA6OzCud6hgCVGqFZBfqnpZeU%2BDR3gun2DnZFzWWOnYBHb58ahTyPNn%2BmI%2F2yNZ1Wekhbqae%2BRhWYZ0P%2FQBVxGddejXML5nWtxADoo3mQO9avGQg%3D
Create archive for target
(Internal use only) Generate an archive and saves it to the path provided.
POST /v2/asset_files/{path}/deflateRequest
Custom Headers
(Internal use only) Authorization value should use Basic [token] format where [token] is an opaque access token obtained by authenticating with appropriate auth service.
Default:
Basic token
Path Parameters
The filename where the project archive will be saved.
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0The flag for git-based projects.
(Internal use only) Make request relative to the specific iam id. Respected only when 'userfs' is also supplied.
Example:
0000000000If true only one element can be supplied in body and it must be directory. The entire directory content will be zipped into the archive. Default is false.
On completion of the archinving a rabbit MQ task will be sent out. Default is true.
The event type to specify in the rabbitMQ message once archiving completes. Default is "export_deflate".
In true, the deflate log will be a hidden file. Default is false.
Either a list of asset paths that should be included in the archive being created or object with key 'file' with list of contents to include. Empty array will result in everything being included.
Response
Status Code
Returned if the deflate operation was started successfully.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified target does not exist.
Internal server error.
No Sample Response
Inflate the source archive to the target location
(Internal use only) Inflate the source archive to the specified target location.
POST /v2/asset_files/inflate
Request
Custom Headers
(Internal use only) Authorization value should use Basic [token] format where [token] is an opaque access token obtained by authenticating with appropriate auth service.
Default:
Basic token
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffMake request relative to the specified space.
Example:
00ad857d-44e5-4224-b02f-d6d67bbb97c0
The source and target specifications.
The relative path to the archive in asset-files
The relative target location to inflate the file to
Response
Status Code
Returned if the inflate operation was completed successfully.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified target does not exist.
Internal server error.
No Sample Response
Copy Asset File
Copies a file between source and target provided in the POST body. Any combination of spaces, projects and catalogs are allowed. Viewer permission is required for the source and editor permission is required for the target. Assets for a catalog are not available to external users. For larger files async_copy is recomended.
POST /v2/asset_files/copy
Request
Information on the asset to copy.
- source
The type of the source container.
The guid of the source container.
The location of the asset being copied
(Internal use only) If set to true the path will be relative to the container root directory. Note, there is one exception. If supplied along with 'userfs' param targetting a project where the user has correct permissions this is also viable'
Specify path based on git based project structure.
Default:
false
- target
The type of the source container.
The guid of the source container.
The location where the asset should be copied
(Internal use only) If set to true the path will be relative to the container root directory. Note, there is one exception. If supplied along with 'userfs' param targetting a project where the user has correct permissions this is also viable'
Specify path based on git based project structure.
Default:
false
Response
Status Code
Will be returned when the asset is copied successfully.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space, account or asset does not exist.
Internal server error.
No Sample Response
Copy Asset File (async)
Similar to copy asset however, the response will be returned upon the copy starting instead of on completion.
POST /v2/asset_files/async_copy
Request
Information on the asset to copy.
- source
The type of the source container.
The guid of the source container.
The location of the asset being copied
(Internal use only) If set to true the path will be relative to the container root directory. Note, there is one exception. If supplied along with 'userfs' param targetting a project where the user has correct permissions this is also viable'
Specify path based on git based project structure.
Default:
false
- target
The type of the source container.
The guid of the source container.
The location where the asset should be copied
(Internal use only) If set to true the path will be relative to the container root directory. Note, there is one exception. If supplied along with 'userfs' param targetting a project where the user has correct permissions this is also viable'
Specify path based on git based project structure.
Default:
false
Response
Status Code
Will be returned after initial validation is complete and the copy operation started.
Bad Request. Returned if missing / invalid params are supplied.
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified catalog, project, space, account or asset does not exist.
Internal server error.
No Sample Response
Git Export
Performs git add on the assets provided in the body, then commit and push to the remote
POST /v2/asset_files/git_transactions/export
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffOptional paramater, the supplied id will be used in resulting RabbitMQ event.
Git export body
Relative asset path.
- access_token
The value for the desired git host.
Allowable values: [
github,github_enterprise,bitbucket,bitbucket_enterprise,gitlab,gitlab_self_managed]
Response
Status Code
Export transaction accepted
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified project or asset does not exist.
Internal server error.
No Sample Response
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffOptional paramater, the supplied id will be used in resulting RabbitMQ event.
Git import body
- access_token
The value for the desired git host.
Allowable values: [
github,github_enterprise,bitbucket,bitbucket_enterprise,gitlab,gitlab_self_managed]
Response
Status Code
Import transaction accepted
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified project or asset does not exist.
Internal server error.
No Sample Response
Git Add Remote
Performs a git remote add on the given project
POST /v2/asset_files/git_transactions/remote
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ff
Git add remote repository information
- access_token
The value for the desired git host.
Allowable values: [
github,github_enterprise,bitbucket,bitbucket_enterprise,gitlab,gitlab_self_managed]
Response
Status Code
Successfully added remote
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified project or asset does not exist.
Internal server error.
No Sample Response
Git Remove Remote
Performs a git remote remove on the given project
POST /v2/asset_files/git_transactions/delete_remote
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ff
Response
Status Code
Successfully removed remote
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified project or asset does not exist.
Internal server error.
No Sample Response
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ffOptional paramater, the supplied id will be used in resulting RabbitMQ event.
Git pull body
Response
Status Code
Pull transaction accepted
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified project or asset does not exist.
Internal server error.
No Sample Response
Change Git Settings
Modifies an existing git repo's config
PUT /v2/asset_files/git_transactions/settings
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ff
Git settings body
- http
Response
- http
Status Code
Change complete
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified project or asset does not exist.
Internal server error.
No Sample Response
Get Git Settings
Retrieves an existing git repo's config
GET /v2/asset_files/git_transactions/settings
Request
Query Parameters
Make request relative to the specified project.
Example:
7cda791d-fcbc-405a-93f4-4be95d09e4ff
Response
- http
Status Code
Current settings
Unauthorized. Returned when a user makes a request without proper Authorization header.
Forbidden. Returned when a user makes a request to something they do not have access to.
Not Found. Specified project or asset does not exist.
Internal server error.
No Sample Response
Archive the asset container
Archive the assets database of the asset container.
Archiving the assets database of not used asset containers helps saving storage and computing resources of the database, therefore reduce the footprint of CAMS.The information stored in the archived asset containers will not be accessible until the asset containers are restored.
POST /v2/asset_containers/archive
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Archive request
Response
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Status Code
Accepted
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Get archive information of the asset container
Get archive information of the asset container.
GET /v2/asset_containers/archive_info
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Response
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Get configurations
Get the configurations of a catalog/project/space.
GET /v2/asset_containers/configurations
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Response
Action to take if duplicate assets are found for a given asset
Possible values: [
IGNORE,REJECT,REPLACE,UPDATE]Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]Duplicate detection strategies of assets with specified asset types in this catalog/project/space
Authorize reporting in this catalog
Whether assets has to be purged on delete
Days after which assets has to be purged after soft delete
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
No Sample Response
Replace or create configurations
Replace the configurations of a catalog/project/space or create the configurations if they do not exist.
PUT /v2/asset_containers/configurations
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Configurations
Action to take if duplicate assets are found for a given asset
Allowable values: [
IGNORE,REJECT,REPLACE,UPDATE]Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined
Allowable values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]Duplicate detection strategies of assets with specified asset types in this catalog/project/space
Authorize reporting in this catalog
Whether assets has to be purged on delete
Days after which assets has to be purged after soft delete
Response
Action to take if duplicate assets are found for a given asset
Possible values: [
IGNORE,REJECT,REPLACE,UPDATE]Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]Duplicate detection strategies of assets with specified asset types in this catalog/project/space
Authorize reporting in this catalog
Whether assets has to be purged on delete
Days after which assets has to be purged after soft delete
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Restore the asset container
Restore the assets database of the archived asset container. Only successfully archived asset container can be restored.
POST /v2/asset_containers/restore
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Response
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Status Code
OK
Accepted
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
List all asset lists defined for an account
Retrieve a paginated list of asset lists defined for an account.
GET /v2/asset_lists
Request
Query Parameters
Query to retrieve a paginated list of asset list metadatas for which the request user has permission to view.
Search query in Common Expression Language, with special characters encoded. For example, & is %26.
Examples of query parameters:
* id
* type
* state
* access_control.owner
* created_at
* last_updated_atPossible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$%&=|\(\)\s\-\_\^"]+$Example:
type==order%26%26created_at%3E=2023-08-23T21:10:40ZStart token for pagination
Possible values: 1 ≤ length ≤ 512, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Search result limit
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
10This parameter can be repeated to add additional sort fields.
Default: nullExamples of sort fields (these are case insensitive):
- created_at
- -created_at
- last_updated_at
- -last_updated_at
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$
curl --request GET --url '{url}/v2/asset_lists' --header 'authorization: Bearer {access_token}' --header 'accept: application/json'
Response
The Asset list collection response API model.
Collection of asset list results.
Possible values: 0 ≤ number of items ≤ 200
The limit on the number of results returned.
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Example:
50A page in a pagination collection.
The next page in the collection.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
{ "limit": 200, "total_count": 1, "first": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists" }, "next": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists?start=start_token", "start": "start_token" }, "asset_lists": [ { "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId" } ] }
Create a new asset list
Use this API to creates a new asset list.
If the state is not specified, the asset list will be created in DEFAULT state.
The list may be created with items, or without items.
The list will be owned by the request user.
POST /v2/asset_lists
Request
The asset list for creation.
Example REST body for asset list creation of type ORDER.
{
"name": "my_order",
"description": "Order of multiple items",
"type": "order",
"items": [
{
"asset": {
"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a",
"type": "data_asset",
"container": {
"id": "71993ab5-3374-4355-8a38-fc4c32debc00",
"type": "catalog"
}
},
"properties": {
"my_property_1": "Value 1",
"my_property_2": "Value 2"
}
},
{
"asset": {
"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69b",
"type": "data_asset",
"container": {
"id": "71993ab5-3374-4355-8a38-fc4c32debc00",
"type": "catalog"
}
},
"properties": {
"my_property_1": "Value 1",
"my_property_map": {
"my_property_map_key": "Value 2"
}
}
}
]
}Asset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Allowable values: [
cart,wishlist,order]Example:
orderAn asset from a container.
The items in the asset list.
Possible values: 0 ≤ number of items ≤ 20
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.The state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Allowable values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Default:
default_stateExample:
default_stateA message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
curl --request POST --url '{url}/v2/asset_lists' --header 'accept: application/json' --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' --data '{"name": "my_order","description": "Order of multiple items","items": [{"asset": {"metadata": {"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a","type": "data_asset","container": {"id": "71993ab5-3374-4355-8a38-fc4c32debc00","type": "catalog"}}},"properties": {"my_property_1": "Value 1","my_property_2": "Value 2"}},{"asset": {"metadata": {"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69b","type": "data_asset","container": {"id": "71993ab5-3374-4355-8a38-fc4c32debc00","type": "catalog"}}},"properties": {"my_property_1": "Value 1","my_property_map": {"my_property_map_key": "Value 2"}}}],"type": "order"}'
Response
The Asset list summary API model for retrieval.
The unique identifier of the asset list formatted either as a UUID or a special case such as cart_userID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list was created (system managed).
Example:
2022-04-22T03:22:32.000ZRFC 3339 timestamp when the asset list was last updated (system managed).
Example:
2022-04-22T03:22:32.000ZThe user who last updated the asset list.
Example:
userIdAsset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Possible values: [
cart,wishlist,order]Example:
orderThe state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Possible values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Example:
default_stateAn asset from a container.
Access control permissions for the asset list.
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.A message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
Internal Server Error
{ "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId" }
Delete asset lists
Deletes asset lists based on a query in Common Expression Language format.
DELETE /v2/asset_lists
Request
Query Parameters
Query to delete asset lists for which the request user has permission.
Search query in Common Expression Language, with special characters encoded. For example, & is %26.
Examples of query parameters:
* id
* type
* state
* access_control.owner
* created_at
* last_updated_atPossible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$%&=|\(\)\s\-\_\^"]+$Example:
type==order%26%26created_at%3E=2023-08-23T21:10:40Z
curl --request DELETE --url '{url}/v2/asset_lists?query=created_at%3E%3D2023-08-23T21%3A10%3A40Z' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Retrieve an asset list identified by ID
Retrieves the metadata of an asset list of a given identified by ID.
GET /v2/asset_lists/{asset_list_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
curl --request GET --url '{url}/v2/asset_lists/{asset_list_id}' --header 'authorization: Bearer {access_token}' --header 'accept: application/json'
Response
The Asset list summary API model for retrieval.
The unique identifier of the asset list formatted either as a UUID or a special case such as cart_userID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list was created (system managed).
Example:
2022-04-22T03:22:32.000ZRFC 3339 timestamp when the asset list was last updated (system managed).
Example:
2022-04-22T03:22:32.000ZThe user who last updated the asset list.
Example:
userIdAsset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Possible values: [
cart,wishlist,order]Example:
orderThe state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Possible values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Example:
default_stateAn asset from a container.
Access control permissions for the asset list.
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.A message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId" }
Delete an asset list identified by ID
Deletes an asset list identified by ID. The user must have permission to perform this action.
DELETE /v2/asset_lists/{asset_list_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
curl --request DELETE --url '{url}/v2/asset_lists/{asset_list_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Update the metadata of an asset list
Use this API to update the asset list metadata. Specify patch operations using http://jsonpatch.com/ syntax.
Fields that can be patched:
- /name
- /description
- /type
- /state (Approvers and Functional users only)
- /message (Approvers and Functional users only)
Note: The ownership cannot be modified after creation.
PATCH /v2/asset_lists/{asset_list_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Example REST body for asset list update of the state parameter.
[
{
"op": "replace",
"path": "/state",
"value": "confirmed"
}
]The Json patch path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch from path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch value.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$The Json patch operation as defined by RFC 6902.
Allowable values: [
add,replace,remove,move,copy,test]
curl --request PATCH --url '{url}/v2/asset_lists/{asset_list_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' --data '[{"op": "replace","path": "/state","value": "confirmed"}]'
Response
The Asset list summary API model for retrieval.
The unique identifier of the asset list formatted either as a UUID or a special case such as cart_userID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list was created (system managed).
Example:
2022-04-22T03:22:32.000ZRFC 3339 timestamp when the asset list was last updated (system managed).
Example:
2022-04-22T03:22:32.000ZThe user who last updated the asset list.
Example:
userIdAsset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Possible values: [
cart,wishlist,order]Example:
orderThe state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Possible values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Example:
default_stateAn asset from a container.
Access control permissions for the asset list.
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.A message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Conflict
Unsupported Media Type
Internal Server Error
{ "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId" }
List the items of an asset list identified by ID
Retrieves the list items of an asset list identified by ID.
GET /v2/asset_lists/{asset_list_id}/itemsRequest
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
Query Parameters
Query to retrieve a paginated list of asset list items for which the request user has permission to view.
Search query in Common Expression Language, with special characters encoded. For example, & is %26.Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$%&=|\(\)\s\-\_\^"]+$Example:
properties.data_product_id==aaff9159-8ba4-4ae5-a9d7-3e59d5903d72%26%26created_at%3E=2023-08-23T21:10:40ZStart token for pagination
Possible values: 1 ≤ length ≤ 512, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Search result limit
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
10This parameter can be repeated to add additional sort fields.
Default: nullExamples of sort fields (these are case insensitive):
- created_at
- -created_at
- last_update_time
- -last_update_time
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$
curl --request GET --url '{url}/v2/asset_lists/{asset_list_id}/items' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Response
The Asset list item collection response API model.
Collection of asset list item results.
Possible values: 0 ≤ number of items ≤ 200
The limit on the number of results returned.
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Example:
50A page in a pagination collection.
The next page in the collection.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "limit": 200, "total_count": 2, "first": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists/3204c622-dcb8-4728-869f-484b6ac73dff/items" }, "next": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists/3204c622-dcb8-4728-869f-484b6ac73dff/items?start=start_token", "start": "start_token" }, "items": [ { "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_2": "Value 2" }, "id": "6357fce0-41ef-433b-95ee-03ade01bd02d", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } }, { "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69b", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_map": { "my_property_map_key": "Value 2" } }, "id": "cdaf6713-ede0-4a61-9fa4-d65467c59e9c", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } } ] }
Retrieve an item in an asset list
Retrieves an item identified by ID of an asset list identified by ID.
GET /v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72Asset list item id (GUID)
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d73
curl --request GET --url '{url}/v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Response
The Asset list item canonical API model.
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list item was created (system managed).
Example:
2022-04-22T03:22:32.000ZRFC 3339 timestamp when the asset list item was last updated (system managed).
Example:
2022-04-22T03:22:32.000ZThe user who last updated the asset list item.
Example:
userIdThe reference to the asset list to which the item belongs.
- asset_list
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69f
An asset from a container.
Access control permissions for the asset list.
The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_2": "Value 2" }, "id": "6357fce0-41ef-433b-95ee-03ade01bd02d", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } }
Update an asset list item
Use this API to update an asset list item. Specify patch operations using http://jsonpatch.com/ syntax.
Fields that can be patched:
- /properties
PATCH /v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72Asset list item id (GUID)
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d73
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Example REST body for asset list item update of the properties map.
[
{
"op": "add",
"path": "/properties/my_prop",
"value": {
"key": "Val 1"
}
},
{
"op": "replace",
"path": "/properties/my_prop2",
"value": {
"key": "Val 2"
}
}
]The Json patch path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch from path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch value.
The Json patch operation as defined by RFC 6902.
Allowable values: [
add,replace,remove,move,copy,test]
curl --request PATCH --url '{url}/v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' --data '[{"op": "add","path": "/properties/my_prop","value": {"key": "Val 1"}},{"op": "replace","path": "/properties/my_prop2/key","value": "Val 2"}]'
Response
The Asset list item canonical API model.
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list item was created (system managed).
Example:
2022-04-22T03:22:32.000ZRFC 3339 timestamp when the asset list item was last updated (system managed).
Example:
2022-04-22T03:22:32.000ZThe user who last updated the asset list item.
Example:
userIdThe reference to the asset list to which the item belongs.
- asset_list
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69f
An asset from a container.
Access control permissions for the asset list.
The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Unsupported Media Type
Internal Server Error
{ "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_2": "Value 2" }, "id": "6357fce0-41ef-433b-95ee-03ade01bd02d", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08.000Z", "last_updated_at": "2023-09-17T23:19:08.000Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } }
Searches for relationship types
Searches for relationship types using various criteria. The query parameters here provide filters for the relationship types that are returned in the result. If no query parameters are provided, the result will include all relationship types that are visible to your bss account. If an asset container is specified, the results are limited to relationship types where at least one end can be used with the specified asset container. This is the case if the relationship end either has no declared asset container (for example because the end references a global asset type or is untyped) or if the end has an asset container that is the same as the asset container specified. If a relname filter is specified, the results are limited to relationship types where at least one end has a relationship name in the list. In order to see relationship types where at least one end is in the container asset type(s), you must either belong to the container's BSS account or have at least editor permission on the container. All users have permission to see global relationship types.
Limit the relationship types based on the item types:
- If the
asset_typeis specified, the results are limited to relationship types where at least one end is either untyped or is in the specified asset type list. - If both
asset_typeandrelated_asset_typeare specified, the results are limited to relationship types where both ends are untyped, or where one end is in the specified asset type list and the other end has the specified asset type list. - If the
artifact_typeis specified, the results are limited to relationship types where at least one end is either untyped or is in the specified artifact type list. - If both
artifact_typeandrelated_asset_typeare specified, the results are limited to relationship types where both ends are untyped, or where one end is in the specified artifact type list and the other end has the specified asset type list. - If the
asset_typeorrelated_asset_typeis set to*#_column, the results are limited to relationship types where one end can be used with any supported column type (currently limited todata_assetcolumns) - If the item type is set to
*, the results are limited to relationship types where one end can be used with any asset type or any artifact type.
Note: In CP4D environments there is just one global bss account, so all relationship types are always visible to all users.
GET /v2/asset_relationship_types
Request
Query Parameters
Required when container_id is specified and the container is not a catalog. Specifies the type of the container (CATALOG/PROJECT/SPACE). Defaults to CATALOG.
Default:
CATALOGContainer ID. This limits results to relationship types that have an endpoint with the specified ID of a catalog, project, or space. If the container is a project or space, the container_type parameter must be also specified, otherwise container_id is treated as a catalog ID. This parameter is required when querying for relationship types associated with a catalog, project, or space. If this parameter is omitted, relationships types are not filtered by their container. Note that any type with an endpoint that has no container ID will also be included the result.
The parameter
type_nameis deprecated, please useasset_typeinsteadAsset Type Name(s). This limits the results to only relationship types that have an endpoint in the specified asset type list, or have an endpoint that is untyped.
Artifact Type Name(s). This limits the results to only relationship types that have an endpoint in the specified artifact type list, or have an endpoint that is untyped.
Related Asset Type Name(s). This parameter can only be set when either asset_type or artifact_type is also set.
When asset_type is set, this limits the results to only relationship types that have an endpoint with the specified asset type and the other endpoint with this specified asset type.
When artifact_type is set, this limits the results to only relationship types that have an endpoint with the specified artifact type and the other endpoint with this specified asset type.
limit to use when finding relationship types
Default:
25Optional bookmark to use when finding relationship types.
Relationship name(s). This limits the results to relationship types that have an endpoint with the specified name. The parameter should be repeated for each allowed relationship name.
Default display name(s). This limits the results to relationship types that have an endpoint with the specified name. The parameter should be repeated for each allowed relationship name.
Specifies the scope of the relationship types which can be (GLOBAL/BSS_ACCOUNT). If GLOBAL - it returns all types scoped to Global.If BSS_ACCOUNT - it returns all types scoped to BSS_ACCOUNT.If query parameter is omitted, it returns all.
If specified, the results are limited to relationship types that can be accessed by the specified BSS account. If
container_idis also specified, the catalog's BSS account must be the same as the BSS account specified here.If
bss_account_idis not specified and the API is called with an accredited service ID access token, then there is no filtering of the results based on BSS account.If
bss_account_idis not specified, and the API is called with a regular user (i.e. non-service ID) access token, then the result depends on whethercontainer_idis specified. Ifcontainer_idis specified, then the result includes global relationship types and account-scoped relationship types for the container's BSS account. Ifcontainer_idis not specified, then the result includes global relationship types, and account-scoped relationship types for all of the user's BSS accounts.
Creates an asset relationship type
Use this API to create an asset relationship type. The type definition consists of two endpoints which specify the two ends of a bidirectional relationship. The endpoints define the name of the relationship at each end, and the qualified asset type or the qualified artifact type that contains the relationship endpoint. The names of the relationships that can be used with any given asset type or artifact type are required to be unique. If the qualified asset type and the qualified artifact type are omitted, that end can be used with any asset type and any artifact type in any container.
Specifying the Type
The combination of container_type, container_id, and containing_asset_type(s) control what asset types can be used at each end of the relationship. The asset type can be a global asset type, an account-level asset type, a container-scoped asset type, or any asset type.
Global Asset Type
To define a relationship end for a global asset type, the containing_asset_type(s) field must be set to the name of the asset type and the container_id must be omitted. In this case, the relationship end can only be used with the specified global asset type. If the container_type field is set when using a global asset type, it is ignored.
Account Level Asset Type
To define a relationship end for an account-level asset type, the containing_asset_type(s) field must be set to the name of the asset type and the container_id must be omitted. In addition, the bss_account_id query parameter must be set to the bss account that owns the account-level asset type. In this case, the relationship end can only be used with the specified account-level asset type. If the container_type field is set when using an account-level asset type, it is ignored.
Container-Scoped Asset Type
The relationship mechanism allows relationship ends to be restricted to an asset type defined in a specific catalog, project, or space. To do this, the containing_asset_type(s), container_type, and container_id fields must all be set.
Artifact Type
To define a relationship end for an governance artifact type, the containing_artifact_type(s) field must be set to the name of the artifact type and the container_id must be omitted.
The on_delete field can only set to IGNORE on both ends
Column Type
To define a relationship end for a column type, the containing_asset_type(s) field must be set in the format of <asset_type>#_column.
When *#_column is specified, the relationship end can be used with any supported column type.
Currently, only data_asset columns are supported.
The on_delete field can only set to IGNORE on both ends
Any Type
To allow a relationship end to be used with any asset type, the containing_artifact_type(s), containing_asset_type(s) and container_id fields for the relationship end must be omitted. In this case, the relationship end can be used with any asset type, any artifact type, and any supported column type in any container. If the container_type field is set, it will be ignored.
Note: Cannot have containing_artifact_type(s) specified in both ends
Specifying the Relationship Type Scope
A relationship type can either be global or be scoped to a BSS account.
A relationship type can be explicitly scoped to a specific bss account using the bss_account_id query parameter. When a relationship type is scoped to a bss account, all specified asset containers and account-level asset types must belong to that bss account. If either endpoint for the relationship type has a specific asset container, the relationship type is automatically scoped to the bss account for the asset container. Account scoped relationship types can only be created if the user either belongs to the same bss account or is an administrator of all asset containers in the relationship type definition.
By default, if neither end of the relationship type specifies an asset container, the relationship type is created in the global scope and is accessible to all users. Only service ids with permission to create global asset types are allowed to create globally scoped relationship types. It is possible to scope a relationship type where neither end has an asset container to a specific BSS account. To do this, you must set the bss_account_id query parameter when creating the relationship type. The bss account must be set to a bss account that you have access to. In that case, the relationship type will be created, but its use will be restricted to asset containers associated with that bss account.
By default, on_delete is set to IGNORE if it is not specified
Note that in CP4D environments, there is only one bss account (999). As a result, in that context relationship types scoped to a specific BSS account are effectively global.
Cascading clone/publish/promote to Referenced Assets
The following flags control how related assets are processed when an asset is copied using the deepcopy endpoint
|Option |Allowed Value |Default |Description |
|-----------|----------------|----------|-----------------------------------------------------------------------------------------------------------|
|on_clone |CASCADE/IGNORE |IGNORE |If CASCADE, deepcopy from a catalog to a project causes the referenced assets to be copied as well |
|on_publish |CASCADE/IGNORE |IGNORE |If CASCADE, deepcopy from project to a catalog causes the referenced assets to be copied as well |
|on_promote |CASCADE/IGNORE |IGNORE |If CASCADE, deepcopy from a project to a space causes the referenced assets to be coped as well |
POST /v2/asset_relationship_types
Request
Query Parameters
This parameter forces the relationship type to be scoped to the specified bss account. It allows the creation of an account-scoped relationship type where both ends are either untyped, or are global asset types. It is required if the relationship type entity references any account-level asset types. An account-scoped relationship type is only visible to users in the BSS account for the relationship type. If the query parameter is unset, such relationships will be global in scope and can only be created if the user has permission to create a global asset type. Note: the BSS account can also be set via an impersonation header. If it is set in both places, the
bss_account_idquery parameter has precedence. This parameter is not required if either end of the relationship type has a catalog asset type. If it is set for a relationship type that has a catalog asset type, it must be the same as the BSS account for the catalog.
Relationship Type request body
First relationship type endpoint (order is not important)
- end1
Default display name for this end of the relationship. This is what will be shown in the UI.
Internal, non-translated, name for this end of the relationship. This becomes part of the path in the APIs for manipulating and querying relationship types.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Allowable values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Allowable values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Allowable values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Second relationship type endpoint (order is not important)
- end2
Default display name for this end of the relationship. This is what will be shown in the UI.
Internal, non-translated, name for this end of the relationship. This becomes part of the path in the APIs for manipulating and querying relationship types.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Allowable values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Allowable values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Allowable values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Set of flags. These flags determine the relationship type's behavior
- flags
Description of the relationship type
Response
relationship type metadata
- metadata
Unique ID of the relationship type
ID of the user that created the relationship type
Creation timestamp in milliseconds
Creation timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
Update timestamp in milliseconds
Update timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
ID of the user that updated the relationship type
Tenancy of the relationship type
- tenancy
Possible values: [
GLOBAL,BSS_ACCOUNT]
relationship type entity
- entity
First relationship type endpoint (order is not important)
- end1
Default display name for this end of the relationship. This is what will be shown in the UI.
Internal, non-translated, name for this end of the relationship. This becomes part of the path in the APIs for manipulating and querying relationship types.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Second relationship type endpoint (order is not important)
- end2
Default display name for this end of the relationship. This is what will be shown in the UI.
Internal, non-translated, name for this end of the relationship. This becomes part of the path in the APIs for manipulating and querying relationship types.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Set of flags. These flags determine the relationship type's behavior
- flags
Description of the relationship type
Status Code
Created
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Request
No Sample Response
Searches for relationship type ends
Find relationship type ends that can be used with an asset type or artifact type. This API supports finding relationship type ends that use global or catalog asset types.
For an asset type:
- set
asset_type. This parameter should be repeated for each allowed asset type - All asset types in the list must either be global/account level asset types or be scoped to the asset container specified by the
catalog_id,project_id, orspace_id.
For a column type:
- set
asset_typeas<asset_type>#_column - if
asset_typeis specific to a container (catalog, space, or project), then set a container ID parameter as appropriate (catalog_id,space_id,project_id).
For a governance artifact type:
- set
artifact_type. This parameter should be repeated for each allowed artifact type
POST /v2/asset_relationship_types/search_ends
Request
Query Parameters
catalog_id. If no container parameters are set, any asset container the user has access to are allowed.
project_id. If no container parameters are set, any asset containers the user has access to are allowed.
space_id. If no container parameters are set, any asset containers the user has access to are allowed.
asset_type(s). This specifies the asset type(s) whose relationship type ends should be found. This parameter should be repeated for each allowed asset type.
artifact_type(s). This specifies the artifact type(s) whose relationship type ends should be found. This parameter should be repeated for each allowed artifact type.
end_types. This filters the result to only include relationship type ends of the specified type(s) - valid filter values are {ASSET, ARTIFACT, COLUMN}. If this parameter is not specified, all relationship ends that match other criteria will be returned.
Optional limit to use when finding relationship type ends
Default:
25Optional bookmark to use when finding relationship type ends.
orderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported sort fields (these are case insensitive):
- relationship_name_asc
- relationship_name_desc
- relationship_display_name_asc
- relationship_display_name_desc
- create_time_asc
- create_time_desc
Default:
relationship_display_name_ascLimits results to only include the specified relationships. By default, all relationship type ends which match the other search criteria are included. Repeat the query parameter to specify multiple relationship names.
Response
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Finds relationship types that are used by an asset, column or governance artifact
Finds relationship types that are used by an asset, column or a governance artifact. This API only returns the first page of results. It does not accept a bookmark. Any additional pages of results must be fetched using the next page url included in the response.
You can refer to the options in the response to get the full list of relationship names.
POST /v2/asset_relationship_types/search_used_ends
Request
Query Parameters
Catalog ID
Project ID
Space ID
Asset ID
Artifact ID
Artifact Type
Optional limit to use when finding relationship types
Default:
25Includes a list of the related asset types and artifact types in the result. This option adds overhead, so enable it only if the related type information is needed.
Default:
falseorderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported sort fields (these are case insensitive):
- relationship_name_asc
- relationship_name_desc
- relationship_display_name_asc
- relationship_display_name_desc
- create_time_asc
- create_time_desc
Default:
relationship_display_name_asc
Response
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Patches a relationship type
Updates an existing relationship type. The patch body must be an array of json patch operations as defined in RFC 6902.
The following fields can be patched in each relationship type endpoint:
default_display_name(value can be changed but not removed)localized_display_name(values can be added, changed, and removed)on_delete(value can be added, removed, or deleted)
Relationship types where at least one endpoint is a catalog asset type can be patched either by an admin member of the catalog, or by a user in the catalog's BSS account. Global relationship types can only be patched by a user with permission to create global asset types.
It is important to note that the patch specifies updates to apply the current json representation of the relationship types. When specifying an add/replace/remove patch operation, all of parent elements in the path must already exist. In particular, if the
relationship type endpoint was originally created without a localized_display_name element, that element needs to be created by the patch operations.
Here are some examples of patches that can be applied:
Add a display name to an endpoint without an existing localized_display_name element:
[
{
"op": "add",
"path": "/end2/localized_display_name",
"value": {"
"en-us": "English Display Name"
}
}
]
Add a display name to an endpoint with an existing localized_display_name element:
[
{
"op": "add",
"path": "/end2/localized_display_name/en-gb",
"value": "British Display Name",
}
]
Change localized display name for en-gb in end2:"
[
{
"op": "replace",
"path": "/end2/localized_display_name/en-gb",
"value": "New British Display Name"
}
]
Remove localized display name for en-gb rom end1:
[
{
"op": "remove",
"path": "/end1/localized_display_name/en-gb"
}
]
Add a relationship option override, replace an existing relationship option override, delete an existing relationship option override:
[
{
"op": "add",
"path": "/end1/option_overrides/-",
"value": {
"this_asset_type": "ibm_bi_report",
"other_asset_type": "ibm_bi_report_query",
"on_delete": "CASCADE",
"on_publish": "IGNORE",
"on_promote": "CASCADE",
"on_clone": "IGNORE"
}
},
{
"op": "replace",
"path": "/end1/option_overrides/1/on_delete",
"value": "CASCADE"
},
{
"op": "add",
"path": "/end1/option_overrides/1/on_promote",
"value": "IGNORE"
},
{
"op": "remove",
"path": "/end1/option_overrides/1/on_promote"
}
[
PATCH /v2/asset_relationship_types/{relationship_type_id}Request
Path Parameters
relationship_type_id
JSON array of patch operations as defined in RFC 6902.
Note: Any ‘~’ characters need to be escaped as ~0 in the path field.
Any ‘/’ characters need to be escaped as ~1 in the path field.
For example, in `{"foo/" : {"~bar" : "value"}}`, the path for `"~bar"` is `"/foo~1/~0bar"`.
[
{
"op": "replace",
"path": "/end2/default_display_name",
"value": "new end2 display name"
},
{
"op": "replace",
"path": "/end1/default_display_name",
"value": "new end1 display name"
},
{
"op": "add",
"path": "/flags/use_for_lineage_traversal",
"value": "true or false"
},
{
"op": "add",
"path": "flags/copy_to_knowledge_graph",
"value": "true or false"
}
]
Response
relationship type metadata
- metadata
Unique ID of the relationship type
ID of the user that created the relationship type
Creation timestamp in milliseconds
Creation timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
Update timestamp in milliseconds
Update timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
ID of the user that updated the relationship type
Tenancy of the relationship type
- tenancy
Possible values: [
GLOBAL,BSS_ACCOUNT]
relationship type entity
- entity
First relationship type endpoint (order is not important)
- end1
Default display name for this end of the relationship. This is what will be shown in the UI.
Internal, non-translated, name for this end of the relationship. This becomes part of the path in the APIs for manipulating and querying relationship types.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Second relationship type endpoint (order is not important)
- end2
Default display name for this end of the relationship. This is what will be shown in the UI.
Internal, non-translated, name for this end of the relationship. This becomes part of the path in the APIs for manipulating and querying relationship types.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Set of flags. These flags determine the relationship type's behavior
- flags
Description of the relationship type
Status Code
Relationship type was successfully patched
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
List all asset types defined for an account, catalog, project or space.
Get all asset types in an account, catalog, project or space. Custom properties added/updated at the account level asset types can only be fetched if bss_account_id parameter is passed
GET /v2/asset_types
Request
Query Parameters
This parameter allows retrieving catalog-scoped asset types. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving project-scoped asset types. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving space-scoped asset types. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving account-scoped asset types. May be different than account of user specified in Bearer token. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows to retrieve asset types which can be decorated. You can provide either a true or a false.
Default:
FALSEThis parameter allows to retrieve asset types which can be used only as attributes and are user defined. You can provide either a true or a false. At a time, either permits_decorators or custom_attributes can be true.
Default:
FALSELanguage code, such as default, en, etc.
Creates an asset type in an account, catalog, project or space.
Creates an asset type in account, catalog, project or space.
POST /v2/asset_types
Request
Query Parameters
This parameter allows the creation of a catalog-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows the creation of a project-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows the creation of a space-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows the creation of an account-scoped asset type. May be different than account of user specified in Bearer token. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
Asset Type request body
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Allowable values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Allowable values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1
Response
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Possible values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1The scope of defined asset type. Derived-field. Will be one of GLOBAL, ACCOUNT, CATALOG, PROJECT, or SPACE.
Example:
GLOBALList of pointers to types this type can be decorated by.
Status Code
Created
Accepted - indicates the asset type creation is being completed in the background
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Request
No Sample Response
Retrieves an asset type of a given name.
Retrieves an asset type of a given name. Custom properties added/updated at the account level asset types can only be fetched if bss_account_id parameter is passed
GET /v2/asset_types/{type_name}Request
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
This parameter allows retrieving a catalog-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving a project-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving a space-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving an account-scoped asset type. May be different than account of user specified in Bearer token. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
Language code, such as default, en, etc.
This parameter can have one or more values as below:
- GLOBAL - return asset type in global scope
- BSS_ACCOUNT - return asset type in account scope
- CONTAINER - return asset type in catalog/ project/ space scope
If no value is provided, the default value is taken as null, and the asset type with the highest search scope is returned. A combination of more than one search scope is also valid. In this case, an asset type with the highest search scope from the given scopes will be returned.
Response
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Possible values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1The scope of defined asset type. Derived-field. Will be one of GLOBAL, ACCOUNT, CATALOG, PROJECT, or SPACE.
Example:
GLOBALList of pointers to types this type can be decorated by.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
No Sample Response
Replace an asset type
Replace asset attributes for the given asset type or create a new asset type if the given asset type does not exist.
PUT /v2/asset_types/{type_name}Request
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
This parameter allows creating or updating a catalog-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows creating or updating a project-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows creating or updating a space-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows creating or updating an account-scoped asset type. May be different than account of user specified in Bearer token. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
Asset Type request body
Fields that are indexed if present in the asset.
Asset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Allowable values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Allowable values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
Response
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Possible values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1The scope of defined asset type. Derived-field. Will be one of GLOBAL, ACCOUNT, CATALOG, PROJECT, or SPACE.
Example:
GLOBALList of pointers to types this type can be decorated by.
Status Code
OK
Accepted
Bad Request
Unauthorized
Forbidden
Not Found
Conflict
Too Many Request
Internal Server Error
No Sample Response
Deletes an asset type
Deletes an asset type in given account or container. Note that, deletion of an account scope asset type or a container scope asset type triggers background clean up of assets:
- Assets of this type are deleted.
- And in case of other assets, attributes of this type are removed.
DELETE /v2/asset_types/{type_name}Request
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
This parameter allows creating or updating a catalog-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows creating or updating a project-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows creating or updating a space-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows creating or updating an account-scoped asset type. May be different than account of user specified in Bearer token. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
Finds relationship types for an asset type
Finds relationship types that originate from a given asset type. This API supports limiting the results to a specific set of relationship types as well as providing pagination and sorting options. It also supports finding relationship types that use both global and catalog asset types.
This API is deprecated - use POST /v2/asset_relationship_types/search_ends instead
GET /v2/asset_types/{type_name}/relationshipsRequest
Path Parameters
type_name. This specifies the asset type whose relationships should be found.
Query Parameters
catalog_id. If set, this restricts catalog asset types in the result to the given catalog. If no container parameters are set, any asset container the user has access to are allowed.
catalog_id. If set, this restricts catalog asset types in the result to the given project. If no container parameters are set, any asset containers the user has access to are allowed.
catalog_id. If set, this restricts catalog asset types in the result to the given space. If no container parameters are set, any asset containers the user has access to are allowed.
Optional limit to use when finding relationship types
Default:
25Optional bookmark to use when finding relationship types.
orderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported sort fields (these are case insensitive):
- relationship_name_asc
- relationship_name_desc
- relationship_display_name_asc
- relationship_display_name_desc
- create_time_asc
- create_time_desc
Default:
relationship_display_name_ascLimits results to only include the specified relationships. By default, all relationship types for the asset type are included. Repeat the query parameter to specify multiple relationship names.
Response
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Search for asset metadata within assets of the specified type
Use this API to search for assets of the generic asset type (asset) or any specific asset type in a Catalog, Space, or Project.
The request body must contain a query field, which specifies a Lucene query to search for assets on indexed fields.
See Searchable Asset and Attachment Fields below for the list of fields that can be searched in the query.
If query contains no selection criteria ("*:*"), then the result includes all assets that are instances of the type specified in the type_name path parameter,
including assets whose primary asset type (i.e. its metadata.asset_type value) is that type, and assets that have an attribute of that type.
To filter out assets whose primary type does not match the type_name parameter, the query must include an asset.asset_type:{type_name} predicate.
The query results can be sorted by specifying a sort field in the request with format field<sort_type>. The sort_type can be either number or string (e.g. "sort" : "asset.name<string>").
Search With Pagination
The limit request body field can be specified to limit the number of assets in the search results.
The default limit is 200. The maximum limit value is 200, and any greater value is ignored.
Sample Request Body:
{
"query" : "asset.name:Asset*",
"limit" : 2,
"sort" : "asset.name<string>"
}
Response:
{
"next": {
"bookmark": "g1AAAXXXXXXXX",
"query" : "asset.name:Asset*",
"limit" : 2,
"sort" : "asset.name<string>"
},
"results": [
{
..asset 1...
},
{
..asset 2...
}
],
"total_rows": 3
}
When more search results are available, then the response will contain a next JSON object - next contains bookmark along with original query which needs to be returned
to retrieve the next page of results. To paginate through the entire result set, the request should be re-executed with the bookmark from the next.bookmark value of the
previous response until there is no next object in the response (note that this response may contain an empty results array).
Sample request body to get the next page of results:
{
"bookmark": "g1AAAXXXXXXXX",
"query" : "asset.name:Asset*",
"limit" : 2,
"sort" : "asset.name<string>"
}
Searchable Asset and Attachment Fields
The following asset and attachment fields can be searched in the query - note that type <string> or <number> only needs to be added for use in the sort request field:
asset.asset_attributes<string>
asset.asset_category<string>
asset.asset_state<string>
asset.asset_type<string>
asset.catalog_id<string>
asset.created_at<string>
asset.delete_timestamp<string>
asset.description<string>
asset.memberIds<string>
asset.editor_id<string>
asset.viewer_id<string>
asset.member_or_owner_id<string>
asset.memberGroupIds<string>
asset.editor_group_id<string>
asset.viewer_group_id<string>
asset.member_or_owner_group_id<string>
asset.mode<number>
asset.name<string>
asset.owner_id<string>
asset.owner_group_id<string>
asset.project_id<string>
asset.rating<number>
asset.resource_key<string>
asset.identity_key<string>
asset.source_asset_id<string>
asset.source_catalog_id<string>
asset.source_project_id<string>
asset.source_space_id<string>
asset.source_system<string>
asset.source_system_asset_id<string>
asset.source_system_created_at<string>
asset.source_system_id<string>
asset.source_history_asset_id<string>
asset.source_history_system_id<string>
asset.space_id<string>
asset.tags<string>
attachment.connection_id<string>
attachment.connection_path<string>
attachment.name<string>
attachment.object_key<string>
POST /v2/asset_types/{type_name}/searchRequest
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseThe parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Search Criteria. The "include" field in the request body is a list of asset sections to include in the search results, values are comma-separated and the supported values are "entity" or "entity,attachments".
Lucene query
Example:
*:*Returns the number of query results for each unique value of each named field.
Examples:[ "asset.tags", "asset.asset_type" ]Restrict results to documents with a dimension equal to the specified label. Note that, multiple values for a single key in a drilldown means an OR relation between them and there is an AND relation between multiple keys.
Examples:[ { "asset.tags": [ "tag1", "untagged" ], "asset.asset_type": [ "data_asset", "job" ] } ]- drilldown
Bookmark of the query result
Sort order for the query
Example:
asset.name<string>entity
Example:
entity
Get the status of an account scope or global scope asset type.
Retrieves an account scope or global scope status, If bss_account_id is not provided, api will try to retreive status of an asset type at global level if present.
GET /v2/asset_types/{type_name}/statusCreate an asset
Use this API to create an asset in catalog or project. Assets contain information about the contents of your data and how to access the data. You store asset metadata in a catalog and add collaborators from your organization to analyze data. Your data can reside in a variety of sources. For example, you can keep your data in your existing on-premises data sources, cloud data services, or streaming data feeds. By adding connection information to these remote sources in the catalog, you can allow other catalog users to access the data with the stored credentials. Alternatively, you can copy a snapshot of the remote data into the catalog's encrypted cloud storage.
All asset types have a common set of properties. Some asset types have additional properties.
When you add an asset to a catalog, you specify these common properties:
- The asset name and an optional description. The name can only contain letters, numbers, underscore, dash, space, and period. The name can't be only blank spaces.
- Privacy. You can choose to restrict access to the asset with the privacy level and asset membership.
- Public = Default. No restrictions on finding or using the asset.
- Private = Only asset members can find or use the asset.
- Members. The catalog collaborators can be added as members of the asset. Members are important if you restrict access to the asset. When you create an asset, you are the owner (and implicitly a member) of it. Members can be set in metadata/rov/collaborator_ids or metadata/rov/member_roles, but not both. Members set in metadata/rov/member_roles are given an explicit set of roles. Members can have up to two roles: OWNER and either EDITOR or VIEWER. Only service ids can assign the OWNER role. The request to add the OWNER role is ignored for other callers. Asset members with the EDITOR or VIEWER role must also be members of the catalog. Members set in metadata/rov/collaborator_ids are automatically assigned a role based on their role in the catalog.
- Tags. Metadata that makes searching for the asset easier. Tags can contain only letters, numbers, underscores, dashes, and the symbols # and @.
POST /v2/assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Asset metadata
- Examples:
{ "data_asset": { "mime_type": "text/csv", "dataset": false } }- entity
AssetMetadata Model
Get one or more assets.
Use this API to retrieve one or more assets located in catalog or project or space. Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Governance. Data assets in ungoverned catalogs are not subject to governance policies.
Response includes, for each asset, asset ID, status, HTTP status and, if no errors, asset details & relationship count or list of errors. For example:
{
"resources":[
{
"asset_id":"cf38d92c-eb55-462e-89bf-cdb9fe67f0b7",
"status":"success",
"http_status":200,
"asset":{...},
"relationship_count":2
},
{
"asset_id":"c6650020-3176-4d67-8fbe-5a19ba1c2c7e",
"status":"failed",
"http_status":404,
"errors":[
...
]
},
...
]
}
GET /v2/assets/bulk
Request
Query Parameters
Comma separated list of asset IDs; maximum of 20. For assets with revisions, an optional revision number can be specified using colon character in the form of '<asset id>:<revision>,<asset id>,...'. Revision numbers are non-zero positive numbers likes 1, 2, 3 etc.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseWhether to include per-asset relationship count. Note: The default will be changed to 'false' in a later release.
Default:
trueWhether to include relationships where source end is a column of the source asset in the asset's relationship counter.
Default:
false
Marks existing assets for delete
Use this API to delete assets. You can delete an asset if you are the owner of the asset or a member of the asset with Admin or Editor permissions on the catalog or project or space.
Purge Options to Delete Assets
purge_on_delete = true and purge_after_days is not specified: the asset is purged immediately. purge_on_delete = true and purge_after_days = n: the asset is moved to trash and purged after n days. purge_on_delete = false and purge_after_days is not specified: the asset is moved to trash and never purged. purge_on_delete is not specified and purge_after_days is not specified: the asset will be deleted/purged based on the catalog setting. purge_on_delete = false or is not specified and purge_after_days = n: invalid combination - the call will fail with a 400 Bad Request error.
DELETE /v2/assets/bulk
Request
Query Parameters
Comma separated list of asset IDs; maximum of 20.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
If true, asset is also deleted from the trash.
Default:
falseNumber of days after which asset will be purged. Purge On Delete should be true for this to be valid
Get assets membership for a specific user
Returns any memberships this user has on assets, including direct membership and any access group memberships.
GET /v2/assets/bulk/members/{member_id}Request
Path Parameters
member_id
Query Parameters
Comma separated list of asset IDs; maximum of 25.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Should resolve member roles from usergroup(s) and collaborator roles
Default:
falseType of the member specified by the member_id. If not specified, the service will determine if the member is a user or an access group based on the member_id, which is not always possible or accurate. Always supplying the member type is recommended.
Allowable values: [
user,group]IAM Profile ID for Trusted Profile users: If the getMemberForAssetV2 API is called to fetch details for a Trusted Profile, the member_id is the IAM ID of the actual user, and the profile_id will be the IAM ID of the trusted user. For IBM users and App ID users, this value should be null.
Copies one or more assets and, if deep copy option is on, their related assets from a source container to a target container.
Use this API to publish one or more assets from a project to a catalog or promote from a project to a space. This API can also be used to clone one or more assets from a catalog to a project. The default maximum number of assets in a request is 50.
Copy sends the same Rabbit MQ messages as publish, promote or clone. Messages are sent for all assets that are copied.
This API supports using a refresh token in place of an access token. This can be helpful if the copy is expected to be a long running operation. The copy operation uses the access token to authenticate with other services, so it is important that it not expire while the operation is in progress. When a refresh token is specified, it is used to generate an initial access token as well as additional access tokens if the initial access token expires
POST /v2/assets/bulk_copy
Request
Query Parameters
Source catalog ID. Only one of either catalog ID or project ID must be provided.
Source project ID. Only one of either catalog ID or project ID must be provided.
Determines if the copy operation should be cascaded to referenced assets. Referenced assets are determined using bidirectional external relationships and as well as in-line relationships. In-line relationship types are defined as part of asset type definitions. Cascading happens only if
CASCADEis set for the following relationship type property:on_clone, in case of copying from catalog to project,on_publish, in case of copying from project to catalog andon_promote, in case of copying from project to space.
Default:
falseWhether to automatically copy connections in remote attachments
Default:
trueAction to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Request body should include target container ID and list of assets with metadata overrides, and may include asset permissions override. Target container ID should be either that of a catalog (publish) or of a space (promote) if source conatiner is a project, or that of a project (clone) if source is a catalog. Example:
{
"catalog_id": "string",
"rov_mode": "integer",
"member_roles": {
"Member's IAM ID": {
"user_iam_id": "Member's IAM ID",
"roles": ["EDITOR"]
},
"Access Group ID": {
"access_group_id": "Access Group ID",
"roles": ["VIEWER"]
},
"Another IAM ID": {
...
}
},
"copy_configurations":[
{
"asset_id": "string",
"revision_id": "string",
"metadata_overrides": {
"name":"string", "description":"string", "tags":["string","string"]
}
},
...
]
}
Fields 'rov_mode' and 'member_roles' are optional.
- If specified, they apply to all newly copied (target) assets.
- If not supplied, newly copied asset gets mode and 'member_roles' from its corresponding source asset.
- Valid values for 'rov_mode' are 0 (public), 8 (private) and 16 (hidden).
- If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
- If supplied, 'member_roles' should include at least one OWNER role.
The 'metadata_overrides' field is optional and may contain attributes to overwrite the values in original asset. Currently only name, description and tags can be overriden. If specified 'metadata_overrides' cannot be empty and only applies to respective root asset.
Any cross-referenced asset is copied only once.
To assign owners and other collaborators on newly copied target assets.
- member_roles
Response
Possible values: [
WAITING,IN_PROGRESS,COMPLETED,FAILED]
Status Code
OK - indicates the copy operation has completed - assets and its related assets (if applicable) have been fully copied to the target catalog.
Accepted - indicates that the copy request is being completed in the background.
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Create one or more assets.
Use this API to create one or more assets in a catalog or a project or a space. The default maximum number of assets in a request is 20. Example of request (POST) data:
{
"assets":[
{
"name":"<Name of the first asset>",
"description":"<Description of the first asset>",
"tags":["<Tag 1>", "<Tag 2>", ...],
"asset_type":"<Asset type such as "connection", "data_asset", etc.>",
"entity":{
...
}
"attachments":{
...
}
},
{
"name":"<Name of the second asset>",
...
},
...
]
}
Response includes, for each asset in the request and in the same order, details of newly created asset or details of updated asset if a duplicate/match is found or errors if any:
{
"trace":"<Trace ID, if failed to create or update one or more assets>",
"responses":[
{
"http_status":201,
"asset":{...}
},
{
"http_status":400,
"errors":[
...
]
},
...
]
}
POST /v2/assets/bulk_create
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
JSON containing list of assets to be created.
Asset Model
Patch one or more assets.
Use this API to patch one or more assets in catalog or project or space. The default maximum number of assets in a request is 20.
The API supports the following operations:
- Patching of allowed metadata properties. See
PATCH /v2/assets/{asset_id}API for list of allowed metadata properties that can be patched." - Add, update and delete of attributes such as
asset_terms,data_profile, etc." - Create, update and delete of attachments:
- The (asset)
attachmentsfield is an array and the index of the first attachment is 0, the index of the second one is 1 and so on. Adding or deleting an attachment shifts indexes of any attachments that follow it. - A newly created attachment is added at the specified location. If the
pathis/attachments/-then it will be added at the end. - Newly added attachment cannot be updated or deleted (in the same API call). And, newly updated attachment cannot be deleted.
- Some of the new attachment fields like
attachment_id,url1,url2, etc. are only included in the response the first time when the attachments are created. - Only the following attachment fields can be updated:
name,description,mime,size,partitionsandtransfer_complete.
- The (asset)
The API does not support patching of whole metadata, entity and attachments.
- i.e. The
pathcannot be the following values:/metadata,/entityor/attachments.
Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Governance. Data assets in ungoverned catalogs are not subject to governance policies.
Note: Patch 'operations' should conform to RFC 6902 specification.
Example of request (POST) data:
{
"resources": [
{
"asset_id": "cf38d92c-eb55-462e-89bf-cdb9fe67f0b7",
"operations": [
{
"op": "add",
"path": "/metadata/description",
"value": "Four score and seven years ago..."
},
{
"op": "add",
"path": "/entity/data_asset/mime_type",
"value": "text/csv"
},
{
"op": "replace",
"path": "/attachments/1/name",
"value": "New name for the 2nd attachment."
},
{
"op": "remove",
"path": "/attachments/0"
}
{
"op":"add",
"path":"/attachments/-",
"value":{...}
},
{
"op":"replace",
"path":"/attachments/1/name",
"value":"New name for the 2nd attachment."
},
{
"op":"add",
"path":"/attachments/2",
"value":{...}
},
]
},
{
"asset_id":"c6650020-3176-4d67-8fbe-5a19ba1c2c7e",
"operations": [
...
]
},
...
]
}
Response includes, for each asset, asset ID, status and updated version or errors, if any:
{
"resources": [
{
"asset_id": "cf38d92c-eb55-462e-89bf-cdb9fe67f0b7",
"status": 200,
"http_status": 200,
"asset": {
...
}
},
{
"asset_id": "c6650020-3176-4d67-8fbe-5a19ba1c2c7e",
"status": 404,
"http_status": 404,
"errors": [
...
]
},
...
]
}
Currently the API allows to patch up to twenty (20) assets. There is no limit on number of patch instructions. Any number of (allowed) metadata properties and/or attributes can be:
- modified,
- new ones added,
- existing ones be replaced or
- deleted
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Note: Any
~characters need to be escaped as~0in the path field
Any / characters need to be escaped as ~1 in the path field
For example, in {"foo/: {"~bar: "value"}}, the path for ~bar is /foo~1/~0bar
POST /v2/assets/bulk_patch
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
JSON containing per-asset updates/patches.
Gets the status of asset copy operation
For large deep copies, portions of the copy operation are performed in the background. This API provides a way to get the status of the background processing. It also provides additional details about deep copy operations that have already been completed.
Similar to /v2/assets/deepcopy/{deep_copy_task_id} API but response can support completion details of multiple source assets.
Note: The status of completed copy operations is only available for 24 hours.
GET /v2/assets/copy_status/{copy_task_id}Create a PUT signed url for an object or a file
Use this API to create a PUT signed url to an object or a file in the catalog/project/space bucket/storage.
You must specify both name and asset_type (to create a new object or a file) OR the asset_id (to overwrite an existing object or a file) in the request.
You must specify one of these -- catalog_id, project_id or the space_id as a query parameter.
Details:
- No new meta-data (asset_id) is created or updated for this request.
- Only the PUT signed url is returned for the object or the file.
- If the asset_id is given in the request, a PUT signed url is returned for that asset's attachment's object/file, if the object/file is stored in the catalog/project/space bucket/storage. If the asset_type is given, the object/file from the first attachment with that asset_type is the one for which the PUT signed url will be returned. If the asset_type is not given, then, the asset's asset_type, then the "data_asset", will be used to find the attachment with the object/file.
- If the asset_id is not given in the request, and asset_type and name are specified, a PUT signed url is returned for an object_key where the object_key value is created using the combination of asset_type, sanitized name, and a random string.
- The name in the request can only contain letters, numbers, underscore, dash, space, and period -- same requirements as the attachment name.
- The value of expires_in is in seconds. The default value of expires_in is 604800 (7 days). Given a value of 0, the default value will be applied. The max value is the same as the default value; if a value larger than the max value is input, the max value will be used.
POST /v2/assets/create_object_url
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
object_url request
Gets the status of a deep copy operation
For large deep copies, portions of the copy operation are performed in the background. This API provides a way to get the status of the background processing. It also provides additional details about deep copy operations that have already been completed.
Note: The status of completed deep copy operations is only available for 24 hours.
GET /v2/assets/deepcopy/{deep_copy_task_id}Bulk search duplicate assets
Use this API to search for duplicate assets of an array of assets in the target catalog, project, or space. The maximum number of assets in a request is 20.
Each asset in the request can either be an existing asset, or an asset object that is the same as the user would provide for creating a new asset. E.g.,
{
"resources":[
{
"asset": {
"metadata": {},
"entity": {}
}
},
{
"project_id": "6f79ff7d-9227-4cba-81e7-726db8984d16",
"asset_id": "faad7530-4a30-41da-ac27-d3a0f07b2070"
},
{
"asset": {
"metadata": {},
"entity": {}
}
}
]
}
The response contains an array of duplicate search results. The index of the results in the array is the same as the index of the corresponding asset in the request array. Each result can be a success or failure depending on the corresponding request asset. E.g.,
{
"trace":"32s0wywr3wdqpsn86b4cfzb4i",
"resources":[
{
"http_status": 200,
"total_count": 1,
"best_updatable_duplicate_asset_id": "b81c84f5-a551-43bb-9a6e-c8e7820995f9",
"results": [
{
"asset_id": "b81c84f5-a551-43bb-9a6e-c8e7820995f9",
"highest_match_score": {},
"asset": {
"metadata": {},
"entity": {}
}
}
]
},
{
"http_status": 404,
"errors": [
{
"code": "does_not_exist",
"message": "ATTSV3024E: There is no asset with an ID of 'faad7530-4a30-41da-ac27-d3a0f07b2070' in a project with an ID of '6f79ff7d-9227-4cba-81e7-726db8984d16' ."
}
]
},
{
"http_status": 200,
"total_count": 0,
"results": [
]
}
]
}
The response of each requested item contains a http_status field that can be used to determine if the specific request was successful or not. If a request failed, the corresponding response will contain a field errors indicating the cause of the failure. For detail explaination of other fields in the request and response of each item, please refer to the POST /v2/assets/duplicates/search endpoint.
POST /v2/assets/duplicates/bulk_search
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
The maximum number of items to return for each requested asset
Default:
100
The assets to search for duplicate assets.
the assets to search duplicates for
Search duplicate assets
Use this API to search for duplicate assets of an asset in the target catalog, project, or space.
Users can provide an existing asset like below to search for duplicate assets of the given asset in the target asset container. The authenticated user needs to have the read access to the specified asset.
{
"project_id": "6f79ff7d-9227-4cba-81e7-726db8984d16",
"asset_id": "faad7530-4a30-41da-ac27-d3a0f07b2070"
}
Or provide an asset object to search for duplicate assets of the given asset payload in the target asset container. The asset payload is the same as the user would provide for creating a new asset.
{
"asset": {
"metadata": {},
"entity": {}
}
}
The query parameter limit can be used to limit the number of duplicates in the response. If not supplied, the maximum allowed value 100 is used. Note that the API does not support paignation as users usually only care about top x number of duplicates instead of all duplicates. If they do, they can always use a large limit to retrieve all duplicates. There number of the duplicates of any given asset should be far less than the maximum allowed value of the parameter limit. The system would become unusable long before the number of duplicates reaches that value.
The duplicate assets in the response are ordered by the matching score from high to low. The higher the matching score, the more certain that the asset is a duplicate of the incoming asset.
The total_count indicates the total number of duplicates of the given asset. This is useful in case the total number of duplicates is greater than the specified limit.
The best_updatable_duplicate_asset_id indicates the highest ranking duplicate asset that can be updated by the authenticated user. This duplicate asset would be updated/replaced if the incoming asset were to be added in the target asset container and the effective duplicate_action were UPDATE/REPLACE. If duplicates are found but this field doesn't have a value, it indicates that the authenticated user doesn't have permission to update any of the duplicates. In such a case, if the incoming asset were to be added in the target asset container and the effective duplicate_action were UPDATE/REPLACE, the transaction would fail.
POST /v2/assets/duplicates/search
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
The maximum number of items to return
Default:
100Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Supply either an existing asset or an asset payload to search for duplicate assets.
Id of the catalog the existing asset resides in. You must provide either a catalog id, a project id, or a space id, but not more than one
Example:
b81c84f5-a551-43bb-9a6e-c8e7820995f9Id of the project the existing asset resides in. You must provide either a catalog id, a project id, or a space id, but not more than one
Example:
814bc4e9-a8e6-4a02-9fb8-096211f09fb5Id of the space the existing asset resides in. You must provide either a catalog id, a project id, or a space id, but not more than one
Example:
21a374d0-9d04-48d5-884b-0f6cbfc67779Id of the existing asset
Example:
c43efbc1-7a65-44b8-bc40-c59f008716a8Revision of the existing asset
Example:
1,2,...,latestThe asset payload, which is the same as the user would provide for creating a new asset.
- asset
- Examples:
{ "data_asset": { "mime_type": "text/csv", "dataset": false } }- entity
AssetMetadata Model
Response
List of matching duplicate assets
The id of the best updatable duplicate asset that would be chosen for updating/overwriting in a real persistence transaction. It is possible that there are matching duplicate assets but this field is null, which indicates the caller does not have permission to update/replace any of the matching duplicate assets
Example:
b81c84f5-a551-43bb-9a6e-c8e7820995f9Total number of duplicates
Example:
1
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
Get an ibm_data_source asset
Use this API to get an ibm_data_source asset with provided endpoint or physical_collection. There is only one ibm_data_source asset that meets the specified parameters. Currently we only support the following three query methods:
- host + port, the host is either ipV4 or ipV6 or a DNS name
- host + port + physical_collection
- physical_collection
GET /v2/assets/ibm_data_source
Request
Query Parameters
Catalog GUID or UID
the bss_account_id
It can be database, project_id or bucket
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Publish an asset from a project which is only referenced in that project
Use this API to publish an asset whose only metadata are only in project as reference to a target catalog. Assets contain information about the contents of your data and how to access the data. You store asset metadata in a catalog and add collaborators from your organization to analyze data. Your data can reside in a variety of sources. For example, you can keep your data in your existing on-premises data sources, cloud data services, or streaming data feeds. By adding connection information to these remote sources in the catalog, you can allow other catalog users to access the data with the stored credentials. Alternatively, you can copy a snapshot of the remote data into the catalog's encrypted cloud storage.
All asset types have a common set of properties. Some asset types have additional properties.
When you add an asset to a catalog, you specify these common properties:
- The asset name and an optional description. The name can only contain letters, numbers, underscore, dash, space, and period. The name can't be only blank spaces.
- Privacy. You can choose to restrict access to the asset with the privacy level and asset membership.
- Public = Default. No restrictions on finding or using the asset.
- Private = Only asset members can find or use the asset.
- Members. The catalog collaborators can be added as members of the asset. Members are important if you restrict access to the asset. When you create an asset, you are the owner (and a member) of it.
- Tags. Metadata that makes searching for the asset easier. Tags can contain only letters, numbers, underscores, dashes, and the symbols # and @.
POST /v2/assets/publish
Request
Query Parameters
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Asset metadata
Publish Asset Metadata
- entity
Get an asset
Use this API to retrieve an asset located in catalog or project. Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Catalog. Data assets in ungoverned catalogs are not subject to governance policies.
GET /v2/assets/{asset_id}Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Marks an existing asset for delete
Use this API to delete an existing asset.
Permissions Required to Delete an Asset
To delete an asset in a project or space, all of the following must hold:
- Caller must have the EDITOR or ADMIN role in the project/space
To delete a public asset in a catalog, any of the following must hold:
- Caller must have the ADMIN role in the catalog
- Caller must have the EDITOR role in the catalog and caller must have either the OWNER or EDITOR role on the asset
To delete a private asset in a catalog, all of the following must hold:
- Caller must have either the ADMIN or EDITOR role in the CATALOG
- Caller must have either the OWNER, EDITOR, or VIEWER role in the asset
Purge Options to Delete an Asset
purge_on_delete = true and purge_after_days is not specified: the asset is purged immediately. purge_on_delete = true and purge_after_days = n: the asset is moved to trash and purged after n days. purge_on_delete = false and purge_after_days is not specified: the asset is moved to trash and never purged. purge_on_delete is not specified and purge_after_days is not specified: the asset will be deleted/purged based on the catalog setting. purge_on_delete = false or is not specified and purge_after_days = n: invalid combination - the call will fail with a 400 Bad Request error.
DELETE /v2/assets/{asset_id}Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
If true, asset is also deleted from the trash.
Default:
falseNumber of days after which asset will be purged. Purge On Delete should be true for this to be valid
Update an asset
Overview
Use this API to update certain metadata fields in assets.
Fields that can be patched:
/metadata/name/metadata/description/metadata/tags/metadata/origin_country/metadata/resource_key/metadata/source_system/last_modification_timestamp, Expected Format:yyyy-MM-ddTHH:mm:ssX/metadata/child_source_systems/{idx}/last_modification_timestamp, Expected Format:yyyy-MM-ddTHH:mm:ssX/metadata/source_system_history- array, useaddoperation with path/metadata/source_system_history/-to append a new element/metadata/rov/mode- allowed values are 0 (public), 8 (private) or 16 (hidden)/metadata/rov/collaborator_ids/metadata/rov/member_roles/metadata/rov/member_roles/{iam id}/roles- array, allowed values are OWNER/EDITOR/VIEWER, see below for details
Updating Asset Collaborators and Owners
Either the metadata/rov/collaborator_ids field or the metadata/rov/member_roles field can be updated, but not both.
The collaborator_ids field shown in the asset is derived from the information in member_roles, so updating one of these fields will automatically update the other. The collaborator_ids field shows the members in the member_roles field that have either the asset editor role or the asset viewer role. This field is present for backward compatibility with earlier versions of the catalog service.
Collaborators added to the metadata/rov/collaborator_ids field will be assigned a default asset role based on their role in the catalog. Catalog editors will be assigned the asset editor role, and Catalog viewers will be assigned the asset viewer role.
Users added to the metadata/rov/member_roles present must have either the OWNER role, the OWNER role and EDITOR role, or the OWNER role and VIEWER role. Other combinations of roles are not allowed. Asset users with the VIEWER or EDITOR role must be members of the catalog. In addition, asset users with the OWNER role must also be members if the catalog with either the EDITOR or ADMIN role unless certain service ids are used. For projects and spaces, new owners must have a role in the project/space.
Permissions Required to Modify Asset
To update non-governed fields an asset in a project or space, all of the following must hold:
- Caller must have the EDITOR or ADMIN role in the project/space
To update non-governed fields in a private asset in a catalog, all of the following must hold:
- Caller must have either the ADMIN or EDITOR role in the CATALOG
- Caller must have either the OWNER, EDITOR, or VIEWER role in the asset
To update non-governed fields in a public asset in a catalog, any of the following must hold:
- Caller must have the ADMIN role in the CATALOG
- Caller must have the EDITOR role in the CATALOG and caller must have either the OWNER or EDITOR role in the asset
Permissions required to modify governed metadata fields
The "tags" field is the only governed field. For governed catalogs a policy check is made to determine whether updates to it are allowed and if an asset transformation is needed. The outcome of the policy check can either be "ALLOW", "DENY", or "TRANSFORM"
- If the outcome is "ALLOW", the operation is allowed if the caller has either the "ADMIN" or "EDITOR" catalog role
- If the outcome is "TRANSFORM", the permission checks described above for non-governed fields are applied
- If the outcome is "DENY", the permission checks described above for non-governed fields are applied
Allowed Operations
The combination of asset roles and catalog roles determines what asset operations are allowed by users.
These abilities apply to public assets:
- All members of the catalog can find the asset and see its properties.
- All members of the catalog who have the Editor, Auditor, or Admin roles can use the asset.
These abilities apply to private assets:
- All asset collaborators can find the asset and see its properties. Asset collaborators with the Editor, Auditor, or Admin role can use the asset.
PATCH /v2/assets/{asset_id}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Note:
Any ‘~’ characters need to be escaped as ~0 in the path field.
Any ‘/’ characters need to be escaped as ~1 in the path field.
For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".
Clone an asset
Use this API to clone catalog asset to project. This will create new copy of asset metadata, including asset attachments.
POST /v2/assets/{asset_id}/cloneRequest
Path Parameters
asset_id
Query Parameters
catalog_id must be provided
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Request body should include project ID, and may include asset permissions override.
{
"project_id": "string",
"member_roles": {
"Member's IAM ID": {
"user_iam_id": "Member's IAM ID",
"roles": ["EDITOR"]
},
"Access Group ID": {
"access_group_id": "Access Group ID",
"roles": ["VIEWER"]
},
"Another IAM ID": {
...
}
}
}
Field 'member_roles' is optional.
- If specified, 'member_roles' apply to newly cloned asset.
- If not supplied, newly cloned asset gets 'member_roles' from its source asset.
- If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
- If supplied, 'member_roles' should include at least one OWNER role.
- If caller has only EDITOR role on the source asset and if 'member_roles' does not include all the owners of the source asset then it will be ignored.
'project_id' is the target project id.
Optional owners and other collaborators to assign to newly copied target assets
- member_roles
Set the privacy level mode to be Public (0), Private (8), or Hidden (16)
Add/Update asset collaborators
Overview
This API adds and removes users as collaborators and owners on an asset. A collaborator or owner is identified by user ID. Note that access groups are not supported as asset collaborators or owners. Access groups can be configured as catalog members.
Either the metadata/rov/collaborator_ids field or the metadata/rov/member_roles field can be updated, but not both.
The collaborator_ids field shown in the asset is derived from the information in member_roles, so updating one of these fields will automatically update the other. The collaborator_ids field shows the members in the member_roles field that have either the asset editor role or the asset viewer role. This field is present for backward compatibility with earlier versions of the catalog service.
Collaborators added to the metadata/rov/collaborator_ids field will be assigned a default asset role based on their role in the catalog. Catalog editors will be assigned the asset editor role, and Catalog viewers will be assigned the asset viewer role.
Users added to the metadata/rov/member_roles present must have either the OWNER role, the OWNER role and EDITOR role, or the OWNER role and VIEWER role. Other combinations of roles are not allowed. Asset users with the VIEWER or EDITOR role must be members of the catalog. In addition, asset users with the OWNER role must also be members of the catalog with either the EDITOR or ADMIN role unless certain service ids are used. For projects and spaces, new owners must have a role in the project/space.
Permissions Required to Modify Asset Members
To add or remove asset owners for a private asset in a catalog, any of the following must hold:
- Caller must have OWNER role on the asset
- Caller must have the ADMIN role on catalog and caller must have either the OWNER, EDITOR, or VIEWER role in the asset
To add or remove asset owners for a public asset in a catalog, any of the following must hold:
- Caller must have OWNER role on the asset
- Caller must have the ADMIN role in the catalog
To add or remove asset collaborators, other than asset owner, for a private asset in a catalog, any of the following must hold:
- Caller must have OWNER role on the asset
- Caller must have EDITOR role on the asset
- Caller must have the ADMIN role on catalog and caller must have either the OWNER, EDITOR, or VIEWER role in the asset
To add or remove asset collaborators, other than asset owner, for a public asset in a catalog, any of the following must hold:
- Caller must have OWNER role on the asset
- Caller must have EDITOR role on the asset
- Caller must have the ADMIN role on catalog
Allowed Operations
The combination of asset roles and catalog roles determines what asset operations are allowed by users.
These abilities apply to public assets:
- All members of the catalog can find the asset and see its properties.
- All members of the catalog who have the Editor, Auditor, or Admin catalog roles can use the asset.
These abilities apply to private assets:
- All asset collaborators can find the asset and see its properties. Asset collaborators with the Editor, Auditor, or Admin catalog role can use the asset.
PATCH /v2/assets/{asset_id}/collaboratorsRequest
Custom Headers
Allowable values: [
application/json,application/json-patch+json,application/merge-patch+json]
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
[{
"op": "add",
"path": "/metadata/rov/collaborator_ids/test-iam-id",
"value": {
"user_id": "test@us.ibm.com",
"user_iam_id": "test-iam-id"
}
},
{
"op": "replace",
"path": "/metadata/rov/collaborator_ids/test-iam-id",
"value": {
"user_id": "test2-iam-id",
"user_iam_id": "test-iam-id"
}
},
{
"op": "remove",
"path": "/metadata/rov/collaborator_ids/test2-iam-id"
}
]
(DEPRECATED)
[{
"op": "add",
"path": "/metadata/rov/collaborators/test@us.ibm.com",
"value": {
"user_id": "test@us.ibm.com"
}
},
{
"op": "replace",
"path": "/metadata/rov/collaborators/test@us.ibm.com",
"value": {
"user_id": "test2@us.ibm.com"
}
},
{
"op": "remove",
"path": "/metadata/rov/collaborators/test2@us.ibm.com"
}
]
Note: Any ‘~’ characters need to be escaped as ~0 in the path field.
Any ‘/’ characters need to be escaped as ~1 in the path field.
For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is /foo~1/~0bar.
Deep copies an asset and its related assets to a catalog, project, or space
Use this API to deep copy an asset to a project, catalog, or space. Unlike clone, publish, and promote, this API enables cascading the copy operation to referenced assets.
When copying from a project to a space, the on_promote relationship option is used to determine whether the related assets for a given relationship type should be copied. In addition, you must have Admin or Editor permissions on both the project and the space.
Deep copy sends the same Rabbit MQ messages as clone, publish, and promote. Messages are sent for all assets that are copied.
This API supports copying from a project to a catalog (publish), from a project to a space (promote), and from a catalog to a project (clone).
This API supports using a refresh token in place of an access token. This can be helpful if the deep copy is expected to be a long running operation. The deep copy uses the access token to authenticate with other services, so it is important that it not expire while the operation is in progress.
POST /v2/assets/{asset_id}/deepcopyRequest
Path Parameters
asset_id
Query Parameters
project_id
catalog_id
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]
Request body should include target (container) ID, and may include asset permissions and metadata overrides. Fields 'mode' and 'member_roles' are optional.
- If specified, they apply to newly copied (target) assets.
- If not supplied, newly copied asset gets mode and 'member_roles' from its corresponding source asset.
- Valid values for 'mode' are 0 (public), 8 (private) and 16 (hidden).
- If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
- If supplied, 'member_roles' should include at least one OWNER role.
'space_id' is the target space ID i.e. target container ID.
'metadata' is optional and may contain attributes to overwrite the values in original asset;currently only name, description and tags may be overwritten.
requestBody in json
{
"space_id": "string",
"mode": 0,
"member_roles": {
"Member's IAM ID": {
"user_iam_id": "Member's IAM ID",
"roles": [
"EDITOR"
]
},
"Access Group ID": {
"access_group_id": "Access Group ID",
"roles": [
"VIEWER"
]
},
"Another IAM ID": {
"iam_id": "Another IAM ID",
"roles": [
"role"
]
}
},
"metadata": {
"name": "string",
"description": "string",
"tags": [
"string",
"string"
]
}
}Response
Status Code
OK - indicates the deep copy operation has completed - the asset and its related assets (if applicable) have been fully copied to the target container
Accepted - indicates that the copy request is being completed in the background.
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Update the owner of an asset
Use this API to assign new owner of an asset. You must be the current owner of the asset or a collaborator of the asset with Admin permissions to change the owner. If the asset has multiple owners and the specified user is not currently an owner, the last owner in the owner list (which is the one shown in the owner_id field) is replaced with the specified owner. If the specified user is already an owner of the asset, the user is moved to the end of the owner list so that it is reported in the owner_id field.
This API is deprecated, since this is an older API and supports only single asset owner, not assets with multiple owners. Moving forward owners should be created or updated using below APIs
/v2/assets/{asset_id}
or
/v2/assets/{asset_id}/collaborators
PUT /v2/assets/{asset_id}/ownerRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Asset Owner
Example:
test@us.ibm.comExample:
IBMid-310002980
Update privacy settings of an asset
Use this API to change privacy settings on an asset.
- The owner of the asset or asset collaborators with the Admin role can change the owner of the asset or delete the asset.
- Asset collaborators with the Editor, Auditor, or Admin role can change the asset members or the privacy setting.
PUT /v2/assets/{asset_id}/permsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Asset ROV
Promote an asset
Use this API to promote project assets to space. You must have Admin or Editor permissions on both the project and the space.
POST /v2/assets/{asset_id}/promoteRequest
Path Parameters
asset_id
Query Parameters
project_id must be provided
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Request body should include space ID, and may include asset permissions and metadata overrides. Fields 'mode' and 'member_roles' are optional.
- If specified, they apply to newly promoted asset.
- If not supplied, newly promoted asset gets mode and 'member_roles' from source asset.
- Valid values for 'mode' are 0 (public), 8 (private) and 16 (hidden).
- If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
- If supplied, 'member_roles' should include at least one OWNER role.
- If caller has only EDITOR role on the source asset and if 'member_roles' does not include all the owners of the source asset then it will be ignored.
'space_id' is the target space id.'
metadata' is optional and may contain attributes to overwrite the values in original asset; currently only name, description and tags may be overwritten.
requestBody in json
{
"space_id": "string",
"mode": 0,
"member_roles": {
"Member's IAM ID": {
"user_iam_id": "Member's IAM ID",
"roles": [
"EDITOR"
]
},
"Access Group ID": {
"access_group_id": "Access Group ID",
"roles": [
"VIEWER"
]
},
"Another IAM ID": {
"iam_id": "Another IAM ID",
"roles": [
"role"
]
}
},
"metadata": {
"name": "string",
"description": "string",
"tags": [
"string",
"string"
]
}
}Publish an asset
Use this API to publish project assets to catalog. You can publish data assets from a project into a catalog. You must have Admin or Editor permissions on both the project and the catalog.
POST /v2/assets/{asset_id}/publishRequest
Path Parameters
asset_id
Query Parameters
project_id must be provided
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Request body should include catalog ID, and may include asset permissions and metadata overrides. Fields 'mode' and 'member_roles' are optional.
- If specified, they apply to newly published asset.
- If not supplied, newly published asset gets mode and 'member_roles' from source asset.
- Valid values for 'mode' are 0 (public), 8 (private) and 16 (hidden).
- If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
- If supplied, 'member_roles' should include at least one OWNER role.
- If caller has only EDITOR role on the source asset and if 'member_roles' does not include all the owners of the source asset then it will be ignored.
'catalog_id' is the target catalog id. To support backwards compatibility when it is not supplied, the asset is published to the catalog associated with the project.
'metadata' is optional and may contain attributes to overwrite the values in original asset; currently only name, description and tags may be overwritten.
requestBody in json
{
"catalog_id": "string",
"mode": 0,
"member_roles": {
"Member's IAM ID": {
"user_iam_id": "Member's IAM ID",
"roles": [
"EDITOR"
]
},
"Access Group ID": {
"access_group_id": "Access Group ID",
"roles": [
"VIEWER"
]
},
"Another IAM ID": {
"iam_id": "Another IAM ID",
"roles": [
"role"
]
}
},
"metadata": {
"name": "string",
"description": "string",
"tags": [
"string",
"string"
]
}
}Finds related assets
Finds assets related to a given asset or a given governance artifact. This API supports limiting the results to a specific set of relationships as well as providing pagination and sorting options.
Finds assets and artifacts related to an asset:
- One of the {
catalog_id,project_id,space_id} must be specified. - asset_id must be specified.
- artifact_id and artifact_type cannot be specified.
Finds assets related to an artifact:
- artifact_id and artifact_type must be specified.
- asset_id and container id cannot be specified.
Finds assets and artifacts related to a column:
- One of the {
catalog_id,project_id,space_id} must be specified. - asset_id must be specified. asset_id should be in the format of
<asset_id>#COLUMN#<column_identifier> - artifact_id and artifact_type cannot be specified.
Note:When self references are present (i.e. when the source and target asset in the relationship are the same), more rows than specified by the limit may be returned. When this happens, the total rows reported is accurate and the bookmark points to next page of results.
POST /v2/assets/get_relationships
Request
Query Parameters
Catalog ID
Project ID
Space ID
Asset ID
Artifact ID
Artifact Type
Related Asset Types
Related Artifact Types
bookmark
limit. Defaults to 25
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: update_time_ascSupported sort fields (these are case insensitive):
- create_time_asc
- create_time_desc
- update_time_asc
- update_time_desc
- creator_id_asc
- creator_id_desc
- updater_id_asc
- updater_id_desc
Default:
update_time_ascLimits results to only include the specified relationships. By default, all relationships are included. Repeat the query parameter to specify multiple relationship names.
Whether to lookup the asset names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseWhether to lookup the artifact names. This adds overhead, so only set this to true if the artifact names are required. Defaults to false.
Default:
falseWhether to lookup the container names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
false(DEPRECATED) Whether to return relationships where target end is a column for the given source asset, artifact, or column. This parameter is deprecated. Use 'include_target_columns' instead.
Default:
falseWhether to return relationships where target end is a column for the given source asset, artifact, or column.
Default:
falseWhether to return relationships where source end is either the given asset or a column of the given asset. When this parameter set to 'true', 'include_target_columns' must also be set to 'true'. By this, all relationships of asset-asset, asset-column, asset-artifact, column-asset, column-column, column-artifact will be returned.Use this parameter when 'asset_id' refers to an asset which has columns.
Default:
false
Searches for relationships
Finds relationships that match the specified criteria. There are two general kinds of criteria that can be used: criteria that at least one relationship end must match and criteria that the overall relationship must match.
Specifying conditions that at least one end of the relationship must match
There are three different conditions of this type that can be specified:
-
relationship name - limits results to relationships with the specified name(s)
-
Required object criteria:
- required artifact — must specify artifact_type and artifact_id
- required asset - must specify asset_id and one of: catalog_id, project_id, space_id
- required asset container - must specify one of: catalog_id, project_id, space_id
- Only one type of required object criteria can be used
-
Opposite end criteria:
- related_asset_types - specifies that opposite end must have one of the specified asset types
- related_artifact_types - specifies that opposite end must have one of the specified artifact types
- related_asset_types and related_artifact_types can be used together to specify that the opposite end must have either the specified asset or artifact types
Specifying global conditions that the overall relationship much match:
There are 2 global conditions that can be specified:
- modified_after - Restricts results to relationships created/updated after a specific date and time
- modified_before - Restricts results to relationships created/updated before a specific date and time
- modified_after and modified_before can be used together to filter for relationships created/updated within a specific time window.
POST /v2/assets/search_relationships
Request
Query Parameters
Catalog ID. Specifies that a specific catalog_id must be in the returned relationships. If filtering by asset container, either catalog_id, project_id, or space_id must be specified.
Project ID. Specifies that a specific project_id must be in the returned relationships. If filtering by asset container, either catalog_id, project_id, or space_id must be specified.
Space ID. Specifies that a specific space_id must be in the returned relationships. If filtering by asset container, either catalog_id, project_id, or space_id must be specified.
Asset ID. Specifies that a specific asset must be in the returned relationships If specified, either catalog_id, project_id, or space_id must also be specified.
Artifact ID. Specifies that a specific artifact must be in the returned relationships. If specified, artifact_type must also be specified
Artifact Type. Required if artifact_id is specified
Related Asset Types. Filters the result to include relationships based on their target asset type. The parameter can be repeated to specify multiple asset types. If both related_artifact_types and related_asset types are omitted, all target types are included in the result.
Related Artifact Types. Filters the result to include relationships based on their target artifact type. The parameter can be repeated to specify multiple artifact types. If both related_artifact_types and related_asset types are omitted, all target types are included in the result.
bookmark
limit. Defaults to 25
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: update_time_ascSupported sort fields (these are case insensitive):
- create_time_asc
- create_time_desc
- update_time_asc
- update_time_desc
- creator_id_asc
- creator_id_desc
- updater_id_asc
- updater_id_desc
Default:
update_time_ascLimits results to only include the specified relationships. By default, all relationships are included. Repeat the query parameter to specify multiple relationship names.
Whether to lookup the asset names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseWhether to lookup the artifact names. This adds overhead, so only set this to true if the artifact names are required. Defaults to false.
Default:
falseWhether to lookup the container names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseIncludes relationships modified after this date/time - specified in ISO-8601 format (examples: 2022-09-01T14:32:17Z, 2022-09-01T14:32:17.802Z). This can be used in conjunction with modified_before to specify a required modification time window.
Includes relationships modified before this date/time - specified in ISO-8601 format (examples: 2022-09-01T14:32:17Z, 2022-09-01T14:32:17.802Z). This can be used in conjunction with modified_after to specify a required modification time window.
(DEPRECATED) Whether to return relationships where target end is a column for the given source asset, artifact, or column. This parameter is deprecated. Use 'include_target_columns' instead.
Default:
falseWhether to return relationships where target end is a column for the given source asset, artifact, or column.
Default:
falseWhether to return relationships where source end is either the given asset or a column of the given asset. When this parameter set to 'true', 'include_target_columns' must also be set to 'true'. By this, all relationships of asset-asset, asset-column, asset-artifact, column-asset, column-column, column-artifact will be returned.Use this parameter when 'asset_id' refers to an asset which has columns.
Default:
false
Create asset relationships
Use this API to create up to 20 asset relationships.
- The relationship name must correspond to a relationship type defined on the source type.
- The source must be an asset, column or governance artifact of the type specified in the relationship type definition.
Relationships created with a governance artifact as the source cannot be retrieved, modified, or deleted in the IKC UI.
These relationships can only be accessed through API calls such asPOST /v2/assets/search_relationships,POST /v2/assets/get_relationships, andPOST /v2/assets/unset_relationships. - The target must be an asset, column or governance artifact of the type specified in the relationship type definition.
- If the specified relationship does not exist between a source and target, a new relationship is created.
- If either end of the relationship is defined as multiplicity-one, any existing value of a multiplicity-one end is replaced.
For Asset
- The
asset_idand one of the {catalog_id,project_id,space_id} must be set
For Column
- The
asset_idand one of the {catalog_id,project_id,space_id} must be set - The
asset_idof a column must be in the format of<asset_id>#COLUMN#<column_identifier>
For Artifact
- The
artifact_idandartifact_typemust be set. Use the global id of the artifact forartifact_id
POST /v2/assets/set_relationships
Deletes asset relationships
Use this API to delete up to 20 asset relationships.
- The relationship name must correspond to a relationship type defined on the source type.
- The source must be an asset or governance artifact of the type specified in the relationship type definition.
- The target must be an asset or governance artifact of the type specified in the relationship type definition.
- If the specified relationship does not exist between the source and the target, it will be ignored.
For Asset
- The
asset_idand one of the {catalog_id,project_id,space_id} must be set
For Column
- The
asset_idand one of the {catalog_id,project_id,space_id} must be set - The
asset_idof a column must be in the format of<asset_id>#COLUMN#<column_identifier>
For Artifact
- The
artifact_idandartifact_typemust be set
POST /v2/assets/unset_relationships
Finds relationship types used by an asset
Finds relationship types that are used by a given asset. This API only returns the first page of results. It does not accept a bookmark. Any additional pages of results must be be fetched using the next page url included in the response.
You can refer to the options in the response to get the full list of relationship names.
This API is deprecated - use POST /v2/assets/search_relationships instead.
GET /v2/assets/{asset_id}/relationship_typesRequest
Path Parameters
Asset ID
Query Parameters
Catalog ID
Project ID
Space ID
Optional limit to use when finding relationship types
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported sort fields (these are case insensitive):
- relationship_name_asc
- relationship_name_desc
- relationship_display_name_asc
- relationship_display_name_desc
- create_time_asc
- create_time_desc
Default:
relationship_display_name_asc
Response
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Finds related assets
Finds assets related to a given asset. This API supports limiting the results to a specific set of relationships as well as providing pagination and sorting options.
Note:When self references are present (i.e. when the source and target asset in the relationship are the same), more rows than specified by the limit may be returned. When this happens, the total rows reported is accurate and the bookmark points to next page of results.
This API is deprecated - use POST /v2/assets/get_relationships instead.
GET /v2/assets/{asset_id}/relationshipsRequest
Path Parameters
Asset ID
Query Parameters
Catalog ID
Project ID
Space ID
bookmark
limit. Defaults to 25
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: update_time_ascSupported sort fields (these are case insensitive):
- create_time_asc
- create_time_desc
- update_time_asc
- update_time_desc
- creator_id_asc
- creator_id_desc
- updater_id_asc
- updater_id_desc
Default:
update_time_ascLimits results to only include the specified relationships. By default, all relationships are included. Repeat the query parameter to specify multiple relationship names.
Whether to lookup the asset names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseWhether to lookup the container names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
false
Create asset relationships
Use this API to create relationships between a source asset and up to 20 target artifacts.
- The relationship name must correspond to a relationship type defined on the source asset's type.
- The target artifacts must be assets of the type specified in the relationship type definition.
- If the specified relationship does not exist between a source and target asset, a new relationship is created.
- If either end of the relationship is defined as multiplicity-one, any existing value of a multiplicity-one end is replaced.
This API is deprecated - use POST /v2/assets/set_relationships instead.
PUT /v2/assets/{asset_id}/relationships/{relationship_name}Deletes asset relationships
Use this API to remove a relationship between an asset and one or more target artifacts. The relationship name must correspond to a relationship type defined on the source asset's type. If the specified relationship does not exist between the source and one or more target assets, it will be ignored. For this api, all of the relationship targets need to be in the same catalog, project, or space. If the target space/catalog/project is omitted, it is assumed to be the same as the source.
This API is deprecated - use POST /v2/assets/unset_relationships instead.
DELETE /v2/assets/{asset_id}/relationships/{relationship_name}Request
Path Parameters
Source Asset Id
Name of relationship defined on the source asset type
Query Parameters
target asset id. To delete multiple relationships, this parameter can be repeated.
Source Asset Catalog
Source Asset Project
Source Asset Space
Target Asset Catalog
Target Asset Project
Target Asset Space
Determine if a relationship exists between an asset and a target artifact
Use this API to determine if a relationship exists between an asset and a target artifact. The relationship name must correspond to a relationship type defined on the source asset's type. The target artifact must be an asset of the type specified in the relationship type definition. The source and target assets must reside in the same catalog.
HEAD /v2/assets/{asset_id}/relationships/{relationship_name}Request
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
Attachment meta-data.
The "asset_type" is required.
The "mime" is a reliable way to indicate the nature and format of the attachment. It should be used instead of other implementation-specific means, e.g., file extension.
If not supplied, or if the value given is less than 1, data_partitions defaults to 1 (for non-remote and non-referenced attachments).
For remote attachments, both connection_id and connection_path are required.
For referenced attachments, both object_key and object_key_is_read_only are required.
Request
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
private_url
Default:
falseresponse-content-disposition
response-content-type
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
Request
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
Update attachment metadata
Update attachment metadata. Only the following fields are allowed to update:
- name
- description
- mime
- size
- partitions
- transfer_complete
PATCH /v2/assets/{asset_id}/attachments/{attachment_id}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json,application/merge-patch+json]
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
[
{ "op": "add", "path": "/name", "value": "my_attachment"},
{ "op": "replace", "path": "/mime", "value": "text/csv" },
{ "op": "remove", "path":"/description"}
]
Note:
- Any ‘~’ characters need to be escaped as ~0 in the path field.
Any ‘/’ characters need to be escaped as ~1 in the path field.
For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar". - The transfer_complete field can only be set to true if its current value is false and the type of attachment is managed.
Mark an attachment as transfer complete
Marks an attachment as transfer complete.
POST /v2/assets/{asset_id}/attachments/{attachment_id}/completeRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Auto update attachment's datasource_type from connection asset
Auto update attachment's datasource_type from connection asset
PATCH /v2/assets/{asset_id}/attachments/{attachment_id}/datasource_typeRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Get resources info for an attachment
Get resources info for an attachment.
GET /v2/assets/{asset_id}/attachments/{attachment_id}/resourcesRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
Increase resources for an attachment
Increase resources for an attachment.
PUT /v2/assets/{asset_id}/attachments/{attachment_id}/resourcesRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
attachment resource to increase, e.g. {"data_partitions":5, "private_url":false}
List all attributes
Use this API to retrieve all attributes of an asset.
GET /v2/assets/{asset_id}/attributesRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Create an attribute
Use this API to create an asset attribute. An attribute is identically named with, and has fields that are partially defined by, an asset type.
The name specified in the request payload must match an existing built-in or user-defined asset type.
column_info attribute
The built-in column_info type defines metadata (e.g. description, tags) for columns contained in a data asset which represents a relational database table or columnar data file (e.g. csv file).
Create a column_info asset attribute to add column descriptions and/or tags if that attribute does not already exist on the asset.
Once the column_info attribute has been created, entries can be added, updated, or removed using the PATCH /v2/assets/{asset_id}/attributes/column_info endpoint.
The column_info attribute is a map structure where the key is a column name corresponding to an existing entry in the asset's entity.data_asset.columns array.
For example, here is the request payload to create a column_info attribute that assigns a description and tags to ACCOUNT_HOLDER_ID and NAME columns:
{
"name": "column_info",
"entity": {
"ACCOUNT_HOLDER_ID": {
"column_description": "Globally unique identifier of the account holder.",
"column_tags": [
"identifier",
"unique_key"
]
},
"NAME": {
"column_description": "Full legal name of the account holder.",
"column_tags": [
"legal_name"
]
}
}
}
POST /v2/assets/{asset_id}/attributesRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
Attribute metadata. The "entity" is required.
Example:
TestAttribute- entity
Get an attribute
Use this API to retrieve an attribute of an asset.
GET /v2/assets/{asset_id}/attributes/{attribute_key}Request
Path Parameters
asset_id
attribute_key
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Delete an attribute
Use this API to delete an attribute of an asset.
DELETE /v2/assets/{asset_id}/attributes/{attribute_key}Request
Path Parameters
asset_id
attribute_key
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
Update attributes
Use this API to update/modify an asset attribute.
Updating the column_info attribute
Use this API for updating an existing column_info attribute to set or replace the column_description or column_tags for any column.
Note: Use
POST /v2/assets/{asset_id}/attributesto create thecolumn_infoattribute if it does not exist on the asset. UseGET /v2/assets/{asset_id}/attributes/column_infoto check the existence of the attribute.
Payload Examples
To add a column_info entry that specifies a description and tags for the INVOICE_ID column:
[{"op":"add","path":"/INVOICE_ID","value":{"column_description":"Unique identifier of the invoice", "column_tags":["tag1", "tag2"]}}]
To add or update a description on the existing column_info entry for the ADDRESS column:
[{"op":"add","path":"/ADDRESS/column_description","value":"customer street address"}]
To unset/remove the ADDRESS column's description:
[{"op": "remove", "path":"/ADDRESS/column_description"}]
To remove the entire column_info entry for the ADDRESS column: [{"op": "remove", "path":"/ADDRESS"}]
To update value of properties of data_asset:
{
"entity": {
"data_asset": {
"mime_type": "text/csv",
"dataset": true,
"properties": [
{
"name": "schema_name",
"value": "GOSALES1021"
},
{
"name": "table_name",
"value": "COUNTRY"
}
]
}
}
}
Request body:
[
{ "op": "replace", "path": "/properties/1/value", "value": "COUNTRY2" }
]
To update value of data_source_deployment:
{
"entity": {
"ibm_data_source": {
"data_source_type_id": "8c1a4480-1c29-4b33-9086-9cb799d7b157",
"data_source_deployment": "on_cloud",
"data_source_flags": [],
"data_source_state": "ACTIVE",
"data_source_encoding": "UTF-8",
"data_source_protection_method": "guardium"
}
}
}
Request body:
[
{ "op": "replace", "path": "/data_source_deployment", "value": "cpd" }
]
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Note: Any ‘~’ characters need to be escaped as ~0 in the path field. Any ‘/’ characters need to be escaped as ~1 in the path field. For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".
PATCH /v2/assets/{asset_id}/attributes/{attribute_key}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
asset_id
attribute_key
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
JSON array of patch operations as defined in RFC 6902.
Get asset document conflicts
Use this API to retrieve asset document conflicts in database.
GET /v2/assets/{asset_id}/conflictsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
The number of items to skip before starting to collect the result set
The maximum number of items to return
Default:
10Whether to retrieve conflict revision document content
Delete asset document conflicts
Use this API to delete asset document conflicts in database.
DELETE /v2/assets/{asset_id}/conflictsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Document conflicts to delete
List of conflicting documents revs
Request
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Upload an image for asset
Upload an image for asset. Use this api, you must put the image's binary data to the HTTP body.
For example:
curl -X "PUT" "api_url" -H "Authorization: $access token" --data-binary "@/image_dir_path/abc.png"
PUT /v2/assets/{asset_id}/imagesRequest
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Request
Path Parameters
Asset GUID
Image id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Get asset or column notes
Use this API to retrieve a paginated list of notes from an asset or a column within an asset. Any user who has viewer permission on an asset can retrieve its notes.
GET /v2/assets/{asset_id}/notesRequest
Path Parameters
Asset ID
Query Parameters
The maximum number of asset/column notes to return.
The default value is 25. The limit cannot exceed 200.
Use thenextURL from the response to retrieve the next page of notes.Default:
25Sorting order.
The following fields can be used for sorting. Use hyphen prefix (-) for descending order:column_namecreated_atupdated_atDefault:
-updated_atYou must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Filters the result to include notes on the specified column(s). The parameter should be repeated for each column name.
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Type of notes to include in the search result:
Note Type Description ALLInclude all asset and column notes ASSETInclude asset notes only - cannot be used with the column_namesparameterCOLUMNInclude column notes only Allowable values: [
ALL,ASSET,COLUMN]Default:
ALL
Create notes on an asset
Use this API to create notes for an asset and for columns within an asset. Accredited Service Editors and Viewers, and any user who has edit permission on an asset can create a note.
POST /v2/assets/{asset_id}/notesRequest
Path Parameters
Asset ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Asset notes to be created - limited to 20 notes per request
notes to be created for an asset and for columns of an asset
Get an asset or column note
Use this API to retrieve a note from an asset or a column within an asset. Any user who has viewer permission on an asset can retrieve a note.
GET /v2/assets/{asset_id}/notes/{note_id}Request
Path Parameters
Asset ID
Note ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Response
Asset note metadata
- metadata
system generated unique asset note identifier
unique Identifier of asset associated with this note
Example:
892aaa55-1b0e-438a-b05f-4224246a0f3fname of the column associated with this note
Example:
cityID of user that created the asset note (system managed)
Example:
IBMid-66100421ANID of user that updated the asset note (system managed)
Example:
IBMid-66100421ANRFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was created (system managed)
Example:
2023-05-24T16:34:06.000ZEpoch timestamp when the asset note was created (system managed)
Example:
1621874046338RFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was updated (system managed)
Example:
2023-05-24T16:34:06.000ZEpoch timestamp when the asset note was updated (system managed)
Example:
1621874046338
Asset note entity
- entity
a note associated with an asset or a column of an asset
Example:
description of a note
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Delete an asset or a column note
Use this API to delete an asset or a column note. Accredited Service Editors and Viewers, and any user who has edit permission on an asset can delete a note.
DELETE /v2/assets/{asset_id}/notes/{note_id}Request
Path Parameters
Asset ID
Asset or column note ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Update an asset or column note
Use this API to update a note on an asset or a column within an asset. Accredited Service Editors and Viewers, and any user who has edit permission on an asset can update a note.
PATCH /v2/assets/{asset_id}/notes/{note_id}Request
Path Parameters
Asset ID
Note ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Example :
[ {"op": "replace", "path": "/note", "value": "Description of a Note" } ]
Note:
Only supported operation is replace.
Any ‘~’ characters need to be escaped as ~0 in the path field.
Any ‘/’ characters need to be escaped as ~1 in the path field.
For example, in {"foo/" : {"~bar" : "value"}}, the path for ~bar is /foo~1/~0bar.
Response
Asset note metadata
- metadata
system generated unique asset note identifier
unique Identifier of asset associated with this note
Example:
892aaa55-1b0e-438a-b05f-4224246a0f3fname of the column associated with this note
Example:
cityID of user that created the asset note (system managed)
Example:
IBMid-66100421ANID of user that updated the asset note (system managed)
Example:
IBMid-66100421ANRFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was created (system managed)
Example:
2023-05-24T16:34:06.000ZEpoch timestamp when the asset note was created (system managed)
Example:
1621874046338RFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was updated (system managed)
Example:
2023-05-24T16:34:06.000ZEpoch timestamp when the asset note was updated (system managed)
Example:
1621874046338
Asset note entity
- entity
a note associated with an asset or a column of an asset
Example:
description of a note
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Request
Path Parameters
asset_id
Query Parameters
The maximum number of asset ratings to return.
The default value is 25.Default:
25Bookmark that gives the start of the page.
Sorting order.
Valid values:updated_at,rating
Use hyphen prefix (-) for descending orderDefault:
-updated_atFilter results by user.
Valid values:all,user,other
The default value isallAllowable values: [
all,user,other]Default:
allYou must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Asset rating to be created
user's rating of an asset
Example:
5user's review of an asset
Example:
Such an asset!
Get the count of each rating value for the specified asset
Get the counts of each rating value for the specified asset.
GET /v2/assets/{asset_id}/ratings/statsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Delete an asset rating
Use this API to delete an asset rating.
DELETE /v2/assets/{asset_id}/ratings/{asset_rating_id}Request
Path Parameters
asset_id
asset_rating_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Use this API to update an asset rating.
Update an asset rating
PATCH /v2/assets/{asset_id}/ratings/{asset_rating_id}Request
Path Parameters
asset_id
asset_rating_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Asset rating to be updated
user's rating of an asset
Example:
5user's review of an asset
Example:
Such an asset!
Get a list of revisions for an asset
Use this API to retrieve an ordered list of revisions for an asset, most to least recent.
GET /v2/assets/{asset_id}/revisionsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
The parameter
includeis deprecated.The maximum number of revisions to return. The default is 25. Maximum is 200
Default:
25The revision number to start from, or 'latest'. Latest revision is the default.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Commit a revision of an asset
Use this API to commit a revision of an asset.
POST /v2/assets/{asset_id}/revisionsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Commit options
Delete a revision
Use this API to delete a revision of an asset.
DELETE /v2/assets/{asset_id}/revisionsRequest
Path Parameters
asset_id
Query Parameters
You must provide a revision id (1, 2, 3, ...)
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Find and repair stuck temporary design documents by creating cache entries that resume their processing
Use this API to find and repair broken indexes
POST /v2/cams/admin/index_repairs
Request
Query Parameters
Optionally limits to checking to certain catalogs. For projects and spaces you must use the id of the private catalog. Repeat this parameter to check multiple catalogs. If this is omitted, all catalogs are checked
Allows rate limiting the creation of cache entries. To disable rate limiting, set to -1. If set, the operation pauses every time this number of cache entries have been created.
Default:
50When using cache entry rate limiting, this controls how long the service pauses between creating groups of cache entries.
Default:
1Allows restricting total the number of cache entries created.
Default:
true
Response
The options being used for the indexing repair task.
- options
If rate liming is enabled, the number of minute to sleep between creating batches of cache entries
Number of created cache entries between pauses, if rate limiting is enabled
The configured list of catalogs to process, if there is one
The number of threads processing the catalogs
Whether preview mode is enabled
The number maximum number of cache entries to create
Link that can be used to get the status of the indexing repair task.
The id of the indexing repair task that was created.
Status Code
Accept, the processing was successfully started
Bad Request
Unauthorized
Forbidden
No Sample Response
Gets the status of a temporary design document repair operation
Use this API to get the status of the task to find and repair stuck temporary design documents
GET /v2/cams/admin/index_repairs/{id}Response
The options being used for the indexing repair task.
- options
If rate liming is enabled, the number of minute to sleep between creating batches of cache entries
Number of created cache entries between pauses, if rate limiting is enabled
The configured list of catalogs to process, if there is one
The number of threads processing the catalogs
Whether preview mode is enabled
The number maximum number of cache entries to create
The current state of the repair task.
Possible values: [
QUEUED,RUNNING,FINISHED,FAILED]The time when the task started.
The amount of time the repair task has been running.
The percentage of the databases that have been processed.
The estimated time when the processing will be complete.
The time when the processing completed.
The estimated amount of processing time remaining.
The number of databases that have been processed so far.
The total number of databases that need to be processed.
The number of stuck temporary design documents that have been found.
The stuck temporary design documents that have been found.
The number of stuck temporary design documents that have been repaired so far.
The number of temporary design documents that have been processed so far.
The ids of any catalogs that were unable to be processed.
The error message if the processing failed.
Status Code
OK
Bad Request
Unauthorized
Forbidden
No Sample Response
Reconfigure the asset container
Use this API to reconfigure the asset container. The supported items are:
- type_search_indexes - reconfigure type search indexes for all asset types. It requires the user to have permission to register asset types.
POST /v2/cams/admin/reconfigure
Request
Query Parameters
The item to reconfigure, e.g. type_search_indexes
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Get metrics of the asset lists
Get metrics of the asset lists.
The caller should use the href returned by the service to navigate through pages and should not try to manually construct URLs for pagination.
The href for the first page is always available, and the href for the next page is only available if there may be a next page.
The total_rows field is only available when summary_level is CATALOG.
The caller must be in at least one of the allow-lists based on the product offering to perform the operation:
DATA_PRODUCT-data_product_account_viewers,data_product_account_managers
GET /v2/cams/metrics/asset_list_count
Request
Query Parameters
The month of the metrics to retrieve. The value must be in format
yyyy-MM. If not supplied, the metrics of the current month are retrieved.Retrieve metrics only for asset lists belonging to any of the given bss accounts. Specify as a comma-separated list.
The maximum number of items to return. If not specified, it will be set to 200.
Default:
200Start token for pagination
Response
The user access metrics response API model.
The limit on the number of results returned.
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Example:
50A page in a pagination collection.
The next page in the collection.
Collection of user access statistics
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Get metrics of the users who accessed the catalogs
Get metrics of the users who accessed the catalogs.
The caller should use the href returned by the service to navigate through pages and should not try to manually construct URLs for pagination.
The href for the first page is always available, and the href for the next page is only available if there may be a next page.
The total_rows field is only available when summary_level is CATALOG.
The caller must be in at least one of the allow-lists based on the product offering to perform the operation:
(Note: the WKC product offering represents IBM Knowledge Catalog):
DATA_PRODUCT-data_product_account_viewers,data_product_account_managersWATSONX_GOVERNANCE-watsonx_governance_account_viewers,watsonx_governance_account_managersWKC-wkc_account_viewers,wkc_account_managers
GET /v2/cams/metrics/user_access_count
Request
Query Parameters
The month of the metrics to retrieve. The value must be in format
yyyy-MM. If not supplied, the metrics of the current month is retrieved.The level for aggregating the user access statistics.
Allowable values: [
ACCOUNT,CATALOG]Default:
ACCOUNTProduct offering. If omitted, it is default to WKC.
Allowable values: [
WKC,DATA_PRODUCT,WATSONX_GOVERNANCE]Default:
WKCRetrieve metrics only for catalogs belonging to any of the given bss accounts. Specify as a comma-separated list.
Retrieve metrics only for catalogs with the given ids. Specify as a comma-separated list.
The maximum number of items to return. If not specified, it will be set to 200.
Default:
200Start token for pagination
Response
The user access metrics response API model.
The limit on the number of results returned.
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Example:
50A page in a pagination collection.
The next page in the collection.
Collection of user access statistics
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
List all catalogs for a specific account
Use this API to get a list of catalogs or projects or spaces, or to get the total number of public catalogs, for a given account. You can use 'roles' parameter to filter results by roles for standard callers.
- Standard Callers: to list all catalogs where caller is collaborator, omit "bss_account_id" field and "include" field.
- Accredited Services: to list all catalogs or projects or spaces for a specific account, enter bss account value in "bss_account_id" field and one of 'catalogs', 'projects', or 'spaces' in "include" field.
- Accredited Services: to get the number of public catalogs for a specific account, enter bss account value in "bss_account_id" field and 'total_count' in "include" field.
GET /v2/catalogs
Request
Query Parameters
limit
Default:
25bookmark
skip
Default:
0Limited to use by accredited services (which must also supply 'bss_account_id'). Currently, the only supported values are 'catalogs', 'projects', 'spaces' or 'total_count'. Not supplying any of these values results in public 'catalogs', 'projects', AND 'spaces' being returned for a specific account.
- Use 'catalogs' for including all public catalogs for a specific bss_account_id.
- Use 'projects' for including all projects for a specific bss_account_id.
- Use 'spaces' for including all spaces for a specific bss_account_id.
- Use 'total_count' for including total number of public catalogs for a specific account.
- Use 'catalogs' for including all public catalogs for a specific bss_account_id.
"Used for listing catalogs, projects, or spaces for the account, or for retrieving the number of public catalogs for the account. Must be supplied when caller is an accredited service."
- "If caller is a non-service id user, then the catalogs from that user's bss account are included in the list.
Filter results by user roles. Use comma separated list for multiple roles. Valid role value: admin, editor, viewer. This param is not allowed if caller is from accredited service or ICIP mode is enabled.
orderby. This parameter can be repeated to add additional sort fields.
Default: nullSupported sort fields (these are case insensitive):
- catalog_name_asc
- catalog_name_desc
- create_time_asc
- create_time_desc
- update_time_asc
- update_time_desc
(DEPRECATED) Indicates whether results should include catalogs with a subtype. If not specified, catalogs with a subtype are excluded.This parameter is deprecated. Use 'subtype' instead.
Filter results by catalogs with the specified subtypes.
If nothing is specified, by default catalogs with subtype are not returned.
- If set to 'NO_SUBTYPES', catalogs with subtype are not returned
- If set to 'ALL_SUBTYPES', only catalogs with a subtype are returned
- If set to 'ALL_SUBYTPES, NO_SUBTYPES', both catalogs which have subtypes and not are returned
- If set to 'subtypeA, subtypeB' , only catalogs with those subtypes are returned.
Filter results by catalogs with a case insensitive name. This matches substrings.
Filter results by catalogs with the specified governance type. Allowed values: governed, ungoverned, all. Default: all
Create a catalog
Use this API to create a catalog to organize your assets and collaborators. You can use a catalog to easily find and share data for your organization, regardless of the location or format of the data.
On IBM Cloud, to create a catalog you must have the Manager role in your organization's IBM Knowledge Catalog account.
In CPD, to create a catalog you must have the Administrator role.
The catalog name can be 1 to 256 printable Unicode characters - ISO control characters and Unicode Special characters are not permitted.
On IBM Cloud, IBM Cloud Object Storage (S3 API) credentials are required in the request body's bucket structure. This provides encrypted storage for file assets that are copied to the catalog.
In CPD, file asset storage for a catalog is provisioned after catalog creation, via a separate call to the Asset Files API. Creating a catalog does not automatically provision this storage.
When creating a catalog in CPD, set the check_bucket_existence query parameter to false, and the request body's bucket structure should just have bucket_type set to assetfiles.
After the catalog is created, call the PUT /v2/asset_files API to create a bucket for this catalog.
Sample request body for creating a catalog in CPD:
{
"name": "catalog1",
"description": "A catalog in CPD",
"generator": "catalogadmin@mycompany.com",
"bucket": {
"bucket_type": "assetfiles"
}
}
POST /v2/catalogs
Request
Query Parameters
Whether an existence check should be performed on the catalog bucket
Default:
trueWhether to check if catalogs with the same name already exist
Default:
false
Note: name, generator, and the bucket structure are required fields in the request body.
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
Created
Bad Request
Unauthorized
Forbidden
Too Many Request
No Sample Response
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
OK
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
Request
Query Parameters
Whether an existence check should be performed on the catalog bucket
Default:
trueWhether to check if catalogs with the same name already exist
Default:
false
Example:
{
"catalog": {
"name": "The Default Catalog",
"generator": "API",
"description": "The default catalog",
"bss_account_id": "999",
"is_governed": true,
"bucket": {
"bucket_type": "assetfiles"
}
}
}
Schema for catalogEntity with bucket details
Rehome one or more synced assets.
Use this API for rehoming assets in a catalog that had been synced from an external OMRS repository to be native IKC assets. The API supports rehoming a single asset, or a bulk rehome of all synced data assets of specific external repository.
If the request is accepted, the response header contains the rehome request ID x-future-id which can then be used to monitor the request status via /v2/catalogs/default/rehome/status?request_id=<x-future-id>.
Service ID is required to call this API.
POST /v2/catalogs/default/rehome
Request
Query Parameters
Set to true to bulk re-home all synced data assets in a catalog
Synced asset to be rehomed - if omitted, all synced assets of
source_metadata_collection_idrepository will be rehomedSource metadata collection id required if all assets of single external repository need to be rehomed
Catalog containing the synced assets to be re-homed. If not specified, synced assets in the default catalog are re-homed.
Get a catalog by catalog ID
Members of the catalog can use this API to retrieve information about a catalog.
GET /v2/catalogs/{catalog_id}Request
Path Parameters
Catalog GUID or UID
Query Parameters
You must provide bss_account_id when querying for uid
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
OK
Bad Request
Unauthorized
Forbidden
No Sample Response
Update catalog
Use this API to update the name or description of the catalog.
PATCH /v2/catalogs/{catalog_id}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
catalog GUID
Query Parameters
Whether to check if catalogs with the same name already exist. Only applicable if the name is to be updated.
Default:
false
JSON array of patch operations as defined in RFC 6902.
[
{ "op": "replace", "path": "/entity/name", "value": "new-name" },
{ "op": "replace", "path": "/entity/description", "value": "new-description" }
]
Note:
Any ‘~’ characters need to be escaped as ~0 in the path field.
Any ‘/’ characters need to be escaped as ~1 in the path field.
For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
OK
Bad Request
Unauthorized
Forbidden
Conflict
Internal Server Error
No Sample Response
Update catalog properties
Use this API to patch catalog properties.
PATCH /v2/catalogs/{catalog_id}/propertiesRequest
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
catalog GUID
JSON array of patch operations as defined in RFC 6902.
[
{ "op": "add", "path": "/properties/new-property", "value": "new-value" }
]
Note:
Any ‘~’ characters need to be escaped as ~0 in the path field.
Any ‘/’ characters need to be escaped as ~1 in the path field.
For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".
Export as a zip file containing appropriate csv files for the selected assets
This API is responsible for preparing a zip file containing csv files related to the selected assets for export.
POST /v2/catalogs/export_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
The id of the ibm_export_asset type asset
The list of export types the operation is expected to handle. Export Type includes
metadata, relationship, lineage. But, for now, we are supporting onlymetadata, relationship.
A json object containing a list of asset IDs; maximum of 100.
Process an import asset
This API begins processing of import assets. This function is used to import lineage mappings from EMD CSV documents.
POST /v2/catalogs/import_assets
Request
Query Parameters
The id of the import_asset
The action to perform on this import_asset. "process" (default): Validate and run an import job, "validate": Validate an import only without starting an import job.
You must provide either a catalog id, a project id, or a space id, but not more than one
When performing a processing request, proceed with the import even if validation fails. This option is only used when 'action' = 'process' (which is the default case)
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]
Request temporary security credentials
Request temporary security credentails that can be used for storing asset attachment files.
The endpoint is currently only applicable for AWS deployments.
If role_arn and external_id are supplied, the caller must be a sevice id in the allow-list 'aws_s3_administrator'. The requested credentials will have permission for accessing the resources in the bucket of the catalog or the bucket itself depending on the supplied information. The allowed combinations of the fields are:
- role_arn, external_id: list and create buckets in the account that the role is defined in
- role_arn, external_id, bucket_name, shared (optional, default to false), catalog_id (must be supplied if shared is true): put/get/list/delete objects in the bucket, and list multipart uploads and delete the bucket if the bucket is not shared.
If catalog_id is supplied, the caller must be a member of the catalog, or a service id that is in the allow-list 'aws_s3_administrator', 'accredited_service_editors', 'accredited_service_viewers', or 'accredited_service_exporters'. The requested credentials will have permission for accessing the resources in the bucket of the catalog or the bucket itself based on the membership.
- admin or service id in allow-list 'aws_s3_administrator': put/get/list/delete objects in the bucket, and list multipart uploads and delete the bucket if the bucket is not shared.
- editor or service id in allow-list 'accredited_service_editors': put/get/delete objects in the bucket
- viewer or service id in allow-list 'accredited_service_viewers' or 'accredited_service_exporters': get objects in the bucket
If none of above is supplied, the caller must have permission to create catalogs in the account that the access token is scoped for. The requested credentials will have permission to list and create buckets in the account.
If min_duration_seconds is supplied, the requested temporary credentials must be valid for at least the specified duration. If it is not supplied or if the cached temporary credentials of the same requirement is valid for at least specified duration, the cached credentials will be returned.
Note: when a bucket is shared, the objects in the shared bucket must have the prefix of '{catalog_id}/', e.g. '553fa5a8-bea5-43fa-9f04-b2f5ed39e6d3/myreport.csv'. All the permissions in shared buckets are granted to only allow accesing resources with the prefix of a specific catalog id.
POST /v2/catalogs/temporary_credentials
Request
Request body
Catalog id
ARN of the AWS integration role
External id for AWS integration
Name of the bucket
Indicate if the bucket is shared by multiple asset containers
Minimum duration (in seconds) that the credentials should be valid for. The value cannot be greater than 3600 seconds. If not supplied, cached credentials that have the same requested permission can be returned.
Response
AWS access key, used to identify the user interacting with AWS
AWS secret access key, used to authenticate the user interacting with AWS
AWS session token. This token is retrieved from an AWS token service, and is used for authenticating that this user has received temporary permission to access some resource.
The epoch timestamp when the credentials will expire.
Session policy applied on the role session created for the temporary credentials. The field is only available in development environment and not in production environment for performance reason.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Delete members from a catalog
Delete members from a catalog.You can delete a member or more if you are the owner of the catalog or a member of the catalog with Admin or Editor permissions on the catalog.
DELETE /v2/catalogs/{catalog_id}/members/bulkRequest
Path Parameters
catalog GUID
Query Parameters
Comma-separated list of Member GUIDs, with a maximum of 20.
Type of the members specified in the
member_idsparameter. Specifyuserorgroupif all members are user or access group IDs. Ifmember_idscontains a mixture of user or group IDs, then specifyallformember_typeor alternatively do not specify any value. Ifmember_typeisallor not specified, usemember_typesto indicate the type of each member inmember_idsAllowable values: [
user,group,all]Comma-separated list of types for each member specified in
member_ids. The supported types areuserandgroup. If bothmember_typesandmember_typeparameters are specified,member_typestakes precedence overmember_type. Ifmember_typesis not specified, andmember_typeis not specified or isall, the API will attempt to determine the member type based on the member ID. In a CPD environment, user and access group IDs are numeric and have no prefix indicating whether the ID represents a user or group ID, somember_typesshould be specified ifmember_idscontains a mixture of user and access group IDs
Get catalog membership for a specific user
Returns any memberships this user has on the catalog, including direct membership and any access group memberships.
GET /v2/catalogs/{catalog_id}/members/{member_id}Request
Path Parameters
catalog GUID
member ID
Query Parameters
Should resolve member roles from usergroup(s) and collaborator roles
Default:
falseType of the member specified by the member_id. If not specified, the service will determine if the member is a user or an access group based on the member_id, which is not always possible or accurate. Always supplying the member type is recommended.
Allowable values: [
user,group]IAM Profile ID for Trusted Profile users: If the getMemberV2 API is called to fetch details for a Trusted Profile, the member_id is the IAM ID of the actual user, and the profile_id will be the IAM ID of the trusted user. For IBM users and App ID users, this value should be null.
Delete a member from a catalog
Delete a member from a catalog.
DELETE /v2/catalogs/{catalog_id}/members/{member_id}Request
Path Parameters
catalog GUID
Member GUID
Query Parameters
Type of the member specified by the member_id. If not specified, the service will determine if the member is a user or an access group based on the member_id, which is not always possible or accurate. Always supplying the member type is recommended.
Allowable values: [
user,group]
Update members in a catalog
Update a member of a catalog.
PATCH /v2/catalogs/{catalog_id}/members/{member_id}Request
Path Parameters
catalog GUID
Member GUID
Query Parameters
Type of the member specified by the member_id. If not specified, the service will determine if the member is a user or an access group based on the member_id, which is not always possible or accurate. Always supplying the member type is recommended.
Allowable values: [
user,group]
Member updates
Response
Identity and Access Management ID (IAM) of the member
Example:
IBMid-abcd1234ID of the access group member
Example:
AccessGroupId-abcd1234Role of the member in the Catalog
Example:
admin(Deprecated) User id like user email address of the member.
Example:
xyz@ibm.comPossible values: contains only unique items
Read only - The date and time when the member is added to the catalog
Status Code
Updated
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
Create a data asset
You can use this API to add data assets to a catalog. Data assets could be data from a connection to a data source (ex. tables) or files from your local system uploaded into cloud object storage associated with Projects or Catalog.All asset types have a common set of properties, such as name, description, asset type, visibility, tags, classifications. Data Asset have additional attributes such as mime type, columns with types, and properties. Use v2/attachments API to indicate location of data (ex. table path) from a connection to a data source.
POST /v2/data_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Data Asset Metadata
- Examples:
{ "data_asset": { "mime_type": "text/csv", "dataset": false } }- entity
AssetMetadata Model
Get a data asset
Use this API to retrieve metadata about a data asset. The response document will contain three top-level fields:
- 'metadata': contains metadata common to all types of assets
- 'entity': contains metadata specific to the asset_type - in this case 'data_asset'
- 'attachments': an array containing one item of metadata per attached resource
The data described by the above metadata is stored in attached resources. Examples of attached resources are database tables, csv files, word documents, extended metadata documents, etc. Because an item in the 'attachments' array only contains metadata about an attached resource, accessing the actual attached resource requires additional server calls. Exactly which additional server calls are needed depends on the kind of attached resource. Follow the steps below to access an attached resource.
Step 1: find the index i of the item in the above 'attachments' array whose 'asset_type' value matches the type of the attached resource you want to access. For a 'data_asset' attached resource look for the item i where 'attachments[i].asset_type' is 'data_asset'.
There are two important pairs of fields (among many others) which may appear in 'attachments[i]'. Only one of those pairs will actually appear. Which pair appears influences which steps to perform next. - Pair 1: 'connection_id' and 'connection_path':
- The above two fields will appear in 'attachments[i]' if the value of 'attachments[i].is_remote' is true.
- 'attachments[i].is_remote' WILL be true if the attached resource is a database table. In this case, 'attachments[i].connection_path' will contain a schema name and table name.
- 'attachments[i].is_remote' MAY be true if the attached resource is, for example, a csv file. In this case, 'attachments[i].connection_path' will contain a folder path and file name.
If the above pair of fields are present in 'attachments[i]' then:
Step 2: use the value of the 'attachments[i].connection_id' field to make a call to the GET /v2/connections/{connection_id} API. You'll need appropriate credentials.
Step 3: use the values in the 'entity.properties' field of the result from Step 2 to either create a connection to the database containing the table or to retrieve the file.
Note: even if 'attachments[i].is_remote' is true and the above pair of fields are present in 'attachments[i]', if the attached resource is located in the catalog/project bucket then you may optionally perform the two steps discussed for Pair 2 ('object_key' and 'handle') below.
- Pair 2: 'object_key' and 'handle':
- The above two fields will appear in 'attachments[i]' if the value of 'attachments[i].is_remote' is false. In this case, 'attachments[i].handle' will contain information about the attached resource.
Step 2: use the value of the 'attachments[i].id' field as the value for 'attachment_id' in a call to the GET /v2/assets/{asset_id}/attachments/{attachment_id} API. The value to use for 'asset_id' in the call to the attachments API is the same as the value that was used for 'data_asset_id' in the original call to the GET /v2/data_assets/{data_asset_id} API.
Step 3: use the value in the 'url' field of the result from Step 2 to download (for example, with a browser) a copy of the file.
- The above two fields will appear in 'attachments[i]' if the value of 'attachments[i].is_remote' is false. In this case, 'attachments[i].handle' will contain information about the attached resource.
GET /v2/data_assets/{data_asset_id}Request
Path Parameters
data_asset_id
Query Parameters
catalog_id
project_id (only catalog_id is supported at this time)
space_id (only catalog_id is supported at this time)
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Get columns of a data asset
Use this API to retrieve columns of a data asset located in catalog or project. Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Catalog. Data assets in ungoverned catalogs are not subject to governance policies.
GET /v2/data_assets/{data_asset_id}/columnsRequest
Path Parameters
data_asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The maximum number of items to return
Default:
100The bookmark for the next page of results, received from a previous call.
Sorting the columns, e.g., 'data_asset.columns', '-column_info.column_info_quality_score', 'data_asset.columns,column_info.column_info_quality_score
Filter columns by name, e.g., 'A*'
Create a folder asset
You can use this API to add folder assets to a catalog. Folder assets are similar to folders or directories in a file system. In the same way that a directory in a file system can contain many files, a folder asset can represent groups of files or objects all sharing a common path. An example of a path may be '/sales_data/by_month/february'. There may be many different files with that common path, but we only need to register just the common path when we create a folder asset.
Along with other types of assets, such as data assets, folder assets share a common set of properties such as name, description, asset type, visibility, tags, classifications, etc. In addition to other types of assets, folder assets are denoted by a folder_asset json object within the common entity object. The folder_asset json object contains a connection_id, and a connection_path. E.g.,
{
"metadata":{...},
"entity":{
"folder_asset":{
"connection_id":"f1fea17c-a7e5-49e4-9f8e-23cef3e11ed5",
"connection_path":"/bucket1/folder1/folder1.1"
}
}
}
A folder asset can be mediated by a connection. In other words, you can access the contents of the folder asset only through a connection in the connection service. The connection can be to any external data store such as DashDB, Salesforce.com,IBM's Cloud Object Storage, etc. You must specify the connection_id and the connection_path within the folder_asset json object.
Folder assets can also be local to the catalog or project, similar to local or referenced data attachments. For such a folder asset you don't need the connection_id in the folder_asset json. You only need to provide the connection_path. The API can use it's internal connection to asset storage associated with the catalog/project/space (Cloud Object Storage in IBM Cloud, or Asset Files storage in CPD) for accessing that folder.
A connection path is like the path of a folder or a directory in a file system. Using IBM Cloud Object Storage as an example, a connection_path for a folder object might be /Bucket1/monthly_data_collection/March. Any objects falling under that path are part of the folder asset. This API cannot show you those files directly. Instead, you can use your IBM Cloud Object Storage connection to traverse to that folder location and retrieve the files.
POST /v2/folder_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Folder Asset Metadata
- Examples:
{ "folder_asset": { "connection_id": "f1fea17c-a7e5-49e4-9f8e-23cef3e11ed5", "connection_path": "/bucket1/folder1/folder1.1" } }- entity
AssetMetadata Model
Get a folder asset
Use this API to retrieve metadata about a folder asset.
GET /v2/folder_assets/{asset_id}Request
Path Parameters
Enter the id of the folder asset whose metadata you want to retrieve.
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated.Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Get a signed URL of an item to be downloaded
If you have created folder assets for things that you store in IBM Cloud Object Storage, you can download individual contents of that folder. Every item within a folder has a path within that folder. For example there may be a folder asset in IBM Cloud Object Storage whose path is /bucket1/retail_sales/cosmetics. Within that folder, there may be several individual files. You can download these files with this API. When you call the API, you will receive a URL that, when you invoke it with a GET HTTP command, you can download a file that is within that folder.
GET /v2/folder_assets/{asset_id}/contentsRequest
Path Parameters
Enter the id of the folder asset whose content you want to download.
Query Parameters
The path to the object from where the folder leaves off. For example if your folder path is
/Bucket1/homedecoreand your object path is/bathrooms/sinkaccessories/soapdish1000.jpgthen the API will return a signed URL that includes the full object key/Bucket1/homedecore/bathrooms/sinkaccessories/soapdish1000.jpg.You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
The type of content you will download. Default is
application/octet-streamDefault:
application/octet-streamcontent_disposition specifies how you want the content downloaded. The default is as an attachment (i.e. a separate file).
Default:
attachment
List all assets in the trash (Marked for delete)
Retrieve all assets in the trash (Marked for delete.
GET /v2/trashed_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
older than the given timestamp. Format: "yyyy-MM-dd'T'hh:mm:ss[.sss]X" Example '2017-11-23T00:00:00-12', '2017-11-23T23:59:59.999Z', etc.
newer than the given timestamp. Format: "yyyy-MM-dd'T'hh:mm:ss[.sss]X" Example '2017-11-23T00:00:00-12', '2017-11-23T23:59:59.999Z', etc.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated.Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falselimit
Default:
25bookmark
Get count of all assets in the trash (Marked for delete)
Get count of all assets in the trash (Marked for delete.
GET /v2/trashed_assets/count
Delete all assets from trash
Delete all assets from trash.
If number of assets in trash is less than or equal to 20 , the assets will be deleted synchrnonously and response will be 204 - No Content.
If number of assets in trash is more than 20, the assets will be deleted asynchrnonously, response will be 202 - Accepted and the status can be tracked using /v2/trashed_assets/count.
DELETE /v2/trashed_assets/purge_all
Get a soft-deleted object from trash
Get a soft-deleted object from trash.
GET /v2/trashed_assets/{asset_id}Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Restore an asset from the trash
Restore an asset from the trash.
POST /v2/trashed_assets/{asset_id}/restoreRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseAction to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
List defined connections
Lists defined connections.
Connections created with shared credentials will return secrets such as database passwords and API keys in clear text. Such secrets are stored encrypted but will be decrypted by the API when retrieved by the caller in order to access the data source defined by the connection. Clear text credentials are allowed because it is understood that the caller has already been explicitly added as a collabaorator in the project or catalog in which the connection is stored and is thus implicitly permitted access to the credentials required to connect to a data source.
Connections created with personal credentials will only display clear text credentials to the same user who provided them.
Use the following parameters to sort the results:
| Field | Example | | ------------------------- | ----------------------------------- | | entity.name | ?_sort=+entity.name | | metadata.create_time | ?_sort=-metadata.create_time |
Use the following parameters to filter the results:
| Field | Example | |-------------------------- | ----------------------------------- | | entity.name | ?entity.name=MyConnection | | entity.datasource_type | ?entity.datasource_type=<asset_id> | | entity.context | ?entity.context=source | | entity.properties | ?entity.properties={"name":"value"} | | entity.flags | ?entity.flags=+personal_credentials | | metadata.creator_id | ?metadata.creator_id=userid |
Filtering is done by specifying the fields to filter on.
To filter on the properties of a connection, the exact values to compare must be provided in the entities.properties field and all values supplied must exactly match a property of a connection.
The entity.flags field specifies the flags a connection can have to be included in the list results. By default, all connections with no flags are returned.
Adding the name of a flag to entity.flags will add the connections with that flag to the list results. The name can be optionally prefixed with a plus sign (+) to indicate that it is being added.
Adding the name of a flag to entity.flags with a minus sign (-) prefix will remove those connections with that flag from the list results. All additions are done before the subtractions.
GET /v2/connections
Request
Custom Headers
Boolean indicator if cluster username and access token should be injected into connection properties. It has to be ensured that access token is not revealed unintentionally together with connection properties.
Default:
false
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseThe field to sort the results on, including whether to sort ascending (+) or descending (-), for example, sort=-metadata.create_time
The page token indicating where to start paging from.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The creator of the connection.
The name of the connection.
The data source type of the connection. To specify multiple data source types, use a comma-separated string, such as entity.datasource_type=<asset_id>,<asset_id>.
The context of the connection. Can be one of "source", "target", or "source,target".
The properties of the connection that must match for the connection to be included in the list.
A comma separated list of flags that must be present for the connection to be included in the list. If not provided, only connections with no flags will be returned.
Whether to return information about source and target interaction properties.
Whether to return decrypted secrets for unrestricted connections.
Default:
trueWhether to return information about connection and interaction properties.
Default:
true
Response
A page from a collection of connections.
List of connections
The number of assets skipped before this page.
The total number of assets available.
Status Code
Connections with metadata.
You are not authorized to list the defined connections.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The defined connections cannot be listed.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Define connection
Defines a connection.
By default, a connection is created with shared credentials. Though credentials' secrets are stored encrypted, all credentials including secrets will be visible in clear text to API users who retrieve the connection and who are collaborators of the project or catalog in which a connection with shared credentials has been created.
Alternatively, a connection can be created with personal credentials by using the personal_credentials flag. The credentials' secrets will be visible only to the user who created the connection.
POST /v2/connections
Request
Custom Headers
The indicator whether shared credentials disablement and vault credentials enforcement guards should be disabled for creation and updates
Default:
false
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseWhether to test the connection before saving it. By default an attempt to establish a connection will be made, and the connection will not be saved if the connection cannot be established.
Default:
trueWhether to persist assets or changes on assets. If set to false, it makes the service to perform all the actions on the way, execute testing, inject properties (like satellite properties or vault properties), if applicable, and then return the object as it would look like if persisted + with all the usual additioanl elements of response properties returned via Java API (like interaction_properties), but metadata record itself that gets filled with properties from the response from CAMS service is not filled, so it only contains those properties that are set directly from the entity taken from payload.
Default:
true
The definition of the connection.
The id or the name of the data source type to connect to. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7" or "db2".
The name of the connection.
The id of the data source definition asset related to connection. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7".
The name of the data source definition asset related to connection. For example "Data privacy profile for DB2".
The concatenation of values of conection properties identified as data source definition asset identity properties. For example "host1.fyre.ibm.com|12212|BLUEDB".
Properties that are not stored and obtained from CAMS, but calculated/derived on-the-fly by reading operation
The description of the connection.
Folder that the connection asset lives in.
The ID of the catalog that this connection refers to for properties values.
The ID of the connection in reference catalog that this connection refers to for properties values.
The id of the secure gateway to use with the connection. A Secure Gateway is needed when connecting to an on-premises data source. This is the id of the Secure Gateway created with the SecureGateway Service. Your Secure Gateway Client running on-premises must be connected to the gateway with this Id. For example, "E9oXGRIhv1e_prod_ng".
Specifies how a connection is to be treated internally.
Allowable values: [
restricted,internal_use_only,personal_credentials,parameterized]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Connection properties.
- properties
- any property
Interaction properties allowed for a connection.
Custom data to be associated with a given object
- source_system
The asset category
Allowable values: [
user,system]Indicates the location used by this connection.
Response
A connection.
System metadata about an asset
The connection definition.
Status Code
The connection was created.
The connection test failed. See the error message for details.
You are not authorized to define a connection.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. A connection was not created.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Get connection
Gets details of a specific connection definition.
Connections created with shared credentials will return secrets such as database passwords and API keys in clear text. Such secrets are stored encrypted but will be decrypted by the API when retrieved by the caller in order to access the data source defined by the connection. Clear text credentials are allowed because it is understood that the caller has already been explicitly added as a collabaorator in the project or catalog in which the connection is stored and is thus implicitly permitted access to the credentials required to connect to a data source.
Connections created with personal credentials will only display clear text credentials to the same user who provided them.
GET /v2/connections/{connection_id}Request
Custom Headers
Boolean indicator if cluster username and access token should be injected into connection properties. It has to be ensured that access token is not revealed unintentionally together with connection properties.
Default:
false
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseSpecify the product the data source type must support to be returned. The available products are 'catalog', 'cpd', 'datastage', 'dv', 'igc', 'mdi', 'ml' and 'studio'. If no entity.product is specified, no filtering is applied. To specify multiple products, use a comma-separated string, such as entity.product=catalog,studio.
Whether to return information about source and target interaction properties.
Whether to return decrypted secrets for unrestricted connections.
Default:
true
Response
A connection.
System metadata about an asset
The connection definition.
Status Code
The connection object.
You are not authorized to get details about the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection definition details cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Delete connection
Deletes a connection definition. This call does not check whether the connection is used by activities, data sets or other assets. The caller must check this before deleting a connection.
DELETE /v2/connections/{connection_id}Request
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
false
Response
Status Code
The connection was deleted.
You are not authorized to delete a connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection was not deleted.
No Sample Response
Request
Custom Headers
The indicator whether shared credentials disablement and vault credentials enforcement guards should be disabled for creation and updates
Default:
false
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseWhether to test the connection before saving it. By default an attempt to establish a connection will be made, and the connection will not be saved if the connection cannot be established.
Default:
trueWhether to persist assets or changes on assets. If set to false, it makes the service to perform all the actions on the way, execute testing, inject properties (like satellite properties or vault properties), if applicable, and then return the object as it would look like if persisted + with all the usual additioanl elements of response properties returned via Java API (like interaction_properties), but metadata record itself that gets filled with properties from the response from CAMS service is not filled, so it only contains those properties that are set directly from the entity taken from payload.
Default:
true
Fields to update within the connection.
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
The connection definition.
The id or the name of the data source type to connect to. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7" or "db2".
The name of the connection.
The id of the data source definition asset related to connection. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7".
The name of the data source definition asset related to connection. For example "Data privacy profile for DB2".
The concatenation of values of conection properties identified as data source definition asset identity properties. For example "host1.fyre.ibm.com|12212|BLUEDB".
Properties that are not stored and obtained from CAMS, but calculated/derived on-the-fly by reading operation
The description of the connection.
Folder that the connection asset lives in.
The ID of the catalog that this connection refers to for properties values.
The ID of the connection in reference catalog that this connection refers to for properties values.
The id of the secure gateway to use with the connection. A Secure Gateway is needed when connecting to an on-premises data source. This is the id of the Secure Gateway created with the SecureGateway Service. Your Secure Gateway Client running on-premises must be connected to the gateway with this Id. For example, "E9oXGRIhv1e_prod_ng".
Specifies how a connection is to be treated internally.
Possible values: [
restricted,internal_use_only,personal_credentials,parameterized]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Connection properties.
- properties
- any property
Interaction properties allowed for a connection.
Custom data to be associated with a given object
- source_system
The asset category
Possible values: [
user,system]Indicates the location used by this connection.
Status Code
The updated connection definition object.
The connection test failed. See the error message for details.
You are not authorized to update the connection definition.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection definition was not updated.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
The page token indicating where to start paging from.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100Whether to calculate resource keys for updated connections.
Default:
falseWhether to calculate data_source_definition_searchable property for updated connections.
Default:
false
Response
Result of connection upgrade request.
- any property
Status Code
The connections were upgraded.
Bad request. See the error message for details.
You are not authorized to define a connection.
You are not permitted to perform this action.
An error occurred. Connections were not updated.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Discover assets
Discovers assets from the data source accessed via a connection description.
POST /v2/connections/assets
Request
Custom Headers
Specify whether to return the asset's data in parsed form (application/json) or as raw bytes. This only applies to sources that produce data as a file, document or stream of bytes. To return bytes specify application/octet-stream.
Query Parameters
Path of the asset.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0Specify whether to return the asset's metadata, the asset's data, interaction properties, connection properties, or data source type. If not specified, metadata is used by default. This parameter only applies when requesting details about a data set. To specify multiple fetch values, use a comma-separated string, such as fetch=data,metadata,interaction,connection,datasource_type.
Specify whether to return additional asset-specific details. If not specified, these details are not returned.
Specify whether assets are discovered for the purpose of reading (source) or writing (target). If not specified, source is used by default.
Allowable values: [
source,target]A JSON object containing a set of properties to configure aspects of the asset browsing.
A JSON object containing a set of properties to define filtering of the assets to be returned.
The connection definition.
The id or the name of the data source type to connect to. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7" or "db2".
The name of the connection.
The id of the data source definition asset related to connection. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7".
The name of the data source definition asset related to connection. For example "Data privacy profile for DB2".
The concatenation of values of conection properties identified as data source definition asset identity properties. For example "host1.fyre.ibm.com|12212|BLUEDB".
Properties that are not stored and obtained from CAMS, but calculated/derived on-the-fly by reading operation
The description of the connection.
Folder that the connection asset lives in.
The ID of the catalog that this connection refers to for properties values.
The ID of the connection in reference catalog that this connection refers to for properties values.
The id of the secure gateway to use with the connection. A Secure Gateway is needed when connecting to an on-premises data source. This is the id of the Secure Gateway created with the SecureGateway Service. Your Secure Gateway Client running on-premises must be connected to the gateway with this Id. For example, "E9oXGRIhv1e_prod_ng".
Specifies how a connection is to be treated internally.
Allowable values: [
restricted,internal_use_only,personal_credentials,parameterized]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Connection properties.
- properties
- any property
Interaction properties allowed for a connection.
Custom data to be associated with a given object
- source_system
The asset category
Allowable values: [
user,system]Indicates the location used by this connection.
Response
A page from a collection of discovered assets.
A page from a collection of discovered assets.
The path of the asset.
An ID for the asset.
Properties defining the returned assets.
- properties
- any property
Discovered types
Discovered assets
Discovered fields
The definition of a data source type.
Connection properties.
- connection_properties
- any property
The interaction properties needed to find the asset.
- interaction_properties
- any property
Extended metadata properties
The data returned when the fetch parameter contains the value "data".
- data
Details about a discovered asset.
- details
- any property
The number of assets skipped before this page.
The total number of assets available.
Log events created during the discovery of the assets.
Status Code
The discovered assets.
You are not authorized to discover assets.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No assets were found.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Discover assets
Discovers assets from the data source accessed via the connection.
GET /v2/connections/{connection_id}/assetsRequest
Custom Headers
Specify whether to return the asset's data in parsed form (application/json) or as raw bytes. This only applies to sources that produce data as a file, document or stream of bytes. To return bytes specify application/octet-stream.
Path Parameters
The ID of the connection.
Query Parameters
Path of the asset.
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseThe ID of the data asset.
The ID of the catalog that contains the data asset.
The ID of the project that contains the data asset.
The ID of the space that contains the data asset.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0Specify whether to return the asset's metadata, the asset's data, interaction properties, connection properties, or data source type. If not specified, metadata is used by default. This parameter only applies when requesting details about a data set. To specify multiple fetch values, use a comma-separated string, such as fetch=data,metadata,interaction,connection,datasource_type.
Specify whether to return additional asset-specific details. If not specified, these details are not returned.
Specify whether assets are discovered for the purpose of reading (source) or writing (target). If not specified, source is used by default.
Allowable values: [
source,target]A JSON object containing a set of properties to configure aspects of the asset browsing.
A JSON object containing a set of properties to define filtering of the assets to be returned.
Response
A page from a collection of discovered assets.
A page from a collection of discovered assets.
The path of the asset.
An ID for the asset.
Properties defining the returned assets.
- properties
- any property
Discovered types
Discovered assets
Discovered fields
The definition of a data source type.
Connection properties.
- connection_properties
- any property
The interaction properties needed to find the asset.
- interaction_properties
- any property
Extended metadata properties
The data returned when the fetch parameter contains the value "data".
- data
Details about a discovered asset.
- details
- any property
The number of assets skipped before this page.
The total number of assets available.
Log events created during the discovery of the assets.
Status Code
The discovered assets.
You are not authorized to discover assets in the data source accessed through the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No assets were discovered in the data source.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
Custom Headers
Specify whether to return the asset's data in parsed form (application/json) or as raw bytes. This only applies to sources that produce data as a file, document or stream of bytes. To return bytes specify application/octet-stream.
Path Parameters
The ID of the data asset.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseThe limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0Specify whether to return the asset's metadata, the asset's data, interaction properties, connection properties, or data source type. If not specified, metadata is used by default. This parameter only applies when requesting details about a data set. To specify multiple fetch values, use a comma-separated string, such as fetch=data,metadata,interaction,connection,datasource_type.
Specify whether to return additional asset-specific details. If not specified, these details are not returned.
Specify whether assets are discovered for the purpose of reading (source) or writing (target). If not specified, source is used by default.
Allowable values: [
source,target]A JSON object containing a set of properties to configure aspects of the asset browsing.
A JSON object containing a set of properties to define filtering of the assets to be returned.
Path of the asset.
Response
A page from a collection of discovered assets.
A page from a collection of discovered assets.
The path of the asset.
An ID for the asset.
Properties defining the returned assets.
- properties
- any property
Discovered types
Discovered assets
Discovered fields
The definition of a data source type.
Connection properties.
- connection_properties
- any property
The interaction properties needed to find the asset.
- interaction_properties
- any property
Extended metadata properties
The data returned when the fetch parameter contains the value "data".
- data
Details about a discovered asset.
- details
- any property
The number of assets skipped before this page.
The total number of assets available.
Log events created during the discovery of the assets.
Status Code
The discovered asset.
You are not authorized to discover the asset.
You are not permitted to perform this action.
The asset cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No assets were discovered in the data source.
A timeout occurred when processing your request. Please retry later.
No Sample Response
List actions
Lists all supported actions for the connection.
GET /v2/connections/{connection_id}/actionsRequest
Custom Headers
The user's preferred locale identifier.
Default:
en-US
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
false
Response
Connection actions.
The actions supported for the data source.
Status Code
The actions supported for the connection.
You are not authorized to list the actions for the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The actions for the connection cannot be listed.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Perform action
Performs an action on the data source accessed using the connection.
PUT /v2/connections/{connection_id}/actions/{action_name}Request
Path Parameters
The ID of the connection.
The name of the action to be performed. This list is expanded over time. The current actions are:
| action | description | | --------------------- | ------------------------------------------------------------------------ | | get_dsd_details | to obtain Data Source Definition Asset details from a connector. | | get_oauth2_tokens | to get refresh and authorization tokens for sources that support OAuth2. | | get_record_count | to get the number of records available for the specified asset. | | get_signed_url | to get a signed URL for accessing a data source. | | test | to check if a connection can be established to the data source. | | validate | to validate the connection properties without establishing a connection. |
Allowable values: [
get_dsd_details,get_oauth2_tokens,get_record_count,get_signed_url,test,validate]
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
false
The perform action request configuration.
- any property
Response
Results of a connection perform action request.
- any property
Status Code
Any output produced by the action.
The perform action request is invalid.
You are not authorized to perform an action on a data source accessed through the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No action was performed on the data source.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Response
Status Code
The file object.
You are not authorized to get content of the file.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Upload a file
Upload a file and get back a signed handle in 'Location' header with a hash
POST /v2/connections/files/{file_name}Response
Status Code
The file object.
You are not authorized to get content of the file.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Response
Status Code
The file was deleted.
You are not authorized to get content of the file.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
Query Parameters
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0
Response
A page from a collection of uploaded files.
List of uploaded files
The number of assets skipped before this page.
The total number of assets available.
Status Code
List of available files
You are not authorized to get the list of files.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
Query Parameters
Indicator, if only list files to be migrated.
Indicator, if migrate connections from catalogs.
Indicator, if migrate connections from projects.
Indicator, if migrate connections from spaces.
Response
A page from a collection of migrated connections.
List of migrated connections
The number of assets available.
The name of the log with migration process logging.
List of exceptions encountered durring the migration process.
Status Code
List of newly uploaded files
You are not authorized to migrate files.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
List defined types of data sources
Gets all defined types of data sources.
The following fields are available for use with the sort parameter:
| field name | description | | ------------ | ---------------------------------------------------- | | entity.label | The name of the data source type in a readable form. | | entity.type | The major type of the data source type. |
GET /v2/datasource_types
Request
Custom Headers
The user's preferred locale identifier.
Default:
en-US
Query Parameters
The field to sort the results on, including whether to sort ascending (+) or descending (-), for example, sort=-metadata.create_time
The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100Whether to return information about connection properties.
Whether to return information about source and target interaction properties.
Whether to return information about discovery capabilities.
Whether to return information about supported actions.
Specify the environment the data source types must support to be included in the returned list. The available environments are 'cloud', 'streams' and 'local'. If no entity.environment is specified, the default for service's deploy environment is used. To specify multiple environments, use a comma-separated string, such as entity.environment=cloud,streams.
Specify the product the data source type must support to be returned. The available products are 'catalog', 'cpd', 'datastage', 'dv', 'igc', 'mdi', 'ml' and 'studio'. If no entity.product is specified, no filtering is applied. To specify multiple products, use a comma-separated string, such as entity.product=catalog,studio.
Scope of ui-only product selector property. Applies to output under common_properties key. Genreated ui contains additional checkbox to switch between first of the requested products and the rest. If only a single one is given it switches between that product and remaining products supported by the data source.
Allowable values: [
global,context]Whether to generate extra conditions in common properties format that will make them behave in a transitive manner under default configuration options of Elyra i.e. when a condition is part of a chain it will enable/disable everything down the chain rather than just hiding the control. Support for this option has been removed. Option itself was not removed to preserve binary compatibility but it no longer has any effect.
Default:
falseWhether to filter the list of available datasource types and return only those that have their dataSourceDefinitionId parameter set and its value is the same as the value of the datasource type id. That means that returned are only datasource types which should have proper deep enforcement in Data Privacy Service supported and are the canonical types (not the connectors that use the same engine, but have a different flavor).
Default:
false
Response
A page from a collection of data source types.
List of data source types
The number of assets skipped before this page.
The total number of assets available.
Status Code
Collection of data source types.
You are not authorized to list the defined types of data sources.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No data source types were retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
The definition of the data source type.
Information needed to connect to a custom Arrow Flight service.
The UUID of the base datasource type for this custom datasource type
A unique name, such as "dashdb".
A localized, displayable label such as, "IBM dashDB".
A localized, displayable description of the data source.
Whether the data source can be accessed as a source of data. That is, data can be read from the data source.
Whether the data source can be accessed as a target. That is, data can be written to the data source.
The definition of the discovery features of the data source type.
Custom data to be associated with a given object
- properties
Definition of a data source property for a custom datasource type.
The status of the data source.
Allowable values: [
active,deprecated,inactive,internal,pending,system]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Custom data to be associated with a given object
- source_system
Tags associated with a data source type.
The actions supported for the data source.
Response
A collection of custom data source types.
List of data source types
Status Code
The data source type was created.
The data source type definition is not valid. See the error message for details.
You are not authorized to define a data source type.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. A data source type was not created.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Get details for type of data source
Get details for type of data source.
GET /v2/datasource_types/{datasource_type}Request
Custom Headers
The user's preferred locale identifier.
Default:
en-US
Path Parameters
The data source type.
Query Parameters
Whether to return information about connection properties.
Whether to return information about source and target interaction properties.
Whether to return information about discovery capabilities.
Whether to return information about supported actions.
Specify the environment the data source types must support to be included in the returned list. The available environments are 'cloud', 'streams' and 'local'. If no entity.environment is specified, the default for service's deploy environment is used. To specify multiple environments, use a comma-separated string, such as entity.environment=cloud,streams.
Specify the product the data source type must support to be returned. The available products are 'catalog', 'cpd', 'datastage', 'dv', 'igc', 'mdi', 'ml' and 'studio'. If no entity.product is specified, no filtering is applied. To specify multiple products, use a comma-separated string, such as entity.product=catalog,studio.
Scope of ui-only product selector property. Applies to output under common_properties key. Genreated ui contains additional checkbox to switch between first of the requested products and the rest. If only a single one is given it switches between that product and remaining products supported by the data source.
Allowable values: [
global,context]Whether to generate extra conditions in common properties format that will make them behave in a transitive manner under default configuration options of Elyra i.e. when a condition is part of a chain it will enable/disable everything down the chain rather than just hiding the control. Support for this option has been removed. Option itself was not removed to preserve binary compatibility but it no longer has any effect.
Default:
false
Response
The definition of a data source type.
System metadata about an asset
The definition of a data source type.
Status Code
A data source type definition.
You are not authorized to retrieve the type details of the data source.
You are not permitted to perform this action.
The data source type details cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No data source type details were retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Delete data source type
Deletes a data source type definition. This call does not check whether the data source type is used by connections or other assets. The caller must check this before deleting a data source type.
DELETE /v2/datasource_types/{datasource_type}Response
Status Code
The data source type was deleted.
You are not authorized to delete a data source type.
You are not permitted to perform this action.
The data source type cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection was not deleted.
No Sample Response
Update datasource type
Updates the definition of a datasource type.
PATCH /v2/datasource_types/{datasource_type}Request
Path Parameters
The data source type.
Fields to update within the data source type.
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
The definition of a custom data source type.
Information needed to connect to a custom Arrow Flight service.
The UUID of the base datasource type for this custom datasource type
A unique name, such as "dashdb".
A localized, displayable label such as, "IBM dashDB".
A localized, displayable description of the data source.
Whether the data source can be accessed as a source of data. That is, data can be read from the data source.
Whether the data source can be accessed as a target. That is, data can be written to the data source.
The definition of the discovery features of the data source type.
Custom data to be associated with a given object
- properties
Definition of a data source property for a custom datasource type.
The status of the data source.
Possible values: [
active,deprecated,inactive,internal,pending,system]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Custom data to be associated with a given object
- source_system
Tags associated with a data source type.
The actions supported for the data source.
Status Code
The updated data source type definition object.
The data source type patch request is not valid. See the error message for details.
You are not authorized to update the data source type definition.
You are not permitted to perform this action.
The data source type cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The data source type definition was not updated.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Create a metadata enrichment area asset
Creates a new metadata enrichment asset and the corresponding job definition. If a data scope is provided the decoration of data scope assets will be started in background and the response will contain the execution ID of that background process. After background processing has finished a RabbitMQ event is sent to CAMS topic exchange CatalogServiceMessageHub with topic v2.metadata_enrichment.{mdeAreaId}.create_enrichment_area and message body as described in model RabbitMqNotificationMessage. If no data scope is provided an empty enrichment area is created without starting a background decoration task. In that case the field asyncExecutionInfo will be missing in the response. If query paramter enrichImmediate is true, which is the default setting, and the data scope is not empty a new enrichment job run will be triggered automatically.
POST /v2/metadata_enrichment/metadata_enrichment_area
Request
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
should enrichment be run immediately after area creation
Default:
true
Object containing information for creating a metadata enrichment area asset
name of the metadata enrichment asset
Example:
Sample enrichment- objective
- enrichment_options
- structured
true if profile is enabled for structured data. Required when creating and optional when updating.
true if assign terms is enabled for structured data. Required when creating and optional when updating.
true if analyze quality is enabled for structured data. Required when creating and optional when updating.
- unstructured
always true as profile is always enabled for unstructured data
true if assign terms is enabled for unstructured data
Required when creating and optional when updating.
- sampling
- structured
Set true to apply project level default settings to this metadata enrichment area.
Sampling method for this metadata enrichment area. The value is respected when project_default_settings is false.
Allowable values: [
RANDOM,TOP,TOP, RANDOM]Analysis method to use when sampling data. Either sample a
FIXEDnumber of rows or a givenPERCENTAGEof all table rows. The value is respected when project_default_settings is false. Providing this attribute is optional, if not specified, the analysis method defaults toFIXED.Allowable values: [
FIXED,PERCENTAGE,FIXED, PERCENTAGE]- sample_size
Allowable values: [
BASIC,COMPREHENSIVE,CUSTOM,MODERATE,BASIC, MODERATE, COMPREHENSIVE, CUSTOM]- options
Enrich top # of rows / table.
Example:
100Classify based on # values / column.
Example:
10
- percentage_options
Percentage of rows to enrich, as decimal
Example:
0.8Minimum number of rows to include in sampling
Example:
100Maximum number of rows to include in sampling
Example:
100Classify based on # values/columns.
Example:
10
- unstructured
sampling method
Allowable values: [
RANDOM]- sample_size
Allowable values: [
BASIC,COMPREHENSIVE,MODERATE,BASIC, MODERATE, COMPREHENSIVE]
Data scope of reruns
Allowable values: [
ALL,DELTA,DELTA, ALL]
description of the metadata enrichment area asset
Example:
This is a description for my sample metadata enrichment.Id of the catalog to metadata enrichment area assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5- job
Name of the metadata enrichment job
Example:
My Enrichment JobA cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 3 21 13 1 ? 2019- schedule_info
Indicate a repeated job
Example:
trueA timestamp in epoch time, the scheduled job will be triggered after this timestamp.
Example:
1547578689512A timestamp in epoch time, the scheduled job will be triggered before this timestamp.
Example:
1547578689512
- publish_job
Id of the metadata publish job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the MDE area publish job
Example:
My MDE area publish JobA cron string defining when the job should be run. This is going to be always empty as publish is not scheduled to run.
- data_scope
IDs of assets to enrich metadata
- container_assets
list of tags
Response
An object containing information about a metadata enrichment area asset
- metadata
The metadata enrichment area id assigned by the system. Read-only
Example:
4412e9b2-3661-11e7-a919-92ebcb67fe33The type of the asset
Example:
metadata_enrichment_areaThe IAM ID of the user that created the asset
Example:
IBMid-550000FRA0Timestamp representing creation datetime of metadata enrichment area asset read-only
Example:
1631089384058The ID of the project which contains the asset.
Example:
487084de-de8d-4981-9205-952732a90b3d- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
list of tags
- entity
name of the metadata enrichmentarea asset
Example:
my_emrichmentdescription of the metadata enrichment area asset
Example:
Enrichment of assetsId of the catalog to meetadata enrichment area assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5- job
Id of the metadata enrichment job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the metadata enrichment job
Example:
My Enrichment JobA cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 3 21 13 1 ? 2019- schedule_info
Indicate a repeated job
Example:
trueA timestamp in epoch time, the scheduled job will be triggered after this timestamp.
Example:
1547578689512A timestamp in epoch time, the scheduled job will be triggered before this timestamp.
Example:
1547578689512
- data_asset_summary
- structured
Number of structured data assets
Example:
1203
- unstructured
Number of unstructured data assets
Example:
890
- objective
- enrichment_options
- structured
true if profile is enabled for structured data. Required when creating and optional when updating.
true if assign terms is enabled for structured data. Required when creating and optional when updating.
true if analyze quality is enabled for structured data. Required when creating and optional when updating.
- unstructured
always true as profile is always enabled for unstructured data
true if assign terms is enabled for unstructured data
Required when creating and optional when updating.
- sampling
- structured
Set true to apply project level default settings to this metadata enrichment area.
Sampling method for this metadata enrichment area. The value is respected when project_default_settings is false.
Possible values: [
RANDOM,TOP,TOP, RANDOM]Analysis method to use when sampling data. Either sample a
FIXEDnumber of rows or a givenPERCENTAGEof all table rows. The value is respected when project_default_settings is false. Providing this attribute is optional, if not specified, the analysis method defaults toFIXED.Possible values: [
FIXED,PERCENTAGE,FIXED, PERCENTAGE]- sample_size
Possible values: [
BASIC,COMPREHENSIVE,CUSTOM,MODERATE,BASIC, MODERATE, COMPREHENSIVE, CUSTOM]- options
Enrich top # of rows / table.
Example:
100Classify based on # values / column.
Example:
10
- percentage_options
Percentage of rows to enrich, as decimal
Example:
0.8Minimum number of rows to include in sampling
Example:
100Maximum number of rows to include in sampling
Example:
100Classify based on # values/columns.
Example:
10
- unstructured
sampling method
Possible values: [
RANDOM]- sample_size
Possible values: [
BASIC,COMPREHENSIVE,MODERATE,BASIC, MODERATE, COMPREHENSIVE]
Data scope of reruns
Possible values: [
ALL,DELTA,DELTA, ALL]
Possible values: [
DELETING,FAILED,READY,UPDATING,READY, UPDATING, DELETING, FAILED]- publish_job
Id of the metadata publish job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the MDE area publish job
Example:
My MDE area publish JobA cron string defining when the job should be run. This is going to be always empty as publish is not scheduled to run.
- data_scope_processing
Example:
1631089384058If not null, retrys after this interval in millisecond.
Example:
8000Error messages while setting data scope
Status Code
Success
Unauthorized
Forbidden
Error
No Sample Response
Retrieve metadata enrichment settings
Retrieve metadata enrichment settings
GET /v2/metadata_enrichment/metadata_enrichment_area/settings
Create or update metadata enrichment settings
Create or update metadata enrichment settings
PUT /v2/metadata_enrichment/metadata_enrichment_area/settings
Retrieve details of a Metadata Enrichment Area asset
Retrieve details of a metadata enrichment area asset
GET /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}Request
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
whether to include data asset count summary in the response
Default:
false
Response
An object containing information about a metadata enrichment area asset
- metadata
The metadata enrichment area id assigned by the system. Read-only
Example:
4412e9b2-3661-11e7-a919-92ebcb67fe33The type of the asset
Example:
metadata_enrichment_areaThe IAM ID of the user that created the asset
Example:
IBMid-550000FRA0Timestamp representing creation datetime of metadata enrichment area asset read-only
Example:
1631089384058The ID of the project which contains the asset.
Example:
487084de-de8d-4981-9205-952732a90b3d- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
list of tags
- entity
name of the metadata enrichmentarea asset
Example:
my_emrichmentdescription of the metadata enrichment area asset
Example:
Enrichment of assetsId of the catalog to meetadata enrichment area assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5- job
Id of the metadata enrichment job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the metadata enrichment job
Example:
My Enrichment JobA cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 3 21 13 1 ? 2019- schedule_info
Indicate a repeated job
Example:
trueA timestamp in epoch time, the scheduled job will be triggered after this timestamp.
Example:
1547578689512A timestamp in epoch time, the scheduled job will be triggered before this timestamp.
Example:
1547578689512
- data_asset_summary
- structured
Number of structured data assets
Example:
1203
- unstructured
Number of unstructured data assets
Example:
890
- objective
- enrichment_options
- structured
true if profile is enabled for structured data. Required when creating and optional when updating.
true if assign terms is enabled for structured data. Required when creating and optional when updating.
true if analyze quality is enabled for structured data. Required when creating and optional when updating.
- unstructured
always true as profile is always enabled for unstructured data
true if assign terms is enabled for unstructured data
Required when creating and optional when updating.
- sampling
- structured
Set true to apply project level default settings to this metadata enrichment area.
Sampling method for this metadata enrichment area. The value is respected when project_default_settings is false.
Possible values: [
RANDOM,TOP,TOP, RANDOM]Analysis method to use when sampling data. Either sample a
FIXEDnumber of rows or a givenPERCENTAGEof all table rows. The value is respected when project_default_settings is false. Providing this attribute is optional, if not specified, the analysis method defaults toFIXED.Possible values: [
FIXED,PERCENTAGE,FIXED, PERCENTAGE]- sample_size
Possible values: [
BASIC,COMPREHENSIVE,CUSTOM,MODERATE,BASIC, MODERATE, COMPREHENSIVE, CUSTOM]- options
Enrich top # of rows / table.
Example:
100Classify based on # values / column.
Example:
10
- percentage_options
Percentage of rows to enrich, as decimal
Example:
0.8Minimum number of rows to include in sampling
Example:
100Maximum number of rows to include in sampling
Example:
100Classify based on # values/columns.
Example:
10
- unstructured
sampling method
Possible values: [
RANDOM]- sample_size
Possible values: [
BASIC,COMPREHENSIVE,MODERATE,BASIC, MODERATE, COMPREHENSIVE]
Data scope of reruns
Possible values: [
ALL,DELTA,DELTA, ALL]
Possible values: [
DELETING,FAILED,READY,UPDATING,READY, UPDATING, DELETING, FAILED]- publish_job
Id of the metadata publish job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the MDE area publish job
Example:
My MDE area publish JobA cron string defining when the job should be run. This is going to be always empty as publish is not scheduled to run.
- data_scope_processing
Example:
1631089384058If not null, retrys after this interval in millisecond.
Example:
8000Error messages while setting data scope
Status Code
Success
Unauthorized
Forbidden
Not found
Gone
Error
No Sample Response
Delete a metadata enrichment asset
Delete a metadata enrichment area asset
DELETE /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}edit a metadata enrichment area asset
Edit a metadata enrichment area asset
PATCH /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}Request
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Force the operation even when the metadata enrichment area is being updated.
Object carrying the update request.
name of the metadata enrichment area asset
Example:
Sample enrichmentdescription of the metadata enrichment area asset
Example:
This is a description for my sample metadata enrichment.Id of the catalog to metadata enrichment area assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5- job
Name of the metadata enrichment job
Example:
My Enrichment JobA cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 3 21 13 1 ? 2019- schedule_info
Indicate a repeated job
Example:
trueA timestamp in epoch time, the scheduled job will be triggered after this timestamp.
Example:
1547578689512A timestamp in epoch time, the scheduled job will be triggered before this timestamp.
Example:
1547578689512
- publish_job
Id of the metadata publish job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the MDE area publish job
Example:
My MDE area publish JobA cron string defining when the job should be run. This is going to be always empty as publish is not scheduled to run.
- objective
- enrichment_options
- structured
true if profile is enabled for structured data. Required when creating and optional when updating.
true if assign terms is enabled for structured data. Required when creating and optional when updating.
true if analyze quality is enabled for structured data. Required when creating and optional when updating.
- unstructured
always true as profile is always enabled for unstructured data
true if assign terms is enabled for unstructured data
Required when creating and optional when updating.
- sampling
- structured
Set true to apply project level default settings to this metadata enrichment area.
Sampling method for this metadata enrichment area. The value is respected when project_default_settings is false.
Allowable values: [
RANDOM,TOP,TOP, RANDOM]Analysis method to use when sampling data. Either sample a
FIXEDnumber of rows or a givenPERCENTAGEof all table rows. The value is respected when project_default_settings is false. Providing this attribute is optional, if not specified, the analysis method defaults toFIXED.Allowable values: [
FIXED,PERCENTAGE,FIXED, PERCENTAGE]- sample_size
Allowable values: [
BASIC,COMPREHENSIVE,CUSTOM,MODERATE,BASIC, MODERATE, COMPREHENSIVE, CUSTOM]- options
Enrich top # of rows / table.
Example:
100Classify based on # values / column.
Example:
10
- percentage_options
Percentage of rows to enrich, as decimal
Example:
0.8Minimum number of rows to include in sampling
Example:
100Maximum number of rows to include in sampling
Example:
100Classify based on # values/columns.
Example:
10
- unstructured
sampling method
Allowable values: [
RANDOM]- sample_size
Allowable values: [
BASIC,COMPREHENSIVE,MODERATE,BASIC, MODERATE, COMPREHENSIVE]
Data scope of reruns
Allowable values: [
ALL,DELTA,DELTA, ALL]
list of tags
Response
An object containing information about a metadata enrichment area asset
- metadata
The metadata enrichment area id assigned by the system. Read-only
Example:
4412e9b2-3661-11e7-a919-92ebcb67fe33The type of the asset
Example:
metadata_enrichment_areaThe IAM ID of the user that created the asset
Example:
IBMid-550000FRA0Timestamp representing creation datetime of metadata enrichment area asset read-only
Example:
1631089384058The ID of the project which contains the asset.
Example:
487084de-de8d-4981-9205-952732a90b3d- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
list of tags
- entity
name of the metadata enrichmentarea asset
Example:
my_emrichmentdescription of the metadata enrichment area asset
Example:
Enrichment of assetsId of the catalog to meetadata enrichment area assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5- job
Id of the metadata enrichment job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the metadata enrichment job
Example:
My Enrichment JobA cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 3 21 13 1 ? 2019- schedule_info
Indicate a repeated job
Example:
trueA timestamp in epoch time, the scheduled job will be triggered after this timestamp.
Example:
1547578689512A timestamp in epoch time, the scheduled job will be triggered before this timestamp.
Example:
1547578689512
- data_asset_summary
- structured
Number of structured data assets
Example:
1203
- unstructured
Number of unstructured data assets
Example:
890
- objective
- enrichment_options
- structured
true if profile is enabled for structured data. Required when creating and optional when updating.
true if assign terms is enabled for structured data. Required when creating and optional when updating.
true if analyze quality is enabled for structured data. Required when creating and optional when updating.
- unstructured
always true as profile is always enabled for unstructured data
true if assign terms is enabled for unstructured data
Required when creating and optional when updating.
- sampling
- structured
Set true to apply project level default settings to this metadata enrichment area.
Sampling method for this metadata enrichment area. The value is respected when project_default_settings is false.
Possible values: [
RANDOM,TOP,TOP, RANDOM]Analysis method to use when sampling data. Either sample a
FIXEDnumber of rows or a givenPERCENTAGEof all table rows. The value is respected when project_default_settings is false. Providing this attribute is optional, if not specified, the analysis method defaults toFIXED.Possible values: [
FIXED,PERCENTAGE,FIXED, PERCENTAGE]- sample_size
Possible values: [
BASIC,COMPREHENSIVE,CUSTOM,MODERATE,BASIC, MODERATE, COMPREHENSIVE, CUSTOM]- options
Enrich top # of rows / table.
Example:
100Classify based on # values / column.
Example:
10
- percentage_options
Percentage of rows to enrich, as decimal
Example:
0.8Minimum number of rows to include in sampling
Example:
100Maximum number of rows to include in sampling
Example:
100Classify based on # values/columns.
Example:
10
- unstructured
sampling method
Possible values: [
RANDOM]- sample_size
Possible values: [
BASIC,COMPREHENSIVE,MODERATE,BASIC, MODERATE, COMPREHENSIVE]
Data scope of reruns
Possible values: [
ALL,DELTA,DELTA, ALL]
Possible values: [
DELETING,FAILED,READY,UPDATING,READY, UPDATING, DELETING, FAILED]- publish_job
Id of the metadata publish job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the MDE area publish job
Example:
My MDE area publish JobA cron string defining when the job should be run. This is going to be always empty as publish is not scheduled to run.
- data_scope_processing
Example:
1631089384058If not null, retrys after this interval in millisecond.
Example:
8000Error messages while setting data scope
Status Code
Success
Unauthorized
Forbidden
Not found
Gone
Error
No Sample Response
Add or remove assets from data scope
Add or remove assets from data scope
PATCH /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scopeRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Force the operation even when the metadata enrichment area is being updated.
Object carrying the update request.
operation to perform
Allowable values: [
ADD,REMOVE,add, remove]Asset type. e.g. data_asset, metadata_import
Example:
data_assetID of the asset to add to or remove from the metadata enrichment area
Example:
30bc8c7a-ef65-4383-b9c6-d304bc191e26
Assign business terms to data assets
Add terms to given data assets. This api is executed synchronously. It verifies that all assets are part of the given MDE area. If validation fails method ends with an error.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/assign_termsRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
whether to process the request asynchronously
Default:
false
List of data assets and terms to assign
IDs of assets to enrich metadata
Assign business terms to columns of data assets
Add terms to given asset columns. This api is executed synchronously. It verifies that all assets are part of the given MDE area. If validation fails method ends with an error.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/assign_termsRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
whether to process the request asynchronously
Default:
false
List of columns of data assets and terms to assign
Assign or remove a data class to columns of data assets
Assign or remove data class to columns of data assets
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/dataclassRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
whether to process the request asynchronously
Default:
false
List of columns of data assets and id of data class and operation to be performed
Example:
b5568a7e-7fca-4824-8466-f18119096e81
Remove business terms from columns of data assets.
Removes either all terms or selected terms from given asset columns. When terms are provided with the payload only the given terms are removed from the given columns. If no terms are provided all terms are removed.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/remove_termsRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
whether to process the request asynchronously
Default:
false
List of columns of data assets and terms to assign
Adds or updates the review timestamp for given columns.
Adds/updates the 'reviewed' time stamp to/of the given asset columns.This api is executed synchronously. It fetches the assets that belong to the given columns via CAMS bulk get and verifies that all given assets are part of the given MDE area and are ready for review which means that either profiling or term assignment must be finished. It also validates that the columns exist on the asset. If validation fails the method returns an error. Otherwise for all given columns the review timestamp gets updated via CAMS bulk patch. Returns the new review timestamp.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/reviewRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Array containing list of asset Ids with columns.
asset_id
Example:
75985844-aa3f-410f-82be-9788ffd6ec75columns of an asset
Removes review timestamp for given columns.
Removes the 'reviewed' time stamp from the given asset columns. This api is executed synchronously. It fetches alle assets that belong to the given columns via CAMS bulk get and verifies that all given assets are part of the given MDE area. Assets that have no review data are skipped. It also validates that the columns exist on the asset. If validation fails the method returns an error. Otherwise for all given columns the review timestamp will be removed via CAMS bulk patch.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/unreviewRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Array containing list of asset Ids with columns.
asset_id
Example:
75985844-aa3f-410f-82be-9788ffd6ec75columns of an asset
Enrich selected data assets
Enrich selected data assets
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/enrichRemove business terms from data assets
Removes either all terms or selected terms from given list of data assets. When terms are provided with the payload only the given terms are removed from the given assets. If no terms are provided all terms are removed.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/remove_termsRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
whether to process the request asynchronously
Default:
false
List of data assets and terms to remove
IDs of assets to enrich metadata
Review a given list of data assets.
Adds/updates the 'reviewed' time stamp to/of given data assets. This api is executed synchronously. It fetches the given assets via CAMS bulk get and verifies that all given assets are part of the given MDE area and are ready for review which means that either profiling or term assignment must be finished. If validation fails the method returns an error. Otherwise the review timestamp of all assets gets updated via CAMS bulk patch. Returns the new review timestamp.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/reviewRemoves review timestamp from the given assets
Removes the 'reviewed' time stamp from the given data assets. This api is executed synchronously. It fetches the given assets via CAMS bulk get and verifies that all given assets are part of the given MDE area. Assets that have no review data are skipped. If validation fails the method returns an error. Otherwise the review timestamp is removed from of all assets via CAMS bulk patch.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/unreviewPublish all assets or a subset of assets of a Metadata Enrichment Area to a catalog
Publish assets asynchronously. If publishScope is 'selected_assets' either /asset_ids or /filter/search_criteria has to be specified. If publisScope is 'all_assets' none of both must be specified.
POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/publish_assetsRequest
Path Parameters
Id of the metadata enrichment area asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
tells if all assets in mde area should be published or only selected assets
Allowable values: [
all_assets,selected_assets]
Publish assets to a catalog
catalog Id
Example:
ae568a7e-7fca-4824-8466-f18119096e82action if asset already exists
Allowable values: [
IGNORE,REPLACE,UPDATE,replace, update, ignore]Example:
updateIDs of assets to enrich metadata
- filter
type of search
Allowable values: [
CATALOG_SEARCH,catalog_search]Asset type for catalog search.
Example:
metadata_enrichment_area_infoJSON object for search payload
Examples:{ "query": "asset.name:Asset* AND metadata_enrichment_area_info.area_id:62df1c42-53cd-4503-a6f5-f020aaabca72" }- search_criteria
Request
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
If this value is set to true, a Job is created together. The relation is also done between mdetadata import asset. The response message includes entity.jobId. The job name is generated from the name of metadata import with a unique suffix.
Default:
falseA candidate of Job name. The job is created with a specified name. If the name already exists, an error is returned. The create_job parameter should be set to true.
Object containing information for creating a metadata import asset
name of the metadata import asset
Example:
db2_tables_importList of the assets to be update with SAP Business Metdata
description of the metadata import asset
Example:
Import of a db2 tableThe type of the import. The possible values are 'metadata' and 'lineage'.
Allowable values: [
LINEAGE,METADATA,metadata, lineage]Id of the connection which is being discovered
Example:
96e2149d-6916-427b-bf98-a0cb989306d7List of connection_id which is being discovered
Examples:[ "69196df7-714f-416b-a49b-ea025cd5d5e7", "224a78fe-7946-4e10-b685-af7b5f047d0a" ]List of configuration/datasource files for which metadata/lineage has to be extracted.
Examples:[ { "asset_id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "technology": "erwin" } ]List of workspace rootPath.
Examples:[ { "id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "path": "/Workspace/export_uc", "name": "Databricks_connection", "type": "Connection" } ]asset ref map when trying to export and import a project .
specify if name, description, column descriptions to be udpated during re-import.
Examples:[ { "update_name": false, "update_description": false, "update_column_descriptions": false, "delete_when_deleted_at_source": false, "delete_when_removed_from_scope": false } ]- business_extraction
- primary_category
- dictionary_connection
List of the assets to be updated with SAP Business Metdata
support advanced options of metadata import.
Examples:[ { "exclude_tables": false, "exclude_views": false, "import_incremental_changes_only": false, "include_foreign_key": false, "include_primary_key": false } ]Id of the catalog to import assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5Id of the project to import assets into
Example:
c5b3daa2-c880-4f83-9bfa-c50ff70d9f42Id of the metadata import job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33- scope
list of paths
Examples:[ "/schema1/table1" ]
list of tags
Examples:[ "tag1", "tag2" ]Name of the metaBroker importflow
Example:
Run open Export- metadata_enrichment_area_info
Example:
2019-01-15T18:58:09.000ZExample:
96e2149d-6916-427b-bf98-a0cb989306d7
The goal the import. The possible values are 'metadata','lineage',
data_model,data_integration,data_integration_discover,business_intelligence,business_intelligence_discoverandopen_mantaAllowable values: [
BUSINESS_INTELLIGENCE,BUSINESS_INTELLIGENCE_DISCOVER,DATA_INTEGRATION,DATA_INTEGRATION_DISCOVER,DATA_MODEL,LINEAGE,METADATA,OPEN_MANTA,metadata, lineage, data_model, data_integration, data_integration_discover, business_intelligence, business_intelligence_discover, open_manta]Example:
metadata
Response
An object containing information about a metadata import asset
- metadata
The metadata import id assigned by the system. Read-only
The type of the asset
The IAM ID of the user that created the asset
Timestamp representing creation datetime of metadata import asset read-only
Example:
2019-01-15T18:58:09.000ZThe ID of the project which contains the asset.
- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
list of tags
Examples:[ "tag1", "tag2" ]
- entity
name of the metadata import asset
Example:
db2_tables_importList of the assets to be update with SAP Business Metdata
description of the metadata import asset
Example:
Import of a db2 tableThe type of the import. The possible values are 'metadata' and 'lineage'.
Example:
metadataId of the connection which is being imported
Example:
96e2149d-6916-427b-bf98-a0cb989306d7List of connection_id which is being discovered
List of configuration/datasource files for which metadata/lineage has to be extracted.
Examples:[ { "asset_id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "technology": "erwin" } ]List of workspace rootPath.
Examples:[ { "id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "path": "/Workspace/export_uc", "name": "Databricks_connection", "type": "Connection" } ]Id of the catalog to import assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5Id of the project to import assets into
Example:
c5b3daa2-c880-4f83-9bfa-c50ff70d9f42Id of the metadata import job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33- scope
list of paths
Examples:[ "/schema1/table1" ]
The type of the data source. The possible values are 'database', 'file', and 'generic'.
Possible values: [
DATABASE,FILE,GENERIC,database, file, generic]Started time of the last run.
Example:
1547578689512Completed time of the last run.
Example:
1547578689512Number of runs.
Example:
10Version of metadata import.
Example:
1Name of the metabroker importflow
Example:
Run Open ExportMetaBroker importflow executionid
The number of assets imported newly since last importing.
Example:
10The number of assets updated since last importing.
Example:
5The number of assets removed since last importing.
Example:
3the flag if the metadata enrichment can work or not.
Example:
trueoptions while reimporting metadata.
Examples:[ { "update_name": false, "update_description": false, "update_column_descriptions": false, "delete_when_deleted_at_source": false, "delete_when_removed_from_scope": false } ]support advanced options of metadata import.
Examples:[ { "exclude_tables": false, "exclude_views": false, "import_incremental_changes_only": false, "include_foreign_key": false, "include_primary_key": false } ]- business_extraction
- primary_category
- dictionary_connection
List of the assets to be updated with SAP Business Metdata
- metadata_enrichment_area_info
Example:
2019-01-15T18:58:09.000ZExample:
96e2149d-6916-427b-bf98-a0cb989306d7
Contains warning message, if validation of metabroker scanner passes partially.
Example:
trueThe goal the import. The possible values are 'metadata','lineage',
data_model,data_integration,data_integration_discover,business_intelligence,business_intelligence_discoverandopen_mantaExample:
metadata
Status Code
Success
Unauthorized
Forbidden
Error
No Sample Response
Bulk delete data assets in Metadata discovery
Delete assets in bulk
POST /v2/metadata_imports/bulk_delete_assets
Request
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
The catalog_id and / or project_id must be provided. If catalog_id is provided, the catalog must exist and the caller must be an admin or editor member of the catalog. Only data discovery runs associated with the catalog will be returned.
Array containing list of data asset Ids.
Bulk delete metadata import assets in Metadata discovery
Delete metadata import assets in bulk
DELETE /v2/metadata_imports/bulk_delete_metadataImport_assets
Bulk publish data assets in Metadata discovery
Publish assets in bulk
POST /v2/metadata_imports/bulk_publish_assets
Request
Query Parameters
The connection_id may be optionally provided to retrieve data discovery runs associated with the connection.
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
The catalog_id and / or project_id must be provided. If catalog_id is provided, the catalog must exist and the caller must be an admin or editor member of the catalog. Only data discovery runs associated with the catalog will be returned.
Array containing list of data asset Ids.
Get a list of supported datasource types
INTERNAL: Get list of supported connection types.
GET /v2/metadata_imports/connections
Response
datasource id
Example:
96e2149d-6916-427b-bf98-a0cb989306d7Whether datasource supports scoping.
Example:
trueWhether datasource supports manta.
Example:
trueWhether datasource is of type relational database.
Indicates whether data be can fetched from this connection type, It will be true for SCAPI connections and false for manta only connections.
Example:
true
Status Code
Success
Unauthorized
Forbidden
Error
No Sample Response
Reconcile the status of the job run record w.r.t the Discovery status
INTERNAL: Reconcile the status of the job run record w.r.t the Discovery status
POST /v2/metadata_imports/job_runs/reconcile
Request
Query Parameters
Id of the metadata import job run.
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
- metadata
Example:
NameExample:
USERExample:
jobExample:
usExample:
Description.Example:
d5d898ac-b87a-40a1-9648-2c5f49fd0096- rov
Example:
727a9f14-e692-4096-84ac-0db57dae0530Example:
727a9f14-e692-4096-84ac-0db57dae0530- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
Example:
edc30d9a-1691-4860-b947-4c8514e69f50Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
2Example:
available- Examples:
[ "job" ] Example:
['tag1', 'tag2', 'tag3']
- entity
- job_run
The ID of the job used to create this run.
Example:
958b4236-0148-4d5d-a14d-0e51f13e4ef3The state that a job can be in. Possible values: 'Completed', 'Failed', 'Canceled', 'Starting', 'Running'.
Example:
StartingThe runtime job ID returned from the runtime system, used to identify the job run in the runtime system.
Example:
1556290769-999:4cfe93c01afbadd7The duration of the job run in seconds.
Example:
10- data_flow_job_output
The total rows read by the Data Flow job.
Example:
4000The total rows written by the Data Flow job.
Example:
10The total bytes read by the Data Flow job.
Example:
232469The total bytes written by the Data Flow job.
Example:
508
Restart the pending a job run
Restart the pending a job run. It should be called after restore from the backup data. This API is not unavailable on IBM Cloud. The Admin role is necessary to call this API.
POST /v2/metadata_imports/recover_task
Request
Object containing information for recovering import
The timestamp when the data was restored (in format YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.sssZ, matching the date-time format as specified by RFC 3339)
Example:
2022-04-13T14:59:04.000ZThe status that will be restarted. The possible values are 'starting' and 'running'. The 'running' includes 'starting' status, too.
Allowable values: [
RUNNING,STARTING,starting, running]
Validate the attempt to delete job associated with Metadata import asset
Validate the attempt to delete job associated with Metadata import asset
POST /v2/metadata_imports/validate_metadata_import_job
Validates a SAP Business Metadata connection
Validates a SAP Business Metadata connection.
POST /v2/metadata_imports/validate_sap_connection
Retrieve details of a Metadata Import
Retrieve details of a metadata import
GET /v2/metadata_imports/{metadata_import_id}Request
Path Parameters
Id of the metadata import asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Response
An object containing information about a metadata import asset
- metadata
The metadata import id assigned by the system. Read-only
The type of the asset
The IAM ID of the user that created the asset
Timestamp representing creation datetime of metadata import asset read-only
Example:
2019-01-15T18:58:09.000ZThe ID of the project which contains the asset.
- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
list of tags
Examples:[ "tag1", "tag2" ]
- entity
name of the metadata import asset
Example:
db2_tables_importList of the assets to be update with SAP Business Metdata
description of the metadata import asset
Example:
Import of a db2 tableThe type of the import. The possible values are 'metadata' and 'lineage'.
Example:
metadataId of the connection which is being imported
Example:
96e2149d-6916-427b-bf98-a0cb989306d7List of connection_id which is being discovered
List of configuration/datasource files for which metadata/lineage has to be extracted.
Examples:[ { "asset_id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "technology": "erwin" } ]List of workspace rootPath.
Examples:[ { "id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "path": "/Workspace/export_uc", "name": "Databricks_connection", "type": "Connection" } ]Id of the catalog to import assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5Id of the project to import assets into
Example:
c5b3daa2-c880-4f83-9bfa-c50ff70d9f42Id of the metadata import job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33- scope
list of paths
Examples:[ "/schema1/table1" ]
The type of the data source. The possible values are 'database', 'file', and 'generic'.
Possible values: [
DATABASE,FILE,GENERIC,database, file, generic]Started time of the last run.
Example:
1547578689512Completed time of the last run.
Example:
1547578689512Number of runs.
Example:
10Version of metadata import.
Example:
1Name of the metabroker importflow
Example:
Run Open ExportMetaBroker importflow executionid
The number of assets imported newly since last importing.
Example:
10The number of assets updated since last importing.
Example:
5The number of assets removed since last importing.
Example:
3the flag if the metadata enrichment can work or not.
Example:
trueoptions while reimporting metadata.
Examples:[ { "update_name": false, "update_description": false, "update_column_descriptions": false, "delete_when_deleted_at_source": false, "delete_when_removed_from_scope": false } ]support advanced options of metadata import.
Examples:[ { "exclude_tables": false, "exclude_views": false, "import_incremental_changes_only": false, "include_foreign_key": false, "include_primary_key": false } ]- business_extraction
- primary_category
- dictionary_connection
List of the assets to be updated with SAP Business Metdata
- metadata_enrichment_area_info
Example:
2019-01-15T18:58:09.000ZExample:
96e2149d-6916-427b-bf98-a0cb989306d7
Contains warning message, if validation of metabroker scanner passes partially.
Example:
trueThe goal the import. The possible values are 'metadata','lineage',
data_model,data_integration,data_integration_discover,business_intelligence,business_intelligence_discoverandopen_mantaExample:
metadata
Status Code
Success
Unauthorized
Forbidden
Not found
Gone
Error
No Sample Response
delete a metadata import asset
delete a metadata import asset
DELETE /v2/metadata_imports/{metadata_import_id}edit a metadata import asset
edit a metadata import asset
PATCH /v2/metadata_imports/{metadata_import_id}Request
Path Parameters
Id of the metadata import asset.
Query Parameters
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Object carrying the update request.
name of the metadata import asset
Example:
db2_tables_importdescription of the metadata import asset
Example:
Import of a db2 tableId of the connection which is being discovered
Example:
96e2149d-6916-427b-bf98-a0cb989306d7Id of the catalog to import assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5Id of the project to import assets into
Example:
c5b3daa2-c880-4f83-9bfa-c50ff70d9f42Id of the metadata import job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33Name of the metabroker importflow
Example:
Run Open Export- scope
list of paths
Examples:[ "/schema1/table1" ]
list of tags
Examples:[ "tag1", "tag2" ]the flag if the metadata enrichment can work or not.
Example:
trueasset ref map when trying to export and import a project .
specify if name, description, column descriptions to be udpated during re-import.
Examples:[ { "update_name": false, "update_description": false, "update_column_descriptions": false, "delete_when_deleted_at_source": false, "delete_when_removed_from_scope": false } ]support advanced options of metadata import.
Examples:[ { "exclude_tables": false, "exclude_views": false, "import_incremental_changes_only": false, "include_foreign_key": false, "include_primary_key": false } ]
Response
An object containing information about a metadata import asset
- metadata
The metadata import id assigned by the system. Read-only
The type of the asset
The IAM ID of the user that created the asset
Timestamp representing creation datetime of metadata import asset read-only
Example:
2019-01-15T18:58:09.000ZThe ID of the project which contains the asset.
- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
list of tags
Examples:[ "tag1", "tag2" ]
- entity
name of the metadata import asset
Example:
db2_tables_importList of the assets to be update with SAP Business Metdata
description of the metadata import asset
Example:
Import of a db2 tableThe type of the import. The possible values are 'metadata' and 'lineage'.
Example:
metadataId of the connection which is being imported
Example:
96e2149d-6916-427b-bf98-a0cb989306d7List of connection_id which is being discovered
List of configuration/datasource files for which metadata/lineage has to be extracted.
Examples:[ { "asset_id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "technology": "erwin" } ]List of workspace rootPath.
Examples:[ { "id": "dde62b91-ae75-4d7d-aa08-e93065520aa4", "path": "/Workspace/export_uc", "name": "Databricks_connection", "type": "Connection" } ]Id of the catalog to import assets into
Example:
342b07da-fbe5-4a0a-94ee-ab89696975d5Id of the project to import assets into
Example:
c5b3daa2-c880-4f83-9bfa-c50ff70d9f42Id of the metadata import job
Example:
330c6256-3661-11e7-a919-92ebcb67fe33- scope
list of paths
Examples:[ "/schema1/table1" ]
The type of the data source. The possible values are 'database', 'file', and 'generic'.
Possible values: [
DATABASE,FILE,GENERIC,database, file, generic]Started time of the last run.
Example:
1547578689512Completed time of the last run.
Example:
1547578689512Number of runs.
Example:
10Version of metadata import.
Example:
1Name of the metabroker importflow
Example:
Run Open ExportMetaBroker importflow executionid
The number of assets imported newly since last importing.
Example:
10The number of assets updated since last importing.
Example:
5The number of assets removed since last importing.
Example:
3the flag if the metadata enrichment can work or not.
Example:
trueoptions while reimporting metadata.
Examples:[ { "update_name": false, "update_description": false, "update_column_descriptions": false, "delete_when_deleted_at_source": false, "delete_when_removed_from_scope": false } ]support advanced options of metadata import.
Examples:[ { "exclude_tables": false, "exclude_views": false, "import_incremental_changes_only": false, "include_foreign_key": false, "include_primary_key": false } ]- business_extraction
- primary_category
- dictionary_connection
List of the assets to be updated with SAP Business Metdata
- metadata_enrichment_area_info
Example:
2019-01-15T18:58:09.000ZExample:
96e2149d-6916-427b-bf98-a0cb989306d7
Contains warning message, if validation of metabroker scanner passes partially.
Example:
trueThe goal the import. The possible values are 'metadata','lineage',
data_model,data_integration,data_integration_discover,business_intelligence,business_intelligence_discoverandopen_mantaExample:
metadata
Status Code
Success
Unauthorized
Forbidden
Not found
Gone
Error
No Sample Response
Request
Query Parameters
Id of the metadata import job.
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Job definition object
- metadata
Example:
NameExample:
USERExample:
jobExample:
usExample:
Description.Example:
d5d898ac-b87a-40a1-9648-2c5f49fd0096- rov
Example:
727a9f14-e692-4096-84ac-0db57dae0530Example:
727a9f14-e692-4096-84ac-0db57dae0530- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
Example:
edc30d9a-1691-4860-b947-4c8514e69f50Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
2Example:
available- Examples:
[ "job" ] Example:
['tag1', 'tag2', 'tag3']
- entity
- job
ID of associated asset to run.
Example:
ff1ab70b-0553-409a-93f9-ccc31471c218Name of associated asset to run.
Example:
Data preparationRead-only field used to distinguish between different types of jobs based on the associated asset to run.
Example:
notebookStatus of the last run. 'None' if there is no run yet.
Example:
CompletedStatus of the last run. 'None' if there is no run yet.
Example:
1547578689512Creation time of the last run. 'None' if there is no run yet.
Example:
2019-07-04T21:00:48.000ZInitiator of last run. None if there is no run yet, and Scheduler if the job is a scheduled job.
Example:
SchedulerA cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 3 21 13 1 ? 2019- schedule_info
Whether the job has a repeating schedule
Example:
trueEpoch time
Example:
1564686345309Epoch time
Example:
1564686395309
cancel a Metadata Import run
INTERNAL: Cancel a metadata import job run
POST /v2/metadata_imports/job_runs/cancel
Request
Query Parameters
Id of the metadata import job run.
The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.
Job definition object
- metadata
Example:
NameExample:
USERExample:
jobExample:
usExample:
Description.Example:
d5d898ac-b87a-40a1-9648-2c5f49fd0096- rov
Example:
727a9f14-e692-4096-84ac-0db57dae0530Example:
727a9f14-e692-4096-84ac-0db57dae0530- usage
Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
1547578689512Example:
IBMid-550000FRA0
Example:
edc30d9a-1691-4860-b947-4c8514e69f50Example:
1547578689512Example:
2019-01-15T18:58:09.000ZExample:
IBMid-550000FRA0Example:
2Example:
available- Examples:
[ "job" ] Example:
['tag1', 'tag2', 'tag3']
- entity
- job_run
The ID of the job used to create this run.
Example:
958b4236-0148-4d5d-a14d-0e51f13e4ef3The state that a job can be in. Possible values: 'Completed', 'Failed', 'Canceled', 'Starting', 'Running'.
Example:
StartingThe runtime job ID returned from the runtime system, used to identify the job run in the runtime system.
Example:
1556290769-999:4cfe93c01afbadd7The duration of the job run in seconds.
Example:
10- data_flow_job_output
The total rows read by the Data Flow job.
Example:
4000The total rows written by the Data Flow job.
Example:
10The total bytes read by the Data Flow job.
Example:
232469The total bytes written by the Data Flow job.
Example:
508
List data profiles
Status: Complete
Get the list of data profiles in the specified project or catalog for a given dataAsset, provided the caller has the necessary rights to do so. The returned results can be filtered by using one or more of the listed parameters.
| Field | Match type | Example | | --------------- | ------------ | ------------------------------ | | dataset_id | Equals | ?dataset_id=5210c7d-cf6b |
GET /v2/data_profiles
Request
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to include the entity component. If set to false, only the metadata component is populated in the response.
Default:
trueInclude minimum payload for profiling results. If set to true, only minimum required details for DPS are available in the response.
Default:
falseReturn the analysis results for specified column. This option will be ignored for data profile run using data flow.
Create data profile
Status: Complete
Creates a data profile for a given data set in the specified project or catalog, provided the caller has the necessary rights to do so. Subsequent calls to use the data profile must specify the relevant project or catalog ID that the data profile was created in.
The request payload must include the 'metadata' section containing the data set id and catalog/project id.
The request payload can have the 'entity' section which is optional specifying the data profile options. If these options are not specified, default options are taken. To create several data profiles at once in the specified project or catalog, specify an array of data set in the attribute dataset_ids instead of a single data set in the attribute dataset_id. In this case, the data profiles are created in a single job that can be found in the execution section of the returned data profile entity.
AMQP 1.0 Messages
When a new data profile is created, a message is fired with a state of the new data profile in the body.
Topic
v2.data_profiles.:guid.POST ,where the ":guid" represents the profile_id of the created Data Profile
Subscribe to it by using "v2.data_profiles.*.POST" Binding Key.
Example Message
Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.POST
Message:
{
"event": "CREATE_DATA_PROFILE",
"actor": {
"user_name": "john@acme.com"
},
"published": "2015-05-10T15:04:15Z",
"url": { /* The href of the DataProfile created */}
"status_code": { /* The Http Status code , 201 if the DataProfile is created successfully */}
"state": { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
"details": {
"catalog_id": "f3c59258-abdd-4e24-828b-0495ec519339",
"dataset_id": "e522db21-59e8-44ab-81b2-bb40c3030a6f",
"profile_id": "5165d439-96f0-40d4-90b2-93795deab61b",
"is_governed": false { /* set to true if the catalog is_governed else set it to false}
}
}
POST /v2/data_profiles
Request
Query Parameters
Whether to start the profiling service immediately after the data profile is created.
Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
falseWhether to charge the bulk profiling to include term assignment charges.
Default:
false
The data profile to create.
Profiling specific metadata
Profiling specific metadata
Information about the number of records
The underlying asset entity.
- entity
The data profile definition.
The data profile definition.
Column metadata inferred by analysis.
The location url where the data profile is created.
Response
A data profile holds the data profiling controls, options and results of a data set.
Profiling specific metadata
Profiling specific metadata
Information about the number of records
The underlying asset entity.
- entity
The data profile definition.
The data profile definition.
Column metadata inferred by analysis.
The location url where the data profile is created.
Status Code
Success.
Accepted.
You are not authorized to create a data profile.
You are not permitted to perform this action.
The data profile cannot be found.
An error occurred. The data profile cannot be created.
No Sample Response
Get data profile
Status: Complete
Gets a data profile from a project or catalog, provided the call has the required right to do so.
GET /v2/data_profiles/{profile_id}Request
Path Parameters
The profile ID to use.
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Include minimum payload for profiling results. If set to true, only minimum required details for DPS are available in the response.
Default:
false
Response
A data profile holds the data profiling controls, options and results of a data set.
Profiling specific metadata
Profiling specific metadata
Information about the number of records
The underlying asset entity.
- entity
The data profile definition.
The data profile definition.
Column metadata inferred by analysis.
The location url where the data profile is created.
Status Code
Success.
You are not authorized to get the data profile you specified.
You are not permitted to perform this action.
The data profile you specified cannot be found.
An error occurred. The data profile you specified cannot be fetched.
No Sample Response
Delete data profile
Status: Complete
Deletes a specified data profile in a project or catalog, provided the caller has the necessary rights to do so.
The data profile is not deleted if the profiling process is still running unless the stop_in_progress_runs parameter is set to true.
DELETE /v2/data_profiles/{profile_id}Request
Path Parameters
The profile ID to use.
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to stop all running profiling processes. Data profiles that are running must be stopped before they can be deleted.
Default:
falseWhether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
false
Update data profile
Status: Complete
Updates a data profile in the project or catalog specified in the data profile, provided the caller has the necessary rights to do so.
During update, the entire data profile is replaced, apart from any read-only or response-only attributes.
If the profiling processes is running and the start parameter is set to true, then a data profile is only updated if the stop_in_progress_runs parameter is set to true.
The updates must be specified by using the JSON patch format, described in RFC 6902.
AMQP 1.0 Messages
When a data profile is modified, a message is fired with a state of the modified data profile in the body.
Topic
v2.data_profiles.:guid.PATCH
Subscribe to it by using "v2.data_profiles.*.PATCH" Binding Key.
Example Message
Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.PATCH
Message:
{
"event": "UPDATE_DATA_PROFILE",
"actor": {
"user_name": "john@acme.com",
},
"published": "2015-05-10T15:04:15Z",
"url": { /* The href of the DataProfile created */}
"status_code": { /* The Http Status code , 200 if the DataProfile is updated successfully */}
"state": { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
"details": {
"catalog_id": "f3c59258-abdd-4e24-828b-0495ec519339",
"dataset_id": "e522db21-59e8-44ab-81b2-bb40c3030a6f",
"profile_id": "5165d439-96f0-40d4-90b2-93795deab61b",
"is_governed": false { /* set to true if the catalog is_governed else set it to false}
}
}
PATCH /v2/data_profiles/{profile_id}Request
Path Parameters
The profile ID to use.
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to stop all running profiling processes. Data profiles that are running must be stopped before they can be deleted.
Default:
falseWhether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
falseWhether to start the profiling service immediately after the data profile is updated.
The updates to make in the data profile.
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
A data profile holds the data profiling controls, options and results of a data set.
Profiling specific metadata
Profiling specific metadata
Information about the number of records
The underlying asset entity.
- entity
The data profile definition.
The data profile definition.
Column metadata inferred by analysis.
The location url where the data profile is created.
Status Code
Success.
You are not authorized to update the data profile you specified.
You are not permitted to perform this action.
The data profile you specified cannot be found.
An error occurred. The data profile you specified cannot be updated.
No Sample Response
Update data profiles
Status: Complete
Updates data profiles in the project or catalog for one or more assets, provided the caller has the necessary rights to do so.
During update, the entire data profiles are replaced, apart from any read-only or response-only attributes.
If any profiling process is running and the start parameter is set to true, then a data profile is only updated if the stop_in_progress_runs parameter is set to true.
The updates must be specified by using the JSON patch format, described in RFC 6902.
AMQP 1.0 Messages
When a data profile is modified, a message is fired with a state of the modified data profile in the body.
Topic
v2.data_profiles.:guid.PATCH
Subscribe to it by using "v2.data_profiles.*.PATCH" Binding Key.
Example Message
Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.PATCH Message:
{
"event": "UPDATE_DATA_PROFILE",
"actor": {
"user_name": "john@acme.com",
},
"published": "2015-05-10T15:04:15Z",
"url": { /* The href of the DataProfile created */}
"status_code": { /* The Http Status code , 200 if the DataProfile is updated successfully */}
"state": { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
"details": {
"catalog_id": "f3c59258-abdd-4e24-828b-0495ec519339",
"dataset_id": "e522db21-59e8-44ab-81b2-bb40c3030a6f",
"profile_id": "5165d439-96f0-40d4-90b2-93795deab61b",
"is_governed": false { /* set to true if the catalog is_governed else set it to false}
}
}
POST /v2/data_profiles/bulk
Request
Query Parameters
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
The updates to make in the one or more data profiles.
The ID of the profile asset
Contains updates to an object via a PATCH request, as specified by the JSON patch format in RFC 6902
Response
Contains updates to more than one asset via a POST request, as specified by the JSON patch format in RFC 6902
Contains respone details for one asset in a bulk assets update response, as specified by the JSON patch format in RFC 6902
Trace key associated with the current request
Status Code
Success.
You are not authorized to update the data profile you specified.
You are not permitted to perform this action.
The catalog / project you specified cannot be found.
An error occurred. The catalog / project you specified cannot be updated.
No Sample Response
Stop profiling process
Status: Complete
Stops an in-progress profiling run in the specified project or catalog, provided the caller has the necessary rights to do so. This API will request the action to be performed and return, not perform the action and wait for it to complete.
PUT /v2/data_profiles/{profile_id}/executionRequest
Path Parameters
The profile ID to use.
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
false
The requested action to perform on the profile run.
The requested action (Response only).
Allowable values: [
stop,stop_all]
Get profiling logs
Status: Complete
Get the logs for the data profile job run on data set in a project or catalog.
GET /v2/data_profiles/{profile_id}/logsRequest
Path Parameters
The profile ID to use.
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Response
A collection of data profile job run log entries.
A collection of data profile job run log entries.
Status Code
Success.
You are not authorized to get the profiling logs.
You are not permitted to perform this action.
The data profile you specified cannot be found.
An error occurred. Failed to get profiling logs.
No Sample Response
Modify asset level classification
Status: Complete
Modifies asset level classification detail in the data_profile attribute in the specified project or catalog, provided the caller has the necessary rights to do so. This API is used for CRUD operations on asset level classification.
The patch request for classification should contain the classification details that are to be added to the data_profile attribute.
The updates must be specified by using the JSON patch format, described in RFC 6902.
PATCH /v2/data_profiles/classification
Request
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
false
The asset level classification details that are added to the data_profile attribute.
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
Custom data to be associated with a given object
Status Code
Success.
Invalid classification details provided as part of the patch call.
You are not authorized to modify the data_profile attribute with asset level classification details.
You are not permitted to perform this action.
The asset classification cannot be found.
An error occurred. The data_profile attribute cannot be modified with asset level classification detail.
No Sample Response
Export data profile
Status: Complete
Export data profile of dataset in a project or catalog. (For internal use only)
GET /v2/data_profiles/export
Request
Query Parameters
The ID of the data set to use.
The ID of the export task ID to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Response
List of file paths that hold the profiling results. These files should be added to the project export archive.
Status Code
Success.
You are not authorized to persist results.
You are not permitted to perform this action.
Asset or profile is missing
An error occurred. The profiling results cannot be saved.
This API is not Implemented.
No Sample Response
Import data profile
Status: Complete
Import data profile of dataset in a project or catalog. (For internal use only)
POST /v2/data_profiles/import
Request
Query Parameters
The ID of the data set to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
The data profile to import.
Source path where the import archive is deflated. If this value is provided, the profiling results are read from source_path/assets/profiling directory by setting the root=true. If this value is not provided, results files are read from profiling directory by setting the root=false.
Map of the old asset ids to new asset ids
- asset_ref_map
IBM cloud IAM user id of the creator of the asset.
Possible values: 1 ≤ length ≤ 100
Example:
IBMid-270002ABCD
This filters rows from the frequency distribution.
This filters rows from the frequency distribution.
POST /v2/data_profiles/{profile_id}/unique_valuesRequest
Path Parameters
The profile ID to use.
filters to get frequency distribution
Example:
dataset_idExample:
col1Example:
project_idExample:
catalog_idDefault:
falseExample:
some_valueExample:
10Example:
AAAExample:
100Possible values: 0 ≤ value ≤ 1000
Example:
100Example:
INT8Example:
10Example:
5Example:
2Example:
AAAExample:
U
Response
list of frequency distribution result of the column
Example:
120frequency distribution result
Status Code
Success.
You are not authorized to get the key analysis you specified.
You are not permitted to perform this action.
The key analysis task you specified cannot be found.
An error occurred. The data profile you specified cannot be fetched.
No Sample Response
Get data profile options
Status: Complete
Get the data profile options for the Account specified in the IAM token. If the account level data profile options is not available check if it is specified at project or catalog account level, provided the caller has the necessary rights to do so.
GET /v2/data_profiles/options
Request
Query Parameters
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
false
Response
Definition of a data profile options.
Metadata about data profile options
The underlying asset entity.
- entity
The options of the profiling execution.
Status Code
Success.
You are not permitted to perform this action.
You are not authorized to list the available data profiles options.
Not Found.
An error occurred. The data profiles options cannot be listed.
This API is not Implemented.
No Sample Response
Create data profile options
Status: Complete
Creates a data profile options for a given Account Id in the specified project or catalog, provided the caller has the necessary rights to do so.
POST /v2/data_profiles/options
Request
Query Parameters
Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
false
The data profile option to create.
Metadata about data profile options
The underlying asset entity.
- entity
The options of the profiling execution.
Response
Definition of a data profile options.
Metadata about data profile options
The underlying asset entity.
- entity
The options of the profiling execution.
Status Code
Success.
You are not authorized to create data profile options.
You are not permitted to perform this action.
The data profile options cannot be found.
An error occurred. The data profile options cannot be created.
This API is not Implemented.
No Sample Response
Delete data profile options
Status: Complete
Delete the list of data profile options in the specified project or catalog, provided the caller has the necessary rights to do so. If the user specifies the catalog_id or the project_id then the data profile options specified for the catalog or project is deleted. If none of the query parameters,catalog_id or project_id is specified, the default is to delete the account level data profile options.
DELETE /v2/data_profiles/options
Request
Query Parameters
Comma separated list of the BSS Account IDs to use (restriced usage).
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
false
Update the data profile options.
Status: Complete
Updates the data profile options for a given Account in the specified project or catalog, provided the caller has the necessary rights to do so. The data profile options that can be modified are max_row_count,row_percentage,max_distribution_size,max_numeric_stats_bin disabled flag in classification options,ibm_class_codes and custom_class_codes.
If the user specifies the catalog_id or the project_id then the data profile options specified for the catalog or project is updated. Update the account level data profile options if catalog_id or project_id is not specified.
PATCH /v2/data_profiles/options
Request
Query Parameters
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).
Default:
false
The data profile options to add.
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
Definition of a data profile options.
Metadata about data profile options
The underlying asset entity.
- entity
The options of the profiling execution.
Status Code
Success.
You are not authorized to update the data profile options.
You are not permitted to perform this action.
The data profile options you specified cannot be found.
An error occurred. The data profile options cannot be updated.
This API is not Implemented.
No Sample Response
Persist profiling results
Status: Complete
Persist profiling results of dataset in a project or catalog. (For internal use only)
POST /v2/data_profiles/results
Update data profile results status
Status: Complete
Update data profile result status of dataset in a project or catalog. (For internal use only)
POST /v2/data_profiles/results/status
Request
Query Parameters
The ID of the data set to use.
The tenant ID to use.
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
The ID to be used for tracking end to end flow.
The data profile result status to update.
The data profile status.
Get bivariate results of given asset.
Status: Complete
Get bivariate results of dataset in a project or catalog. (For internal use only)
GET /v2/data_profiles/bivariate_results
Persist bivariate results of given asset.
Status: Complete
Persist bivariate results of dataset in a project or catalog. (For internal use only)
POST /v2/data_profiles/bivariate_results
Migrate data profile quality results to new Data Quality service
Status: Complete
Migrate data profile quality results of dataset in a project or catalog to new Data Quality service.
POST /v2/data_profiles/migrate
Request
Query Parameters
The ID of the catalog to use. catalog_id or project_id is required.
The ID of the project to use. catalog_id or project_id is required.
The ID of the data set to use.(Use comma separated data set Id's for multiple data sets)
Response
Migration status logging to track progress.
Status Code
Successfully initiated migration process.
Bad request. Provided parameters could be invalid.
You are not authorized, either token is expired or invalid.
You are not permitted to perform this action. Only Editor or Admin are allowed.
Catalog or Project not found.
An error occurred. The profiling results cannot be migrated to data quality service.
This API is not Implemented.
No Sample Response
List Hummingbird tasks
Status: Complete
Get the list of Hummingbird tasks for a specified accout or type, provided the caller has the necessary rights to do so.
GET /v1/hb_tasks
Request
Query Parameters
The BSS Account ID to use.
The type of the job.
Fetch complete details of job.
Default:
false
Response
Collection of HB tasks.
The ID of the task
The ID of the account
Indicates if account plan is free plan
Type of the job
The job payload
The id to track complete flow
Priority of the HB job
The ID of the HB job
Timestamp of task creation
Timestamp of job submission
Timestamp of job completion
The duration for which job was run
The number of times the job was retried
Status of the HB job
Possible values: [
REQUESTED,SUBMITTED,RUNNING,COMPLETED,ERROR,STOPPED,STOPPED_CAPACITY_UNIT_EXCEEDED,QUEUED]The ID of the project where the spark job logs need to be saved. If this value is not provided or is invalid then the spark job logs will be stored in default COS bucket.
A RuntimeRegistrationParameters holds details to be sent to runtimes api to report CUH for HB job.
A ComputeUnits holds details to determine if a particular account has surpassed its CUH.
Status Code
Success.
You are not permitted to perform this action.
You are not authorized to list the available Hummingbird tasks.
Not Found.
An error occurred. The HB tasks cannot be listed.
No Sample Response
Request
The Hummingbird task to create.
The ID of the account
Indicates if account plan is free plan
Type of the job
The job payload
The id to track complete flow
Status of the HB job
Allowable values: [
REQUESTED,QUEUED]Default:
REQUESTEDPriority of the HB job
Default:
1The ID of the project where the spark job logs need to be saved. If this value is not provided or is invalid then the spark job logs will be stored in default COS bucket.
A RuntimeRegistrationParameters holds details to be sent to runtimes api to report CUH for HB job.
A ComputeUnits holds details to determine if a particular account has surpassed its CUH.
Response
An HbTaskResponse holds details about Hummingbird job and the status of task in queue.
The ID of the task
The ID of the account
Indicates if account plan is free plan
Type of the job
The job payload
The id to track complete flow
Priority of the HB job
The ID of the HB job
Timestamp of task creation
Timestamp of job submission
Timestamp of job completion
The duration for which job was run
The number of times the job was retried
Status of the HB job
Possible values: [
REQUESTED,SUBMITTED,RUNNING,COMPLETED,ERROR,STOPPED,STOPPED_CAPACITY_UNIT_EXCEEDED,QUEUED]The ID of the project where the spark job logs need to be saved. If this value is not provided or is invalid then the spark job logs will be stored in default COS bucket.
A RuntimeRegistrationParameters holds details to be sent to runtimes api to report CUH for HB job.
A ComputeUnits holds details to determine if a particular account has surpassed its CUH.
Status Code
Success.
You are not authorized to create a Hummingbird task.
You are not permitted to perform this action.
The data profile cannot be found.
An error occurred. The Hummingbird task cannot be created.
No Sample Response
Stop Hummingbird tasks
Status: Complete
Stops given Hummingbird task ids. If the Hummingbird task is already completed or is not found then it will be ignored. If the task is locked by other process then it will be ignored as well.
POST /v1/hb_tasks/stop
Response
A StopHbTasksResponse holds details about stop Hummingbird tasks response.
The array of hb_task_id that were already completed. These Hummingbird tasks will be ignored.
The array of hb_task_id that were not found. These Hummingbird tasks will be ignored.
The array of hb_task_id that were actually stopped
The array of hb_task_id that were locked by other process.
Status Code
Success.
You are not authorized to cancel Hummingbird tasks.
You are not permitted to perform this action.
An error occurred. The Hummingbird tasks cannot be stopped.
No Sample Response
Delete Hummingbird tasks
Status: Complete
Delete given Hummingbird task ids. If a Hummingbird task is not found then it will be ignored. If the Hummingbird task is running and stop_in_progress_job is not true then it will be ignored. If the task is locked by other process then it will be ignored as well.
POST /v1/hb_tasks/delete
Request
Query Parameters
Stop running job.
Default:
false
The Hummingbird task ids to delete.
The array of hb_task_id to use during bulk processing
Response
A StopHbTasksResponse holds details about stop Hummingbird tasks response.
The array of hb_task_id that were deleted.
The array of hb_task_id that were not found. These Hummingbird tasks will be ignored.
The array of hb_task_id that are running
The array of hb_task_id that were locked by other process.
Status Code
Success.
You are not authorized to cancel a Hummingbird task.
You are not permitted to perform this action.
An error occurred. The Hummingbird tasks cannot be deleted.
No Sample Response
Response
An HbTaskResponse holds details about Hummingbird job and the status of task in queue.
The ID of the task
The ID of the account
Indicates if account plan is free plan
Type of the job
The job payload
The id to track complete flow
Priority of the HB job
The ID of the HB job
Timestamp of task creation
Timestamp of job submission
Timestamp of job completion
The duration for which job was run
The number of times the job was retried
Status of the HB job
Possible values: [
REQUESTED,SUBMITTED,RUNNING,COMPLETED,ERROR,STOPPED,STOPPED_CAPACITY_UNIT_EXCEEDED,QUEUED]The ID of the project where the spark job logs need to be saved. If this value is not provided or is invalid then the spark job logs will be stored in default COS bucket.
A RuntimeRegistrationParameters holds details to be sent to runtimes api to report CUH for HB job.
A ComputeUnits holds details to determine if a particular account has surpassed its CUH.
Status Code
Success.
You are not authorized to get the data profile you specified.
You are not permitted to perform this action.
The HB task you specified cannot be found.
An error occurred. The HB task you specified cannot be fetched.
No Sample Response
Delete Hummingbird task
Status: Complete
Deletes a specified Hummingbird task.
This api will throw an exception if stop_in_progress_job parameter is not true and if job is running.
DELETE /v1/hb_tasks/{hb_task_id}Get Hummingbird task logs
Status: Complete
Get the spark job logs for Hummingbird task. In order to retrieve the job logs, the HB spark job must be successfully submitted. This will generate a job_id. When successful, this api would return the Hummingbird spark job log.
GET /v1/hb_tasks/{hb_task_id}/logsRequest
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
falseThe type of the resource to search. If omitted, filtering on type is not applied
Possible values: 1 ≤ length ≤ 200
Response
A collection of data quality assets.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality assets.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality assets.
An error occurred. The list of data quality assets cannot be returned.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/assets?limit=200"},"assets":[{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","name":"CUSTOMERS","type":"data_asset","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","weight":1,"creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Data quality asset to create.
Example: {"native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","name":"CUSTOMERS","type":"data_asset","weight":1}
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CUSTOMERSUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/6835c729-8d79-4b12-b02d-c82a20ac00a6The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_assetThe weight of this asset in the computation of the data quality scores
The Id of an eventual parent, or null if this asset has no parent
- parent
The type of the IBM Knowledge Catalog asset
Possible values: 1 ≤ length ≤ 200
Example:
DataSetThe identity of the IBM Knowledge Catalog asset this Asset is referring
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The identity of the IBM Knowledge Catalog container (either project/catalog/space) this asset belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If specified, indicates that this asset is the virtualization of another asset whose id is specified in this field
- virtualized_asset
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Response
A data asset on which data quality is measured.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CUSTOMERSUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/6835c729-8d79-4b12-b02d-c82a20ac00a6The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_assetThe weight of this asset in the computation of the data quality scores
Possible values: 0 ≤ value ≤ 1
Eventual children of this asset. If omitted, no children for this asset.
Possible values: 0 ≤ number of items ≤ 100000
The Id of an eventual parent, or null if this asset has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The type of the IBM Knowledge Catalog asset
Possible values: 1 ≤ length ≤ 200
Example:
DataSetThe identity of the IBM Knowledge Catalog asset this Asset is referring
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The identity of the IBM Knowledge Catalog container (either project/catalog/space) this asset belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If specified, indicates that this asset is the virtualization of another asset whose id is specified in this field
- virtualized_asset
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success
The given payload is invalid and the asset is not created.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create a data quality asset.
The data quality asset exists already and cannot be created.
An error occurred. The data quality asset cannot be created.
{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","name":"CUSTOMERS","type":"data_asset","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","weight":1,"creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}{"trace":"6vbjp9d2t4s9b2ckyspdw4vft","status_code":400,"errors":[{"code":"missing_required_field","message":"Bad Request: {\"trace\":\"8f7b7693-1f08-4b4a-b2bd-5732d06ad19e\", \"errors\":[{\"code\":\"invalid_parameter\", \"message\":\"COMSV3006E: Missing or Invalid asset id\", \"target\":{\"name\":\"asset\",\"type\":\"parameter\"}}]}"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"28izpw5l1a4orh823i6bkqmm","status_code":409,"errors":[{"code":"already_exists","message":"The dimension with name 'Completeness' already exists."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get a data quality asset
Get the data quality asset with the given identifier.
GET /data_quality/v4/assets/{id}Request
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
false
Response
A data asset on which data quality is measured.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CUSTOMERSUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/6835c729-8d79-4b12-b02d-c82a20ac00a6The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_assetThe weight of this asset in the computation of the data quality scores
Possible values: 0 ≤ value ≤ 1
Eventual children of this asset. If omitted, no children for this asset.
Possible values: 0 ≤ number of items ≤ 100000
The Id of an eventual parent, or null if this asset has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The type of the IBM Knowledge Catalog asset
Possible values: 1 ≤ length ≤ 200
Example:
DataSetThe identity of the IBM Knowledge Catalog asset this Asset is referring
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The identity of the IBM Knowledge Catalog container (either project/catalog/space) this asset belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If specified, indicates that this asset is the virtualization of another asset whose id is specified in this field
- virtualized_asset
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality asset.
The data quality asset with the given ID cannot be found.
An error occurred. The data quality asset cannot be returned.
{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","name":"CUSTOMERS","type":"data_asset","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","weight":1,"creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Delete data quality asset
Delete the data quality asset with the given identifier and all its children recursively
DELETE /data_quality/v4/assets/{id}Request
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
If true, delete all children recursively. Otherwise, only selected one is deleted.
Default:
false
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality asset.
The data quality asset cannot be found.
An error occurred. The data quality asset cannot be deleted.
{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Update or patch a data quality asset
Update a data quality asset as specified in the payload details of the request.
The updates must be specified by using the JSON patch format, described in RFC 6902.
The following attributes can be updated: - /name (value can only be replaced) - /weight (value can only be replaced)
PATCH /data_quality/v4/assets/{id}Request
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The updates to make in the data quality rule.
Example: [{"op":"replace","path":"/description","value":"The proportion of data stored against the potential for 100% of the data."}]
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
A data asset on which data quality is measured.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CUSTOMERSUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/6835c729-8d79-4b12-b02d-c82a20ac00a6The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_assetThe weight of this asset in the computation of the data quality scores
Possible values: 0 ≤ value ≤ 1
Eventual children of this asset. If omitted, no children for this asset.
Possible values: 0 ≤ number of items ≤ 100000
The Id of an eventual parent, or null if this asset has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The type of the IBM Knowledge Catalog asset
Possible values: 1 ≤ length ≤ 200
Example:
DataSetThe identity of the IBM Knowledge Catalog asset this Asset is referring
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The identity of the IBM Knowledge Catalog container (either project/catalog/space) this asset belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If specified, indicates that this asset is the virtualization of another asset whose id is specified in this field
- virtualized_asset
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality asset.
The data quality asset with the given ID cannot be found.
An error occurred. The data quality asset cannot be updated.
{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","name":"CUSTOMERS","type":"data_asset","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","weight":1,"creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Search data quality asset with given native id and type
Search for a data quality asset by its native id and type
POST /data_quality/v4/search_dq_asset
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The native id, as known by the DQ producer, of the resource to search. If not provided, other identity parameters must be provided.
Possible values: 1 ≤ length ≤ 500
The type of the resource to search. If omitted, filtering on type is not applied
Possible values: 1 ≤ length ≤ 200
The IBM Knowledge Catalog asset ID in cams. If omitted, the field is not set.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
false
Response
A data asset on which data quality is measured.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CUSTOMERSUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/6835c729-8d79-4b12-b02d-c82a20ac00a6The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_assetThe weight of this asset in the computation of the data quality scores
Possible values: 0 ≤ value ≤ 1
Eventual children of this asset. If omitted, no children for this asset.
Possible values: 0 ≤ number of items ≤ 100000
The Id of an eventual parent, or null if this asset has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The type of the IBM Knowledge Catalog asset
Possible values: 1 ≤ length ≤ 200
Example:
DataSetThe identity of the IBM Knowledge Catalog asset this Asset is referring
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The identity of the IBM Knowledge Catalog container (either project/catalog/space) this asset belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If specified, indicates that this asset is the virtualization of another asset whose id is specified in this field
- virtualized_asset
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to search data quality assets.
The data quality asset cannot be found.
An error occurred. The data quality asset cannot be searched.
{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","name":"CUSTOMERS","type":"data_asset","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","weight":1,"creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
List SLA assessments for an asset
List the Service Level Agreement assessments for an asset
GET /data_quality/v4/assets/{id}/sla_assessmentsRequest
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The data quality Service Level Agreement identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If true, returns only the latest assessment for each SLA.
Default:
falseDefines whether assessments with violations should be listed first. Ignored when an SLA id is provided.
Default:
trueThe start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20
Response
A collection of data quality SLA assessments
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20The total number of resources available
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality SLA assessments
Possible values: 0 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality SLA assessments.
An error occurred. The list of data quality SLA assessments cannot be returned.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/slas/assessments?asset_id=333605b5-48d9-489e-b846-8ef96a7a1abc&limit=200"},"sla_assessments":[{"id":"222605b5-48d9-489e-b846-8ef96a7a1def","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"sla":{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address SLA"},"is_latest":true,"num_violations":3,"violations_on_asset":1,"violations_on_children":2,"dimensions_with_violations":[{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Consistency"},null],"actions":[{"type":"workflow","name":"DQ Remediation for customer US Government","native_id":"255505b5-8888-489e-b846-8ef96a7a1def","native_definition_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd","completed":true,"details":"{completed_on_time: true}","created_at":"2023-02-01T18:11:02.000Z"}],"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get an SLA assessment
Get the Service Level Agreement assessment with the given identifier
GET /data_quality/v4/assets/{id}/sla_assessments/{assessment_id}Request
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality SLA assessment identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The maximum number of violations to return.
Possible values: 0 ≤ value ≤ 200
Default:
20Example:
20
Response
An instance of an SLA assessment for a specific asset and its sub-assets
The main asset that was evaluated for SLA violations (potentially including child assets)
- asset
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CUSTOMERSThe identity of the IBM Knowledge Catalog asset this Asset is referring
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The type of the IBM Knowledge Catalog asset
Possible values: 1 ≤ length ≤ 200
Example:
DataSetResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The evaluated SLA
- sla
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The name of the SLA
Possible values: 1 ≤ length ≤ 200
The total number of found violations
The number of found violations on the asset itself
The number of found violations on the asset's children
Flag indicating whether this is the latest assessment for the referenced SLA on the referenced asset
The actions triggered by this assessment
Possible values: 0 ≤ number of items ≤ 200
The assessment time.
Possible values: 20 ≤ length ≤ 24
A list of all data quality dimensions with violations in this assessment. The 'overall' dimension is represented by an empty object.
The violations found in this assessment (optional, limited to the first page of the full list)
- violations
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20The total number of resources available
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality SLA violations
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality SLA assessment.
The data quality SLA assessment with the given ID cannot be found.
An error occurred. The data quality SLA assessment cannot be returned.
{"id":"222605b5-48d9-489e-b846-8ef96a7a1def","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"sla":{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address SLA"},"is_latest":true,"num_violations":3,"violations_on_asset":1,"violations_on_children":2,"dimensions_with_violations":[{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Consistency"},null],"violations":{"total_count":3,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/slas?limit=200"},"violations":[{"id":"6b744574-573a-4cf8-8ab7-e428506e4289","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"Address"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"missed_threshold":0.9,"score":0.4,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4290","asset":{"wkc_asset_id":"48e18374-573a-4cf8-8ab7-e428506e428b","name":"AGE","wkc_asset_type":"Column"},"filter":{"type":"name","value":"age"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Freshness"},"missed_threshold":1,"score":0.7,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4291","asset":{"wkc_asset_id":"46849374-573a-4cf8-8ab7-e428506e428b","name":"ZIP","wkc_asset_type":"Column"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1ccc","name":"Zip"},"dimension":{"id":"45645632-573a-4cf8-8ab7-e428506e428b","name":"Correctness"},"missed_threshold":0.98,"score":0.8,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}]},"actions":[{"type":"workflow","name":"DQ Remediation","native_id":"255505b5-8888-489e-b846-8ef96a7a1def","native_definition_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd","completed":true,"details":"{completed_on_time: true}","created_at":"2022-02-02T14:00:45.000Z"}],"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get the SLA violations for the given assessment
Get the Service Level Agreement violations for the assessment with the given identifier. The violations are sorted by descending score deviation (threshold minus score).
GET /data_quality/v4/assets/{id}/sla_assessments/{assessment_id}/violationsRequest
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality SLA assessment identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20
Response
A collection of data quality SLA violations
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20The total number of resources available
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality SLA violations
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality SLA violations.
The data quality SLA violations for the assessment with the given ID cannot be found.
An error occurred. The data quality SLA violations cannot be returned.
{"total_count":3,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/slas?limit=200"},"violations":[{"id":"6b744574-573a-4cf8-8ab7-e428506e4289","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"Address"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS"},"missed_threshold":0.9,"score":0.4,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4290","asset":{"wkc_asset_id":"48e18374-573a-4cf8-8ab7-e428506e428b","name":"AGE","wkc_asset_type":"Column"},"filter":{"type":"name","value":"age"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Freshness","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"missed_threshold":1,"score":0.7,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4291","asset":{"wkc_asset_id":"46849374-573a-4cf8-8ab7-e428506e428b","name":"ZIP","wkc_asset_type":"Column"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1ccc","name":"Zip"},"dimension":{"id":"45645632-573a-4cf8-8ab7-e428506e428b","name":"Correctness"},"missed_threshold":0.98,"score":0.8,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
falseThe type of the resource to search. If omitted, filtering on type is not applied
Possible values: 1 ≤ length ≤ 200
Response
A collection of data quality checks.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality checks.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality checks.
An error occurred. The list of data quality checks cannot be returned.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/checks?limit=200"},"checks":[{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","name":"check_uniqueness_of_id","dimension":{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"COMPLETENESS","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"type":"data_rule","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Data quality check to create.
Example: {"dimension":{"id":"371114cd-5516-4691-8b2e-1e66edf66486"},"name":"check_uniqueness_of_id","type":"data_rule","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702"}
the dimension this check belongs to
- dimension
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe Id of an eventual parent, or null if this check has no parent
- parent
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Response
A data quality check, i.e. an action to measure data quality.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe optional eventual children of this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
An optional list of issues reported by this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
- issues
the dimension this check belongs to
- dimension
Flag indicating whether the dimension is a built-in dimension or not.
The identity of the IBM Knowledge Catalog container (either project/catalog/space) this check belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The Id of an eventual parent, or null if this check has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success
The given payload is invalid and the check is not created.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create a data quality check.
The data quality check exists already and cannot be created.
An error occurred. The data quality check cannot be created.
{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"check_uniqueness_of_id","dimension":{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"COMPLETENESS","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"type":"data_rule","native_id":"4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"}{"trace":"6vbjp9d2t4s9b2ckyspdw4vft","status_code":400,"errors":[{"code":"missing_required_field","message":"Bad Request: {\"trace\":\"8f7b7693-1f08-4b4a-b2bd-5732d06ad19e\", \"errors\":[{\"code\":\"invalid_parameter\", \"message\":\"COMSV3006E: Missing or Invalid asset id\", \"target\":{\"name\":\"asset\",\"type\":\"parameter\"}}]}"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"28izpw5l1a4orh823i6bkqmm","status_code":409,"errors":[{"code":"already_exists","message":"The dimension with name 'Completeness' already exists."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get a data quality check
Get the data quality check with the given identifier.
GET /data_quality/v4/checks/{id}Request
Path Parameters
The data quality check identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
false
Response
A data quality check, i.e. an action to measure data quality.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe optional eventual children of this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
An optional list of issues reported by this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
- issues
the dimension this check belongs to
- dimension
Flag indicating whether the dimension is a built-in dimension or not.
The identity of the IBM Knowledge Catalog container (either project/catalog/space) this check belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The Id of an eventual parent, or null if this check has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality check.
The data quality check with the given ID cannot be found.
An error occurred. The data quality check cannot be returned.
{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"check_uniqueness_of_id","dimension":{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"COMPLETENESS","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"type":"data_rule","native_id":"4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Delete a data quality check
Delete the data quality check with the given identifier and all its children recursively
DELETE /data_quality/v4/checks/{id}Request
Path Parameters
The data quality check identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
If true, delete all children recursively. Otherwise, only selected one is deleted.
Default:
false
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality check.
The data quality check cannot be found.
An error occurred. The data quality check cannot be deleted.
{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Update or patch a data quality check
Update a data quality check as specified in the payload details of the request.
The updates must be specified by using the JSON patch format, described in RFC 6902.
The following attributes can be updated: - /name (value can only be replace) - /dimension/id (value can be add, remove or replace) - /details (value can be add, remove or replace)
PATCH /data_quality/v4/checks/{id}Request
Path Parameters
The data quality check identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The updates to make in the data quality rule.
Example: [{"op":"replace","path":"/description","value":"The proportion of data stored against the potential for 100% of the data."}]
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
A data quality check, i.e. an action to measure data quality.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe optional eventual children of this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
An optional list of issues reported by this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
- issues
the dimension this check belongs to
- dimension
Flag indicating whether the dimension is a built-in dimension or not.
The identity of the IBM Knowledge Catalog container (either project/catalog/space) this check belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The Id of an eventual parent, or null if this check has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality check.
The data quality check with the given ID cannot be found.
An error occurred. The data quality check cannot be updated.
{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"check_uniqueness_of_id","dimension":{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"COMPLETENESS","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"type":"data_rule","native_id":"4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Search for a data quality check by its native id and type
Search for a data quality check by its native id and type
POST /data_quality/v4/search_dq_check
Request
Query Parameters
The native id, as known by the DQ producer, of the resource to search.
Possible values: 1 ≤ length ≤ 500
The type of the resource to search.
Possible values: 1 ≤ length ≤ 200
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
false
Response
A data quality check, i.e. an action to measure data quality.
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe optional eventual children of this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
An optional list of issues reported by this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
- issues
the dimension this check belongs to
- dimension
Flag indicating whether the dimension is a built-in dimension or not.
The identity of the IBM Knowledge Catalog container (either project/catalog/space) this check belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The Id of an eventual parent, or null if this check has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to search data quality checks.
The data quality check cannot be found.
An error occurred. The data quality check cannot be searched.
{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"check_uniqueness_of_id","dimension":{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"COMPLETENESS","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"type":"data_rule","native_id":"4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get a list of data quality dimensions
Get a list of data quality dimensions.
GET /data_quality/v4/dimensions
Request
Query Parameters
The start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20
Response
A collection of data quality dimensions.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality dimensions.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality dimensions.
An error occurred. The list of data quality dimensions cannot be returned.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/dimensions?limit=200"},"dimensions":[{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"Completeness","description":"The proportion of data stored against the potential for 100 percent.","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Request
Data quality dimension to create.
Example: {"name":"Completeness10","description":"The proportion of data stored against the potential for 100 percent represented as integer 10."}
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CompletenessThe optional description of the dimension. Provide a description to understand the reason for its existence.
Possible values: 0 ≤ length ≤ 255
Example:
The proportion of data stored against the potential for 100 percent. If this property is omitted, no description is set.
Response
Flag indicating whether the dimension is a built-in dimension or not.
Status Code
Success
The given payload is invalid and the dimension is not created.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create a data quality dimension.
The data quality dimension exists already and cannot be created.
An error occurred. The data quality dimension cannot be created.
{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"Completeness","description":"The proportion of data stored against the potential for 100 percent.","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"}{"trace":"6vbjp9d2t4s9b2ckyspdw4vft","status_code":400,"errors":[{"code":"missing_required_field","message":"Bad Request: {\"trace\":\"8f7b7693-1f08-4b4a-b2bd-5732d06ad19e\", \"errors\":[{\"code\":\"invalid_parameter\", \"message\":\"COMSV3006E: Missing or Invalid asset id\", \"target\":{\"name\":\"asset\",\"type\":\"parameter\"}}]}"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"28izpw5l1a4orh823i6bkqmm","status_code":409,"errors":[{"code":"already_exists","message":"The dimension with name 'Completeness' already exists."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get the data quality dimension with the given identifier
Get the data quality dimension with the given identifier.
GET /data_quality/v4/dimensions/{id}Request
Path Parameters
The data quality dimension identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
Flag indicating whether the dimension is a built-in dimension or not.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality dimension.
The data quality dimension with the given ID cannot be found.
An error occurred. The data quality dimension cannot be returned.
{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"Completeness","description":"The proportion of data stored against the potential for 100 percent.","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Delete the data quality dimension with the given identifier.
Delete the data quality dimension with the given identifier.
All data quality checks associated to this dimension will point to no dimension. All DQ scores stored for this dimension will be deleted
DELETE /data_quality/v4/dimensions/{id}Request
Path Parameters
The data quality dimension identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality dimension.
The data quality dimension cannot be found.
An error occurred. The data quality dimension cannot be deleted.
{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Update a data quality dimension as specified in the payload details of the request
Update a data quality dimension as specified in the payload details of the request.
The updates must be specified by using the JSON patch format, described in RFC 6902.
The following attributes can be updated: - /name (value can only be replaced) - /description (value can be added, removed, or replaced)
PATCH /data_quality/v4/dimensions/{id}Request
Path Parameters
The data quality dimension identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The updates to make in the data quality rule.
Example: [{"op":"replace","path":"/description","value":"The proportion of data stored against the potential for 100% of the data."}]
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
Flag indicating whether the dimension is a built-in dimension or not.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality dimension.
The data quality dimension with the given ID cannot be found.
An error occurred. The data quality dimension cannot be updated.
{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"Completeness","description":"The proportion of data stored against the potential for 100 percent.","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Search for data quality dimensions by name or part of their names
Search for data quality dimensions by name or part of their names
POST /data_quality/v4/search_dq_dimension
Request
Query Parameters
The name of the resource to search or a part of the name of the resources to search.
Possible values: 1 ≤ length ≤ 200
Response
A collection of data quality dimensions.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality dimensions.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to search data quality dimensions.
An error occurred. The data quality dimension cannot be searched.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/dimensions?limit=200"},"dimensions":[{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"Completeness","description":"The proportion of data stored against the potential for 100 percent.","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20Comma-separated list of data quality asset identifier to search issues of. If not provided, filtering on asset is not applied.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710Comma-separated list of data quality check id identifier to search issues of. If not provided, filtering on a check is not applied.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710Comma-separated list of data quality check native id identifier to search issues of. If not provided, filtering on a check is not applied. Only one of checkId or checkNativeId should be provided; if both are provided, an error will be thrown.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710The name or part of the name of data quality check identifier to search issues of. If not provided, filtering on name of check is not applied.
Possible values: 1 ≤ length ≤ 200
Comma-separated list of data quality dimension identifiers.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710If true, returns only the latest issue summary of each DQ check. If false, returns the latest and archived issues.
Default:
trueThe type of the resource to search. If omitted, filtering on type is not applied
Possible values: 1 ≤ length ≤ 200
If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
trueThe issue attribute to sort on. If omitted, sorting on last update time is applied
Allowable values: [
check_name,check_type,check_dimension_name,percent_occurrences,ignored,updated_at]Default:
updated_atExample:
check_nameThe direction to sort with. If omitted, sorting attribute descending is applied
Allowable values: [
asc,desc]Default:
descExample:
asc
Response
A collection of data quality issues.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality issues.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality issues.
An error occurred. The list of data quality issues cannot be returned.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/issues?limit=200"},"issues":[{"id":"046605b5-48d9-489e-b846-8ef96a7a1aba","check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"MY_RULE","native_id":"cdcd4382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","type":"ANY","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","nativeId":"739e06f8-3gk2-4c4u-8ab7-e5682g06f05a"},"number_of_occurrences":123,"number_of_tested_records":456789,"creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Data quality issue to create.
Example: {"check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a"},"number_of_occurrences":123,"number_of_tested_records":456789,"status":"actual","ignored":false}
the check that produces this issue
- check
The Id of the asset on which this issue was found
- reported_for
Flag indicating whether the issue is ignored or not.
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
123The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
456789The relative frequency of the issue (percentage of tested records having the issue), as a number between 0.0 and 1.0. If omitted, it is calculated using number_of_occurrences and number_of_tested_records.
Possible values: 0 ≤ value ≤ 1
The status of the issue.
Allowable values: [
actual,aggregation]Default:
actualExample:
actual
Response
A data quality issue, i.e. a data quality problem detected during a check.
the check that produces this issue
- check
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe optional eventual children of this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
An optional list of issues reported by this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
- issues
the dimension this check belongs to
- dimension
Flag indicating whether the dimension is a built-in dimension or not.
The identity of the IBM Knowledge Catalog container (either project/catalog/space) this check belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The Id of an eventual parent, or null if this check has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
The Id of the asset on which this issue was found
- reported_for
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Flag indicating whether the issue is ignored or not.
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
123The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
456789The relative frequency of the issue (percentage of tested records having the issue), as a number between 0.0 and 1.0. If omitted, it is calculated using number_of_occurrences and number_of_tested_records.
Possible values: 0 ≤ value ≤ 1
The status of the issue.
Possible values: [
actual,aggregation,archive]Example:
actual
Status Code
Success
The given payload is invalid and the issue is not created.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create a data quality issue.
The data quality issue exists already and cannot be created.
An error occurred. The data quality issue cannot be created.
{"id":"046605b5-48d9-489e-b846-8ef96a7a1aba","check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"MY_RULE","native_id":"cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","type":"ANY","created_at":"2022-02-02T14:00:45.000Z","creator_id":"SYSTEM"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a"},"number_of_occurrences":123,"number_of_tested_records":456789,"status":"actual","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"}{"trace":"6vbjp9d2t4s9b2ckyspdw4vft","status_code":400,"errors":[{"code":"missing_required_field","message":"Bad Request: {\"trace\":\"8f7b7693-1f08-4b4a-b2bd-5732d06ad19e\", \"errors\":[{\"code\":\"invalid_parameter\", \"message\":\"COMSV3006E: Missing or Invalid asset id\", \"target\":{\"name\":\"asset\",\"type\":\"parameter\"}}]}"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"28izpw5l1a4orh823i6bkqmm","status_code":409,"errors":[{"code":"already_exists","message":"The dimension with name 'Completeness' already exists."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get the data quality issue with the given identifier
Get the data quality issue with the given identifier.
GET /data_quality/v4/issues/{id}Request
Path Parameters
The data quality issue identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Response
A data quality issue, i.e. a data quality problem detected during a check.
the check that produces this issue
- check
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe optional eventual children of this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
An optional list of issues reported by this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
- issues
the dimension this check belongs to
- dimension
Flag indicating whether the dimension is a built-in dimension or not.
The identity of the IBM Knowledge Catalog container (either project/catalog/space) this check belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The Id of an eventual parent, or null if this check has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
The Id of the asset on which this issue was found
- reported_for
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Flag indicating whether the issue is ignored or not.
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
123The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
456789The relative frequency of the issue (percentage of tested records having the issue), as a number between 0.0 and 1.0. If omitted, it is calculated using number_of_occurrences and number_of_tested_records.
Possible values: 0 ≤ value ≤ 1
The status of the issue.
Possible values: [
actual,aggregation,archive]Example:
actual
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality issue.
The data quality issue with the given ID cannot be found.
An error occurred. The data quality issue cannot be returned.
{"id":"046605b5-48d9-489e-b846-8ef96a7a1aba","check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"MY_RULE","native_id":"cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","type":"ANY","created_at":"2022-02-02T14:00:45.000Z","creator_id":"SYSTEM"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a"},"number_of_occurrences":123,"number_of_tested_records":456789,"status":"actual","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Update a data quality issue as specified in the payload details of the request.
Update a data quality issue as specified in the payload details of the request.
The updates must be specified by using the JSON patch format, described in RFC 6902.
The following attributes can be updated: - /ignored (value can only be replaced)
PATCH /data_quality/v4/issues/{id}Request
Path Parameters
The data quality issue identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The updates to make in the data quality rule.
Example: [{"op":"replace","path":"/description","value":"The proportion of data stored against the potential for 100% of the data."}]
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
A data quality issue, i.e. a data quality problem detected during a check.
the check that produces this issue
- check
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
check_uniqueness_of_idUnique identifier set by the creator of the resource
Possible values: 1 ≤ length ≤ 500
Example:
4cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47The type of the data quality resource
Possible values: 1 ≤ length ≤ 200
Example:
data_ruleThe optional eventual children of this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
An optional list of issues reported by this data quality check.
Possible values: 0 ≤ number of items ≤ 100000
- issues
the dimension this check belongs to
- dimension
Flag indicating whether the dimension is a built-in dimension or not.
The identity of the IBM Knowledge Catalog container (either project/catalog/space) this check belongs to.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The Id of an eventual parent, or null if this check has no parent
- parent
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223
The Id of the asset on which this issue was found
- reported_for
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Flag indicating whether the issue is ignored or not.
Link to corresponding data quality component. No default link is available, it is empty if not provided.
Possible values: 1 ≤ length ≤ 500
Example:
/v2/assets/f0d42bb9-55b5-4ec8-aca5-f77e42978a86?project_id=08716e38-1a1b-4e0e-9533-c2b419063223The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
123The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
456789The relative frequency of the issue (percentage of tested records having the issue), as a number between 0.0 and 1.0. If omitted, it is calculated using number_of_occurrences and number_of_tested_records.
Possible values: 0 ≤ value ≤ 1
The status of the issue.
Possible values: [
actual,aggregation,archive]Example:
actual
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality issue.
The data quality issue with the given ID cannot be found.
An error occurred. The data quality issue cannot be updated.
{"id":"046605b5-48d9-489e-b846-8ef96a7a1aba","check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"MY_RULE","native_id":"cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","type":"ANY","created_at":"2022-02-02T14:00:45.000Z","creator_id":"SYSTEM"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a"},"number_of_occurrences":123,"number_of_tested_records":456789,"status":"actual","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Search for a data quality issue by its native id
Search for a data quality issue by its native id
POST /data_quality/v4/search_dq_issue
Request
Query Parameters
The data quality asset identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality check identifier to search issues of.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Response
A data quality issue, i.e. a data quality problem detected during a check on a given asset.
An array of previous data quality issues detected during the same check on the given asset.
Possible values: 0 ≤ number of items ≤ 100
An array of data quality issues detected during the same check on children of the given asset.
Possible values: 0 ≤ number of items ≤ 10000
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to search data quality issues.
The data quality issue cannot be found.
An error occurred. The data quality issue cannot be searched.
{"id":"046605b5-48d9-489e-b846-8ef96a7a1aba","check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"MY_RULE","native_id":"cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","type":"ANY","created_at":"2022-02-02T14:00:45.000Z","creator_id":"SYSTEM"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a"},"number_of_occurrences":123,"number_of_tested_records":456789,"status":"actual","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z","archived_issues":[{"id":"046605b5-48d9-489e-b846-8ef96a7a1aba","check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"MY_RULE","native_id":"cdcd382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","type":"ANY","created_at":"2022-02-02T14:00:45.000Z","creator_id":"SYSTEM"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a"},"number_of_occurrences":123,"number_of_tested_records":456789,"status":"archive","creator_id":"SYSTEM","created_at":"2022-02-01T14:00:45.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Create several data quality issues. The related DQ assets referenced by their native ID are created if they do not already exist
Create several data quality issues. The related DQ assets referenced by their native ID are created if they do not already exist.
POST /data_quality/v4/create_issues
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Data quality issues to create and their related DQ assets.
Example: {"issues":[{"check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b"},"reported_for":{"native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","type":"profile"},"number_of_occurrences":123,"number_of_tested_records":456789,"ignored":false}],"assets":[{"name":"CUSTOMERS","type":"data_asset","native_id":"8ddc659c-b155-498d-b310-4ac8cf629ccc/9a1f3644-3ad4-47be-8eb5-006d367c8702","weight":1}],"existing_checks":[{"id":"6be18374-573a-4cf8-8ab7-e428506e428b"}]}
list of issues to create.
Possible values: 0 ≤ number of items ≤ 100000
Optional list of assets to create. For each of these assets the system will check if an asset with the same native_id exists. If yes, it will ignore it, if not it will create it
Possible values: 0 ≤ number of items ≤ 100000
Optional list of existing checks. For each pair of (asset, check) given, system will create, update or remove an issue depending on the current issue stored for this pair and the new issue given in the payload (or not for deletion).
Possible values: 0 ≤ number of items ≤ 100000
- existing_checks
Response
A collection of data quality issues.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality issues.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create data quality issues.
An error occurred. The data quality issues cannot be created.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/issues?limit=200"},"issues":[{"id":"046605b5-48d9-489e-b846-8ef96a7a1aba","check":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"MY_RULE","native_id":"cdcd4382-4e3a-4537-b7ae-09993acee4cf/3e51167c-6eb2-4069-96dc-5d6df808fd47","type":"ANY","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"reported_for":{"id":"894d01fd-bdfc-4a4f-b68b-62751e06e06a","nativeId":"739e06f8-3gk2-4c4u-8ab7-e5682g06f05a"},"number_of_occurrences":123,"number_of_tested_records":456789,"creator_id":"SYSTEM","created_at":"2022-02-02T10:51:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get a list of data quality scores for a given asset
Get a list of data quality scores for a given asset.
GET /data_quality/v4/scores
Request
Query Parameters
The data quality asset identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The data quality dimension identifier. If not provided, filtering on dimension is not applied.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
falseScore of asset or dimension that is older by given days.
Default:
0
Response
A collection of data quality scores.
Total number of scores available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100Information of asset.
An array of data quality scores.
Possible values: 1 ≤ number of items ≤ 200
An array of data quality scores.
Possible values: 1 ≤ number of items ≤ 200
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality scores.
An error occurred. The list of data quality scores cannot be returned.
{"total_count":100,"asset":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"CUSTOMERS"},"scores":[{"status":"actual","score":0.8,"number_of_checks":1,"timestamp":"2022-02-14T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"score":0.4,"timestamp":"2022-02-14T18:11:02Z"},{"dimension":{"id":"7be18374-573a-4cf8-8ab7-e428506e428b","name":"ACCURACY","description":"Dimension related to accuracy","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"score":0.7,"timestamp":"2022-02-13T18:11:02Z"}]},{"status":"archive","score":0.6,"number_of_checks":2,"timestamp":"2022-02-12T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"score":0.23,"timestamp":"2022-02-12T18:11:02Z"}]},{"status":"archive","score":0.7,"number_of_checks":2,"timestamp":"2022-02-11T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"score":0.23,"timestamp":"2022-02-11T18:11:02Z"}]}],"children":[{"asset":{"id":"5be18374-573a-4cf8-8ab7-e428506e428b","name":"ID"},"scores":[{"status":"actual","score":0.8,"number_of_checks":1,"timestamp":"2022-02-14T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"score":0.4,"timestamp":"2022-02-14T18:11:02Z"}]},{"status":"archive","score":0.6,"number_of_checks":1,"timestamp":"2022-02-12T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"score":0.23,"timestamp":"2022-02-12T18:11:02Z"}]},{"status":"archive","score":0.7,"number_of_checks":1,"timestamp":"2022-02-11T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"score":0.23,"timestamp":"2022-02-11T18:11:02Z"}]}]}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get a list of data quality scores for a given assets
Get a list of data quality scores for a given assets.
GET /data_quality/v4/bulkScores
Request
Query Parameters
Comma-separated list of data quality assets identifier
Possible values: 1 ≤ length ≤ 1000000000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The data quality dimension identifier. If not provided, filtering on dimension is not applied.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If true include the children in the returned resource. If false, only return the resource without its eventual children.
Default:
falseScore of asset or dimension that is older by given days.
Default:
0
Response
An array of ScoreCollection objects.
Total number of scores available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100Information of asset.
An array of data quality scores.
Possible values: 1 ≤ number of items ≤ 200
An array of data quality scores.
Possible values: 1 ≤ number of items ≤ 200
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality scores.
An error occurred. The list of data quality scores cannot be returned.
[{"total_count":100,"asset":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"CUSTOMERS"},"scores":[{"status":"actual","score":0.8,"number_of_checks":1,"timestamp":"2022-02-14T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45Z"},"score":0.4,"timestamp":"2022-02-14T18:11:02Z"},{"dimension":{"id":"7be18374-573a-4cf8-8ab7-e428506e428b","name":"ACCURACY","description":"Dimension related to accuracy","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45Z"},"score":0.7,"timestamp":"2022-02-13T18:11:02Z"}]},{"status":"archive","score":0.6,"number_of_checks":2,"timestamp":"2022-02-12T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45Z"},"score":0.23,"timestamp":"2022-02-12T18:11:02Z"}]},{"status":"archive","score":0.7,"number_of_checks":2,"timestamp":"2022-02-11T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45Z"},"score":0.23,"timestamp":"2022-02-11T18:11:02Z"}]}],"children":[{"asset":{"id":"5be18374-573a-4cf8-8ab7-e428506e428b","name":"ID"},"scores":[{"status":"actual","score":0.8,"number_of_checks":1,"timestamp":"2022-02-14T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45Z"},"score":0.4,"timestamp":"2022-02-14T18:11:02Z"}]},{"status":"archive","score":0.6,"number_of_checks":1,"timestamp":"2022-02-12T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45Z"},"score":0.23,"timestamp":"2022-02-12T18:11:02Z"}]},{"status":"archive","score":0.7,"number_of_checks":1,"timestamp":"2022-02-11T18:11:02Z","dimension_scores":[{"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","description":"Dimension related to completeness","is_default":false,"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45Z"},"score":0.23,"timestamp":"2022-02-11T18:11:02Z"}]}]}]}]{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get a list of data quality SLAs
Returns all defined data quality Service Level Agreements
GET /data_quality/v4/slas
Request
Query Parameters
The start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20
Response
A collection of data quality Service Level Agreements
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality SLAs
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality SLAs.
An error occurred. The list of data quality SLAs cannot be returned.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/slas?limit=200"},"slas":[{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address completeness","description":"Makes sure that customers' addresses are reasonably complete","filters":[{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"Address"},{"type":"term","native_id":"943405b5-48d9-489e-b846-8ef96a7a1abf","name":"Zip"}],"conditions":[{"dimension":{"id":"888605b5-48d9-489e-b846-8ef96a7a1abc","name":"Completeness"},"threshold":0.9}],"children":[{"filters":[{"type":"name","value":"address"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.8}]},{"filters":[{"type":"name","value":"zip"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.95}]}],"actions":[{"type":"workflow","native_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd"}],"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Create a data quality SLA
Create a data quality Service Level Agreement (SLA) as specified in the payload. SLAs apply globally and are not tied to specific asset containers.
POST /data_quality/v4/slas
Request
Data quality SLA to create
Example: {"name":"Customer address completeness","description":"Makes sure that customers' addresses are reasonably complete","filters":[{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"CUSTOMER"},{"type":"term","native_id":"943405b5-48d9-489e-b846-8ef96a7a1abf","name":"SUPPLIER"}],"conditions":[{"dimension":{"id":"888605b5-48d9-489e-b846-8ef96a7a1abc","name":"Completeness"},"threshold":0.9}],"children":[{"filters":[{"type":"name","value":"address"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.8}]},{"filters":[{"type":"name","value":"zip"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.95}]}],"actions":[{"type":"workflow","native_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd"}]}
The name of the SLA. Must be unique.
Possible values: 1 ≤ length ≤ 200
The description of the SLA
Possible values: 0 ≤ length ≤ 255
The filter conditions determining which assets are governed by this SLA
Possible values: 0 ≤ number of items ≤ 200
The conditions that have to be met to fulfill this SLA
Possible values: 0 ≤ number of items ≤ 200
The sub-SLAs applying to the children of assets governed directly by this SLA
Possible values: 0 ≤ number of items ≤ 200
The actions to be performed when the SLA conditions are not met
Possible values: 0 ≤ number of items ≤ 200
Response
A Data Quality Service Level Agreement specifying data quality thresholds for specific assets as well as the remediation actions to be triggered when violations are found.
The name of the SLA
Possible values: 1 ≤ length ≤ 200
The filter conditions determining which assets are governed by this SLA
Possible values: 0 ≤ number of items ≤ 100
The conditions that have to be met to fulfill this SLA
Possible values: 0 ≤ number of items ≤ 100
The child SLAs applying to the children of assets governed directly by this SLA
Possible values: 0 ≤ number of items ≤ 100
The actions to be performed when the SLA conditions are not met
Possible values: 0 ≤ number of items ≤ 100
The description of the SLA
Possible values: 0 ≤ length ≤ 255
Status Code
Success
The given payload is invalid and the asset is not created.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create the data quality SLA.
The data quality SLA name exists already and cannot be created.
An error occurred. The data quality SLA cannot be created.
{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address completeness","description":"Makes sure that customers' addresses are reasonably complete","filters":[{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"CUSTOMER"},{"type":"term","native_id":"943405b5-48d9-489e-b846-8ef96a7a1abf","name":"SUPPLIER"}],"conditions":[{"dimension":{"id":"888605b5-48d9-489e-b846-8ef96a7a1abc","name":"Completeness"},"threshold":0.9}],"children":[{"filters":[{"type":"name","value":"address"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.8}]},{"filters":[{"type":"name","value":"zip"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.95}]}],"actions":[{"type":"workflow","native_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd"}],"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z","updater_id":"SYSTEM","updated_at":"2022-02-03T16:12:42.000Z"}{"trace":"6vbjp9d2t4s9b2ckyspdw4vft","status_code":400,"errors":[{"code":"missing_required_field","message":"Bad Request: {\"trace\":\"8f7b7693-1f08-4b4a-b2bd-5732d06ad19e\", \"errors\":[{\"code\":\"invalid_parameter\", \"message\":\"COMSV3006E: Missing or Invalid asset id\", \"target\":{\"name\":\"asset\",\"type\":\"parameter\"}}]}"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"28izpw5l1a4orh823i6bkqmm","status_code":409,"errors":[{"code":"already_exists","message":"The dimension with name 'Completeness' already exists."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get a data quality SLA
Get the data quality Service Level Agreement with the given identifier
GET /data_quality/v4/slas/{sla_id}Request
Path Parameters
The data quality Service Level Agreement identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
A Data Quality Service Level Agreement specifying data quality thresholds for specific assets as well as the remediation actions to be triggered when violations are found.
The name of the SLA
Possible values: 1 ≤ length ≤ 200
The filter conditions determining which assets are governed by this SLA
Possible values: 0 ≤ number of items ≤ 100
The conditions that have to be met to fulfill this SLA
Possible values: 0 ≤ number of items ≤ 100
The child SLAs applying to the children of assets governed directly by this SLA
Possible values: 0 ≤ number of items ≤ 100
The actions to be performed when the SLA conditions are not met
Possible values: 0 ≤ number of items ≤ 100
The description of the SLA
Possible values: 0 ≤ length ≤ 255
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality SLA.
The data quality SLA with the given ID cannot be found.
An error occurred. The data quality SLA cannot be returned.
{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address completeness","description":"Makes sure that customers' addresses are reasonably complete","filters":[{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"CUSTOMER"},{"type":"term","native_id":"943405b5-48d9-489e-b846-8ef96a7a1abf","name":"SUPPLIER"}],"conditions":[{"dimension":{"id":"888605b5-48d9-489e-b846-8ef96a7a1abc","name":"Completeness"},"threshold":0.9}],"children":[{"filters":[{"type":"name","value":"address"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.8}]},{"filters":[{"type":"name","value":"zip"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.95}]}],"actions":[{"type":"workflow","native_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd"}],"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z","updater_id":"SYSTEM","updated_at":"2022-02-03T16:12:42.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Update a data quality SLA
Update a data quality SLA as specified in the payload.
PUT /data_quality/v4/slas/{sla_id}Request
Path Parameters
The data quality Service Level Agreement identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The updates to make on the SLA
Example: {"name":"Customer address completeness","description":"Makes sure that customers' addresses are reasonably complete","filters":[{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"CUSTOMER"},{"type":"term","native_id":"943405b5-48d9-489e-b846-8ef96a7a1abf","name":"SUPPLIER"}],"conditions":[{"dimension":{"id":"888605b5-48d9-489e-b846-8ef96a7a1abc","name":"Completeness"},"threshold":0.9}],"children":[{"filters":[{"type":"name","value":"address"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.8}]},{"filters":[{"type":"name","value":"zip"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.95}]}],"actions":[{"type":"workflow","native_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd"}]}
The name of the SLA. Must be unique.
Possible values: 1 ≤ length ≤ 200
The description of the SLA
Possible values: 0 ≤ length ≤ 255
The filter conditions determining which assets are governed by this SLA
Possible values: 0 ≤ number of items ≤ 200
The conditions that have to be met to fulfill this SLA
Possible values: 0 ≤ number of items ≤ 200
The sub-SLAs applying to the children of assets governed directly by this SLA
Possible values: 0 ≤ number of items ≤ 200
The actions to be performed when the SLA conditions are not met
Possible values: 0 ≤ number of items ≤ 200
Response
A Data Quality Service Level Agreement specifying data quality thresholds for specific assets as well as the remediation actions to be triggered when violations are found.
The name of the SLA
Possible values: 1 ≤ length ≤ 200
The filter conditions determining which assets are governed by this SLA
Possible values: 0 ≤ number of items ≤ 100
The conditions that have to be met to fulfill this SLA
Possible values: 0 ≤ number of items ≤ 100
The child SLAs applying to the children of assets governed directly by this SLA
Possible values: 0 ≤ number of items ≤ 100
The actions to be performed when the SLA conditions are not met
Possible values: 0 ≤ number of items ≤ 100
The description of the SLA
Possible values: 0 ≤ length ≤ 255
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality SLA.
The data quality SLA with the given ID cannot be found.
An error occurred. The data quality SLA cannot be updated.
{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address completeness","description":"Makes sure that customers' addresses are reasonably complete","filters":[{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"CUSTOMER"},{"type":"term","native_id":"943405b5-48d9-489e-b846-8ef96a7a1abf","name":"SUPPLIER"}],"conditions":[{"dimension":{"id":"888605b5-48d9-489e-b846-8ef96a7a1abc","name":"Completeness"},"threshold":0.9}],"children":[{"filters":[{"type":"name","value":"address"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.8}]},{"filters":[{"type":"name","value":"zip"}],"conditions":[{"dimension":{"id":"666605b5-48d9-489e-b846-8ef96a7a1abc","name":"Validity"},"threshold":0.95}]}],"actions":[{"type":"workflow","native_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd"}],"creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z","updater_id":"SYSTEM","updated_at":"2022-02-03T16:12:42.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Delete a data quality SLA
Delete the data quality SLA with the given identifier
DELETE /data_quality/v4/slas/{sla_id}Request
Path Parameters
The data quality Service Level Agreement identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality SLA.
The data quality SLA cannot be found.
An error occurred. The data quality SLA cannot be deleted.
{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
List SLA assessments for an asset
List the Service Level Agreement assessments for an asset
GET /data_quality/v4/assets/{id}/sla_assessmentsRequest
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The data quality Service Level Agreement identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5If true, returns only the latest assessment for each SLA.
Default:
falseDefines whether assessments with violations should be listed first. Ignored when an SLA id is provided.
Default:
trueThe start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20
Response
A collection of data quality SLA assessments
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20The total number of resources available
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality SLA assessments
Possible values: 0 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality SLA assessments.
An error occurred. The list of data quality SLA assessments cannot be returned.
{"total_count":1,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/slas/assessments?asset_id=333605b5-48d9-489e-b846-8ef96a7a1abc&limit=200"},"sla_assessments":[{"id":"222605b5-48d9-489e-b846-8ef96a7a1def","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"sla":{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address SLA"},"is_latest":true,"num_violations":3,"violations_on_asset":1,"violations_on_children":2,"dimensions_with_violations":[{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Consistency"},null],"actions":[{"type":"workflow","name":"DQ Remediation for customer US Government","native_id":"255505b5-8888-489e-b846-8ef96a7a1def","native_definition_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd","completed":true,"details":"{completed_on_time: true}","created_at":"2023-02-01T18:11:02.000Z"}],"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get an SLA assessment
Get the Service Level Agreement assessment with the given identifier
GET /data_quality/v4/assets/{id}/sla_assessments/{assessment_id}Request
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality SLA assessment identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The maximum number of violations to return.
Possible values: 0 ≤ value ≤ 200
Default:
20Example:
20
Response
An instance of an SLA assessment for a specific asset and its sub-assets
The main asset that was evaluated for SLA violations (potentially including child assets)
- asset
Name of a data quality resource.(Name need not be unique)
Possible values: 1 ≤ length ≤ 200
Example:
CUSTOMERSThe identity of the IBM Knowledge Catalog asset this Asset is referring
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The type of the IBM Knowledge Catalog asset
Possible values: 1 ≤ length ≤ 200
Example:
DataSetResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The evaluated SLA
- sla
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The name of the SLA
Possible values: 1 ≤ length ≤ 200
The total number of found violations
The number of found violations on the asset itself
The number of found violations on the asset's children
Flag indicating whether this is the latest assessment for the referenced SLA on the referenced asset
The actions triggered by this assessment
Possible values: 0 ≤ number of items ≤ 200
The assessment time.
Possible values: 20 ≤ length ≤ 24
A list of all data quality dimensions with violations in this assessment. The 'overall' dimension is represented by an empty object.
The violations found in this assessment (optional, limited to the first page of the full list)
- violations
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20The total number of resources available
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality SLA violations
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality SLA assessment.
The data quality SLA assessment with the given ID cannot be found.
An error occurred. The data quality SLA assessment cannot be returned.
{"id":"222605b5-48d9-489e-b846-8ef96a7a1def","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"sla":{"id":"999605b5-48d9-489e-b846-8ef96a7a1abc","name":"Customer address SLA"},"is_latest":true,"num_violations":3,"violations_on_asset":1,"violations_on_children":2,"dimensions_with_violations":[{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Consistency"},null],"violations":{"total_count":3,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/slas?limit=200"},"violations":[{"id":"6b744574-573a-4cf8-8ab7-e428506e4289","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"Address"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"missed_threshold":0.9,"score":0.4,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4290","asset":{"wkc_asset_id":"48e18374-573a-4cf8-8ab7-e428506e428b","name":"AGE","wkc_asset_type":"Column"},"filter":{"type":"name","value":"age"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Freshness"},"missed_threshold":1,"score":0.7,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4291","asset":{"wkc_asset_id":"46849374-573a-4cf8-8ab7-e428506e428b","name":"ZIP","wkc_asset_type":"Column"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1ccc","name":"Zip"},"dimension":{"id":"45645632-573a-4cf8-8ab7-e428506e428b","name":"Correctness"},"missed_threshold":0.98,"score":0.8,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}]},"actions":[{"type":"workflow","name":"DQ Remediation","native_id":"255505b5-8888-489e-b846-8ef96a7a1def","native_definition_id":"555605b5-48d9-489e-b846-8ef96a7a1ddd","completed":true,"details":"{completed_on_time: true}","created_at":"2022-02-02T14:00:45.000Z"}],"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get the SLA violations for the given assessment
Get the Service Level Agreement violations for the assessment with the given identifier. The violations are sorted by descending score deviation (threshold minus score).
GET /data_quality/v4/assets/{id}/sla_assessments/{assessment_id}/violationsRequest
Path Parameters
The data quality asset identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality SLA assessment identifier
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The start token of the resource from where the page should begin. If omitted, begins with first resource.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20
Response
A collection of data quality SLA violations
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20The total number of resources available
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality SLA violations
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality SLA violations.
The data quality SLA violations for the assessment with the given ID cannot be found.
An error occurred. The data quality SLA violations cannot be returned.
{"total_count":3,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v4/slas?limit=200"},"violations":[{"id":"6b744574-573a-4cf8-8ab7-e428506e4289","asset":{"wkc_asset_id":"6be18374-573a-4cf8-8ab7-e428506e428b","wkc_asset_type":"Table","name":"CUSTOMERS"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1abd","name":"Address"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"COMPLETENESS"},"missed_threshold":0.9,"score":0.4,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4290","asset":{"wkc_asset_id":"48e18374-573a-4cf8-8ab7-e428506e428b","name":"AGE","wkc_asset_type":"Column"},"filter":{"type":"name","value":"age"},"dimension":{"id":"6be18374-573a-4cf8-8ab7-e428506e428b","name":"Freshness","creator_id":"SYSTEM","created_at":"2022-02-02T14:00:45.000Z"},"missed_threshold":1,"score":0.7,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"},{"id":"6b744574-573a-4cf8-8ab7-e428506e4291","asset":{"wkc_asset_id":"46849374-573a-4cf8-8ab7-e428506e428b","name":"ZIP","wkc_asset_type":"Column"},"filter":{"type":"term","native_id":"043405b5-48d9-489e-b846-8ef96a7a1ccc","name":"Zip"},"dimension":{"id":"45645632-573a-4cf8-8ab7-e428506e428b","name":"Correctness"},"missed_threshold":0.98,"score":0.8,"creator_id":"SYSTEM","created_at":"2023-02-01T18:11:02.000Z"}]}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Get the status of the data quality SLA assessment activation
Get the status of the data quality SLA assessment activation (active/inactive) for a container such as a project or catalog
GET /data_quality/v4/sla_assessment_activation
Request
Query Parameters
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Response
A status object with a boolean value
The status value
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality SLA assessment activation status.
An error occurred. Data quality SLA assessment activation status cannot be retrieved.
{"status":true}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
Activate or deactivate data quality SLA assessments
Activate or deactivate data quality SLA assessments for a IKC(IBM Knowledge Catalog) container such as a project or catalog
PUT /data_quality/v4/sla_assessment_activation
Request
Query Parameters
Whether SLA assessments should be active or inactive
The ID of the catalog to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
The ID of the project to use. A catalog_id or project_id is required.
Possible values: 1 ≤ length ≤ 100
Response
A status object with a boolean value
The status value
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to activate or deactivate data quality SLA assessments.
An error occurred. Data quality SLA assessments cannot be activated or deactivated.
{"status":true}{"trace":"3tirwt88tsejqwh801zw88lek","status_code":403,"errors":[{"code":"not_authorized","message":"User IBMid-341983Z157 with role null is not authorized to perform the operation CREATE."}]}{"trace":"cwuhtyfus0m8f6e49e2g6m4hr","status_code":500,"errors":[{"code":"internal_error","message":"An IOException was caught when accessing asset 'cbf21aa7-cb89-4ee8-9817-0f1d86fbe0cd'."}]}
List all data quality rules or a subset of them
Get a list of data quality rules in the project.
GET /data_quality/v3/projects/{project_id}/rulesRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The start token of the resource from where the page should begin.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20Comma-separated list of data quality rule identifiers.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710
Response
A collection of data quality rules to be returned.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
A collection of data quality rules.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality rules in the specified project.
An error occurred. The list of data quality rules could not be returned.
{"total_count":100,"limit":50,"first":{"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules?limit=50"},"rules":[{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","bound_expression":["TEST.table1.col1<=TEST.table2.col2"],"is_valid":true,"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf","name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Create data quality rule
Create a data quality rule.
POST /data_quality/v3/projects/{project_id}/rulesRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Data quality rule to create.
Example: {"name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}
The name of the data quality rule. The rule name must be unique in the given project. If no unique name is provided, the quality rule will not be created.
Possible values: 1 ≤ length ≤ 200
Example:
address_exists_ruleData quality rule input details.
The description of the data quality rule. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Rule to check address exists.Identity of a data quality dimension resource. If this property is omitted, no data quality dimension is associated with the resource.
Flag indicating whether the rule contributes to all dimensions that are defined in the data quality definitions used in this rule. If the value of this field is set to true, then
dimensionwill be ignored.The output details of a data quality rule. If this property is omitted, no output records are saved.
The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a value for
data_stageis provided.Possible values: 1 ≤ number of items ≤ 50
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Representation of the data stage flow resource to create. If this property is omitted, no subflow is created for the data quality rule.
Response
A data quality rule defines an executable applying a boolean expression on bound columns.
The name of the data quality rule. The name of the quality rule will be unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
address_exists_ruleData quality rule input details.
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5Flag indicating whether the rule is valid or not.
The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality rule. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Rule to check address exists.Identity of a data quality dimension resource.
Flag indicating whether the rule contributes to all dimensions that are defined in the data quality definitions used in this rule. If the value of this field is set to true, then
dimensionwill be ignored.The output details of a data quality rule.
The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a
data_stageelement is provided.Possible values: 1 ≤ number of items ≤ 50
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Data stage flow details.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create data quality rules in the specified project.
An error occurred. The data quality rule could not be created.
{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","bound_expression":["TEST.table1.col1<=TEST.table2.col2"],"is_valid":true,"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf","name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Delete data quality rules
Delete the data quality rules for the given list of rule identifiers.
DELETE /data_quality/v3/projects/{project_id}/rulesRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
Comma-separated list of data quality rule identifiers.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710The option to delete related output tables when deleting data quality rules.
Default:
falseThe option to cancel unfinished jobs before deleting or updating data quality rules.
Default:
false
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality rules in the specified project.
An error occurred. The data quality rules cannot be deleted.
{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Validate data quality rule
Check the validity of the data quality rule.
POST /data_quality/v3/projects/{project_id}/validate_ruleRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Data quality rule to validate.
Example: {"name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}
The name of the data quality rule. The rule name must be unique in the given project. If no unique name is provided, the quality rule will not be created.
Possible values: 1 ≤ length ≤ 200
Example:
address_exists_ruleData quality rule input details.
The description of the data quality rule. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Rule to check address exists.Identity of a data quality dimension resource. If this property is omitted, no data quality dimension is associated with the resource.
Flag indicating whether the rule contributes to all dimensions that are defined in the data quality definitions used in this rule. If the value of this field is set to true, then
dimensionwill be ignored.The output details of a data quality rule. If this property is omitted, no output records are saved.
The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a value for
data_stageis provided.Possible values: 1 ≤ number of items ≤ 50
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Representation of the data stage flow resource to create. If this property is omitted, no subflow is created for the data quality rule.
Response
A data quality rule defines an executable applying a boolean expression on bound columns.
The name of the data quality rule. The name of the quality rule will be unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
address_exists_ruleData quality rule input details.
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5Flag indicating whether the rule is valid or not.
The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality rule. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Rule to check address exists.Identity of a data quality dimension resource.
Flag indicating whether the rule contributes to all dimensions that are defined in the data quality definitions used in this rule. If the value of this field is set to true, then
dimensionwill be ignored.The output details of a data quality rule.
The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a
data_stageelement is provided.Possible values: 1 ≤ number of items ≤ 50
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Data stage flow details.
Status Code
The data quality rule is valid.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to validate data quality rules in the specified project.
The data quality rule is invalid. See the error message for the cause.
{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","bound_expression":["TEST.table1.col1<=TEST.table2.col2"],"is_valid":true,"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf","name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Get data quality rule
Gets the data quality rule with the given identifier.
GET /data_quality/v3/projects/{project_id}/rules/{id}Request
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality rule identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
A data quality rule defines an executable applying a boolean expression on bound columns.
The name of the data quality rule. The name of the quality rule will be unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
address_exists_ruleData quality rule input details.
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5Flag indicating whether the rule is valid or not.
The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality rule. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Rule to check address exists.Identity of a data quality dimension resource.
Flag indicating whether the rule contributes to all dimensions that are defined in the data quality definitions used in this rule. If the value of this field is set to true, then
dimensionwill be ignored.The output details of a data quality rule.
The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a
data_stageelement is provided.Possible values: 1 ≤ number of items ≤ 50
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Data stage flow details.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality rule with the given identifier from the specified project.
The data quality rule cannot be found.
An error occurred. The data quality rule with the given identifier cannot be returned.
{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","bound_expression":["TEST.table1.col1<=TEST.table2.col2"],"is_valid":true,"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf","name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Delete data quality rule
Delete the data quality rule with the given identifier.
DELETE /data_quality/v3/projects/{project_id}/rules/{id}Request
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality rule identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The option to delete related output tables when deleting data quality rules.
Default:
falseThe option to cancel unfinished jobs before deleting or updating data quality rules.
Default:
false
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality rule from the specified project.
The data quality rule cannot be found.
An error occurred. The data quality rule cannot be deleted.
{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Update data quality rule
Updates a data quality rule as specified in the payload details of the update rule request. The updates must be specified by using the JSON patch format, described in RFC 6902.
The following attributes can be patched:
- name (value can only be replaced)
- definition (value can only be replaced)
- description (value can be added, removed, or replaced)
- dimension (value can be added, removed, or replaced)
- input (value can be added, removed or replaced)
- output (value can be added, removed, or replaced)
- joins (value can be added, removed, or replaced)
- sampling (value can be added, removed, or replaced)
- data_stage/propagate_all_incoming_columns (value can be added, removed, or replaced)
PATCH /data_quality/v3/projects/{project_id}/rules/{id}Request
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality rule identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The option to cancel unfinished jobs before deleting or updating data quality rules.
Default:
falseThe option to keep the current data quality rule input binding relationships while updating the data quality rule.
Default:
false
The updates to make in the data quality rule.
Example: [{"op":"replace","path":"/description","value":"Column col1 has fewer or the same number of values as column col2"}]
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
A data quality rule defines an executable applying a boolean expression on bound columns.
The name of the data quality rule. The name of the quality rule will be unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
address_exists_ruleData quality rule input details.
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5Flag indicating whether the rule is valid or not.
The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality rule. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Rule to check address exists.Identity of a data quality dimension resource.
Flag indicating whether the rule contributes to all dimensions that are defined in the data quality definitions used in this rule. If the value of this field is set to true, then
dimensionwill be ignored.The output details of a data quality rule.
The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a
data_stageelement is provided.Possible values: 1 ≤ number of items ≤ 50
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Data stage flow details.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality rule in the specified project.
The data quality rule cannot be found.
An error occurred. The data quality rule was not updated.
{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","bound_expression":["TEST.table1.col1<=TEST.table2.col2"],"is_valid":true,"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf","name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Run data quality rule
Run the data quality rule with the given identifier.
POST /data_quality/v3/projects/{project_id}/rules/{id}/executeRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality rule identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
The representation of a data quality rule execution.
Identity of a job associated with a rule.
Identity of a run associated with a job, which in turn is associated with a a rule.
The status of the rule run.
The name of the user that ran the rule.
Possible values: 1 ≤ length ≤ 50
Example:
IBMid-270002ABCDResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfNumber of passing records.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
900Number of failing records.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100Data quality rule input details.
The output details of a data quality rule.
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Number of records tested.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
1000The start time of the rule run.
Possible values: 20 ≤ length ≤ 24
The end time of the rule run.
Possible values: 20 ≤ length ≤ 24
Name of the result.
Possible values: 1 ≤ length ≤ 200
Example:
execution1A list of execution results per definition.
Possible values: 1 ≤ number of items ≤ 100
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to run the data quality rule in the specified project.
The data quality rule cannot be found.
An error occurred. The data quality rule cannot be run.
{"name":"table1.col1LessOrEqualTable2.col2","job":{"id":"aa398b69-3e91-4830-877a-91a8e21f56de"},"job_run":{"id":"aa398b69-3e91-4830-877a-91a8e21f5123"},"status":{"state":"analyzed"},"started_at":"2022-02-01T18:10:02.000Z","ended_at":"2022-02-01T18:11:02.000Z","run_by":"IBMid-270002ABCD","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"input":{"definitions":[{"bound_expression":"TEST.table1.col1<=TEST.table2.col2"}]},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"aa398b69-3e91-4830-877a-91a8e21f56de"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"output_table":{"id":"5d4254a6-0c9e-4a02-bc24-4a89eee06f12"},"tested_record_count":1000,"passing_record_count":987,"failing_record_count":13,"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf/executions/7b3f3a79-6412-480b-a20c-393a3f7adabc"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Get data quality rule from catalog
Gets the data quality rule from catalog with the given identifier.
GET /data_quality/v3/catalogs/{catalog_id}/rules/{id}Request
Path Parameters
The identifier of the catalog to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality rule identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
A data quality rule defines an executable applying a boolean expression on bound columns.
The name of the data quality rule. The name of the quality rule will be unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
address_exists_ruleData quality rule input details.
Resource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5Flag indicating whether the rule is valid or not.
The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality rule. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Rule to check address exists.Identity of a data quality dimension resource.
Flag indicating whether the rule contributes to all dimensions that are defined in the data quality definitions used in this rule. If the value of this field is set to true, then
dimensionwill be ignored.The output details of a data quality rule.
The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a
data_stageelement is provided.Possible values: 1 ≤ number of items ≤ 50
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Data stage flow details.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality rule with the given identifier from the specified catalog.
The data quality rule cannot be found.
An error occurred. The data quality rule with the given identifier cannot be returned.
{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","bound_expression":["TEST.table1.col1<=TEST.table2.col2"],"is_valid":true,"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf","name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"input":{"definitions":[{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":1,"bindings":[{"variable_name":"col1","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col1","type":"column"}}]},{"definition":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"disambiguator":2,"bindings":[{"variable_name":"col2","target":{"data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"column_name":"col2","type":"column"}}]}]},"joins":[{"type":"inner_join","left_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"right_data_asset":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93xyz"},"left_column_name":"col1","right_column_name":"col2"}],"dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"apply_all_present_dimensions":false}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
List history of all data quality rule run results or a subset of them
Gets the list of data quality rule runs. By default, the runs are sorted newest to oldest.
GET /data_quality/v3/projects/{project_id}/rules/{rule_id}/executionsRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality rule identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The start token of the resource from where the page should begin.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20The property name by which the results should be sorted. For descending order, use the hyphen (-) prefix with the value. If you omit this query parameter, the order value is
-started_at, which means, results are sorted by thestarted_atvalue in descending order. The allowed fields arestarted_at,passing_record_count,failing_record_count,tested_record_count,status.state.Possible values: 1 ≤ length ≤ 128
Response
Data quality rule run history
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
A list of rule run results, sorted based on the value of the
sortquery parameter.Possible values: 1 ≤ number of items ≤ 50
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality rule history in the specified project.
An error occurred. The data quality rule history could not be returned.
{"limit":20,"total_count":100,"first":{"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/c19cde3a-5940-4c7a-ad0f-ee18f5f29c12/executions?limit=20"},"executions":[{"name":"table1.col1LessOrEqualTable2.col2","description":"The column TEST.table1.col1 has fewer or the same number of values as column TEST.table2.col2","job":{"id":"aa398b69-3e91-4830-877a-91a8e21f56de"},"job_run":{"id":"aa398b69-3e91-4830-877a-91a8e21f5123"},"status":{"state":"analyzed"},"started_at":"2022-02-01T18:10:02.000Z","ended_at":"2022-02-01T18:11:02.000Z","run_by":"IBMid-270002ABCD","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"aa398b69-3e91-4830-877a-91a8e21f56de"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"output_table":{"id":"5d4254a6-0c9e-4a02-bc24-4a89eee06f12"},"tested_record_count":1000,"bound_expression":["TEST.table1.col1<=TEST.table2.col2"],"passing_record_count":987,"failing_record_count":13,"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf/executions/7b3f3a79-6412-480b-a20c-393a3f7adabc"}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Get the data quality rule run
Gets the data quality rule run result with the given identifier.
GET /data_quality/v3/projects/{project_id}/rules/{rule_id}/executions/{id}Request
Path Parameters
The data quality rule identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The run identifier to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
The representation of a data quality rule execution.
Identity of a job associated with a rule.
Identity of a run associated with a job, which in turn is associated with a a rule.
The status of the rule run.
The name of the user that ran the rule.
Possible values: 1 ≤ length ≤ 50
Example:
IBMid-270002ABCDResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfNumber of passing records.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
900Number of failing records.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100Data quality rule input details.
The output details of a data quality rule.
The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.
Number of records tested.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
1000The start time of the rule run.
Possible values: 20 ≤ length ≤ 24
The end time of the rule run.
Possible values: 20 ≤ length ≤ 24
Name of the result.
Possible values: 1 ≤ length ≤ 200
Example:
execution1A list of execution results per definition.
Possible values: 1 ≤ number of items ≤ 100
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality rule run result in the specified project.
An error occurred. The result of data quality rule run could not be returned.
{"name":"table1.col1LessOrEqualTable2.col2","job":{"id":"aa398b69-3e91-4830-877a-91a8e21f56de"},"job_run":{"id":"aa398b69-3e91-4830-877a-91a8e21f5123"},"status":{"state":"analyzed"},"started_at":"2022-02-01T18:10:02.000Z","ended_at":"2022-02-01T18:11:02.000Z","run_by":"IBMid-270002ABCD","sampling":{"size":2500,"interval":13,"sampling_type":"every_nth"},"input":{"definitions":[{"bound_expression":"TEST.table1.col1<=TEST.table2.col2"}]},"output":{"columns":[{"variable_name":"col1","name":"out1","type":"rule_variable","disambiguator":1},{"name":"out2","type":"column","source_column":{"data_asset":{"id":"aa398b69-3e91-4830-877a-91a8e21f56de"},"column_name":"col1","type":"column"}},{"expression":"col1-col2","name":"out4","type":"rule_expression","disambiguator":2},{"metric":"system_time","name":"out5","type":"metric"}],"database":{"records_type":"all_records","update_type":"append","location":{"connection":{"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf"},"schema_name":"TEST","table_name":"output"}},"maximum_record_count":500},"output_table":{"id":"5d4254a6-0c9e-4a02-bc24-4a89eee06f12"},"tested_record_count":1000,"passing_record_count":987,"failing_record_count":13,"id":"7b3f3a79-6412-480b-a20c-393a3f7addbf","href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/rules/7b3f3a79-6412-480b-a20c-393a3f7addbf/executions/7b3f3a79-6412-480b-a20c-393a3f7adabc"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
List all data quality definitions or a subset of them
Gets the list of all data quality definitions.
GET /data_quality/v3/projects/{project_id}/definitionsRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The start token of the resource from where the page should begin.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20Comma-separated list of data quality definition identifiers.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710
Response
An array of data quality definitions.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
A collection of existing definitions.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the list of data quality definitions in the specified project.
An error occurred. The list of data quality definitions cannot be returned.
{"total_count":100,"limit":200,"first":{"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions?limit=200"},"definitions":[{"description":"Column col1 has fewer or the same number of values as column col2","id":"7b3f3a79-6412-480b-a20c-393a3f7adoi","name":"col1LessOrEqualCol2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbf"}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Create data quality definition
Creates a data quality definition in the specified project.
POST /data_quality/v3/projects/{project_id}/definitionsRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Data quality definition to create.
Example: {"name":"col1LessOrEqualCol2","description":"Column col1 has fewer or the same number of values as column col2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"}}
The name of the data quality definition. The name of the definition must be unique in the given project. If no unique name is provided, the REST call fails.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource. If this property is omitted, no data quality dimension is associated with the resource.
Response
A data quality definition defines a boolean rule along with the variables.
The name of the data quality definition. The name of the quality definition is unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to create a definition in the specified project.
An error occurred. The definition was not created.
{"description":"Column col1 has fewer or the same number of values as column col2","id":"7b3f3a79-6412-480b-a20c-393a3f7adoi","name":"col1LessOrEqualCol2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbf"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Delete data quality definitions
Delete the data quality definitions with the given identifiers.
DELETE /data_quality/v3/projects/{project_id}/definitionsRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
Comma separated list of data quality definition identifiers.
Possible values: 1 ≤ length ≤ 10000
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5,b1ba1d22-71a7-4adf-99b2-3c8ba1949710
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality definitions in the specified project or catalog.
An error occurred. The data quality definitions cannot be deleted.
{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Validate data quality definition expression
Validate the specified definition expression.
POST /data_quality/v3/projects/{project_id}/validate_definitionRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
True if the expression to validate is an output column expression. False if the expression to validate is a data quality definition expression. Default value is false.
Data quality definition to validate.
Example: {"name":"col1LessOrEqualCol2","description":"Column col1 has fewer or the same number of values as column col2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"}}
The name of the data quality definition. The name of the definition must be unique in the given project. If no unique name is provided, the REST call fails.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource. If this property is omitted, no data quality dimension is associated with the resource.
Response
This response contains the rule expression variables and their types.
The list of variables in this expression. This field is set if the rule is valid (
is_valid=true).Possible values: 1 ≤ number of items ≤ 100
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to validate the data quality definition in the specified project or catalog.
An error occurred. The data quality definitions could not be validated.
{"variables":[{"name":"col1","type":"numeric","usage":"input_data"},{"name":"col2","type":"numeric","usage":"input_data"}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Get data quality definition
Gets the data quality definition with the given identifier.
GET /data_quality/v3/projects/{project_id}/definitions/{id}Request
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality definition identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
A data quality definition defines a boolean rule along with the variables.
The name of the data quality definition. The name of the quality definition is unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality definition with the given ID from the specified project or catalog.
The data quality definition cannot be found.
An error occurred. The data quality definition with the given identifier could not be returned.
{"description":"Column col1 has fewer or the same number of values as column col2","id":"7b3f3a79-6412-480b-a20c-393a3f7adoi","name":"col1LessOrEqualCol2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbf"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Replace data quality definition
Replace a data quality definition.
PUT /data_quality/v3/projects/{project_id}/definitions/{id}Request
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality definition identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Data quality definition to replace.
Example: {"name":"col1LessOrEqualCol2","description":"Column col1 has fewer or the same number of values as column col2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"}}
The name of the data quality definition. The name of the definition must be unique in the given project. If no unique name is provided, the REST call fails.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource. If this property is omitted, no data quality dimension is associated with the resource.
Response
A data quality definition defines a boolean rule along with the variables.
The name of the data quality definition. The name of the quality definition is unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update data quality definitions in the specified project or catalog.
An error occurred. The data quality definition was not updated.
{"description":"Column col1 has fewer or the same number of values as column col2","id":"7b3f3a79-6412-480b-a20c-393a3f7adoi","name":"col1LessOrEqualCol2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbf"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Delete data quality definition
Delete the data quality definition with the given identifier.
DELETE /data_quality/v3/projects/{project_id}/definitions/{id}Request
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality definition identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to delete the data quality definition from the specified project.
The data quality definition cannot be found.
An error occurred. The data quality definition cannot be deleted.
{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Update data quality definition
Updates a data quality definition as specified in the payload details of the update definition request. The updates must be specified by using the JSON patch format, described in RFC 6902.
The following attributes can be patched.
- name (value can only be replaced)
- description (value can be added, removed, or replaced)
- expression (value can only be replaced)
- dimension (value can be added, removed, or replaced)
PATCH /data_quality/v3/projects/{project_id}/definitions/{id}Request
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality definition identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The updates to make in the data quality definition.
Example: [{"op":"replace","path":"/description","value":"Column col1 has fewer or the same number of values as column col2"}]
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
A data quality definition defines a boolean rule along with the variables.
The name of the data quality definition. The name of the quality definition is unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality definition in the specified project.
The data quality definition cannot be found.
An error occurred. The data quality definition was not updated.
{"description":"Column col1 has fewer or the same number of values as column col2","id":"7b3f3a79-6412-480b-a20c-393a3f7adoi","name":"col1LessOrEqualCol2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbf"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Get data quality definition from catalog
Gets the data quality definition from catalog with the given identifier.
GET /data_quality/v3/catalogs/{catalog_id}/definitions/{id}Request
Path Parameters
The identifier of the catalog to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality definition identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
A data quality definition defines a boolean rule along with the variables.
The name of the data quality definition. The name of the quality definition is unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality definition with the given ID from the specified project or catalog.
The data quality definition cannot be found.
An error occurred. The data quality definition with the given identifier could not be returned.
{"description":"Column col1 has fewer or the same number of values as column col2","id":"7b3f3a79-6412-480b-a20c-393a3f7adoi","name":"col1LessOrEqualCol2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbf"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Update data quality definition in catlog
Updates a data quality definition as specified in the payload details of the update definition request. The updates must be specified by using the JSON patch format, described in RFC 6902.
The following attributes can be patched.
- dimension (value can be added, removed, or replaced)
PATCH /data_quality/v3/catalogs/{catalog_id}/definitions/{id}Request
Path Parameters
The identifier of the catalog to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The data quality definition identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
The updates to make in the data quality definition.
Example: [{"op":"replace","path":"/description","value":"Column col1 has fewer or the same number of values as column col2"}]
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
A data quality definition defines a boolean rule along with the variables.
The name of the data quality definition. The name of the quality definition is unique in a given project.
Possible values: 1 ≤ length ≤ 200
Example:
Address exists definitionThe expression of the data quality definition.
Possible values: 1 ≤ length ≤ 10000
Example:
field0 existsResource identifier.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5The location URL of a resource.
Possible values: 1 ≤ length ≤ 512
Example:
https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbfThe description of the data quality definition. If this property is omitted, no description is set.
Possible values: 1 ≤ length ≤ 5000
Example:
Definition to check if address existsIdentity of a data quality dimension resource.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to update the data quality definition in the specified catalog.
The data quality definition cannot be found.
An error occurred. The data quality definition was not updated.
{"description":"Column col1 has fewer or the same number of values as column col2","id":"7b3f3a79-6412-480b-a20c-393a3f7adoi","name":"col1LessOrEqualCol2","expression":"col1 <= col2","dimension":{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93abc"},"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/definitions/7b3f3a79-6412-480b-a20c-393a3f7addbf"}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
List all data quality dimensions
Gets the list of all data quality dimensions
GET /data_quality/v3/projects/{project_id}/dimensionsRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Query Parameters
The start token of the resource from where the page should begin.
Possible values: 1 ≤ length ≤ 512
Example:
g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqzmxiYWJiZGYGkOWDSyBJZAPCBD58The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
20
Response
A collection of data quality dimensions.
The maximum number of resources to return.
Possible values: 1 ≤ value ≤ 200
Example:
20Total number of resources available.
Possible values: 0 ≤ value ≤ 9007199254740991
Example:
100The link to a page in paginated collection.
An array of data quality dimensions.
Possible values: 1 ≤ number of items ≤ 200
The link to a page in paginated collection.
The link to a page in paginated collection.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You are not permitted to get data quality dimensions of the specified project.
An error occurred. The list of data quality dimensions cannot be returned.
{"limit":20,"total_count":100,"first":{"href":"https://cloud.ibm.com/data_quality/v3/projects/c19cde3a-5940-4c7a-ad0f-ee18f5f29c00/dimensions?limit=20"},"dimensions":[{"id":"371114cd-5516-4691-8b2e-1e66edf66486","name":"Completeness","description":"The proportion of data stored against the potential for 100%.","creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"},{"id":"57561203-36e6-4bb0-adfb-ece981fba845","name":"Uniqueness","description":"No entity instance (`abc`) will be recorded more than once based on how `abc` is identified.","creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"},{"id":"a3134282-ed85-4140-ae61-e5f712a61985","name":"Timeliness","description":"The degree to which data represent reality from the required point in time.","creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"},{"id":"ec453723-669c-48bb-82c1-11b69b3b8c93","name":"Validity","description":"Data is valid if it conforms to the syntax (format, type, range) of its definition.","creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"},{"id":"5f66813e-adb1-4f3f-a65f-40e3066aac07","name":"Accuracy","description":"The degree to which data correctly describes the real world object or event being described.","creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"},{"id":"5f66813e-adb1-4f3f-a65f-40e3066aa123","name":"Consistency","description":"The absence of difference when comparing two or more representations of an object against a definition.","creator_id":"SYSTEM","created_at":"2022-02-01T18:11:02.000Z"}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Get project settings for data quality rules
Gets the project settings for data quality rules.
GET /data_quality/v3/projects/{project_id}/settingsRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Response
Project settings.
In rules containing equality tests between strings, this property indicates whether the values to be tested should consider trailing spaces.
This property indicates whether values of data quality rule variables have to be casted automatically to the type expected in the data quality rule expression.
The maximum length of String values when executing data quality rules.
Possible values: 1 ≤ value ≤ 1024
Example:
512In rules with multiple definitions, indicates if definitions evaluating as null (undefined) have to be considered failing (false) or passing (true).
This property indicates whether group keys for aggregations in the data quality rule are case sensitive or not.
If set to true, a string surrounded by double quotes in an expression will be treated as a variable instead of string literal value.
The heap size in MB of the Java stages needed to implement data rules.
Possible values: 1 ≤ value ≤ 2048
Example:
512In rules of the form "IF condition THEN test", this property indicates how data records that do not fulfil the condition have to be evaluated. If the property is not set, the data records are not counted. Otherwise, the records are counted as failing (false) or as passing (true) as defined.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to get the data quality rule settings in the specified project.
An error occurred. The project settings for data quality rules could not be returned.
{"default_else_value":true,"ignore_trailing_spaces":false,"implicit_casting":true,"max_string_length":1024,"allow_quoted_variables":false}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
Replace project settings for data quality rules
Replace project settings for data quality rules.
PUT /data_quality/v3/projects/{project_id}/settingsRequest
Path Parameters
The identifier of the project to use.
Possible values: 1 ≤ length ≤ 128
Example:
b1ba1d22-71a7-4adf-99b2-3c8ba19497f5
Project settings for data quality rules.
Example: {"default_else_value":true,"ignore_trailing_spaces":false,"implicit_casting":true,"max_string_length":1024,"allow_quoted_variables":false}
In rules of the form "IF condition THEN test", this property indicates how data records that do not fulfil the condition have to be evaluated. If the property is not set, the data records are not counted. Otherwise, the records are counted as failing (false) or as passing (true) as defined.
In rules containing equality tests between strings, this property indicates whether the values to be tested should consider trailing spaces.
Default:
falseThis property indicates whether values of data quality rule variables have to be casted automatically to the type expected in the data quality rule expression.
Default:
trueThe maximum length of String values when executing data quality rules.
Possible values: 1 ≤ value ≤ 1024
Default:
1024Example:
512In rules with multiple definitions, indicates if definitions evaluating as null (undefined) have to be considered failing (false) or passing (true).
Default:
trueThis property indicates whether group keys for aggregations in the data quality rule are case sensitive or not.
Default:
trueIf set to true, a string surrounded by double quotes in an expression will be treated as a variable instead of string literal value.
Default:
falseThe heap size in MB of the Java stages needed to implement data rules.
Possible values: 1 ≤ value ≤ 2048
Default:
256Example:
512
Response
Project settings.
In rules containing equality tests between strings, this property indicates whether the values to be tested should consider trailing spaces.
This property indicates whether values of data quality rule variables have to be casted automatically to the type expected in the data quality rule expression.
The maximum length of String values when executing data quality rules.
Possible values: 1 ≤ value ≤ 1024
Example:
512In rules with multiple definitions, indicates if definitions evaluating as null (undefined) have to be considered failing (false) or passing (true).
This property indicates whether group keys for aggregations in the data quality rule are case sensitive or not.
If set to true, a string surrounded by double quotes in an expression will be treated as a variable instead of string literal value.
The heap size in MB of the Java stages needed to implement data rules.
Possible values: 1 ≤ value ≤ 2048
Example:
512In rules of the form "IF condition THEN test", this property indicates how data records that do not fulfil the condition have to be evaluated. If the property is not set, the data records are not counted. Otherwise, the records are counted as failing (false) or as passing (true) as defined.
Status Code
Success.
Your authorization to access this method is missing, invalid, or expired.
You do not have permission to define project settings for data quality rules in the specified project.
An error occurred. The project settings for data quality rules were not created or updated.
{"default_else_value":true,"ignore_trailing_spaces":false,"implicit_casting":true,"max_string_length":1024,"allow_quoted_variables":false}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}{"trace":"cfkvi16tv9bimp2rqve666na0","status_code":404,"errors":[{"code":"not_found","message":"Requested resource was not found.","more_info":"https://www.ibm.com/docs/en/cloud-paks/cp-data/4.5.x?topic=rules-creating-data","target":{"type":"field","name":"name"}}]}
List environments.
Returns a list of environments filtered by type, language or spark version in a project or space.
If no filter is provided, it returns all environments in the project or space, which includes all default environments that are available in every project or space and custom environments created by users.
You need to specify either project_id or space_id.
GET /v2/environments
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4Comma-separated list of environment types. Defaults to list of all types.
Example:
notebook,wml_flowComma-separated list of environment types. Takes precedence over types. Defaults to empty list.
Example:
notebook,wml_flowComma-separated list of kernel languages. Defaults to empty list.
Example:
python2,python3Comma-separated list of Spark versions. If provided, Spark environments will be filtered by these versions. Defaults to list of all default environments with supported Spark versions and all custom environments.
Example:
2.3,2.4
Response
A list of environments.
Size of the list.
Example:
1An array of environments.
Status Code
Success. Returned a list of environments. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my notebook environment", "description": "this is my notebook environment", "asset_type": "environment", "asset_id": "656ca7c3-d971-42c3-918b-a15023cd6b8e", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-10-12T09:18:34.000Z", "href": "/v2/environments/656ca7c3-d971-42c3-918b-a15023cd6b8e" }, "entity": { "environment": { "sub_type": "notebook", "display_name": "My Notebook Environment", "hardware_specification": { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } } } } } }, "software_specification": { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "life_cycle": { "deprecated": true, "wml": { "deprecated": false } }, "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }, "tools_specification": { "supported_kernels": [ { "name": "python3", "language": "python", "version": 3.9, "display_name": "Python 3.9" } ] }, "runtime_definition": "204dac19-7d94-4692-a4c8-2acd77e28792", "spec_type": "referenced" } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new environment.
Returns a new environment with the provided parameters.
You need to specify either project_id or space_id.
Required body parameters vary dependent on environment types:
- notebook:
type,name,display_name,hardware_specification,software_specification,tools_specification,runtime_definition - datastage:
type,name,display_name,hardware_specification - other types:
type,name,display_name,hardware_specification,software_specification
POST /v2/environments
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of the environment to be created.
Create an environment
{
"type": "notebook",
"name": "my notebook environment",
"description": "this is my notebook environment",
"display_name": "My Notebook Environment",
"runtime_definition": "204dac19-7d94-4692-a4c8-2acd77e28792",
"hardware_specification": {
"guid": "2d5191ba-ff9b-4b48-a852-948d49dd9210"
},
"software_specification": {
"guid": "555bd074-cc5b-4396-a7f8-5f03d336a8e5"
},
"tools_specification": {
"supported_kernels": [
{
"name": "python3",
"language": "python",
"version": 3.9,
"display_name": "Python 3.9"
}
]
}
}Type of the environment.
Allowable values: [
notebook,wml_flow,rstudio,default_spark,remote_spark,jupyterlab,remote_yarn,datastage,profiling,modeler,data_privacy,pipelines]Example:
notebookName of the environment.
Example:
my notebook environmentDisplay name of the environment.
Example:
My Notebook EnvironmentA pointer to a hardware specification that was defined elsewhere.
A pointer to a software specification that was defined elsewhere.
Description of the environment.
Example:
this is my notebook environmentEnvironment variables for the environment.
Examples:{ "key1": "value1", "key2": "value2" }Configuration variables for the environment.
Examples:{ "key1": "value1", "key2": "value2" }Runtime idle timeout.
Example:
1800000Runtime definition for the environment.
Example:
204dac19-7d94-4692-a4c8-2acd77e28792Compute specification of the environment.
Tools specification of the environment.
Response
Environment with references to external hardware and software specifications.
Environment metadata.
Environment entity.
Status Code
Success. Created and returned a new environment asset. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
The number of requests has exceeded the rate limit.
{ "metadata": { "name": "my notebook environment", "description": "this is my notebook environment", "asset_type": "environment", "asset_id": "656ca7c3-d971-42c3-918b-a15023cd6b8e", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-10-12T09:18:34.000Z", "href": "/v2/environments/656ca7c3-d971-42c3-918b-a15023cd6b8e" }, "entity": { "environment": { "sub_type": "notebook", "display_name": "My Notebook Environment", "hardware_specification": { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } } } } } }, "software_specification": { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "life_cycle": { "deprecated": true, "wml": { "deprecated": false } }, "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }, "tools_specification": { "supported_kernels": [ { "name": "python3", "language": "python", "version": 3.9, "display_name": "Python 3.9" } ] }, "runtime_definition": "204dac19-7d94-4692-a4c8-2acd77e28792", "spec_type": "referenced" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "rate_limit", "message": "The requests from IBMid-310000A00A exceeds rate limit. Please try again later." } ] }
Retrieve an environment.
Returns an environment of a given ID. You need to specify either project_id or space_id.
GET /v2/environments/{environment_guid}Request
Path Parameters
The guid of the environment.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4Format the response. Defaults to none.
Example:
default_sparkWhether to include conda_yml file content of custom package extensions in the response. Defaults to false.
Response
Environment with references to external hardware and software specifications.
Environment metadata.
Environment entity.
Status Code
Success. Returned the environment. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my notebook environment", "description": "this is my notebook environment", "asset_type": "environment", "asset_id": "656ca7c3-d971-42c3-918b-a15023cd6b8e", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-10-12T09:18:34.000Z", "href": "/v2/environments/656ca7c3-d971-42c3-918b-a15023cd6b8e" }, "entity": { "environment": { "sub_type": "notebook", "display_name": "My Notebook Environment", "hardware_specification": { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } } } } } }, "software_specification": { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "life_cycle": { "deprecated": true, "wml": { "deprecated": false } }, "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }, "tools_specification": { "supported_kernels": [ { "name": "python3", "language": "python", "version": 3.9, "display_name": "Python 3.9" } ] }, "runtime_definition": "204dac19-7d94-4692-a4c8-2acd77e28792", "spec_type": "referenced" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete an environment.
Deletes an environment of a given ID. You need to specify either project_id or space_id.
DELETE /v2/environments/{environment_guid}Request
Path Parameters
The guid of the environment.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Response
Status Code
Success. The environment is deleted.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Update an environment.
Updates an environment of a given ID with the provided parameters. Returns the environment with updated properties. Only custom environments can be updated.
PATCH /v2/environments/{environment_guid}Request
Path Parameters
The guid of the environment.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of changes.
Update an environment
{
"/metadata/name": "my updated notebook environment",
"/metadata/description": "this is my updated notebook environment",
"/entity/environment/display_name": "My Updated Notebook Environment",
"/entity/environment/hardware_specification": {
"guid": "2d5191ba-ff9b-4b48-a852-948d49dd9210"
},
"/entity/environment/software_specification": {
"guid": "555bd074-cc5b-4396-a7f8-5f03d336a8e5"
},
"/entity/environment/runtime_idle_time": 3600000,
"/entity/environment/environment_variables": {
"key1": "value1",
"key2": "value2"
},
"/entity/environment/config_variables": {
"key3": "value3",
"key4": "value4"
},
"/entity/environment/tools_specification": {
"supported_kernels": [
{
"name": "python3",
"language": "python",
"version": 3.9,
"display_name": "Python 3.9"
}
]
}
}Name of the environment.
Example:
my updated notebook environmentDescription of the environment.
Example:
this is my updated notebook environmentDisplay name of the environment.
Example:
My Updated Notebook EnvironmentA pointer to a hardware specification that was defined elsewhere.
A pointer to a software specification that was defined elsewhere.
Compute specification of the environment.
Runtime idle timeout.
Example:
3600000Environment variables for the environment.
Examples:{ "key1": "value1", "key2": "value2" }Config variables for the environment.
Examples:{ "key3": "value3", "key4": "value4" }Tools specification of the environment.
Response
Status Code
Success. Updated the environment.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
List hardware specifications.
Returns a list of hardware specifications.
- If neither
project_idnorspace_idis given, it returns all global hardware specifications. - If
project_idorspace_idis given, it returns all global and scoped hardware specifications. In this case, you need to specify eitherproject_idorspace_id.
GET /v2/hardware_specifications
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The name of the hardware specification. If specified, each of the hardware specification in the returned list will have the specified name.
Response
A list of hardware specifications.
Number of items in the list.
Example:
1An array of hardware specifications.
Status Code
Success. Returned a list of hardware specifications. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } } } } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new hardware specification.
Returns a hardware specification created with provided parameters.
-
To create a global custom hardware specification,
project_idorspace_idis not required. Global custom hardware specifications can be only created with the credentials of thewdp-service-id. -
To create a scoped hardware specification, you need to specify either
project_idorspace_id.
You can only provide exactly one of nodes, spark or datastage in the request body.
POST /v2/hardware_specifications
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of the hardware specification to be created.
Create a hardware specification for nodes
{
"name": "my hardware specification",
"description": "this is my hardware specification",
"nodes": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
},
"gpu": {
"num_gpu": 2,
"name": "v100",
"gpu_profile": "generic",
"mig_profile": "N/A"
},
"num_nodes": 1,
"num_drivers": 1,
"drivers": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
}
}
}Create a hardware specification for Spark
{
"name": "my hardware specification",
"description": "this is my hardware specification",
"spark": {
"num_drivers": 1,
"num_executors": 2,
"driver": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
},
"executor": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
}
}
}Create a hardware specification for DataStage
{
"name": "my hardware specification",
"description": "this is my hardware specification",
"datastage": {
"num_conductors": 1,
"num_computes": 2,
"conductor": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
},
"compute": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
},
"instance": "instance-1"
}
}Name of hardware specification.
Example:
my hardware specificationDescription of hardware specification.
Example:
this is my hardware specificationHardware specification nodes main entity.
- One of
Response
A hardware specification.
Hardware specification metadata.
Hardware specification main entity.
Status Code
Success. Created and returned a new hardware specification asset. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
Conflict. Specification already exists with given name. Restriction applicable only for global specifications.
{ "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "conflict", "message": "Document already exists." } ] }
Retrieve a hardware specification.
Returns a hardware specification of a given ID.
- To retrieve a global hardware specification,
project_idorspace_idis not required. - To retrieve a scoped hardware specification that is scoped to a project or a space, you need to specify either
project_idorspace_id.
GET /v2/hardware_specifications/{hardware_specification_guid}Request
Path Parameters
The guid of the hardware specification.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Response
A hardware specification.
Hardware specification metadata.
Hardware specification main entity.
Status Code
Success. Returned the hardware specification. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete a hardware specification.
Deletes a hardware specification of a given ID. Global built-in hardware specifications cannot be deleted through the API.
-
To delete a global custom hardware specification,
project_idorspace_idis not required. Gloabl custom hardware specifications can be only deleted with the credentials of thewdp-service-id. -
To delete a scoped hardware specification that is scoped to a project or a space, you need to specify either
project_idorspace_id.
DELETE /v2/hardware_specifications/{hardware_specification_guid}Request
Path Parameters
The guid of the hardware specification.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Response
Status Code
Success. The hardware specification is deleted.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Update a hardware specification.
Updates a hardware specification of a given ID with the provided parameters. Global built-in hardware specifications cannot be updated through the API.
-
To update a global custom hardware specification,
project_idorspace_idis not required. Gloabl custom hardware specifications can be only updated with the credentials of thewdp-service-id. -
To update a scoped hardware specification that is scoped to a project or a space, you need to specify either
project_idorspace_id.
PATCH /v2/hardware_specifications/{hardware_specification_guid}Request
Path Parameters
The guid of the hardware specification.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of changes.
Update a hardware specification for nodes
{
"/metadata/name": "my hardware specification",
"/metadata/description": "this is my hardware specification",
"/entity/hardware_specification/nodes/cpu/units": "100m",
"/entity/hardware_specification/nodes/cpu/model": "string",
"/entity/hardware_specification/nodes/mem/size": "8Gi",
"/entity/hardware_specification/nodes/gpu/num_gpu": 2,
"/entity/hardware_specification/nodes/gpu/name": "v100",
"/entity/hardware_specification/nodes/num_nodes": 1
}Update a hardware specification for Spark
{
"/metadata/name": "my hardware specification",
"/metadata/description": "this is my hardware specification",
"/entity/hardware_specification/spark/num_drivers": 1,
"/entity/hardware_specification/spark/num_executors": 2,
"/entity/hardware_specification/spark/driver/cpu/units": "100m",
"/entity/hardware_specification/spark/driver/cpu/model": "string",
"/entity/hardware_specification/spark/driver/mem/size": "8Gi",
"/entity/hardware_specification/spark/executor/cpu/units": "100m",
"/entity/hardware_specification/spark/executor/cpu/model": "string",
"/entity/hardware_specification/spark/executor/mem/size": "8Gi"
}Update a hardware specification for DataStage
{
"/metadata/name": "my hardware specification",
"/metadata/description": "this is my hardware specification",
"/entity/hardware_specification/datastage/num_conductors": 1,
"/entity/hardware_specification/datastage/num_computes": 2,
"/entity/hardware_specification/datastage/conductor/cpu/units": "100m",
"/entity/hardware_specification/datastage/conductor/cpu/model": "string",
"/entity/hardware_specification/datastage/conductor/mem/size": "8Gi",
"/entity/hardware_specification/datastage/compute/cpu/units": "100m",
"/entity/hardware_specification/datastage/compute/cpu/model": "string",
"/entity/hardware_specification/datastage/compute/mem/size": "8Gi",
"/entity/hardware_specification/datastage/instance": "instance-1"
}Name of the hardware specification.
Example:
my hardware specificationDescription of the hardware specification.
Example:
this is my hardware specificationBody parameters to update a nodes hardware specification.
- One of
Response
A hardware specification.
Hardware specification metadata.
Hardware specification main entity.
Status Code
Success. Updated the hardware specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
List software specifications.
Returns a list of software specifications.
- If neither
project_idnorspace_idis given, it returns all base software specifications. - If
project_idorspace_idis given, it returns all base and derived software specifications. In this case, you need to specify eitherproject_idorspace_id.
GET /v2/software_specifications
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519eString of comma-separated package names that refers to the packages that a software specification should contain. If specified, each of the software specification in the returned list will contain all of the packages specified in the query.
Example:
pytorch,scikit-learnThe name of the software specification. If specified, each of the software specification in the returned list will have the specified name.
The purpose of the software specification. If specified, each of the software specification in the returned list will have the specified purpose. Only supports a single purpose.
Example:
notebookWhether the software specification is deprecated or not. Software specifications without this property will be regarded as NOT deprecated by default.
Whether the software specification is constricted or not. Software specifications without this property will be regarded as NOT constricted by default.
Whether the software specification is retired or not. Software specifications without this property will be regarded as NOT retired by default.
Response
A list of software specifications.
Number of results.
Example:
1An array of software specifications.
Status Code
Success. Returned a list of software specifications.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "life_cycle": { "deprecated": true, "wml": { "deprecated": false } }, "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new software specification.
Returns a software specification created with provided parameters.
If a software specification has the purpose wml, its name should be unique.
- To create a base custom software specification:
project_idorspace_idis not required.- Base custom software specifications can be only created with the credentials of the
wdp-service-id. - The parameters
nameandsoftware_configurationare required in the request body.
- To create a derived software specification that is scoped to a project or a space:
- you need to specify either
project_idorspace_id. - The parameters
nameandbase_software_specificationare required in the request body. - You can customize the software specification by adding any number of package extensions.
- The parameters
purposeandlife_cyclecannot be specified when you create a derived software specification, because a derived software specification will inherit both attributes from its base software specification.
POST /v2/software_specifications
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project in which to create the software specification.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the software specification to be created.
Create a derived software specification
{
"name": "my software specification",
"description": "this is my software specification",
"package_extensions": [
{
"guid": "b82b95df-fc3e-4273-98f7-473d62a03c2b"
}
],
"base_software_specification": {
"guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194"
}
}Create a base software specification
{
"name": "my software specification",
"description": "this is my software specification",
"package_extensions": [
{
"guid": "b82b95df-fc3e-4273-98f7-473d62a03c2b"
}
],
"software_configuration": {
"included_packages": [
{
"name": "ipython",
"version": "7.22.0"
}
],
"platform": {
"name": "spark",
"version": 3.2
},
"language": {
"name": "python",
"version": 3.9
}
},
"purpose": [
"notebook",
"wml"
],
"life_cycle": {
"deprecated": true,
"wml": {
"deprecated": false
}
}
}Name of the software specification.
Example:
my software specificationDescription of the software specification.
Example:
this is my software specificationPackage extensions of the software specification.
Payload for creating a new derived software specification.
- One of
Response
A software specification.
The software specification metadata.
Software specification entity.
Status Code
Success. Created and returned a new software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
Conflict. Specification already exists with given name. Restriction applicable only for global specifications.
{ "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "life_cycle": { "deprecated": true, "wml": { "deprecated": false } }, "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "conflict", "message": "Document already exists." } ] }
Update a software specification.
Updates a software specification of a given ID with the provided parameters.
Updatable fields are name, description, display_name and package_extensions.
Base built-in software specifications cannot be updated through the API.
-
To update a base custom software specification,
project_idorspace_idis not required. Base custom software specifications can be only updated with the credentials of thewdp-service-id. -
To update a derived software specification that is scoped to a project or a space, you need to specify either
project_idorspace_id.
PATCH /v2/software_specifications/{software_specification_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the updates for a software specification.
Update a software specification
{
"/metadata/name": "my updated software specification",
"/metadata/description": "this is my updated software specification.",
"/entity/software_specification/display_name": "My Updated Software Specification.",
"/entity/software_specification/package_extensions": [
{
"guid": "b82b95df-fc3e-4273-98f7-473d62a03c2b"
}
]
}Name of the software specification.
Example:
my updated software specificationDescription of the software specification.
Example:
this is my updated software specification.Display name of the software specification.
Example:
My Updated Software Specification.Package extension of the software specification.
Response
Status Code
Success. Updated the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Retrieve a software specification.
Returns a software specification of a given ID.
- To retrieve a base software specification,
project_idorspace_idis not required. - To retrieve a derived software specification that is scoped to a project or a space, you need to specify either
project_idorspace_id. When a derived software specification is retrieved, the return value shows the software configuration inherited from the base software specification instead of the ID of the base software specification.
GET /v2/software_specifications/{software_specification_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
A software specification.
The software specification metadata.
Software specification entity.
Status Code
Success. Returned the given software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "purpose": [ "notebook", "wml" ], "life_cycle": { "deprecated": true, "wml": { "deprecated": false } }, "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete a software specification.
Deletes a software specification of a given ID. Base built-in software specifications cannot be deleted through the API.
-
To delete a base software specification,
project_idorspace_idis not required. Base custom software specifications can be only deleted with the credentials of thewdp-service-id. -
To delete a derived software specification that is scoped to a project or a space, you need to specify either
project_idorspace_id.
DELETE /v2/software_specifications/{software_specification_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project. The deleted software specification must be scoped to the specified project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Deleted the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Add a package extension to a software specification.
When successful, the specified package extension is appended to the array entity.software_specification.package_extensions. It is then the last package extension in that array.
You need to specify either project_id or space_id.
The request is valid if and only if:
- The software specification identified by
software_specification_guidand the package extension identified bypackage_extension_guidexist in the same scope (either project or space). - A successful POST
/v2/package_extensions/{package_extension_guid}/upload_completehas been called before this request is initiated. I.e., the upload of the referencedpip_ziporconda_ymlfile has been indicated to have been successful. - The user is authorized to update the software specification asset.
PUT /v2/software_specifications/{software_specification_guid}/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2bA UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Added the package extension to the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
Conflict. The software specification already references this package extension.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Remove a package extension from a software specification.
When successful, the specified package extension is removed from the array entity.software_specification.package_extensions.
You need to specify either project_id or space_id.
DELETE /v2/software_specifications/{software_specification_guid}/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2bA UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Removed the package extension from the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
List package extensions.
Returns all package extensions within the given project or space. You need to specify either project_id or space_id.
GET /v2/package_extensions
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519eReturning only those package extensions that have a particular name.
Example:
my Package ExtensionReturning only those package extensions that have a particular type.
Allowable values: [
conda_yml,pip_zip]Example:
conda_yml or pip_zip
Response
A list of package extensions.
The number of results.
Example:
1An array of package extensions.
Status Code
Success. Returned a list of Package Extensions.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new package extension.
Returns the new package extension created in the given project or space. You need to specify either project_id or space_id.
For uploading the pip_zip or conda_yml, once you have created a package extension, the response also contains a pre-signed URL which allows you to upload its contents. When the upload is complete, you must call POST /v2/package_extensions/{package_extension_guid}/upload_complete to indicate to the API that the package extension is usable. If the /upload_complete returns successfully, the package extension is usable, i.e., can be assigned to a software specification.
POST /v2/package_extensions
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project in which to create the package extension.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the package extension to be created.
Create a package extension
{
"name": "my package extension",
"description": "this is my package extension",
"type": "conda_yml",
"interpreter": "mamba"
}The name of the package extension. Should be unique.
Example:
my package extensionThe type of the package extension.
Allowable values: [
pip_zip,conda_yml]Example:
conda_ymlThe description of the package extension. Can be any string.
Example:
this is my package extensionThe interpreter of the package extension.
Allowable values: [
conda,mamba]Example:
mamba
Response
A package extension with signed URL.
The package extension metadata.
Package extension entity with signed URL.
Status Code
Success. Created and returned a new package extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "href": "/package_extension/Package_Extension_9GShiX8H0.yml" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Mark file upload complete.
Indicates that the upload of the library file attached to the package extension is complete and this package extension is usable. You need to specify either project_id or space_id.
POST /v2/package_extensions/{package_extension_guid}/upload_completeRequest
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Marked the upload complete, the package extension is now usable.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Update a package extension.
Updates a package extension of a given ID with the provided parameters.
PATCH /v2/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the updates for a package extension.
Update a package extension
{
"/metadata/name": "my updated package extension",
"/metadata/description": "this is my updated package extension",
"/entity/package_extension/type": "pip_zip"
}The name of the package extension.
Example:
my updated package extensionA description of the package extension.
Example:
this is my updated package extensionThe type of the package extension. One would not normally want to change it.
Allowable values: [
conda_yml,pip_zip]Example:
pip_zip
Response
Status Code
Success. Updated the pacakge extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Retrieve a package extension.
Retrieves a package extension of a given ID. You need to specify either project_id or space_id.
GET /v2/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
A package extension with object key and signed URL.
The package extension metadata.
Package extension entity with object key and signed URL.
Status Code
Success. Returned the given package extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml", "href": "/package_extension/Package_Extension_9GShiX8H0.yml" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete a package extension.
Deletes a package extension of a given ID. You need to specify either project_id or space_id.
DELETE /v2/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Deleted the package extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
List runtime definitions.
Returns a list of runtime definitions.
- If
project_idis not given, it returns all default runtime definitions. - If
project_idis given, it returns all default runtime definitions and all runtime definitions scoped to that project.
GET /v2/runtime_definitions
Request
Query Parameters
The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519eThe runtime type of the runtime definitions.
Example:
notebookOpt-in more details to return. Possible value is 'launch_configuration'; when specified, the request must be sent by cluster admins.
Example:
launch_configuration
Response
List of runtime definitions.
Size of list.
Example:
1An array of runtime definitions.
Status Code
Success. Returned a list of runtime definitions.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "guid": "c82b95df-fc3e-4273-98f7-473d62a03c2b", "created_at": "2021-07-01T00:00:00.000Z", "updated_at": "2021-07-01T00:00:00.000Z" }, "entity": { "name": "jupyter-py39", "display_name": "Runtime 22.1 on Python 3.9", "description": "Runtime 22.1 on Python 3.9", "project": "103d3fc4-2e46-4581-a23a-b4484e13519e", "author": "IBM", "tested": true, "is_service": true, "runtime_type": "jupyter-py39" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new runtime definition.
Returns a new runtime definition with the provided parameters.
- If
project_idis given, this runtime definition is scoped to that particular project only. - If
project_idis not given, this runtime definition is scoped to all projects within the cluster. Global runtime definitions can be only created by cluster admins.
You can retrieve an existing runtime definition, patch the content in the entity to your own data and use it as the body parameters for this endpoint.
POST /v2/runtime_definitions
Request
Query Parameters
The guid of the account in which to create the runtime definition.
Example:
121d632a-20b3-4fab-848e-8550707df287The guid of the project in which to create the runtime definition.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the runtime definition to be created.
Create a runtime definition
{
"name": "jupyter-py39",
"display_name": "Runtime 22.1 on Python 3.9",
"description": "Runtime 22.1 on Python 3.9",
"author": "IBM",
"tested": true,
"is_service": true,
"runtime_type": "jupyter-py39"
}Name of the runtime definition.
Example:
jupyter-py39Display name of the runtime definition.
Example:
Runtime 22.1 on Python 3.9Custom launch configuration.
- launch_configuration
Custom software configuration.
- software_configuration
Description of the runtime definition.
Example:
Runtime 22.1 on Python 3.9Author of the runtime definition.
Example:
IBMTested?
Example:
trueService?
Example:
trueAn array of features.
The type of the runtime.
Example:
jupyter-py39
Response
Runtime definition.
Runtime definition metadata.
Main entity of runtime definition.
Status Code
Success. Created and returned a new runtime definition.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "guid": "c82b95df-fc3e-4273-98f7-473d62a03c2b", "created_at": "2021-07-01T00:00:00.000Z", "updated_at": "2021-07-01T00:00:00.000Z" }, "entity": { "name": "jupyter-py39", "display_name": "Runtime 22.1 on Python 3.9", "description": "Runtime 22.1 on Python 3.9", "project": "103d3fc4-2e46-4581-a23a-b4484e13519e", "author": "IBM", "tested": true, "is_service": true, "runtime_type": "jupyter-py39" } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Retrieve a runtime definition.
Retrieves a runtime definition of a given ID.
GET /v2/runtime_definitions/{runtime_definition_guid}Request
Path Parameters
The UUID v4 identifying the runtime definition.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
Required for a project scoped runtime definition. The guid of the project the runtime definition is queried for.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519eOpt-in more details to return. Possible value is 'launch_configuration'; when specified, the request must be sent by cluster admins.
Example:
launch_configuration
Response
Status Code
Success. Returned the given runtime definition.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
Not found. The requested resource was not found
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "runtime_definition_not_found", "message": "DocumentNotFound" } ] }
Update a runtime definition.
Updates a runtime definition of a given ID. Runtime definitions can be only updated by cluster admins.
PUT /v2/runtime_definitions/{runtime_definition_guid}Request
Path Parameters
A UUID v4 identifying the runtime definition.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
Required for a project scoped runtime definition. The guid of the project the runtime definition is queried for.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the updates for a runtime definition.
Update a runtime definition
{
"name": "jupyter-py39",
"display_name": "Runtime 22.1 on Python 3.9",
"description": "Runtime 22.1 on Python 3.9",
"author": "IBM",
"tested": true,
"is_service": true,
"runtime_type": "jupyter-py39"
}Name of the runtime definition.
Example:
jupyter-py39Display name of the runtime definition.
Example:
Runtime 22.1 on Python 3.9Description of the runtime definition.
Example:
Runtime 22.1 on Python 3.9Author of the runtime definition.
Example:
IBMTested?
Example:
trueService?
Example:
trueAn array of features.
The type of the runtime.
Example:
jupyter-py39Custom launch configuration.
- launch_configuration
Custom software configuration.
- software_configuration
Response
Runtime definition.
Runtime definition metadata.
Main entity of runtime definition.
Status Code
Success. Updated and returned a runtime definition.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "guid": "c82b95df-fc3e-4273-98f7-473d62a03c2b", "created_at": "2021-07-01T00:00:00.000Z", "updated_at": "2021-07-01T00:00:00.000Z" }, "entity": { "name": "jupyter-py39", "display_name": "Runtime 22.1 on Python 3.9", "description": "Runtime 22.1 on Python 3.9", "project": "103d3fc4-2e46-4581-a23a-b4484e13519e", "author": "IBM", "tested": true, "is_service": true, "runtime_type": "jupyter-py39" } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete a runtime definition.
Deletes a runtime definition of a given ID. Runtime definitions can be only deleted by cluster admins.
DELETE /v2/runtime_definitions/{runtime_definition_guid}Request
Path Parameters
The UUID v4 identifying the runtime definition.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
Required for a project scoped runtime definition. The guid of the project the runtime definition is queried for.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Deleted the runtime definition.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
A update operation allowing you to update artifacts based on a simple query.
Execute an operation to update artifacts using a simple query for one or more specified microservices (provider_ids).
POST /v3/search/update_by_query
Execute a query based on the Lucene Syntax
Execute a query and pass in a selection of words to search for or pass in a Lucene query. Your Lucene query can be as simple or as sophisticated as you like. Beware, however. If you plan on passing in a query directly from user input, make sure to set the 'isSimple' parameter to 'true' (the default is 'false'). Otherwise, Global Search will use the underlying query_string function that enforces a strict Lucene query syntax, and your query may return an exception if the user input includes reserved Lucene tokens or symbols that are used incorrectly. When the 'isSimple' parameter is set to true, Global Search will the ElasticSearch simple_query_string function that uses a modified Lucene syntax as follows:
+ = AND operation
| = OR operation
- = NOT
" wraps a phrase
* is a wildcard (you can't use it at the beginning of a word but you can use it alone to signify match all)
( and ) evaluates tokens inside brackets with higher precedence
To use one of these characters literally, escape it with a preceding backslash.
Global Search allows users to search for assets and artifacts on the platform. The number of documents for all search results is limited to 10000.
Please notice that the response shows all possible fields, which are not applicable for all types. For example "custom_attributes" are only applicable to assets currently, and even then only to certain custom attributes depending how they have been defined. Likewise, "categories" are only applicable to artifacts, etc.
GET /v3/search
Request
Custom Headers
The Tenant id (which is the BSS Account ID) within which this query is being run. Note: you can also use the header name "account_id" for this purpose.
Default:
999
Query Parameters
The Search Query. Add a list of words being sought or use a Lucene query. Your Lucene query can be as simple or as sophisticated as you like.
The maximum number of items to return
Example:
100Use simple query string syntax
Default:
falseFor governance artifacts limited by zone, limit with this role access.
Allowable values: [
viewer,editor]Default:
viewerUse cached authorization info for building ACL filters.
Default:
falseThe ACL filters applied to the query.
Allowable values: [
all,catalog,project,space,category,ibm_watsonx_governance_catalog,ibm_data_product_catalog]Default:
all
Execute a query and pass in a structured query conforming to the Elasticsearch Domain Specific Language.
Execute a query and pass in a structured query based on the Elasticsearch Domain Specific Language
For example:
{
"query": {
"match_all": {}
}
}
You can also use this API to execute the Global Search user search function as follows:
{
"query": {
"gs_user_query": {
"search_string": "the quick red fox jumped over the lazy brown dog",
"search_fields": ["metadata.name", "metadata.description"],
"nlq_analyzer_enabled": true,
"nested": false
}
}
}
Global Search allows users to search for assets and artifacts on the platform. The number of documents for all search results is limited to 10000.
When search fields are specified, the search will be restricted to the specified fields. If no search fields are specified, the search will run across all fields in the configuration.
When the natural language analyzer is enabled, words which are not relevant to the search will be ignored, and common phrases will be prioritized.
When semantic search is enabled, search strings containing a business term name or abbreviation will also include results for synonym, child and related business terms.
,Knowledge graph installation is required for semantic search.
Please notice that the response shows all possible fields, which are not applicable for all types. For example "custom_attributes" are only applicable to assets currently, and even then only to certain custom attributes depending how they have been defined. Likewise, "categories" are only applicable to artifacts, etc.
For more information regarding how to use this function, consult the Getting Started section of this guide.
POST /v3/search
Request
Custom Headers
The Tenant id (which is the BSS Account ID) within which this query is being run.
Default:
999
Query Parameters
For governance artifacts limited by zone, limit with this role access.
Allowable values: [
viewer,editor]Default:
viewerUse cached authorization info for building ACL filters.
Default:
falseThe ACL filters applied to the query.
Allowable values: [
all,catalog,project,space,category,ibm_watsonx_governance_catalog,ibm_data_product_catalog]Default:
all
A string representing a query. The query must conform to Elasticsearch Domain Specific Language. For more details, read the Search section in the getting started guide.
This API will return all available pre search filters
This API will return all available pre search filters
GET /v3/search/search_facet
Creates a category in the glossary
This method can be used to create a new category in the glossary.
POST /v3/categories
Request
Represents a category to be created.
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Artifact ID of a parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Indicates that it is a reference copy of an artifact managed in an external metadata server.
Used by reporting service for authorization. Can be set only for root level categories.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]
Response
- Response returned on creating a category.
It differs from its base class ({@link CreateResponse}) because it does not include {@code /version/{version_id}} in paths of returned URLs (the categories API does not have such endpoints, only {@code GET /categories/{category_id}}).
IDs of the created items.
Status Code
The category has been created successfully.
Bad Request
Unauthorized
Forbidden
UniqueConstraintViolation - category with given name and parent already exists.
Internal Server Error
{ "resources": [ { "href": "/v3/categories/285b7b78-3d64-48e6-a9b6-e02f4c32295f", "artifact_id": "285b7b78-3d64-48e6-a9b6-e02f4c32295f", "version_id": "12e37d76-f28b-4dc9-a35e-0c3e30f9f8ea_0", "global_id": "18091466-981e-4113-8943-2ddf162bff6d_285b7b78-3d64-48e6-a9b6-e02f4c32295f", "entity_type": "category" } ] }
Start category boostrap process
Assigns default owners and view permissions for root categories without any role assignments set
POST /v3/categories/collaborators/bootstrap
Response
Bootstrap Status
Current bootstrap status
Possible values: [
NOT_STARTED,NEW,IN_PROGRESS,SUCCEEDED,FAILED,STALLED]Number of records already bootstrapped successfully
Overall outcome of the bootstrap process. Set once bootstrapping is finished.
Current bootstrap activity
Bootstrap process errors
Total number of records to be processed by the bootstrap process
Status Code
The boostrap process started successfully
The boostrap is already in progress
Unauthorized
Internal Server Error
IN_PROGRESS
{ "status": "IN_PROGRESS", "current_step": "Bootstrapping category e39ada11-8338-3704-90e3-681a71e7c839", "completed_records": 0, "total_records": 3 }
Get status of category bootstrap process
Get status of category bootstrap process
GET /v3/categories/collaborators/bootstrap/status
Response
Bootstrap Status
Current bootstrap status
Possible values: [
NOT_STARTED,NEW,IN_PROGRESS,SUCCEEDED,FAILED,STALLED]Number of records already bootstrapped successfully
Overall outcome of the bootstrap process. Set once bootstrapping is finished.
Current bootstrap activity
Bootstrap process errors
Total number of records to be processed by the bootstrap process
Status Code
Bootstrap status fetched successfully
Unauthorized
Internal Server Error
IN_PROGRESS
{ "status": "IN_PROGRESS", "current_step": "Bootstrapping category e39ada11-8338-3704-90e3-681a71e7c839", "completed_records": 0, "total_records": 3 }NEW
{ "status": "NEW", "current_step": "Initializing role assignment bootstrap process", "completed_records": 0 }NOT_STARTED
{ "status": "NOT_STARTED" }SUCCEEDED
{ "status": "SUCCEEDED", "completion_message": "Bootstrap process completed", "completed_records": 3, "total_records": 3 }
Get history status of category bootstrap process
Get history status of category bootstrap process
GET /v3/categories/collaborators/bootstrap/status/history
Response
Response returned on retrieving bootstrap status history.
Bootstrap status history list
Status Code
Bootstrap status history fetched successfully
Unauthorized
Internal Server Error
SUCCEEDED
{ "bootstrap_status_history": [ { "status": "SUCCEEDED", "completion_message": "No categories requiring bootstrap process", "completed_records": 0, "total_records": 0 }, { "status": "SUCCEEDED", "completion_message": "Bootstrap process completed", "completed_records": 3, "total_records": 3 } ] }
Retrieves category hierarchy paths for given artifact ids of categories
This method can be used for retrieving hierarchy paths of categories
GET /v3/categories/hierarchy
Request
Query Parameters
The id of the category whose path is fetched
Possible values: 1 ≤ length ≤ 100, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Response
Response returned on retrieving hierarchy path for category.
IDs and names of categories in category hierarchy path for each category id
Status Code
The hierarchy paths of categories have been retrieved successfully
Unauthorized
The category with given {guid} does not exist in the glossary.
Internal Server Error
{ "category_hierarchy_paths": [ { "category_id": "b50f0822-eff3-4912-932e-aa61e5e7ac9a", "category_hierarchy_path": [ { "artifact_id": "4c4b18ae-010c-4986-a308-93c6f22095d6", "name": "category name 1", "user_access": true }, { "artifact_id": "fedc7149-5504-4ea9-aca7-3ad025be6f7d", "name": "category name 2", "user_access": true } ] } ] }
Retrieves category hierarchy paths for given artifact ids of categories
This method can be used for retrieving hierarchy paths of categories
POST /v3/categories/hierarchy
Request
Query Parameters
The maximum number of categories to return - must be at least 1 and cannot exceed 1000. The default value is 10.
Possible values: 1 ≤ value ≤ 1000
Default:
10The index of the first matching category to include in the result.
List of glossary resources
{
"resources": [
{
"artifact_id": "2b9bb7cf-502e-43a2-9ecc-645e909cba33"
}
]
}List of resources.
Response
Response returned on retrieving hierarchy path for category.
IDs and names of categories in category hierarchy path for each category id
Status Code
The hierarchy paths of categories have been retrieved successfully
Unauthorized
Internal Server Error
{ "resources": [ { "metadata": { "artifact_type": "category", "artifact_id": "2b9bb7cf-502e-43a2-9ecc-645e909cba33", "version_id": "5b6a662e-10d5-47fd-b485-655521ee491a_0", "source_repository_id": "2513bb40-5ce0-440e-9aa7-f473d1c22f9f", "source_repository_name": "WKC_BG_2513bb40-5ce0-440e-9aa7-f473d1c22f9f", "global_id": "2513bb40-5ce0-440e-9aa7-f473d1c22f9f_2b9bb7cf-502e-43a2-9ecc-645e909cba33", "created_by": "System", "created_at": "2023-11-13T06:50:09.240Z", "modified_by": "System", "modified_at": "2023-11-13T06:50:09.240Z", "revision": "0", "name": "child of child2 category", "short_description": "child of child2-sd", "state": "PUBLISHED", "tags": [], "read_only": false }, "entity": { "parent_category_id": "b02920a4-09ae-4a62-a25f-03a2d7ba0507", "reporting_authorized": false, "long_description": "child of child2-ld", "state": "PUBLISHED", "default_locale_id": "en-US", "reference_copy": false } } ], "offset": 0, "last": { "href": "/v3/categories/hierarchy?limit=10&offset=0", "offset": "0" }, "set_uri": false, "limit": 10, "count": 1, "first": { "href": "/v3/categories/hierarchy?limit=10&offset=0", "offset": "0" } }
Deletes the category with a given guid
This method can be used to delete a category.
Note! The category must be empty. It can contain neither child categories nor artifacts.
DELETE /v3/categories/{category_id}Request
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Response
Glossary archive response object
Guids of the archived objects.
Guids of the deleted objects.
Guids of the updated objects.
Status Code
The category has been deleted successfully.
Bad Request
Unauthorized
Forbidden
The category with given {guid} does not exist in the glossary.
Internal Server Error
No Sample Response
Retrieves category with given guid
This method can be used for retrieving details of a category.
GET /v3/categories/{category_id}Request
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
When set to true fetch category relationships user has access to. It returns at most 1000 relationships. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Deprecated, functionality will be replaced by new one introduced in the feature releases.Default:
trueIf this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
true
Response
Represents a category object - which contains metadata and category entity.
Represents a category.
Metadata of the entity.
Status Code
The category has been retrieved successfully.
Unauthorized
Forbidden
The category with given {guid} does not exist in the glossary.
Internal Server Error
No Sample Response
Updates category with given id
This method can be used to update a category with given id.
It may be an update of its name, description, etc..
PATCH /v3/categories/{category_id}Request
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})
Category to be updated.
Fields omitted will be unchanged, and fields set to null explicitly will be nulled out.
For multi-valued attributes & relationships, the complete list will be replaced by the given list of values.
Additional Example:
{"description" : "short desc updated"}
Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1Artifact ID of a parent category. This is read only property and should not be changed.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Indicates that it is a reference copy of an artifact managed in an external metadata server.
Used by reporting service for authorization. Can be set only for root level categories.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]
Response
Represents a category object - which contains metadata and category entity.
Represents a category.
Metadata of the entity.
Status Code
The category has been updated successfully.
Bad Request
Unauthorized
Forbidden
The category with given {guid} does not exist in the glossary.
The category was modified by another user.
Internal Server Error
No Sample Response
Removes an artifact from its secondary category
It can be used to remove a secondary category assignment for an artifact. It does not allow to remove an artifact from a primary category as a primary category assignment is obligatory.
DELETE /v3/categories/{category_id}/artifacts/{artifact_id}Request
Path Parameters
The artifact ID or the global ID of a category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The artifact ID or the global ID of an artifact to be removed from a (secondary) category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Response
Status Code
A secondary category assignment removed.
Attempt to remove an artifact from its primary category failed, because a primary category assignment is mandatory.
Unauthorized
The category with the given {category_id} does not exist in the glossary.
Internal Server Error
No Sample Response
Adds an artifact to a category
It can be used to set a primary category for an artifact (replacing an old primary category assignment if existed) as well as to add an artifact to a secondary category.
PUT /v3/categories/{category_id}/artifacts/{artifact_id}Request
Path Parameters
The artifact ID or the global ID of a category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The artifact ID or the global ID of an artifact to be added to the category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Assignment of an artifact to a category
Type of the artifact to be added to a category
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
data_classtrue when a primary category should be set for an artifact, false when the artifact should be added to a secondary category
Example:
true
Response
Assignment of an artifact to a category
Type of the artifact to be added to a category
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
data_classtrue when a primary category should be set for an artifact, false when the artifact should be added to a secondary category
Example:
true
Status Code
An existing category assignment updated (e.g. changed from secondary to primary).
A new category assignment created.
Unauthorized
The category with the given {category_id} or the artifact with the given {artifact_id} does not exist in the glossary.
Internal Server Error
No Sample Response
Retrieves collaborators for given artifact id of a category
Single collaborator is an users with assigned roles in context of given category. A role comes with rights to access the category, its sub-categories and artifacts and potential responsibilities.
GET /v3/categories/{category_id}/collaboratorsRequest
Path Parameters
The artifact ID or the global ID of a category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If this parameter is true, the returned list contains collaborators not only for given category, but also for all parent categories, up to root category.
Default:
trueIf set then the returned list will be reduced to collaborators with given roles only. Maximum allowed number of roles is 100
Possible values: 1 ≤ length ≤ 100, Value must match regular expression
.*
Creates single collaborator for given category
To create collaborator one needs to provide id of the collaborating user and the name of the role he will be permitted. Collaborator is effective for given category and whole tree of its subcategories.
POST /v3/categories/{category_id}/collaboratorsRequest
Path Parameters
The artifact ID or the global ID of a category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
New collaborator data representing user with assigned role. It will be created in the context of specific category.
Id of the user to be assigned to given role
Possible values: 1 ≤ length ≤ 73, Value must match regular expression
.*Role to be assigned
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Type of the user. When not provided defaults to USER
Allowable values: [
USER,GROUP]
Response
Category permission list for given category id
Category Artifact Id
Category Name
Create Time
DPS Rule Id
Id
Principal Id
Role
User type
Status Code
The collaborator has been created successfully.
Bad Request
Unauthorized
UniqueConstraintViolation - collaborator with the same role and user id already exists for given category.
Internal Server Error
No Sample Response
Deletes single collaborator
Collaborator represents single user together with single role that gives him certain privileges in context of given category.
DELETE /v3/categories/{category_id}/collaborators/{collaborator_id}Request
Path Parameters
The artifact ID or the global ID of a category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The id of the collaborator.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
List the relationships of the given type for the specified category
If the result set is larger than the limit parameter, it returns the first limit number of relationships.
To retrieve the next set of relationships, call the method again by using the URI in the property next returned by this method.
GET /v3/categories/{category_id}/relationshipsRequest
Path Parameters
The artifact ID of the category.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Comma-separated list of relationship types.
Available types: is_a_type_of_categoryhas_types_categoryis_a_parent_category_forgrouped_assetsowned_byclassificationscustomall
Note:alldoes not return category hierarchy.Possible values: 1 ≤ length ≤ 255, Value must match regular expression
^(((is_a_type_of_category|has_types_category|is_a_parent_category_for|grouped_assets|owned_by|classifications|custom),?)+)|all$Custom relationship definition Id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4Is custom relationship reversed?
Default:
falseIf this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Default:
falseRetrieves target parent category name of the relationship entity.
Default:
falseThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Default:
0
Response
Response that includes relationships to a managed object, like business term, data class, classification
List of custom relationships
Mapping of the relationship type to the paginated list of relationships
- relationships
Base V3 class for paginated results
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Remove a relationship from category
Currently we support a custom relationship removal from category by relationship ID.
DELETE /v3/categories/{category_id}/relationships/{relationship_id}Request
Path Parameters
The artifact ID of the category to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Get role usage statistics
Get list of roles assigned in glossary, along with number of categories where specific role is used.
GET /v3/category_role_statistics
Response
List of role usage summary
List of roles assigned in glossary, along with number of categories which have role assigned
Status Code
Success
Unauthorized
Internal Server Error
SUCCEEDED
{ "role_assignment_statistics": [ { "role": "custom_role1", "number_of_categories": 1 }, { "role": "custom_role2", "number_of_categories": 2 }, { "role": "owner", "number_of_categories": 2 }, { "role": "viewer", "number_of_categories": 2 } ] }
Returns list of categories which has specific role assigned, along with number of assignments for users and groups
Category statistics
GET /v3/category_statistics
Request
Query Parameters
Role for which statistics are to be retrieved
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
List of category statistic items
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Success
Bad Request
Unauthorized
Internal Server Error
SUCCEEDED
{ "offset": 0, "last": { "href": "v3/category_statistics?offset=0&role=custom_role2", "offset": 0 }, "set_uri": false, "resources": [ { "category_artifact_id": "788e7609-5d1d-4f5f-a2e2-0011f8c726cf", "category_name": "Example category", "category_hierarchy_path": [ { "artifact_id": "4562a011-563d-40c2-ae28-80f64cd8d934", "name": "Parent of example category", "user_access": true }, { "artifact_id": "e6abcaba-203f-4f43-8bc3-f4f25aa96f19", "name": "Root category", "user_access": true } ], "users_assignments_count": 2, "groups_assignments_count": 1 } ], "limit": 10, "count": 1, "first": { "href": "v3/category_statistics?offset=0&role=custom_role2", "offset": 0 } }
Creates a classification in the glossary
This method is used to create a classification in the glossary.
POST /v3/classifications
Request
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
New classification entity
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1Secondary categories the artifact belongs to.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The child classification relationships in the classification type hierarchy.
The parent category of the artifact.
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
The long description of an artifact.The parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
Relationships to categories.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
short descriptionThe steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]Relationships to business terms.
The workflow state of an artifact
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
PUBLISHED
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
Success
Bad Request
Unauthorized
Not found
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
{ "resources": [ { "href": "v3/reference_data/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" } ] }
Retrieves classification with given guid and status
This method can be used for retrieving details of an ACTIVE classification. Only ACTIVE is supported
GET /v3/classifications/{artifact_id}/versionsRequest
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Filter by classification status.
Available statuses: DRAFTartifacts which are being created or modified and not in use PUBLISHEDartifacts which are in published state (does not takes effective dates into account) ACTIVEartifacts which are published, and which effective date period includes current datetime Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
PUBLISHEDComma-separated list of relationship types.
Available types: is_a_type_of_classificationhas_types_classificationshas_types_classifications_hierarchycategoriesparent_categorytermsdata_classespoliciesrulesreference_datarelated_categoriescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
List of paginated artifacts
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Deletes a draft or published version of an artifact
If the artifact state is DRAFT, then the draft version is deleted.
If the artifact state is PUBLISHED, a draft version with marked_for_deletion is created .
If the artifact state is PUBLISHED and workflow is skipped, then the published version is deleted.
If a draft artifact already exists for deletion for a published artifact, then the draft artifact is simply skipped.
Administrator role is required.
DELETE /v3/classifications/{artifact_id}/versions/{version_id}Request
Path Parameters
The guid of the classification to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the classification to delete.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
A draft version has been successfully created for deleting the published artifact.
The artifact has been deleted successfully.
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Retrieves classification with given guid
This method can be used for retrieving details of an ACTIVE or DRAFT classification.
GET /v3/classifications/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the classification to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the classification to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: is_a_type_of_classificationhas_types_classificationshas_types_classifications_hierarchycategoriesparent_categorytermsdata_classespoliciesrulesreference_datarelated_categoriescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10
Updates a draft or published artifact
If a published version is updated, a draft version is created from the published version and the draft version is updated with the requested changes and returned.If any relationships of the artifact are updated, then the updated relationships are returned as a paginated list limited by the give limit parameter. The relationships that are not updated are not returned.
PATCH /v3/classifications/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the classification to be updated.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the classification to be updated.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
The classification to be updated.
Fields omitted will be unchanged, and fields set to null explicitly will be nulled out.
For multi-valued attributes & relationships, the complete list will be replaced by the given list of values.
Additional Example:
{"description" : "description updated"}
The revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Secondary categories the artifact belongs to.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The child classification relationships in the classification type hierarchy.
The parent category of the artifact.
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
The long description of an artifact.The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1The parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
Relationships to categories.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
short descriptionThe steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]Relationships to business terms.
List the associations of the given type for the specified classification
If the result set is larger than the limit parameter, it returns the first limit number of relationships.
To retrieve the next set of relationships, call the method again by using the URI in the property next returned by this method.
GET /v3/classifications/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifactId of the classification
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The versionId of the classification
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: is_a_type_of_classificationhas_types_classificationshas_types_classifications_hierarchycategoriesparent_categorytermsdata_classespoliciesrulesreference_datarelated_categoriescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Custom relationship definition Id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4Is custom relationship reversed?
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Retrieves target parent category name of the relationship entity.
The maximum number of associations to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
Response that includes relationships to a managed object, like business term, data class, classification
List of custom relationships
Mapping of the relationship type to the paginated list of relationships
- relationships
Base V3 class for paginated results
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Create relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and adds the relationship to the draft version. And, it returns the details of the draft version.
POST /v3/classifications/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact id of the classification to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the classification to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Relationships to be created.
Category relationships.
The relationships to data classes.
The child classification relationships in the classification type hierarchy.
The parent category of the artifact.
The parent category of the artifact.
The relationships to categories.
The relationships to business terms.
Deletes relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and deletes the relationship from the draft version. And, it returns the details of the draft version.
DELETE /v3/classifications/{artifact_id}/versions/{version_id}/relationships/{relationship_id}Request
Path Parameters
The artifact id of the classification to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the classification to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Retrieves the data classes matching specified parameters.
This method is used to retrieve the data classes that the user have permissions and they match specified parameters.
GET /v3/data_classes
Request
Custom Headers
Allowable values: [
application/json,application/xml]
Query Parameters
Comma-separated list of dataclass statuses.
Available statuses: PUBLISHEDartifacts which are in published state (does not takes effective dates into account) ACTIVEartifacts which are published, and which effective date period includes current datetime DELETEDartifacts which have been deleted Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Default:
PUBLISHEDTo filter data classes based on enabled property. The enabled query parameter accepts (Yes, No, Both) where Yes is the default value. This option is not applicable for format=xml.
Default:
BothIf this parameter is set to true, then Dataclass' xml definitions are returned. If parameter is not set its default value is 'true'
Default:
trueIf this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'false'.
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
A filter to artifacts that have been created / updated / deleted since the given timestamp in this format: [yyyy-MM-ddTHH:mm:ss.SSSZ]
Possible values: length = 24, Value must match regular expression
^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?(([+-]\d\d:\d\d)|Z)?)?)?)?$The maximum number of data_classes to return - must be at least 1 and cannot exceed 1000. The default value is 10.
Possible values: 1 ≤ value ≤ 1000
Default:
10The index of the first matching data_class to include in the result.
Response
Presents a paginated list of DataClasses
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Creates a draft data class in the glossary
This method is used to create a draft data class in the glossary. If the effective start date of selected reference data set is a future date, then effective start date of data class will be same as that of selected reference data set effective start date.
POST /v3/data_classes
Request
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
Data class to be created.
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify additional applicable for: structured_data_only, unstructured_data_only, all_data; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
all_dataTo specify additional regular expression; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
.*To specify allow substring match boolean flag; ( This property is applicable for data class type: ValidValues )
To specify applicable for: structured_data_only, unstructured_data_only, all_data; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
all_dataTo specify case sensitive boolean flag; ( This property is applicable for data class type: ValidValues )
Secondary categories the artifact belongs to.
Unique class code given to the data class.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
class code1Relationships to classifications.
To specify column name match
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
^[a-zA-Z]*$List of custom attributes with their values.
Custom relationships to asset
To specify the type of data class: ColumnSimilarity, Java, ReferenceDataSet, Regex, Script, Undefined, UnstructuredFilter, ValidValues
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
^(ColumnSimilarity|Java|Regex|Script|Undefined|UnstructuredFilter|ValidValues|ReferenceDataSet|Fingerprint|OtherMatchingCriteria)$DataType: numeric, string, date, time, timestamp
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "numeric", "string", "date", "time", "timestamp" ]The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
This flag indicates whether the data class can be used for data profiling or not.
Data class example
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
example1To specify expression; ( This property is applicable for data class type: UnstructuredFilter )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
expressionList of immediate child data classes in the data class type hierarchy.
The parent category of the artifact.
To specify Java class name; ( This property is applicable for data class type: Java )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify language: JavaScript, DataRule; ( This property is applicable for data class type: Script )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*To specify maximum data length
To specify minimum data length
The parent category of the artifact.
Data class priority used while profiling.
To specify properties; ( This property is applicable for data class type: Java )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The provider of data class
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify reference columns metadata; ( This property is applicable for data class type: ColumnSimilarity )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Indicates that it is a reference copy of an artifact managed in an external metadata server.
To specify regular expression; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
^[a-zA-Z]*$To specify scope: value, column, dataset_columns, dataset; ( This property is applicable for data class types: Script & Java )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
^(value|column|dataset_columns|dataset)$To specify script name; ( This property is applicable for data class type: Script )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify squeeze consecutive white spaces boolean flag; ( This property is applicable for data class type: ValidValues )
The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]Relationships to business terms.
The percentage of threshold.
To specify valid value reference file path; ( This property is applicable for data class type: ValidValues )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify valid values; ( This property is applicable for data class type: ValidValues )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The workflow state of an artifact
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
Success
Bad Request
Unauthorized
Not found
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
No Sample Response
Retrieves data class with given guid and status
This method can be used for retrieving details of an ACTIVE or DRAFT data class. Only ACTIVE is allowed as status right now
GET /v3/data_classes/{artifact_id}/versionsRequest
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Filter by dataclass status.
Available statuses: DRAFTartifacts which are being created or modified and not in use PUBLISHEDartifacts which are in published state (does not takes effective dates into account) ACTIVEartifacts which are published, and which effective date period includes current datetime Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
PUBLISHEDComma-separated list of relationship types.
Available types: is_a_type_of_data_classhas_types_data_classeshas_types_data_class_hierarchyparent_categorycategoriestermsclassificationspoliciesrulesreference_datacustomall
Note:alldoes not return data class hierarchy.Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueIf this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
List of paginated artifacts
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
The data class has been retrieved successfully.
Bad Request
Unauthorized
The data class with given {guid} does not exist in the glossary.
Internal Server Error
No Sample Response
Deletes a draft or published version of an artifact
If the artifact state is DRAFT, then the draft version is deleted.
If the artifact state is PUBLISHED, a draft version with marked_for_deletion is created .
If the artifact state is PUBLISHED and workflow is skipped, then the published version is deleted.
If a draft artifact already exists for deletion for a published artifact, then the draft artifact is simply skipped.
Administrator role is required.
DELETE /v3/data_classes/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the dataclass to delete.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the dataclass to delete.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
A draft version has been successfully created for deleting the published artifact.
The artifact has been deleted successfully.
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Retrieves data class with given guid
This method can be used for retrieving details of an ACTIVE or DRAFT data class.
GET /v3/data_classes/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact ID of the data class to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the data class to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: is_a_type_of_data_classhas_types_data_classeshas_types_data_class_hierarchyparent_categorycategoriestermsclassificationspoliciesrulesreference_datacustomall
Note:alldoes not return data class hierarchy.Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueIf this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10
Updates a draft or published artifact
If a published version is updated, a draft version is created from the published version and the draft version is updated with the requested changes and returned.If any relationships of the artifact are updated, then the updated relationships are returned as a paginated list limited by the give limit parameter. The relationships that are not updated are not returned.
PATCH /v3/data_classes/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the data class to be updated.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the data class to be updated.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
The data class to be updated.
Fields omitted will be unchanged, and fields set to null explicitly will be nulled out.
For multi-valued attributes & relationships, the complete list will be replaced by the given list of values.
Additional Example:
{"description" : "description updated"}If the effective start date of selected reference data set is a future date, then effective start date of data class will be same as that of selected reference data set effective start date.
The revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*To specify additional applicable for: structured_data_only, unstructured_data_only, all_data; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
all_dataTo specify additional regular expression; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
.*To specify allow substring match boolean flag; ( This property is applicable for data class type: ValidValues )
To specify applicable for: structured_data_only, unstructured_data_only, all_data; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
all_dataTo specify case sensitive boolean flag; ( This property is applicable for data class type: ValidValues )
Secondary categories the artifact belongs to.
Unique class code given to the data class.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
class code1Relationships to classifications.
To specify column name match
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
^[a-zA-Z]*$List of custom attributes with their values.
Custom relationships to asset
To specify the type of data class: ColumnSimilarity, Java, ReferenceDataSet, Regex, Script, Undefined, UnstructuredFilter, ValidValues
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
^(ColumnSimilarity|Java|Regex|Script|Undefined|UnstructuredFilter|ValidValues|ReferenceDataSet|Fingerprint|OtherMatchingCriteria)$DataType: numeric, string, date, time, timestamp
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "numeric", "string", "date", "time", "timestamp" ]The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
This flag indicates whether the data class can be used for data profiling or not.
Data class example
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
example1To specify expression; ( This property is applicable for data class type: UnstructuredFilter )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
expressionList of immediate child data classes in the data class type hierarchy.
The parent category of the artifact.
To specify Java class name; ( This property is applicable for data class type: Java )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify language: JavaScript, DataRule; ( This property is applicable for data class type: Script )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*To specify maximum data length
To specify minimum data length
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1The parent category of the artifact.
Data class priority used while profiling.
To specify properties; ( This property is applicable for data class type: Java )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The provider of data class
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify reference columns metadata; ( This property is applicable for data class type: ColumnSimilarity )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Indicates that it is a reference copy of an artifact managed in an external metadata server.
To specify regular expression; ( This property is applicable for data class type: Regex )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
^[a-zA-Z]*$To specify scope: value, column, dataset_columns, dataset; ( This property is applicable for data class types: Script & Java )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
^(value|column|dataset_columns|dataset)$To specify script name; ( This property is applicable for data class type: Script )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify squeeze consecutive white spaces boolean flag; ( This property is applicable for data class type: ValidValues )
The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]Relationships to business terms.
The percentage of threshold.
To specify valid value reference file path; ( This property is applicable for data class type: ValidValues )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*To specify valid values; ( This property is applicable for data class type: ValidValues )
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*
List the relationships of the given type for the specified data class
If the result set is larger than the limit parameter, it returns the first limit number of relationships.
To retrieve the next set of relationships, call the method again by using the URI in the property next returned by this method.
GET /v3/data_classes/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact ID of the data class to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the data class to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: is_a_type_of_data_classhas_types_data_classeshas_types_data_class_hierarchyparent_categorycategoriestermsclassificationspoliciesrulesreference_datacustomall
Note:alldoes not return data class hierarchy.Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Custom relationship definition Id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4Is custom relationship reversed?
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Retrieves target parent category name of the relationship entity.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
Response that includes relationships to a managed object, like business term, data class, classification
List of custom relationships
Mapping of the relationship type to the paginated list of relationships
- relationships
Base V3 class for paginated results
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Create relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and adds the relationship to the draft version. And, it returns the details of the draft version.
POST /v3/data_classes/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact ID of the data class to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the data class to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Relationships to be created.
Category relationships.
The relationships to classifications.
New list of child data classes in the data class type hierarchy.
The parent category of the artifact.
The parent category of the artifact.
The relationships to business terms.
Deletes relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and deletes the relationship from the draft version. And, it returns the details of the draft version.
DELETE /v3/data_classes/{artifact_id}/versions/{version_id}/relationships/{relationship_id}Request
Path Parameters
The artifact ID of the data class to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the data class to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Business Glossary Heartbeat
Returns the build details and health of the dependent services
GET /v3/glossary_status/heartbeat
Response
Holds business glossary build information and DB2 connection status information
Build information.
Status of DB2.
Example:
UPThe status of the external Rabbit MQ listener.
Example:
CONNECTEDThe status of the internal Rabbit MQ listener.
Example:
CONNECTEDOK indicates that the service is up and running.
Example:
OKThe version of the build.
Example:
2.0.0.1000
Status Code
Success
Internal Server Error
No Sample Response
Creates draft terms in the glossary
If the unique constraint on the name or display name of the term is violated, the method fails with 409 Conflict response.
POST /v3/glossary_terms
Request
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
Terms to be created. The terms array must contain at least 1 term, and cannot exceed 100 terms.
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1The list of abbreviations of a business term.
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Secondary categories the artifact belongs to.
Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
Example
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The list of child business terms in the business term containment hierarchy.
The list of child business terms in the business term type hierarchy.
Name of the user who has created the term in the original source for imported term.
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*The timestamp when the term was created in the original source for imported term.
Possible values: 10 ≤ length ≤ 32
The usage of the term in the original source for imported term.
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*The list of parent business terms in the business term type hierarchy.
The list of parent business terms in the business term containment hierarchy.
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
The list of related business terms.
The list of business terms that are replaced by this business term.
The list of business terms that replace this business term.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The list of synonym business terms.
System business reference of a business term.
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Example:
SAP:MANDANT,AWS:XYZ123The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The workflow state of an artifact
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
Success
Bad Request
Unauthorized
Not found
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
No Sample Response
Retrieves versions of a term for the given artifact_id and status
Retrieval of the versions of ACTIVE state is supported.
GET /v3/glossary_terms/{artifact_id}/versionsRequest
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Filter by term status.
Available statuses: DRAFTartifacts which are being created or modified and not in use PUBLISHEDartifacts which are in published state (does not takes effective dates into account) ACTIVEartifacts which are published, and which effective date period includes current datetime Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
PUBLISHEDComma-separated list of relationship types.
Available types: is_a_type_of_termshas_type_termshas_types_term_hierarchysynonym_termsrelated_termsdata_classesis_of_termshas_termscategoriesparent_categoryclassificationspoliciesrulesreference_datareference_data_valuescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueIf this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
List of paginated artifacts
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Deletes a draft or published version of an artifact
If the artifact state is DRAFT, then the draft version is deleted.
If the artifact state is PUBLISHED, a draft version with marked_for_deletion is created .
If the artifact state is PUBLISHED and workflow is skipped, then the published version is deleted.
If a draft artifact already exists for deletion for a published artifact, then the draft artifact is simply skipped.
Administrator role is required.
DELETE /v3/glossary_terms/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the term to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the term to delete.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
A draft version has been successfully created for deleting the published artifact.
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Gets the term in the glossary with a given version id
This method can be used for retrieving details of an ACTIVE or DRAFT term.
GET /v3/glossary_terms/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the term to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the term to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: is_a_type_of_termshas_type_termshas_types_term_hierarchysynonym_termsrelated_termsdata_classesis_of_termshas_termscategoriesparent_categoryclassificationspoliciesrulesreference_datareference_data_valuescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Updates a draft or published artifact
If a published version is updated, a draft version is created from the published version and the draft version is updated with the requested changes and returned.If any relationships of the artifact are updated, then the updated relationships are returned as a paginated list limited by the give limit parameter. The relationships that are not updated are not returned.
PATCH /v3/glossary_terms/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the term to be updated.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the term to be updated.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
The business term to be updated.
Fields omitted will be unchanged, and fields set to null explicitly will be nulled out. If a relationship of the term is updated, then the updated relationship as returned as a paginated list limited by the give limit parameter. Relationships that are not updated are not returned.
The revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*The list of abbreviations of a business term.
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Secondary categories the artifact belongs to.
Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
Example
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The list of child business terms in the business term containment hierarchy.
The list of child business terms in the business term type hierarchy.
Name of the user who has created the term in the original source for imported term.
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*The timestamp when the term was created in the original source for imported term.
Possible values: 10 ≤ length ≤ 32
The usage of the term in the original source for imported term.
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*The list of parent business terms in the business term type hierarchy.
The list of parent business terms in the business term containment hierarchy.
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1The parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
The list of related business terms.
The list of business terms that are replaced by this business term.
The list of business terms that replace this business term.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The list of synonym business terms.
System business reference of a business term.
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Example:
SAP:MANDANT,AWS:XYZ123The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*
List the relationships for the specified term
If the result set is larger than the limit parameter, it returns the first limit number of relationships.
To retrieve the next set of relationships, call the method again by using the URI in the property next returned by this method.
GET /v3/glossary_terms/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The guid of the Term
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The versionID of the Term
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: is_a_type_of_termshas_type_termshas_types_term_hierarchysynonym_termsrelated_termsdata_classesis_of_termshas_termscategoriesparent_categoryclassificationspoliciesrulesreference_datareference_data_valuescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Custom relationship definition Id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4Is custom relationship reversed?
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Retrieves target parent category name of the relationship entity.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
Response that includes relationships to a managed object, like business term, data class, classification
List of custom relationships
Mapping of the relationship type to the paginated list of relationships
- relationships
Base V3 class for paginated results
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Create relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and adds the relationship to the draft version. And, it returns the details of the draft version.
POST /v3/glossary_terms/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact ID of the term to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the term to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Relationships to be created.
Category relationships.
The relationships to the classifications.
The relationships to the data classes.
The list of child business terms in the business term containment hierarchy.
The list of child business terms in the business term type hierarchy.
The list of parent business terms in the business term type hierarchy.
The list of parent business terms in the business term containment hierarchy.
The parent category of the artifact.
The list of related business terms.
The list of business terms that are replaced by this business term.
The list of business terms that replace this business term.
The list of synonym business terms.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
Success
Bad Request
Unauthorized
Not found
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
No Sample Response
Deletes relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and deletes the relationship from the draft version. And, it returns the details of the draft version.
DELETE /v3/glossary_terms/{artifact_id}/versions/{version_id}/relationships/{relationship_id}Request
Path Parameters
The artifact ID of the term to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the term to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Exports custom attribute definitions to a json file
This method can be used to export custom attribute definitions to a json file.
POST /v3/governance_artifact_types/custom_attribute_definitions/export
Request
Query Parameters
The comma-separated list of supported custom attribute types. Allowed values are text, date, number, enum, relationship, all, all_without_relationship.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
text,dateThe artifact type which a custom attribute definition applies to. Allowed values are category, glossary_term, data_class, policy, rule, classification, reference_data
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term,policyThe related artifact type which a custom attribute definition for relationship applies to. Allowed values are category, glossary_term, data_class, policy, rule, classification, reference_data
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term,policy
The list of custom attribute definitions artifact ids to be exported.
An example for resources with ids for custom attribute definitions
An example for resources with ids for custom attribute definitions
{
"resources": [
{
"artifact_id": "455b7b78-3d64-48e6-a9b6-e02f4c32295f"
}
]
}List of resources.
Import values for custom attribute definitions from specified json file
This method can be used to import values custom attribute definitions from specified json file.
POST /v3/governance_artifact_types/custom_attribute_definitions/import
Request
Query Parameters
Determines if only custom properties or custom relationships or both types will be imported. Allowed values: ALL, PROPERTY, RELATIONSHIP.
Allowable values: [
ALL,PROPERTY,RELATIONSHIP]Default:
ALLIf async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.
Form Parameters
File
Possible values: 1 ≤ length ≤ 2147483647
Response
Glossary Import Status
Children statuses
Completion time
Creation time
Error message
Heartbeat time
Heartbeater id
List of import messages
Operations count
- operations_count
Operations count
- any property
Operations count
Process Id
Status
Step message
Step number
Tenant Id
Total steps
Workflow Id
Status Code
Import of assets has been completed
Import of assets has been started
Unauthorized
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
No Sample Response
Export values of all supported types to a ZIP file
This method can be used to export values of all supported types to a ZIP file.
GET /v3/governance_artifact_types/export
Request
Query Parameters
This specifies if artifact ID numbers should be included in exported files, or not. Possible values: "always", artifact ID numbers are included for artifacts, and "never", not included at all.
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
alwaysExample:
alwaysThe comma-separated list of supported artifact types. Allowed values are all, category, classification, data_class, glossary_term, policy, rule, reference_data and role_assignment.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Default:
allExample:
category,glossary_termThe comma-separated list of categories ID numbers, or "all_top_level", which means all top-level categories.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Default:
all_top_levelExample:
e39ada11-8338-3704-90e3-681a71e7c839,c305c9fe-3223-48a0-b146-228a782bc7e4If parameter "include_custom_attribute_definitions" is set to true, information about suitable custom attribute definitions will be included in zip
Default:
falseIf parameter "include_development_log" is set to true, development log content will be included in zip
Default:
false
Import values from specified ZIP file
This method can be used to import values from specified ZIP file.
POST /v3/governance_artifact_types/import
Request
Query Parameters
Import merge option, valid values:
all - imported values will replace existing values in catalog
specified - imported values that are not empty replace existing values in catalog
empty - imported values replace only empty values in catalog.Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
specifiedExample:
specified
Form Parameters
File
Possible values: 1 ≤ length ≤ 2147483647
Response
Glossary Import Status
Children statuses
Completion time
Creation time
Error message
Heartbeat time
Heartbeater id
List of import messages
Operations count
- operations_count
Operations count
- any property
Operations count
Process Id
Status
Step message
Step number
Tenant Id
Total steps
Workflow Id
Status Code
Import of assets has been completed
Import of assets has been started
Unauthorized
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
No Sample Response
Cleanup ZIP import process
This method can be used to cleanup specified stalled ZIP import process that crashed or hanged. Note: This feature is experimental - the API and scope are subject to change. Should not be used on imports that are alive or pending as it can lead to unpredictable results.
POST /v3/governance_artifact_types/import/cleanup/{process_id}Import of assets status
Import of assets status
GET /v3/governance_artifact_types/import/status/{process_id}Request
Path Parameters
Import process id
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})
Query Parameters
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Default:
0
Response
Glossary Import Status
Children statuses
Completion time
Creation time
Error message
Heartbeat time
Heartbeater id
List of import messages
Operations count
- operations_count
Operations count
- any property
Operations count
Process Id
Status
Step message
Step number
Tenant Id
Total steps
Workflow Id
Status Code
Import status available
Unauthorized
Internal Server Error
No Sample Response
Get artifacts of given type that are either published or drafts matching specified criteria
This method can be used for retrieving artifacts of given type that are:
- published,
- drafts matching specified criteria (starts_with, substring, workflow_status, created_by, modified_by, enabled).
GET /v3/governance_artifact_types/{artifact_type}Request
Path Parameters
The artifact type. Allowed values are all, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term
Query Parameters
First character of artifact, applicable only for draft artifact search.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
TesFilter on substring, applicable only for draft artifact search.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
estFilter by workflow status.
Available statuses (if no status is specified, all drafts are retrieved): publishedPublishing (applicable only for draft artifact search)Publish failed (applicable only for draft artifact search)Not started (applicable only for draft artifact search)Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
NOT_STARTEDFilter by creator of artifact, applicable only for draft artifact search.
Possible values: 1 ≤ length ≤ 73, Value must match regular expression
.*Example:
IBMid-1234567ABCFilter by editor of artifact, applicable only for draft artifact search.
Possible values: 1 ≤ length ≤ 73, Value must match regular expression
.*Example:
IBMid-1234567ABCFilter Results based on enabled flag for dataclass,
yeswill give enabled dataclass,nowill give disabled andbothshall return all, applicable only for draft artifact search.Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
trueThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Value on which results need to be sorted, valid sort parameters are NAME, MODIFIED, CREATED, TYPE.Prefix hyphen (-) for descending order, applicable only for draft artifact search.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
-NAME
Response
List of paginated workflow artifacts
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Artifacts have been retrieved successfully.
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Retrieves custom attribute definitions with given artifact type
This method can be used for retrieving details of custom attribute definitions.
GET /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitionsRequest
Path Parameters
The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term
Query Parameters
Is the artifact type defined as related artifact type or not, in case of "RELATIONSHIP" type only!
Response
Used to facilitate serialization and correct swagger documentation.
Custom Attribute Definition Entity
Metadata of the entity.
Status Code
The custom attribute definitions have been retrieved successfully.
Unauthorized
The custom attribute definition with given {artifact_id} does not exist.
Internal Server Error
No Sample Response
Creates custom attribute definition in the glossary
This method can be used to create custom attribute definition in the glossary.
POST /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitionsRequest
Path Parameters
The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term
Custom attribute definition to be created.
Name of custom attribute
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
ca def 1Type of custom attribute values
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
TEXTSet of artifact types
Possible values: 1 ≤ length ≤ 32, contains only unique items, Value must match regular expression
.*Examples:[ "glossary_term" ]Set of restricted category artifact ids
Possible values: length = 36, contains only unique items, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})(,([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}))*The default value of the custom attribute
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
xyzDescription
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
description of custom attribute definitionSpecifies whether custom attribute values should be displayed in child assets
Example:
trueList of predefined values. Supported only for the type ENUM.
Maximum length of custom attribute values of the type string
Example:
500Maximum
Minimum length of custom attribute values of the type string
Example:
5Minimum
Specifies whether the custom attribute can have more than one value
Example:
trueSpecifies whether custom attribute values should be read only
Example:
trueSet of related artifact types
Possible values: 1 ≤ length ≤ 32, contains only unique items, Value must match regular expression
.*Set of restricted related category artifact ids
Possible values: length = 36, contains only unique items, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})(,([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}))*Reversed Custom Attribute relationship name which may be display on the related artifact
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Term related to categorySpecifies whether custom attribute definition should be global search
Example:
true
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The custom attribute definition has been created successfully.
Bad Request
Unauthorized
UniqueConstraintViolation - custom attribute definition with given name already exists.
Internal Server Error
No Sample Response
Deletes the custom attribute definition with a given artifact_id
This method is used to delete the custom attribute definition with a given artifact_id (guid).
DELETE /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions/{custom_attribute_definition_artifact_id}Request
Path Parameters
The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact_id of the custom attribute definition to be purged.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-030745831313
Response
Glossary archive response object
Guids of the archived objects.
Guids of the deleted objects.
Guids of the updated objects.
Status Code
The custom attribute definition has been deleted successfully.
Bad Request
Unauthorized
The custom attribute definition with given {artifact_id} does not exist.
Internal Server Error
No Sample Response
Retrieves custom attribute definition with given artifact_id
This method can be used for retrieving details of a custom attribute definition.
GET /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions/{custom_attribute_definition_artifact_id}Request
Path Parameters
The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact_id of the custom attribute definition to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
d4a5e6e1-a6c0-4580-afbb-6898303adf34
Response
Used to facilitate serialization and correct swagger documentation.
Custom Attribute Definition Entity
Metadata of the entity.
Status Code
The custom attribute definition has been retrieved successfully.
Unauthorized
The custom attribute definition with given {artifact_id} does not exist.
Internal Server Error
No Sample Response
Updates custom attribute definition with given artifact_id
This method is used to update custom attribute definition with given artifact_id.
PATCH /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions/{custom_attribute_definition_artifact_id}Request
Path Parameters
The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact_id of the custom attribute definition to be updated.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})
Custom attribute definition to be updated.
Fields omitted will be unchanged, and fields set to null explicitly will be nulled out.
For multi-valued attributes & relationships, the complete list will be replaced by the given list of values.
Additional Example:
{"business_description" : "business desc updated"}
Set of artifact types
Possible values: 1 ≤ length ≤ 32, contains only unique items, Value must match regular expression
.*Examples:[ "glossary_term" ]Set of restricted category artifact ids
Possible values: length = 36, contains only unique items, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})(,([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}))*The default value of the custom attribute
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
xyzDescription
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
description of custom attribute definitionSpecifies whether custom attribute values should be displayed in child assets
Example:
trueList of predefined values. Supported only for the type ENUM.
Maximum length of custom attribute values of the type string
Example:
500Maximum
Minimum length of custom attribute values of the type string
Example:
5Minimum
Name of custom attribute
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
ca def 1Specifies whether custom attribute values should be read only
Example:
trueSet of related artifact types
Possible values: 1 ≤ length ≤ 32, contains only unique items, Value must match regular expression
.*Set of restricted related category artifact ids
Possible values: length = 36, contains only unique items, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})(,([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}))*Reversed Custom Attribute relationship name which may be display on the related artifact
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Term related to categorySpecifies whether custom attribute definition should be global search
Example:
true
Response
Used to facilitate serialization and correct swagger documentation.
Custom Attribute Definition Entity
Metadata of the entity.
Status Code
The custom attribute definition has been updated successfully.
Bad Request
Unauthorized
Forbidden
The custom attribute definition with given {artifact_id} does not exist.
The custom attribute definition was modified by another user.
Internal Server Error
No Sample Response
Delete a list of draft or published versions of given artifact_type
If the artifact state is DRAFT, then the draft version is deleted.
If the artifact state is PUBLISHED, a draft version with marked_for_deletion is created .
If the artifact state is PUBLISHED and workflow is skipped, then the published version is deleted.
If a draft artifact already exists for deletion for a published artifact, then the draft artifact is simply skipped.
Administrator role is required.
POST /v3/governance_artifact_types/{artifact_type}/deleteRequest
Path Parameters
The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term
Query Parameters
If async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
If someone has already created a draft for deleting or updating an artifact, then the artifact will be ignored.
If specified asset does does not exist, it is skipped.
Default:
false
The list of artifacts to be deleted. All the artifacts must be either in published state or draft state, but mix of draft and published state is not allowed.
List of resource identifiers.
Response
Status Code
A draft version has been successfully created for deleting the published artifact.
If async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.
The artifacts have been deleted successfully.
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Exports values of a specified type to a csv file
This method can be used to export values of a specified type to a csv file.
GET /v3/governance_artifact_types/{artifact_type}/exportRequest
Path Parameters
The artifact type. Allowed values are category, glossary_term, data_class, policy, rule, classification
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term
Query Parameters
The artifactId of the parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4Whether to include the parent category. This applies to category (as asset type) export only, and is ignored for other asset types. The special [uncategorized] category is not included.
Whether to include assets from subcategories
Import values from specified csv file
This method can be used to import values from specified csv file.
POST /v3/governance_artifact_types/{artifact_type}/importRequest
Path Parameters
The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term
Query Parameters
Import merge option, valid values:
all - imported values will replace existing values in catalog
specified - imported values that are not empty replace existing values in catalog
empty - imported values replace only empty values in catalog.Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
emptyExample:
allIf async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.
Form Parameters
File
Possible values: 1 ≤ length ≤ 2147483647
Response
Glossary Import Status
Children statuses
Completion time
Creation time
Error message
Heartbeat time
Heartbeater id
List of import messages
Operations count
- operations_count
Operations count
- any property
Operations count
Process Id
Status
Step message
Step number
Tenant Id
Total steps
Workflow Id
Status Code
Import of assets has been completed
Import of assets has been started
Unauthorized
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
No Sample Response
Search for a list of drafts of given artifact_type
This method can be used for retrieving draft artifacts.
POST /v3/governance_artifact_types/{artifact_type}/searchRequest
Path Parameters
The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_term
The list of draft artifacts to be retrieved. If drafts exist, then they are returned.
List of resources.
Get the latest published version of the specified artifact
This method can be used for getting the latest published version of the specified artifact.
GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}Request
Path Parameters
The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termArtifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Comma-separated list of relationship types.
Relationship TypesArtifact Typescategoryclassificationdata_classglossary_termpolicyreference_dataruleall+ + + + + + + categories- + + + + + + child- - - - - + - classifications+ - + + + + + custom+ + + + + + + data_classes- + - + + + + data_location_rules- - - - + - - data_protection_rules- - - - + - - grouped_assets+ - - - - - - has_terms- - - + - - - has_type_terms- - - + - - - has_types_category+ - - - - - - has_types_classifications- + - - - - - has_types_classifications_hierarchy- + - - - - - has_types_data_class_hierarchy- - + - - - - has_types_data_classes- - + - - - - has_types_term_hierarchy- - - + - - - is_a_parent_category_for+ - - - - - - is_a_type_of_category+ - - - - - - is_a_type_of_classification- + - - - - - is_a_type_of_data_class- - + - - - - is_a_type_of_terms- - - + - - - is_of_terms- - - + - - - multi_value_mappings- - - - - + - owned_by+ - - - - - - parent- - - - - + - parent_category- + + + + + + parent_hierarchy- - - - - + - parent_policy- - - - + - - policies- + + + - - + reference_data- + + + - - + reference_data_values- - - + - - - related_categories- + - - - - - related_terms- - - + - - - replaced_by_terms- - - + - - - replaces_terms- - - + - - - rules- + + + + + + single_value_mappings- - - - - + - sub_policies- - - - + - - synonym_terms- - - + - - - terms- + + - + + + value_mappings- - - - - + - Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'false'.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
This parameter is ignored when artifact type is category.Possible values: 1 ≤ value ≤ 200
Default:
10If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
This parameter is ignored when artifact type is category.
Response
Represents an object that we send back to the end user. It has two parts: entity and metadata.
Base object for entity
Metadata of the entity.
Status Code
The latest published version of the specified artifact has been retrieved successfully.
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Changes the parent category of a published artifact with given id
This method can be used to change given artifact parent. Or make it root-level, in case of category.
Note: change of collaborators access may take longer to complete
POST /v3/governance_artifact_types/{artifact_type}/{artifact_id}/moveRequest
Path Parameters
The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termArtifact ID or global ID of the artifact
Possible values: 1 ≤ length ≤ 73, Value must match regular expression
.*
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Target category (to become a parent of this artifact)
specifies id of category to become parent after move. One can specify either artifact ID or global ID. In case of category, one can specify string
ROOTto move it to the top levelPossible values: 1 ≤ length ≤ 73, Value must match regular expression
.*Example:
e39ada11-8338-3704-90e3-681a71e7c839
Response
Represents an object that we send back to the end user. It has two parts: entity and metadata.
Base object for entity
Metadata of the entity.
Status Code
The artifact has been moved successfully.
Bad Request
Unauthorized
Forbidden
Published artifact not found for given guid
Either the artifact was modified by another user, or the same artifact already exists with the same new parent category
Internal Server Error
No Sample Response
Get development logs & Comments for a draft artifact version
Get development logs & Comments for a draft artifact version
GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/aggregated_logsRequest
Path Parameters
The artifact type. Allowed values are glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Time zone offset based on which the day wise grouping is to be performed. The offset will be of format [+-]hh:mm where hh stands for hour digit and mm for minute digit.
e.g. +05:30 indicates IST. If [+-] is not provided by default + will be appended. e.g 05:30 indicates +05:30.
If hour digit is single like +h:mm provided, then it will be considered as +0h:mm. e.g. +5:30 indicates +05:30.
The range of offsets is restricted to -17:59 to +17:59 inclusive.Possible values: 1 ≤ length ≤ 6, Value must match regular expression
^([+-]?)(0[0-9]|1[0-7]|[0-9]):([0-5][0-9])$
Response
List of paginated asset aggregated comments
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Development logs & Comments retrieved successfully
Bad Request
Unauthorized
Forbidden
Draft artifact version not found for given version_id
Internal Server Error
No Sample Response
Get development logs & Comments for a draft artifact version with development log id
Get development logs & Comments for a draft artifact version with development log id
GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/aggregated_logs/{mod_id}Request
Path Parameters
The artifact type. Allowed values are glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*The development log id.
Possible values: 1 ≤ length ≤ 73, Value must match regular expression
.*
Query Parameters
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
Paginated asset comment modification details
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Development logs & Comments retrieved successfully
Bad Request
Unauthorized
Forbidden
Draft artifact version not found for given version_id
Internal Server Error
No Sample Response
Add a comment for a draft artifact version
Add a comment for a draft artifact version
POST /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/commentsRequest
Path Parameters
The artifact type. Allowed values are glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
The user comment.
User comment
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Indicates whether the development log entry originates from import
Response
Comment By User
User comment
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Indicates whether the development log entry originates from import
Status Code
Comment added successfully
Bad Request
Unauthorized
Forbidden
Draft artifact version not found for given version_id
Internal Server Error
No Sample Response
Delete a comment on a draft artifact version
Delete a comment on a draft artifact version
DELETE /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/comments/{comment_id}Request
Path Parameters
The artifact type. Allowed values are glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The version id.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4The comment id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Update a comment on a draft artifact version
Update a comment on a draft artifact version
PATCH /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/comments/{comment_id}Request
Path Parameters
The artifact type. Allowed values are glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The version id.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4The comment id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
The user comment.
User comment
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Indicates whether the development log entry originates from import
Response
Comment By User
User comment
Possible values: 1 ≤ length ≤ 32672, Value must match regular expression
.*Indicates whether the development log entry originates from import
Status Code
Comment updated successfully
Bad Request
Unauthorized
Draft artifact version not found for given version_id
Internal Server Error
No Sample Response
Get development logs & Comments for a draft artifact version
Get development logs & Comments for a draft artifact version
GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/logsRequest
Path Parameters
The artifact type. Allowed values are glossary_term, classification, data_class, reference_data, policy, rule
Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Example:
glossary_termThe artifact id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})The version id.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*
Query Parameters
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
Paginated Asset Comment List
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Development logs & Comments retrieved successfully
Bad Request
Unauthorized
Forbidden
Draft artifact version not found for given version_id
Internal Server Error
No Sample Response
Request
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
Represents a policy to be created, used for policy POST request.
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1Secondary categories the artifact belongs to.
Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
Relationships to data location rules only. Does not include other rule relationships.
Relationships to data protection rules only. Does not include other rule relationships.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The parent category of the artifact.
The parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
Relationships to governance rules only. Does not include other rule relationships.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The list of sub-policies in the policy type hierarchy.
The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Relationships to business terms.
The workflow state of an artifact
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The policy has been created successfully.
Bad Request
Unauthorized
UniqueConstraintViolation - policy with given name already exists.
Internal Server Error
No Sample Response
Retrieves versions of a policy for the given artifact_id and status
Retrieval of the versions of ACTIVE state is supported.
GET /v3/policies/{artifact_id}/versionsRequest
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Filter by policy status.
Available statuses: DRAFTartifacts which are being created or modified and not in use PUBLISHEDartifacts which are in published state (does not takes effective dates into account) ACTIVEartifacts which are published, and which effective date period includes current datetime Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
PUBLISHEDComma-separated list of relationship types.
Available types: parent_policysub_policiesparent_categorycategoriestermsclassificationsrulesdata_location_rulesdata_protection_rulescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Response
List of paginated artifacts
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Success
Bad Request
Unauthorized
Not found
Internal Server Error
No Sample Response
Deletes a draft or published version of an artifact
If the artifact state is DRAFT, then the draft version is deleted.
If the artifact state is PUBLISHED, a draft version with marked_for_deletion is created .
If the artifact state is PUBLISHED and workflow is skipped, then the published version is deleted.
If a draft artifact already exists for deletion for a published artifact, then the draft artifact is simply skipped.
Administrator role is required.
DELETE /v3/policies/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact ID of the policy.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the policy to delete or to create mark-for-delete draft copy.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The artifact has been deleted successfully.
A draft version has been successfully created for deleting the published artifact.
Bad Request
Unauthorized
Policy with sub-policies cannot be deleted. Try again after re-parenting sub-policies.
Policy with given artifact and version ids does not exist in the glossary.
Internal Server Error
No Sample Response
Retrieves versions of a policy for the given artifact_id and status
Retrieval of the versions of ACTIVE state is supported.
GET /v3/policies/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact ID of the policy to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the policy to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: parent_policysub_policiesparent_categorycategoriestermsclassificationsrulesdata_location_rulesdata_protection_rulescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Response
Policy returned by REST GET method that includes the relationships as paginated list.
Policy entity for GET response.
Metadata of the entity.
Status Code
The policy has been retrieved successfully.
Unauthorized
The policy with given {guid} does not exist in the glossary.
Internal Server Error
No Sample Response
Updates policy with given artifact id and version id
Updates policy with given artifact id and version id. If the policy is in published state then first creates a draft and applies the changes to the newly created draft.
PATCH /v3/policies/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the policy to be updated.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the policy to be updated.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
The policy to be updated.
Fields omitted will be unchanged, and fields set to null explicitly will be nulled out.
For multi-valued attributes & relationships, the complete list will be replaced by the given list of values.
Additional Example:
{"description" : "description updated"}
The revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Secondary categories the artifact belongs to.
Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
Relationships to data location rules only. Does not include other rule relationships.
Relationships to data protection rules only. Does not include other rule relationships.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1The parent category of the artifact.
The parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
Relationships to governance rules only. Does not include other rule relationships.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The list of sub-policies in the policy type hierarchy.
The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Relationships to business terms.
Response
Policy returned by REST GET method that includes the relationships as paginated list.
Policy entity for GET response.
Metadata of the entity.
Status Code
The policy has been updated successfully.
Bad Request
Unauthorized
Forbidden
The policy with given {guid} does not exist in the glossary.
The policy was modified by another user.
Internal Server Error
No Sample Response
Updates DPR rule relationships of a published policy using its artifact id and version id
Updates DPR rule relationships of a published policy using its artifact id and version id
Deprecated, functionality will be replaced by new one introduced in the feature releases.
PATCH /v3/policies/{artifact_id}/versions/{version_id}/data_protection_rulesRequest
Path Parameters
The artifact id of the policy to be updated.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})The version id of the policy to be updated.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
The parent category of the artifact.
Artifact id of the related artifact.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Response
Policy returned by REST GET method that includes the relationships as paginated list.
Policy entity for GET response.
Metadata of the entity.
Status Code
The policy has been updated successfully.
Bad Request
Unauthorized
Forbidden
The policy with given {guid} does not exist in the glossary.
The policy was modified by another user.
Internal Server Error
No Sample Response
List the relationships for the specified policy
If the result set is larger than the limit parameter, it returns the first limit number of relationships.
To retrieve the next set of relationships, call the method again by using the URI in the property next returned by this method.
GET /v3/policies/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The guid of the Policy
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The versionID of the Policy
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: parent_policysub_policiesparent_categorycategoriestermsclassificationsrulesdata_location_rulesdata_protection_rulescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Custom relationship definition Id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4Is custom relationship reversed?
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Retrieves target parent category name of the relationship entity.
Response
Response that includes relationships to a managed object, like business term, data class, classification
List of custom relationships
Mapping of the relationship type to the paginated list of relationships
- relationships
Base V3 class for paginated results
Status Code
Success
Bad Request
Unauthorized
Internal Server Error
No Sample Response
Create relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and adds the relationship to the draft version. And, it returns the details of the draft version.
POST /v3/policies/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact ID of the term to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the term to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Relationships to be created.
Category relationships.
Relationships to classifications.
Relationships to data classes.
Relationships to data location rules only. Does not include other rule relationships.
Relationships to data protection rules only. Does not include other rule relationships.
The parent category of the artifact.
The parent category of the artifact.
Relationships to governance rules only. Does not include other rule relationships.
The list of sub-policies in the policy type hierarchy.
Relationships to business terms.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
Success
Bad Request
Unauthorized
Not found
Unique constraint violated because of optimistic locking or some other constraint.
Internal Server Error
No Sample Response
Deletes a relationship from a draft policy
Deletes a relationship from a draft policy
DELETE /v3/policies/{artifact_id}/versions/{version_id}/relationships/{relationship_id}Request
Path Parameters
The artifact ID of the policy to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the policy to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Retrieves relationships for a given artifact type, artifact_id and artifact version_id
For a given artifact type, a set of predefined relationship attributes with associated artifacts are included for every relationship.
GET /v3/relationships
Request
Query Parameters
The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule
Example:
glossary_termThe id of artifact that is a part of the requested relationship.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of artifact that is a part of the requested relationship.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0Comma-separated list of relationship types.
Relationship TypesArtifact Typescategoryclassificationdata_classglossary_termpolicyreference_dataruleall+ + + + + + + categories- + + + + + + child- - - - - + - classifications+ - + + + + + custom+ + + + + + + data_classes- + - + + + + data_location_rules- - - - + - - data_protection_rules- - - - + - - grouped_assets+ - - - - - - has_terms- - - + - - - has_type_terms- - - + - - - has_types_category+ - - - - - - has_types_classifications- + - - - - - has_types_classifications_hierarchy- + - - - - - has_types_data_class_hierarchy- - + - - - - has_types_data_classes- - + - - - - has_types_term_hierarchy- - - + - - - is_a_parent_category_for+ - - - - - - is_a_type_of_category+ - - - - - - is_a_type_of_classification- + - - - - - is_a_type_of_data_class- - + - - - - is_a_type_of_terms- - - + - - - is_of_terms- - - + - - - multi_value_mappings- - - - - + - owned_by+ - - - - - - parent- - - - - + - parent_category- + + + + + + parent_hierarchy- - - - - + - parent_policy- - - - + - - policies- + + + - - + reference_data- + + + - - + reference_data_values- - - + - - - related_categories- + - - - - - related_terms- - - + - - - replaced_by_terms- - - + - - - replaces_terms- - - + - - - rules- + + + + + + single_value_mappings- - - - - + - sub_policies- - - - + - - synonym_terms- - - + - - - terms- + + - + + + value_mappings- - - - - + - Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*A filter to artifacts that have been created / updated / deleted since the given timestamp in this format: [yyyy-MM-ddTHH:mm:ss.SSSZ]
Possible values: length = 24, Value must match regular expression
^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?(([+-]\d\d:\d\d)|Z)?)?)?)?$The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
Paginated lightweight search artifact list
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
Success
Bad Request
Unauthorized
Internal Server Error
No Sample Response
Request
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
Rule to be created.
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Rule 1Currently supported: Governance.
Allowable values: [
Quality,Automation,DataProtection,Governance,Data]Example:
GovernanceSecondary categories the artifact belongs to.
Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
long descriptionThe parent category of the artifact.
The relationships to governance policies.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
The relationships to reference data sets.
Relationships to governance rules only. Does not include other rule relationships.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
short descriptionThe steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]Relationships to business terms.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The rule has been created successfully.
Bad Request
Unauthorized
UniqueConstraintViolation - rule with given name already exists.
Internal Server Error
{ "resources": [ { "href": "v3/reference_data/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" } ] }
Retrieves rule with given artifact_id and status
This method can be used for retrieving details of an ACTIVE, PUBLISHED or DRAFT rule.
GET /v3/rules/{artifact_id}/versionsRequest
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Filter by rule status.
Available statuses: DRAFTartifacts which are being created or modified and not in use PUBLISHEDartifacts which are in published state (does not takes effective dates into account) ACTIVEartifacts which are published, and which effective date period includes current datetime Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
PUBLISHEDComma-separated list of relationship types.
Available types: parent_categorycategoriestermsrulesreference_datapoliciesclassificationsdata_classescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueIf this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
List of paginated artifacts
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
Results of the list / search.
Status Code
The rule has been retrieved successfully.
Bad Request
Unauthorized
The rule with given {guid} does not exist in the glossary.
Internal Server Error
{ "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "type, rule_type, etc": "TEXT, Governance, etc", "long_description": "string", "is_removed_long_description": false, "state": "PUBLISHED", "default_locale_id": "en-US", "reference_copy": false, "custom_attributes": [] } } ] }
Deletes a draft or published version of an artifact
If the artifact state is DRAFT, then the draft version is deleted.
If the artifact state is PUBLISHED, a draft version with marked_for_deletion is created .
If the artifact state is PUBLISHED and workflow is skipped, then the published version is deleted.
If a draft artifact already exists for deletion for a published artifact, then the draft artifact is simply skipped.
Administrator role is required.
DELETE /v3/rules/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the rule to delete.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the rule to delete.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
A draft version has been successfully created for deleting the published artifact.
The artifact has been deleted successfully.
Bad Request
Unauthorized
Draft version for the given version ID does not exist in the glossary.
Internal Server Error
{ "resources": [ { "href": "v3/reference_data/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" } ] }
Retrieves rule with given guid
This method can be used for retrieving details of an PUBLISHED or DRAFT rule.
GET /v3/rules/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact ID of the rule to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the rule to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: parent_categorycategoriestermsrulesreference_datapoliciesclassificationsdata_classescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
^(parent_category|categories|terms|classifications|data_classes|reference_data|policies|rules|custom|all)(,(parent_category|categories|terms|classifications|data_classes|reference_data|policies|rules|custom|all))*$If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.
Default:
trueIf this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10
Response
Rule returned by REST GET method that includes the relationships as paginated list.
Represents a rule entity returned by REST GET methods that include the relationships as paginated lists
Metadata of the entity.
Status Code
The rule has been retrieved successfully.
Unauthorized
The rule with given {guid} does not exist in the glossary.
Internal Server Error
No Sample Response
Updates rule with given id
This method is used to update rule with given id.
PATCH /v3/rules/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the rule to be updated.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the rule to be updated.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
The rule to be updated.
Fields omitted will be unchanged, and fields set to null explicitly will be nulled out.
For multi-valued attributes & relationships, the complete list will be replaced by the given list of values.
Additional Example:
{"description" : "description updated"}
The revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Secondary categories the artifact belongs to.
Relationships to classifications.
List of custom attributes with their values.
Custom relationships to asset
Relationships to data classes.
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
long descriptionThe name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Name 1The parent category of the artifact.
The relationships to governance policies.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
The relationships to reference data sets.
Relationships to governance rules only. Does not include other rule relationships.
The short description of an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
short descriptionThe steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]The stewards assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]Relationships to business terms.
Response
Rule returned by REST GET method that includes the relationships as paginated list.
Represents a rule entity returned by REST GET methods that include the relationships as paginated lists
Metadata of the entity.
Status Code
The rule has been updated successfully.
Bad Request
Unauthorized
Forbidden
The rule with given {guid} does not exist in the glossary.
The rule was modified by another user.
Internal Server Error
No Sample Response
List the relationships of the given type for the specified rule
If the result set is larger than the limit parameter, it returns the first limit number of relationships.
To retrieve the next set of relationships, call the method again by using the URI in the property next returned by this method.
GET /v3/rules/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact ID of the rule to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the rule to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of relationship types.
Available types: parent_categorycategoriestermsrulesreference_datapoliciesclassificationsdata_classescustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Custom relationship definition Id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4Is custom relationship reversed?
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Retrieves target parent category name of the relationship entity.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
Response
Response that includes relationships to a managed object, like business term, data class, classification
List of custom relationships
Mapping of the relationship type to the paginated list of relationships
- relationships
Base V3 class for paginated results
Status Code
Success
Bad Request
Unauthorized
Internal Server Error
No Sample Response
Create relationships for an artifact in the glossary
If it is a published version, it creates a draft from the published version and adds the relationship to the draft version. And, it returns the details of the draft version.
POST /v3/rules/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact ID of the rule to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the rule to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Relationships to be created.
Category relationships.
The list of related classifications
The list of related data classes
The parent category of the artifact.
The list of parent policies
The list of related reference data sets
The list of related rules
The list of related business terms
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The relationship(s) have been created successfully.
Bad Request
Unauthorized
UniqueConstraintViolation - This Relationships is already exist
Internal Server Error
No Sample Response
Deletes a relationship of a rule artifact
This method can be used for deleting a relationship of a rule artifact.
DELETE /v3/rules/{artifact_id}/versions/{version_id}/relationships/{relationship_id}Request
Path Parameters
The artifact ID of the rule to fetch.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version ID of the rule to fetch.
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The relationship of the rule artifact was successfully deleted.
Bad Request
Unauthorized
The relationship for the given GUID does not exist in the glossary.
Internal Server Error
No Sample Response
Request
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
Represents a Reference Data Set to be created for RDS V4 API version.
The name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
reference data set nameSecondary categories the artifact belongs to.
The relationships to reference data sets.
Relationships to classifications.
Custom relationships to asset
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
description of reference data setThe relationships to reference data sets.
The parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]Stewards Ids
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]Relationships to business terms.
Type
Allowable values: [
TEXT,NUMBER,DATE]Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
TEXT
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The reference data set has been created successfully.
Bad Request
Unauthorized
Reference data set with given name already exists.
Internal Server Error
{ "href": "/v4/reference_data_sets/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Retrieve a reference data set with given artifact_id and status
This method can be used for retrieving details of an ACTIVE, PUBLISHED or DRAFT reference data set.
GET /v4/reference_data_sets/{artifact_id}/versionsRequest
Path Parameters
Artifact ID or global ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Filter by reference data set status.
Available statuses: DRAFTartifacts which are being created or modified and not in use PUBLISHEDartifacts which are in published state (does not takes effective dates into account) ACTIVEartifacts which are published, and which effective date period includes current datetime Possible values: 1 ≤ length ≤ 32, Value must match regular expression
.*Default:
PUBLISHEDFetch only the first page of every requested relationship. Size of the page is defined by
limit. To fetch other relationship pages call: /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationships. Comma-separated list of relationship types.Available types: parent_categorycategoriestermsclassificationsdata_classesruleschildparentallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Fetch custom relationships definitions for reference data set with relationships count.
Default:
falseFetch Custom Column definition for reference dataset.
Default:
falseFetch composite key for reference dataset.
Default:
falseIf this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'false'.
Default:
falseThe maximum number of artifacts to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Response
Paginated list of V4 Reference Data Sets
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
List of reference data set versions
Status Code
The reference data set has been retrieved successfully.
Bad Request
Unauthorized
The reference data set with given {guid} does not exist.
Internal Server Error
{ "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "versions": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "terms": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "classifications": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "parent_category": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "parent_id": "303ed1d2-0885-473e-9050-40f9223549d5", "parent_global_id": "TEMPLATE_303ed1d2-0885-473e-9050-40f9223549d5", "parent_name": "name_example", "parent_href": "/v3/categories/303ed1d2-0885-473e-9050-40f9223549d5", "parent_enabled": true, "child_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "child_global_id": "TEMPLATE_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "child_category_id": "303ed1d2-0885-473e-9050-40f9223549d5", "child_name": "rds_name1", "child_href": "/v4/reference_data/0d6412d5-fce8-4bb7-90c9-891bc3de5c4b/versions?status=ACTIVE", "relationship_type": "parent_category", "source_type": "reference_data", "target_type": "category", "description": "parent example", "reference_copy": false } } ] }, "categories": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "parent": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "child": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "custom_relationships": [ { "definition_id": "44764021-0473-4e53-9653-802e5d705afb", "artifact_id": "51d324a5-d806-48e6-a3bc-472e8c854153", "name": "custom rel ", "related_artifact_types": [ "policy" ], "description": "description custom rel", "is_reversed": false, "read_only": false, "total_count": 10 } ], "custom_columns": [ { "id": "a98edac9-4953-431e-9f8e-d9f1507454d8", "revision": "0", "name": "Custom_Column_Name", "description": "This is a Custom Column", "type": "TEXT", "max_character_count": 2000, "mandatory": true, "composite_key": true, "owner_rds_id": "9ec35f22-db7f-56c9-8a05-25983e485adc", "validator_rds_id": "d58b8247-8f94-4c1f-8ea1-48f1cb55122a", "hidden": false } ], "composite_key": [ { "id": "a98edac9-4953-431e-9f8e-d9f1507454d8", "revision": "0", "name": "Custom_Column_Name", "description": "This is a Custom Column", "type": "TEXT", "max_character_count": 2000, "mandatory": true, "composite_key": true, "owner_rds_id": "9ec35f22-db7f-56c9-8a05-25983e485adc", "validator_rds_id": "d58b8247-8f94-4c1f-8ea1-48f1cb55122a", "hidden": false } ], "rds_values_total_counts": 1, "type, rule_type, etc": "TEXT, Governance, etc", "long_description": "string", "is_removed_long_description": false, "state": "PUBLISHED", "default_locale_id": "en-US", "reference_copy": false, "custom_attributes": [] } } ] }
Delete a reference data set with given artifact_id and version_id
Delete the reference data set with a given artifact_id and version_id. If the artifact is published then a workflow will be started with a draft created with label marked for deletion which on approval will result in a actual delete. If the artifact is a draft copy then the draft copy will be deleted from the system.
DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Specify new reference data parent artifact_id for children of reference data that is to be removed. If move_child_to is not set all reference data children become root objects.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Response
Create response object returned on creating a resource such as a Term, Category, Classification, DataClass, Policy.
IDs of the created items.
Status Code
The reference data set has been deleted successfully if workflow is disabled.
A draft version has been successfully created for deleting the published artifact.Bad Request
Unauthorized
The reference data set with given {guid} does not exist.
The reference data set is currently used in catalog assets, catalog asset columns, data governance rules or data governance policies.
Internal Server Error
{ "href": "/v4/reference_data_sets/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Retrieve a reference data set with given artifact_id and version_id
This method will retrieve details of the specified reference data set.
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Fetch only the first page of every requested relationship. Size of the page is defined by
limit. To fetch other relationship pages call: /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationships. Comma-separated list of relationship types.Available types: parent_categorycategoriestermsclassificationsdata_classesruleschildparentallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Fetch custom relationships definitions for reference data set with relationships count.
Default:
falseFetch Custom Column definition for reference dataset.
Default:
falseFetch composite key for reference dataset.
Default:
falseIf this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'false'.
Default:
falseThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Default:
false
Response
API V4 Response Reference Data Set
Reference Data Set entity returned by V4 REST GET method that includes the relationships as paginated list.
Metadata of the entity.
Status Code
The reference data set has been retrieved successfully.
Unauthorized
The reference data set with given {guid} does not exist.
Internal Server Error
{ "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "terms": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "classifications": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "parent_category": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "parent_id": "303ed1d2-0885-473e-9050-40f9223549d5", "parent_global_id": "TEMPLATE_303ed1d2-0885-473e-9050-40f9223549d5", "parent_name": "name_example", "parent_href": "/v3/categories/303ed1d2-0885-473e-9050-40f9223549d5", "parent_enabled": true, "child_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "child_global_id": "TEMPLATE_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "child_category_id": "303ed1d2-0885-473e-9050-40f9223549d5", "child_name": "rds_name1", "child_href": "/v4/reference_data/0d6412d5-fce8-4bb7-90c9-891bc3de5c4b/versions?status=ACTIVE", "relationship_type": "parent_category", "source_type": "reference_data", "target_type": "category", "description": "parent example", "reference_copy": false } } ] }, "categories": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "parent": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "child": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "resources": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "relationship_type": "related, value_to_term, etc", "reference_copy": false } } ] }, "custom_relationships": [ { "definition_id": "44764021-0473-4e53-9653-802e5d705afb", "artifact_id": "51d324a5-d806-48e6-a3bc-472e8c854153", "name": "custom rel ", "related_artifact_types": [ "policy" ], "description": "description custom rel", "is_reversed": false, "read_only": false, "total_count": 10 } ], "custom_columns": [ { "id": "a98edac9-4953-431e-9f8e-d9f1507454d8", "revision": "0", "name": "Custom_Column_Name", "description": "This is a Custom Column", "type": "TEXT", "max_character_count": 2000, "mandatory": true, "composite_key": true, "owner_rds_id": "9ec35f22-db7f-56c9-8a05-25983e485adc", "validator_rds_id": "d58b8247-8f94-4c1f-8ea1-48f1cb55122a", "hidden": false } ], "composite_key": [ { "id": "a98edac9-4953-431e-9f8e-d9f1507454d8", "revision": "0", "name": "Custom_Column_Name", "description": "This is a Custom Column", "type": "TEXT", "max_character_count": 2000, "mandatory": true, "composite_key": true, "owner_rds_id": "9ec35f22-db7f-56c9-8a05-25983e485adc", "validator_rds_id": "d58b8247-8f94-4c1f-8ea1-48f1cb55122a", "hidden": false } ], "rds_values_total_counts": 1, "type, rule_type, etc": "TEXT, Governance, etc", "long_description": "string", "is_removed_long_description": false, "state": "PUBLISHED", "default_locale_id": "en-US", "reference_copy": false, "custom_attributes": [] } }
Update a reference data set with given artifact id and version id
Update a reference data set with given artifact id and version id
To remove description please specify: "long_description": null.
PATCH /v4/reference_data_sets/{artifact_id}/versions/{version_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
The reference data set to be updated.
Fields omitted will be unchanged. For multi-valued attributes, like values and relationships, use the respective endpoints.
The revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Example:
0New composite key order
The effective end date at which the artifact ends and no longer effective. If the effective end date is not specified, then the artifact remains effect forever.
Possible values: 10 ≤ length ≤ 32
The effective start date at which the artifact goes into effect. If the effective start date is not specified, then the artifact goes into effect immediately.
Possible values: 10 ≤ length ≤ 32
The long description of an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Example:
description of reference data setThe name of the artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
ISO Country CodesThe parent category of the artifact.
Indicates that it is a reference copy of an artifact managed in an external metadata server.
The steward groups assigned to an artifact.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward_group1", "steward_group2" ]Stewards Ids
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Examples:[ "steward1", "steward2" ]The tags assigned to an artifact.
Possible values: 1 ≤ length ≤ 15000, Value must match regular expression
.*Examples:[ "tag1", "tag2" ]
Response
API V4 Response Reference Data Set
Reference Data Set entity returned by V4 REST GET method that includes the relationships as paginated list.
Metadata of the entity.
Status Code
The reference data set has been updated successfully.
Bad Request
Unauthorized
Forbidden
The reference data set with given {guid} does not exist.
The reference data set was modified by another user.
Internal Server Error
{ "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "type, rule_type, etc": "TEXT, Governance, etc", "long_description": "string", "is_removed_long_description": false, "state": "PUBLISHED", "default_locale_id": "en-US", "reference_copy": false, "custom_attributes": [] } }
Create Custom Column definitions
Create Custom Column definitions
- Allowed Custom Column definitions types:
NUMBER, TEXT, DATE. - If a column is a composite key, it must be mandatory.
- For
NUMBERandTEXTtypes the default values formax_characters_count:- for a composite key column: 200,
- for a normal column: 2000.
validator_rds_idmust be an artifact id of a published RDS.
POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columnsRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
RDS custom columns create request
List of custom column Definitions.
Response
Custom column create response
resources of custom columns.
Status Code
The Custom Column(s) have been created successfully.
Bad Request
Unauthorized
UniqueConstraintViolation - Custom Column definition with given name already exists.
Internal Server Error
{ "custom_columns": [ { "id": "a98edac9-4953-431e-9f8e-d9f1507454d8", "revision": "0", "name": "Custom_Column_Name", "description": "This is a Custom Column", "type": "TEXT", "max_character_count": 2000, "mandatory": true, "composite_key": true, "owner_rds_id": "9ec35f22-db7f-56c9-8a05-25983e485adc", "validator_rds_id": "d58b8247-8f94-4c1f-8ea1-48f1cb55122a", "hidden": false } ] }
Delete a Custom Column definition by column_id
Delete a Custom Column definition by column_id
DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columns/{column_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The column id associated with Custom Column definition.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Retrieve a Custom Column definition with given column_id
Retrieve a Custom Column definition with given column_id
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columns/{column_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The column id associated with Custom Column definition.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})
Response
RDS Custom Columns Get Response
List of composite key members
metadata of cust columns.
Status Code
Custom Column definition with given column_id has been retrieved successfully.
Unauthorized
The Custom Column definition with given {column_id} does not exist.
Internal Server Error
{ "metadata": { "id": "8b047b17-8e31-4382-be19-e873d46d32a8", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "created_at": "2017-02-15T02:30:32.000Z", "created_by": "IBMid-1234567ABC", "revision": "0" }, "entity": { "id": "a98edac9-4953-431e-9f8e-d9f1507454d8", "revision": "0", "name": "Custom_Column_Name", "description": "This is a Custom Column", "type": "TEXT", "max_character_count": 2000, "mandatory": true, "composite_key": true, "owner_rds_id": "9ec35f22-db7f-56c9-8a05-25983e485adc", "validator_rds_id": "d58b8247-8f94-4c1f-8ea1-48f1cb55122a", "hidden": false } }
Update Custom Column properties with given column_id
Update Custom Column properties with given column_id
To remove RDS validator please specify: "validator_rds_id": null.
To remove description please specify: "description": null.
PATCH /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columns/{column_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The column id associated with Custom Column definition.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})
Custom Column properties to be updated.
Properties mandatory, max_character_count and validator_rds_id can be changed only when owner (reference data) has no values assigned yet.
name
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Custom Column NameThe revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Example:
0description
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Custom Column DescriptionDeterminate if it is mandatory
Allowed maximum character count
Possible values: 1 ≤ value ≤ 2000, Value must match regular expression
\d*Example:
2000Artifact id of reference data set validating this custom column
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
d58b8247-8f94-4c1f-8ea1-48f1cb55122a
Response
List of composite key members
name
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Custom Column NameDeterminate if it is a part of composite key. If a column is a composite key, it must be mandatory.
description
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Custom Column DescriptionDetermines if column is hidden
Custom Column Definition Id
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4Determinate if it is mandatory
Allowed maximum character count
Possible values: 1 ≤ value ≤ 2000, Value must match regular expression
\d*Example:
2000Artifact id of reference data set owning this custom column
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
9ec35f22-db7f-56c9-8a05-25983e485adcThe revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Example:
0Custom Column definitions type.
Possible values: [
NUMBER,TEXT,DATE]Example:
TEXTArtifact id of reference data set validating this custom column
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
d58b8247-8f94-4c1f-8ea1-48f1cb55122a
Status Code
The Custom Column definition has been updated successfully.
Bad Request
Unauthorized
Forbidden
The Custom Column definition with given {column_id} does not exist.
The Custom Column was modified by another user.
Internal Server Error
{ "id": "a98edac9-4953-431e-9f8e-d9f1507454d8", "revision": "0", "name": "Custom_Column_Name", "description": "This is a Custom Column", "type": "TEXT", "max_character_count": 2000, "mandatory": true, "composite_key": true, "owner_rds_id": "9ec35f22-db7f-56c9-8a05-25983e485adc", "validator_rds_id": "d58b8247-8f94-4c1f-8ea1-48f1cb55122a", "hidden": false }
List the relationships of the given type for the specified reference data set
If the result set is larger than the limit parameter, it returns the first limit number of relationships.
To retrieve the next set of relationships, call the method again by using the URI in the property next returned by this method.
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
The relationship type for reference data set.
Available types: parent_categorycategoriestermsclassificationsdata_classesruleschildparentcustomallPossible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Default:
allCustom relationship definition Id.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4Is custom relationship reversed?
Default:
falseThe maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.
If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.
Default:
falseRetrieves target parent category name of the relationship entity.
Default:
false
Response
Paginated list of relationships
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
List of relationships
Status Code
Success
Bad Request
Unauthorized
Internal Server Error
{ "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_global_id": "867907bd-4c80-458d-9e75-c5683e013533_6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "target_parent_category_id": "e39ada11-8338-3704-90e3-681a71e7c839", "target_parent_category_name": "parent_category_name_example", "target_name": "name_example", "target_effective_start_date": "2022-02-14T13:16:49.355Z", "target_effective_end_date": "2022-02-15T14:16:49.355Z", "source_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "source_type": "reference_data,reference_data_value, etc", "target_type": "glossary_term, reference_data, category, etc", "description": "string", "type": "parent_category", "reference_copy": false } } ] }
Associate Reference data set identified by artifact_id and version_id with other governance artifacts
Associate Reference data set identified by artifact_id and version_id with other governance artifacts
POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationshipsRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
list of relationships that need to created for reference data set
Category relationships.
New relationship with reference data set.
The relationships to classifications.
Custom relationships to asset
New relationship with reference data set.
The parent category of the artifact.
The relationships to business terms.
Response
Create relationship response for Reference Data Set V4
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4secondary category relationships added
child reference data set relationships added
classification relationships added
Custom relationships to asset
- custom_relationships
Custom relationships to asset
The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4parent reference data set relationships added
Response ID's of create relationships
The global ID of the parent category of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6The artifact ID of the parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a667-0307458362d4term relationships added
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
Relationships created for reference data set
Bad Request
Unauthorized
Relationships conflicting for reference data set
Internal Server Error
{ "terms": [ { "relationship_id": "fdbf64ed-8d72-43b8-8752-8b765db51e01", "target_id": "4ce5b4d5-611e-4607-8e18-e2a7d9abbfe7" } ], "classifications": [], "categories": [ { "relationship_id": "eca11f9e-ff14-4692-ad93-35eb364f9f23", "target_id": "166a5f6b-3f42-4706-b868-92f622d5094a" } ], "child": [ { "relationship_id": "382c8bfa-5c2f-4daf-ac6e-b625119b1c6f", "target_id": "eec1c2a4-8bc1-40a6-a557-49af6ab2675d" } ], "parent": [], "parent_category": { "relationship_id": "18d9732c-f1b9-4325-bbf6-7d318e093263", "target_id": "4cdd7c5f-bc32-4d94-bb75-0344a6f93052" }, "href": "string", "artifact_id": "0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "version_id": "cf6243fb-7d5c-4aba-9f50-887919bf08be", "workflow_id": "52f149f8-c15c-40a9-a7ec-7e1d2635a1a1", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0d6412d5-fce8-4bb7-90c9-891bc3de5c4b", "entity_type": "reference_data", "custom_relationships": { "custom_relationship_definition_id": [ { "relationship_id": "fdbf64ed-8d72-43b8-8752-8b765db51e01", "target_id": "4ce5b4d5-611e-4607-8e18-e2a7d9abbfe7" } ] } }
Delete the relationship associated to reference data set with specified artifact_id and version_id
Delete the relationship associated to reference data set with specified artifact_id and version_id
DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationships/{relationship_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Glossary artifact data
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4The global ID of the parent category of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6The artifact ID of the parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a667-0307458362d4The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
The reference data set relationship has been deleted successfully if workflow is disabled.
A draft version has been successfully created for deleting the published artifact.Bad Request
Unauthorized
relationship not found
Internal Server Error
{ "href": "/v4/reference_data_sets/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Import reference data values from csv file to the reference data set with specified artifact_id and version_id
Import reference data values from csv file to the reference data set with specified artifact_id and version_id
To check the current status
of the import please use the endpoint GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_imports/{import_id}.
POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_importsRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Form Parameters
Input stream for a import file with reference data values.
Possible values: length ≥ 1
RDV Import Request Parameters:
code- name of column or column number with codes,value- name of column or column number with values,description- name of column or column number with descriptions,parent- name of column or column number with parent RDVs,related_terms- name of column or column number with related terms,value_conflicts- conflict resolution strategy, allowable values are:- OVERWRITE - in case of duplicates, overwrite existing data,
- IGNORE - in case of duplicates, the existing data remains,
- REJECT - in case of duplicates, import fails
is_first_row_header- indicates if the first row in a file is a header, by default true,trim_white_spaces- indicates if the values should be trimmed, by default false,import_relationships_only- indicates if only relationships should be imported, by default false,skip_workflow_if_possible- indicates if workflow should be skipped, by default false,custom_columns_mappings- mappings for names of custom columns,value_mappings- mappings for relationships for values from other reference data sets, mapping_types: single_value_mappings or multi_value_mappings,
- import_parameters
Column name (number if first_row_header is false) of the code field in CSV file.
Possible values: length ≥ 1, Value must match regular expression
.*Example:
my_codeMapping for custom column names.
- custom_columns_mappings
Name of mapping column in csv file.
Possible values: length ≥ 1, Value must match regular expression
.*Example:
Column1Name of custom column.
Possible values: length ≥ 1, Value must match regular expression
.*Example:
CustomColumn
Column name (number if first_row_header is false) of the description field in CSV file.
Possible values: length ≥ 1, Value must match regular expression
.*Example:
my_descriptionIf set to true only relationships (related terms, parent relationships and value mappings) will be imported.
Column name (number if first_row_header is false) of the parent field in CSV file.
Possible values: length ≥ 1, Value must match regular expression
.*Example:
my_parentColumn name (number if first_row_header is false) of the related_terms field in CSV file.
If column name not provided, the default column name related terms or related_terms will be used.Possible values: length ≥ 1, Value must match regular expression
.*Example:
my_related_termsIf configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Default:
false- standard_column_mappings
Specify if to trim leading and trailing spaces for code, value & description.
Default:
falseColumn name (number if first_row_header is false) of the value field in CSV file.
Possible values: length ≥ 1, Value must match regular expression
.*Example:
my_valueignore/overwrite/reject if a value already exists. Default is overwrite
Allowable values: [
OVERWRITE,IGNORE,REJECT]Default:
OVERWRITEDescription of single or multi mapping to value from another reference data set.
- value_mappings
Name of mapping column in csv file.
Possible values: length ≥ 1, Value must match regular expression
.*Example:
Column1Artifact id of mapping reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4Type of values mapping. Allowed values: one_to_one/many_to_many.
Allowable values: [
single_value_mappings,multi_value_mappings]
Response
RDV Import Info Response V4
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4RDV import info
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
The reference data values import has been initiated successfully.
Bad Request
Unauthorized
Internal Server Error
{ "value_import": { "href": "Url value", "import_id": "d3516e0e-3775-498c-ba32-ce8fb0863376", "import_state": "SUCCEEDED, CANCELLED, IN_PROGRESS, etc", "import_message": "Import Completed, Import Cancelled, Import in progress, etc", "values_count": 1000, "values_processed": 1000, "values_skipped": 0, "values_inserted": 1000, "rels_values_processed": 1000, "rels_processed": 412, "rels_inserted": 400, "rels_skipped": 2, "rels_deleted": 10, "started_by": "IBMid-1234567ABC", "start_time": "2021-02-18T02:30:32.000Z", "warnings_count": 2, "warnings": [ { "row": 3, "info": [ "WKCBG3092E: Cannot create a relationship between reference data value with code IT and artifactId ca72921f-1064-4aa4-b4bd-bc66405cdde4 that is associated with reference data set with id e4256b89-dfc6-4b53-bffa-ee72f4c4a93d and reference data value represented by CAN that is associated with reference data set with versionId e378b0cb-89cb-4b3b-a9aa-006c914ae427. The latter reference data value does not exist." ] }, { "row": 4, "info": [ "WKCBG3092E: Cannot create a relationship between reference data value with code AUS and artifactId 6e3fe150-c648-4d8f-8519-2298379ea777 that is associated with reference data set with id e4256b89-dfc6-4b53-bffa-ee72f4c4a93d and reference data value represented by PAK that is associated with reference data set with versionId e378b0cb-89cb-4b3b-a9aa-006c914ae427. The latter reference data value does not exist." ] } ] }, "href": "v4/reference_data/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Request cancellation of a ongoing reference data values import process with specified import_id
Request cancellation of a ongoing reference data values import process with specified import_id
DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_imports/{import_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The import id for the reference data values import process.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Get current state of reference data values import process with specified import_id
Get current state of reference data values import process with specified import_id
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_imports/{import_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The import id for the reference data values import process.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Response
RDV Import Info Response V4
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4RDV import info
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
Success
Bad Request
Unauthorized
Internal Server Error
{ "value_import": { "href": "Url value", "import_id": "d3516e0e-3775-498c-ba32-ce8fb0863376", "import_state": "SUCCEEDED, CANCELLED, IN_PROGRESS, etc", "import_message": "Import Completed, Import Cancelled, Import in progress, etc", "values_count": 1000, "values_processed": 1000, "values_skipped": 0, "values_inserted": 1000, "rels_values_processed": 1000, "rels_processed": 412, "rels_inserted": 400, "rels_skipped": 2, "rels_deleted": 10, "started_by": "IBMid-1234567ABC", "start_time": "2021-02-18T02:30:32.000Z", "warnings_count": 2, "warnings": [ { "row": 3, "info": [ "WKCBG3092E: Cannot create a relationship between reference data value with code IT and artifactId ca72921f-1064-4aa4-b4bd-bc66405cdde4 that is associated with reference data set with id e4256b89-dfc6-4b53-bffa-ee72f4c4a93d and reference data value represented by CAN that is associated with reference data set with versionId e378b0cb-89cb-4b3b-a9aa-006c914ae427. The latter reference data value does not exist." ] }, { "row": 4, "info": [ "WKCBG3092E: Cannot create a relationship between reference data value with code AUS and artifactId 6e3fe150-c648-4d8f-8519-2298379ea777 that is associated with reference data set with id e4256b89-dfc6-4b53-bffa-ee72f4c4a93d and reference data value represented by PAK that is associated with reference data set with versionId e378b0cb-89cb-4b3b-a9aa-006c914ae427. The latter reference data value does not exist." ] } ] }, "href": "v4/reference_data/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Creates relationships for reference data values
Creates relationships for reference data values
POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_relationshipsRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
Reference Data Values Relationships
Reference Data Values Relationships
Response
V4 response for Create Value Relationships request
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4The global ID of the parent category of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6The artifact ID of the parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a667-0307458362d4List of Reference Data Values with relationships.
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
Relationships created for reference data values
Bad Request
Unauthorized
Relationships conflicting for reference data value
Internal Server Error
{ "value_relationships": [ { "artifact_id": "1f492a25-b3c2-5d73-b0c0-a6133d985bb3", "terms": [ { "relationship_id": "d5e5ba23-ee69-47f1-beb3-b09d29374455", "target_id": "6a8f8630-5cff-4c42-a8f9-1f24371ad80c" } ], "child": [ "1f492a25-b3c2-5d73-b0c0-a6133d985bb5" ] } ], "href": "string", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Retrieve a reference data value relationships with given reference data set artifact_id and version_id and reference data value artifact_id
Retrieve a reference data value relationships with given reference data set artifact_id and version_id and reference data value artifact_id
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_relationships/{rdv_artifact_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
.*Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact id of reference data value.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Only one relationship type can be selected.
Available types: termsparent_hierarchychildsingle_value_mappingsmulti_value_mappingsvalue_mappingsAllowable values: [
terms,parent_hierarchy,child,single_value_mappings,multi_value_mappings,value_mappings]The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10The index of the first matching relationship to include in the result.
Response
V4 API Reference data value details
Artifact ID
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
498ce3d1-4321-44eb-a381-d74c7c34c95bPresents a paginated list of Reference Data Value children
Code
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
GERValues of custom columns being part of composite key
Values of custom columns not being part of composite key
Description
Possible values: 1 ≤ length ≤ 8000, Value must match regular expression
.*Example:
European CountryIndicates if reference data value has at least one child
Presents a paginated list of Reference Data Value relationships
List of parent reference data values in hierarchical order
Parent Artifact ID
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
e28f5002-b16e-4f82-b434-e070636c9aeeRevision, must be provided for reference data value modification
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Example:
0Presents a paginated list of Reference Data Value relationships
Presents a paginated list of Reference Data Value relationships
Value
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
.*Example:
GermanyPresents a paginated list of Reference Data Value relationships
Status Code
The reference data value relationships has been retrieved successfully.
Unauthorized
The reference data set with given {guid} does not exist.
Internal Server Error
{ "parent": { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] }, "parent_hierarchy": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ], "child": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ] }, "terms": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "single_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "multi_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] } }
Search for reference data value(s) details with given RDS artifact_id and version_id using specific code or text value filter
Search for reference data value(s) details with given RDS artifact_id and version_id using specific code or text value filter
Possible values for code_filter: CODE_EQUALS, CODE_OR_VALUE_CONTAINS,
CODE_STARTS_WITH.
The include_relationships is a comma-separated list of relationship types for reference data value
| Available types: | |
terms | |
parent_hierarchy | |
child | |
single_value_mappings | |
multi_value_mappings | |
value_mappings | |
POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_searchRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Search Filter object
Allowable values: [
CODE_EQUALS,CODE_OR_VALUE_CONTAINS,CODE_STARTS_WITH]Reference data value search filter value
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
filter textFetch custom column values for reference data set values.
Default:
falseFetch parent reference data details for reference data set values.
Default:
falseComma-separated list of relationship types for reference data value.
Allowable values: [
parent_value,parent_value_hierarchy,child_value,multi_value_mappings,single_value_mappings,terms,value_mappings]Example:
value_mappingsThe maximum number of values to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
The index of the first matching value to include in the result.
Possible values: 1 ≤ value ≤ 2147483647, Value must match regular expression
\d*Default:
0The maximum number of relationships to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Value on which results need to be sorted, currently only CODE is supported.Prefix hyphen (-) for descending order, applicable only for reference data values search.
Possible values: Value must match regular expression
^(\+|-){0,1}CODE$Example:
-CODE
Response
Presents a paginated list of V4 Reference Data Value search results
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Represents an html link.
Represents an html link.
List of reference data values
Status Code
The reference data value(s) details have been retrieved successfully.
Unauthorized
The reference data set with given {guid} does not exist.
Internal Server Error
{ "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "value_search": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_columns_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "parent": { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] }, "parent_hierarchy": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ], "child": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ] }, "terms": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "single_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "multi_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] } } ] }
Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids
Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/valuesRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Comma-separated list of artifact ids of reference data values. If not provided, all values of given reference data set will be returned.
Possible values: 36 ≤ length ≤ 5120, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})(,([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}))*Example:
aa0e33f5-3108-4d45-a530-0307458362d4,3b5da5ed-8049-423f-848a-3844a6d88ff8Comma-separated list of relationship types for reference data value.
Available types: termsparent_hierarchychildsingle_value_mappingsmulti_value_mappingsvalue_mappingsAllowable values: [
terms,parent_hierarchy,child,single_value_mappings,multi_value_mappings,value_mappings]Fetch parent reference data details for reference data set values.
Fetch custom column values for reference data set values.
Fetch root values (values with no parent assigned) for reference data set.
The maximum number of hierarchy children to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10The index of the first matching hierarchy children to include in the result.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10Value on which results need to be sorted, currently only CODE is supported.Prefix hyphen (-) for descending order, applicable only for reference data values search.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
-CODE
Response
Presents a paginated list of V4 Reference Data Values
The limit parameter passed to the list / search method.
Possible values: 1 ≤ value ≤ 1000
Example:
30Offset used in the list / search method.
Example:
80The total number of items that matches the given criteria.
Example:
300Represents an html link.
Represents an html link.
Reports requested rdv_artifact_ids that do not exist under given version of reference data set
Possible values: contains only unique items
Represents an html link.
Represents an html link.
List of reference data values
Status Code
The reference data value(s) details have been retrieved successfully.
Unauthorized
The reference data set or value with given id does not exist.
Internal Server Error
{ "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "values": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_columns_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "parent": { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] }, "parent_hierarchy": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ], "child": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ] }, "terms": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "single_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "multi_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] } } ] }
Remove or update reference data values for the specified reference data set
Remove or update reference data values for the specified reference data set
PATCH /v4/reference_data_sets/{artifact_id}/versions/{version_id}/valuesRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Valid Json-patch body with either delete or replace operations.
Note: Precision will be lost if long value has more than 15-16 digits as JSON parser will map to double type regardless of whether it is used for integer, long or floating-point numbers. To Preserve all digits pass the value as a string.
Specifies behavior when deleted reference data value has children. Options are:
- root - make them root values
- immediate_parent - move them to the parent of deleted value
- other_value - move them to specified value
Allowable values: [
root,immediate_parent,other_value]Operation to be performed
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Target reference data value (to become parent for children of deleted one) artifact id (note: it has to "belong" to same reference data set as deleted value
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
b4610037-3a7c-4e4e-9e7e-4d2c03f4f75b
Response
Create, update or delete multiple RDVs response for Reference Data Set Api V4
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4Reference data values
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
The reference data value(s) have been added and/or updated and/or deleted successfully.
Bad Request
Unauthorized
Reference data value with given code already exists.
Internal Server Error
{ "values": [ { "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_column_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "code": "example", "value": "string", "description": "This is an RDS Value example", "revision": "0", "parent_value_artifact_id": "4a236376-6426-423f-82ba-b02201e82238", "artifact_id": "4a236376-6426-423f-82ba-b02201e8223b" } ], "href": "string", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Add reference data value to the specified reference data set
Add reference data value to the specified reference data set
POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/valuesRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Schema for creating single Reference Data Value in Reference Data Set - API V4
Code of reference data value.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
INDList of custom column values
Description
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Country code for IndiaArtifact id of parent reference data value
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
e599caea-afea-424b-9cbf-00a72864a557Value of reference data value
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
India
Response
Create, update or delete multiple RDVs response for Reference Data Set Api V4
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4Reference data values
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
The reference data value(s) have been added successfully.
Bad Request
Unauthorized
Reference data value with given composite key already exists.
Internal Server Error
{ "value": { "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_column_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "code": "example", "value": "string", "description": "This is an RDS Value example", "revision": "0", "parent_value_artifact_id": "4a236376-6426-423f-82ba-b02201e82238", "artifact_id": "4a236376-6426-423f-82ba-b02201e8223b" }, "href": "string", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Add or update reference data values for the specified reference data set
Add or update reference data values for the specified reference data set
PUT /v4/reference_data_sets/{artifact_id}/versions/{version_id}/valuesRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Schema for list with new Reference Data Value Entities for Reference Data Set Api V4
Reference data values
Response
Create, update or delete multiple RDVs response for Reference Data Set Api V4
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4Reference data values
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
The reference data values have been added and/or updated successfully.
The reference data value(s) have been added successfully.
Bad Request
Unauthorized
Reference data value with given composite key already exists.
Internal Server Error
{ "values": [ { "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_column_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "code": "example", "value": "string", "description": "This is an RDS Value example", "revision": "0", "parent_value_artifact_id": "4a236376-6426-423f-82ba-b02201e82238", "artifact_id": "4a236376-6426-423f-82ba-b02201e8223b" } ], "href": "string", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }{ "values": [ { "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_column_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "code": "example", "value": "string", "description": "This is an RDS Value example", "revision": "0", "parent_value_artifact_id": "4a236376-6426-423f-82ba-b02201e82238", "artifact_id": "4a236376-6426-423f-82ba-b02201e8223b" } ], "href": "string", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Exports values of a specified reference data set with specified artifact_id and version_id to a csv file
Exports values of a specified reference data set with specified artifact_id and version_id to a csv file
Only Code, Value and Composite Key columns will be exported by default, use parameters to export additional properties.
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/exportRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0
Query Parameters
Export reference data values code and composite key only. Note: If composite key is not defined, only code will be exported.
Default:
falseExport reference data value description.
Default:
falseComma-separated list of custom column definition artifact ids. Use
allto export all custom column definition values.Possible values: 36 ≤ length ≤ 5120, Value must match regular expression
(^all$|(([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})(,([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}))*))Example:
aa0e33f5-3108-4d45-a530-0307458362d4,3b5da5ed-8049-423f-848a-3844a6d88ff8Export reference data value parent.
Default:
falseComma-separated list of relationship types for reference data value.
Available types: termsvalue_mappingsAllowable values: [
terms,value_mappings]Export additional column representing reference data physical key (code + composite key values), columns are delimited with '|'.
Default:
false
Delete the reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id
Delete the reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id. If the reference data set is published then a workflow will be started with a draft created from which the value will be deleted. If the artifact is a draft copy then the value from the draft copy will be removed.
DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact id of reference data value.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Specifies behavior when deleted reference data value has children. Options are:
- root - make them root values
- immediate_parent - move them to the parent of deleted value
- other_value - move them to specified value (you have to specify it in target_value_artifact_id parameter)
Allowable values: [
immediate_parent,root,other_value]Target reference data value (to become parent for children of deleted one) artifact id (note: it has to "belong" to same reference data set as deleted value
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Glossary artifact data
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4The global ID of the parent category of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6The artifact ID of the parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a667-0307458362d4The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
The reference data value has been deleted successfully.
Bad Request
Unauthorized
The reference data set or value with given id does not exist.
The reference data value is currently used in catalog assets, catalog asset columns, data governance rules or data governance policies.
Internal Server Error
{ "href": "/v4/reference_data_sets/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids
Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids
GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact id of reference data value.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
Fetch custom column values for reference data set values.
Comma-separated list of relationship types for reference data value.
Available types: termsparent_hierarchychildsingle_value_mappingsmulti_value_mappingsvalue_mappingsAllowable values: [
terms,parent_hierarchy,child,single_value_mappings,multi_value_mappings,value_mappings]Fetch parent reference data details for reference data set values.
The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.
Possible values: 1 ≤ value ≤ 200
Default:
10
Response
V4 API Reference data value details
Artifact ID
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
498ce3d1-4321-44eb-a381-d74c7c34c95bPresents a paginated list of Reference Data Value children
Code
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
GERValues of custom columns being part of composite key
Values of custom columns not being part of composite key
Description
Possible values: 1 ≤ length ≤ 8000, Value must match regular expression
.*Example:
European CountryIndicates if reference data value has at least one child
Presents a paginated list of Reference Data Value relationships
List of parent reference data values in hierarchical order
Parent Artifact ID
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
e28f5002-b16e-4f82-b434-e070636c9aeeRevision, must be provided for reference data value modification
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Example:
0Presents a paginated list of Reference Data Value relationships
Presents a paginated list of Reference Data Value relationships
Value
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
.*Example:
GermanyPresents a paginated list of Reference Data Value relationships
Status Code
The reference data value(s) details have been retrieved successfully.
Unauthorized
The reference data set or value with given id does not exist.
Internal Server Error
{ "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_columns_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "parent": { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] }, "parent_hierarchy": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ], "child": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "code": "0011", "description": "Forestry, Fishing and Hunting", "value": "Agriculture", "parent_value_artifact_id": "9622cd91-838c-5cb7-8fce-e7f0407d0440", "has_children": true, "revision": "0", "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ] } ] }, "terms": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "single_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "multi_value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] }, "value_mappings": { "offset": 90, "last": { "href": "string", "offset": 270 }, "prev": { "href": "string", "offset": 60 }, "set_uri": true, "limit": 30, "count": 300, "first": { "href": "string", "offset": 0 }, "next": { "href": "string", "offset": 120 }, "relationships": [ { "metadata": { "artifact_type": "glossary_term", "artifact_id": "d109503d-06c3-46b2-b1e7-95482a143d0a", "version_id": "58cfecc6-7182-4665-9dc5-4f030238c106_0", "source_repository_id": "867907bd-4c80-458d-9e75-c5683e013533", "source_repository_name": "repository name", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_d109503d-06c3-46b2-b1e7-95482a143d0a", "workflow_id": "d3a36017-f4b3-4488-b49c-85b08fdce499", "draft_ancestor_id": "971798d5-7d11-4b4f-833c-f1dbac63b126", "effective_start_date": "2021-07-26T12:37:03.919Z", "effective_end_date": "2021-07-29T10:37:03.919Z", "created_by": "IBMid-1234567ABC", "created_at": "2017-02-15T02:30:32.000Z", "modified_by": "IBMid-1234567ABC", "modified_at": "2017-02-15T02:30:32.000Z", "revision": "0", "name": "artifact name", "state": "PUBLISHED", "tags": [ "tag1", "tag2" ], "steward_ids": [ "IBMid-1234567ABC" ], "workflow_state": "DRAFT", "read_only": false, "remove_start_date": false, "remove_end_date": false }, "entity": { "target_id": "6d5b4c71-18f5-416f-bb4f-4929d2d48c4f", "additional_info": { "rds_id": "1a4db093-9305-433b-bc22-ca2373131acc", "rds_value": "{string}", "rds_version_id": "ac0543b3-4fd6-4480-8885-64471811ee1e", "rds_value_description": "string" }, "source_id": "b710c60f-4c29-5f48-bb99-431aad664cc3", "relationship_type": "is_multi_mapped_to, is_single_mapped_to, is_child_of", "source_type": "reference_data_value", "target_type": "reference_data_value", "reference_copy": false } } ] } }
Update reference data value in the specified reference data set
Update reference data value in the specified reference data set
To remove parent RDV please specify: "parent_value_artifact_id": null.
PATCH /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact id of reference data value.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.
Schema for updating single Reference Data Value in Reference Data Set - API V4
List of custom column values
Description
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
Country code for IndiaArtifact id of parent reference data value
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
e599caea-afea-424b-9cbf-00a72864a557The revision of the artifact. It is used for optimistic locking.
Possible values: 1 ≤ length ≤ 20, Value must match regular expression
\d*Example:
1Value of reference data value
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
India
Response
Create, update or delete multiple RDVs response for Reference Data Set Api V4
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4Reference data values
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
The reference data value has been updated successfully.
Bad Request
Unauthorized
Reference data value with given composite key already exists.
Internal Server Error
{ "value": { "composite_key_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "custom_column_values": [ { "id": "c10eb10f-3ab7-4307-a791-bfd10efe0aa3", "value": "custom column value" } ], "code": "example", "value": "string", "description": "This is an RDS Value example", "revision": "0", "parent_value_artifact_id": "4a236376-6426-423f-82ba-b02201e82238", "artifact_id": "4a236376-6426-423f-82ba-b02201e8223b" }, "href": "string", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Creates relationships for reference data value
Creates relationships for reference data value
POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}/value_relationshipsRequest
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact id of reference data value.
Possible values: 1 ≤ length ≤ 255, Value must match regular expression
.*Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.
Reference Data Value relationships request object used in request payload to create RDV relationships
{
"child": [
"1f492a25-b3c2-5d73-b0c0-a6133d985bb"
],
"multi_value_mappings": [
{
"rds_artifact_id": "990e33f5-3108-4d45-a530-0307458362d4",
"rdv_artifact_ids": [
"4fb86a70-7035-4b3e-8825-137c7b9b1687"
]
}
],
"single_value_mappings": [
{
"rds_artifact_id": "990e33f5-3108-4d45-a530-0307458362d4",
"rdv_artifact_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687"
}
],
"terms": [
{
"id": "1f492a25-b3c2-5d73-b0c0-a6133d985bb3"
}
]
}The artifact id to other reference data values as child.
Possible values: Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})(,([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}))*Examples:[ "1fea0a80-98ec-4c13-968b-cebd0ba94726", "5aa0508c-6301-4cd2-8570-78d584fc275e" ]The relationships to other reference data values as multi value mapping.
Artifact id of target reference data value
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The relationship to other reference data value as single value mapping.
The relationships to business terms.
Response
V4 response for Create Value Relationships request
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4The global ID of the parent category of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6The artifact ID of the parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a667-0307458362d4List of Reference Data Values with relationships.
The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
Relationships created for reference data value
Bad Request
Unauthorized
Relationships conflicting for reference data set
Internal Server Error
{ "value_relationships": [ { "artifact_id": "1f492a25-b3c2-5d73-b0c0-a6133d985bb3", "terms": [ { "relationship_id": "d5e5ba23-ee69-47f1-beb3-b09d29374455", "target_id": "6a8f8630-5cff-4c42-a8f9-1f24371ad80c" } ], "child": [ "1f492a25-b3c2-5d73-b0c0-a6133d985bb5" ] } ], "href": "string", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Delete the relationship associated to reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id
Delete the relationship associated to reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id
DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}/value_relationships/{relationship_id}Request
Path Parameters
The artifact id of the reference data set.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).
Possible values: 6 ≤ length ≤ 40, Value must match regular expression
^(([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?|CURRENT|PUBLISHED|ACTIVE)$Example:
990e33f5-3108-4d45-a530-0307458362d4_0The artifact id of reference data value.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4The artifact ID of the relationship to be deleted.
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
aa0e33f5-3108-4d45-a530-0307458362d4
Query Parameters
If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.
Response
Glossary artifact data
The ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4The type of the artifact
Possible values: [
category,glossary_term,classification,data_class,reference_data,policy,rule]Example:
data_classThe global ID of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6Resource url
Possible values: 1 ≤ length ≤ 2048, Value must match regular expression
.*Example:
/v3/glossary_terms/990e33f5-3108-4d45-a530-0307458362d4The global ID of the parent category of the artifact
Possible values: length = 73, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})_([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})Example:
867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6The artifact ID of the parent category
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a667-0307458362d4The version ID of the artifact
Possible values: 36 ≤ length ≤ 40, Value must match regular expression
([a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})(_[0-9]{1,4})?Example:
4fb86a70-7035-4b3e-8825-137c7b9b1687_1The workflow ID of the artifact
Possible values: length = 36, Value must match regular expression
([A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12})Example:
990e33f5-3108-4d45-a530-0307458362d4
Status Code
Deleted the relationship
Bad Request
Unauthorized
relationship not found
Internal Server Error
{ "href": "/v4/reference_data_sets/0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6/versions/4fb86a70-7035-4b3e-8825-137c7b9b1687", "artifact_id": "0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "version_id": "4fb86a70-7035-4b3e-8825-137c7b9b1687", "workflow_id": "56b82aa1-0f3c-4e2c-84bf-bee619c84c7f", "global_id": "867907bd-4c80-458d-9e75-c5683e013533_0da59a9d-3a5a-4e1d-aa0c-e67ac8bfbbb6", "entity_type": "reference_data" }
Get list of jobs under a project or a space.
Lists the jobs in the specified project or space (either project_id or space_id must be set).
GET /v2/jobs
Request
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Optionally get all jobs associated with a particular asset.
Optionally get all jobs associated with the particular asset ref type.
The ID of the job run. Can be used to search parent job of a job run
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Default:
100The optional 'next' field from the response in string format, can be used to get the next batch. The response can contain up to 200 results in a batch, if there are more results, a 'next' field is returned in the response which can be used to get the next batch.
Response
Example:
204Array of all jobs.
Status Code
Success.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Create a new job.
Creates a new job in the specified project or space (either project_id or space_id must be set).
POST /v2/jobs
Request
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
The job to be created. Note: either asset_ref or asset_ref_type must be provided, not both.
- job
The name of the job
Example:
NameID of associated asset to run (provide either asset_ref or asset_ref_type).
Example:
ff1ab70b-0553-409a-93f9-ccc31471c218The type of asset to run (provide either asset_ref or asset_ref_type).
Example:
notebookThe description of the job.
Example:
Description.A cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 0 1 * *- schedule_info
Indicate a repeated job
Example:
trueA timestamp in epoch time, the scheduled job will be triggered after this timestamp.
Example:
1547578689512A timestamp in epoch time, the scheduled job will be triggered before this timestamp.
Example:
1547578689512
A globally unique attribute to be used in place of the job id when sending calls. Must be a combination of lowercase alphanumeric and underscore characters, and must be between 1 and 36 characters.
Example:
my_job_1_2_3- retention_policy
Array of job parameters.
Array of parameter sets.
Response
AssetMetadata Model
The underlying job definition.
Status Code
Created.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Get the information of job identified by the ID.
Gets the info for a single job associated from the specified project or space (either project_id or space_id must be set).
GET /v2/jobs/{job_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Response
AssetMetadata Model
The underlying job definition.
Status Code
Success.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Delete a specific job.
Deletes a specific job in a project or space (either project_id or space_id must be set). If the deletion of the job and its runs will take some time to finish, then a 202 response will be returned and the deletion will continue asynchronously. All the jobs runs associated with the job will also be deleted. If the job is still running, it will not be deleted.
DELETE /v2/jobs/{job_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Response
Status Code
The requested operation completed successfully.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Update information of a job.
Updates specific attributes of a job in the specified project or space (either project_id or space_id must be set). You must specify the updates by using the JSON patch format, described in RFC 6902.
PATCH /v2/jobs/{job_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Updates to make to the job run.
The operation to be performed. Allowable values: [add, replace].
Example:
replaceA JSON pointer to the field to update. Allowable field paths to be updated. Ex /metadata/name or /entity/job/configuration
Example:
/metadata/name (or /entity/job/configuration)
Response
AssetMetadata Model
The underlying job definition.
Status Code
Success.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Get the availability of a given serving_name
Gets the availability of a given serving_name, as serving_name must be globally unique. serving_name must be a combination of alphanumeric and underscore characters, and must be between 1 and 36 characters.
GET /v2/jobs/serving_name/{serving_name}Get list of runs of a job.
Lists the job runs for a specific job in the specified project or space (either project_id or space_id must be set). Only the metadata and certain elements of the entity component of each run are returned.
GET /v2/jobs/{job_id}/runsRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
The optional 'next' field from the response in string format, can be used to get the next batch. The response can contain up to 200 results in a batch, if there are more results, a 'next' field is returned in the response which can be used to get the next batch.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Default:
100A list of comma-separated job run states. Availble values: Completed, Failed, Canceled, Starting, Running, Queued, Canceling, Paused, Resuming, CompletedWithWarnings, CompletedWithErrors
Allowable values: [
Queued,Starting,Running,Paused,Resuming,Canceling,Canceled,Failed,Completed,CompletedWithErrors,CompletedWithWarnings]
Start a run for a job.
Starts the specified job contained in a project or space (either project_id or space_id must be set).
POST /v2/jobs/{job_id}/runsRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
The configuration of the job run to use. If not provided, use the configuration of the associated job.
- job_run
The name of the job run
Example:
NameThe description of the job run
Example:
Description- configuration
The environment variables, only for Notebook and Script jobs.
Examples:[ "key1=value1", "key2=value2" ]
Array of job parameters.
Array of parameter sets.
Response
AssetJobRunMetadata Model
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Get a specific run of a job.
Gets the info for a single job run from the specified project or space (either project_id or space_id must be set).
GET /v2/jobs/{job_id}/runs/{run_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Delete a run.
Delete the specified job run in a project or space (either project_id or space_id must be set).
DELETE /v2/jobs/{job_id}/runs/{run_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Response
Status Code
The requested operation is in progress.
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Retrieve runtime log of a run.
Gets the logs for a job run in the specified project or space (either project_id or space_id must be set)
GET /v2/jobs/{job_id}/runs/{run_id}/logsRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
The limit of the number of lines to return, for example limit=50. If not specified, all log will be returned.
Response
Response of get job run log
Array of log string split by line
Examples:[ "Size: 28 Blocks: 0 IO Block: 4096 directory", "Device: 3000eeh/3145966d Inode: 453833649 Links: 3", "Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root)", "Access: 2019-04-08 19:12:21.930122905 +0000", "Modify: 2019-04-08 19:12:21.932122894 +0000", "Change: 2019-04-08 19:12:21.932122894 +0000", "DONE" ]Total number of lines available
Example:
100
Status Code
Success.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Cancel a run.
Cancels a job run that is in the running state.
POST /v2/jobs/{job_id}/runs/{run_id}/cancelRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
An empty body.
Example: {}
Response
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Pause a run.
Pauses a job run that is in the running state.
POST /v2/jobs/{job_id}/runs/{run_id}/pauseRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
An empty body.
Example: {}
Response
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Resume a run.
Resumes a job run that is in the paused state.
POST /v2/jobs/{job_id}/runs/{run_id}/resumeRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
An empty body.
Example: {}
Response
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Gets the status of assigning terms to the asset
Returns the high level status of the assignments made between a Model in a Catalog, e.g. a Logical Data Model, and Business Terms, including the total number of assignments to be done. The process may still be in progress and in that case a summary of how many assignments have been added will be returned
GET /v1/knowledge_accelerators/asset_assign_terms/status/{process_id}Request
Path Parameters
The process id returned by the corresponding POST endpoint.
Possible values: 30 ≤ length ≤ 40
curl -k -X GET 'https://{cpd_cluster_host}/v1/knowledge_accelerators/asset_assign_terms/status/{process_id}' -H 'accept: application/json' -H 'Authorization: Bearer {token}'
Response
Information related to an Asynchronous endpoint
A unique process id for an Asynchronous endpoint
The type of process (or action) performed by the endpoint
Possible values: [
asset_assign_terms]The current status of progress of the action being performed by the endpoint
The id of the tenant
The user name
Start time
End time
The parameters supplied by the user
Log messages
Possible values: 0 ≤ number of items ≤ 50
Status Code
Success
Bad Request
Unauthorized
Forbidden
Not found
{"status":"in_progress","process_id":"119b2ce9-3fff-4adb-ab8b-2c1a259daf50","process_type":"asset_assign_terms","tenant_id":"f8ddad357e47454eb562484f2f2f3c34","user_name":"myname@mydomain.com","start_time":"2023-11-08T09:34:56.171328500","input_params":{"strategy":"industrymodel_ldm","asset_id":"30ba5f82-13fb-4e68-977d-01a1f4e4fc58","category_ids":[],"ldm_type":"bfmdw_awm","term_matching_method":"id","catalog_id":"e955a953-d57c-4d18-b2d3-220e24e2201a"},"log_messages":[{"level":"INFO","message":"Getting entities and attributes for the logical model named Atomic Warehouse Model"}]}
Assigns terms to the asset using the specified strategy, for example industrymodels_ldm
For the Model in the Catalog specified by the user, this endpoint adds assignments between the Entities and Attributes in the model and the Business Terms that are supported by the assignments strategy.
POST /v1/knowledge_accelerators/asset_assign_terms
Request
imput parameters in JSON format in Request body
The id of the catalog that contains the asset that we want to assign business terms to. You must provide either a Catalog Id or Project Id but not more than one
Possible values: 30 ≤ length ≤ 40
The term assignment strategy to apply on the asset
Allowable values: [
industrymodel_ldm]Default:
industrymodel_ldmThe id of the asset in the catalog, for which to assign Business Terms
Possible values: 10 ≤ length ≤ 40
Default:
LDM-in-Catalog-if-only-one-in-CatalogAn Array containing a comma separated list of the ids of the categories from which to source the Business Terms to map the asset to. This will automatically include the sub-categories of the category supplied and by extension their terms
Possible values: 0 ≤ number of items ≤ 30, 30 ≤ length ≤ 40
The type of Industry Model Logical Model stored assignments to utilise for doing entity/column name to term assignments
Allowable values: [
bfmdw_awm,bfmdw_dwm,iiw_bdm,iiw_awm,iiw_dwm,udmh_bdm,udmh_awm,udmh_dwm,dmeu_bdm,dmeu_awm,dmeu_dwm]Default:
bfmdw_awmThe term matching method, artifact_id (id) is only supported
Allowable values: [
name,id]Default:
id
Response
Response information related adding assignment between LDM entities and attributes and Knowledge Accelerator business terms.
A summary message of the assignment status
A URI for checking the status of the process process
A process id for checking the assignment status
Status Code
Accepted
Bad Request
Unauthorized
Forbidden
Not found
Not found
{"message":"The Business Term assignment on the asset has been submitted, check below process for update state","process_href":"/v1/knowledge_accelerators/asset_assign_terms/status/019b2ce9-3fff-4adb-ab8b-2c1a259daf50","process_id":"019b2ce9-3fff-4adb-ab8b-2c1a259daf50"}
Copy Knowledge Accelerator items into project
Copy the specified Knowledge Accelerator items into specified IKC project.
POST /v1/knowledge_accelerators/{ka_id}/copy_itemsRequest
Path Parameters
The Knowledge Accelerator id
Possible values: 4 ≤ length ≤ 7
Query Parameters
A comma separated list of the item ids of the Knowledge Accelerator to copy.
Possible values: 2 ≤ length ≤ 200
The id of the project where the items are copied to
Possible values: 10 ≤ length ≤ 100
curl -k -X POST 'https://{cpd_cluster_host}/v1/knowledge_accelerators/{ka_id}/copy_items?ids={ids}&project_id={project_id}' -H 'accept: application/json' -H 'Authorization: Bearer {token}' -d ''
Response
Response information related to copying Knowledge Accelerator items into a project.
A summary message of the copy status
The Knowledge Accelerator URI of the items to be copied
A copy status for a specific Knowledge Accelerator.
Possible values: 0 ≤ number of items ≤ 20
Status Code
Success
Bad Request
Unauthorized
Not found
{"message":"The copy has been executed, please check details below for status","knowledge_accelerator":"https://api.dataplatform.cloud.ibm.com/v1/knowledge_accelerators/kaeu20","items":[{"item_id":"base","data_assets":[{"name":"kaeu20-base-2.0.20230726.zip","url":"https://api.dataplatform.cloud.ibm.com/v2/data_assets/b43ddf6d-bb52-4df2-9d55-c7713a2bbadd?project_id=e304ce63-8e2a-4597-8251-0876d20c2a24","status":"copied"}]}]}
Get a specific Knowledge Accelerator
Supply a Knowledge Accelerator id, in order to get detailed information, including contained items that can be imported, statistics and dependencies
GET /v1/knowledge_accelerators/{id}Request
Path Parameters
The Knowledge Accelerator id
Possible values: 4 ≤ length ≤ 7
curl -k -X GET 'https://{cpd_cluster_host}/v1/knowledge_accelerators/{ka_id}' -H 'accept: application/json' -H 'Authorization: Bearer {token}'
Response
A KAArtifact can represent a Knowledge Accelerator or a Knowledge Accelerator item. A knowledge accelerator can contain many knowledge accelerator items, which can be for example, many sub parts of a large IKC glossary. A knowledge accelerator item can depend on other items.
The identifier of the knowledge accelerator, or the knowledge accelerator item
The name of this knowledge accelerator item
The definition that helps describe the content within the knowledge accelerator item
The type of the knowledge accelerator item. If the item is of type glossary, then the type of the glossary will further be indicated, for example "glossary_iav" (Glossary that is of type, Industry Alignment Vocabulary)
The format of the content that is stored in this knowledge accelerator item
The version of the tool or service that the format is compatible with
The version of this knowledge accelerator item. Typically this will only change if the underlying content has changed. If the knowledge accelerator is at a certain version, it would be expected that there would be at least one knowledge accelerator item at that same version
The definition that might optionally accompany this new version of the content, which would summarise the main changes from prior version.
Holds statistics for the knowledge accelerator or item. If in existence for an item, then it will contain at least 1 statistic, for example count of categories.
If a knowledge accelerator item is depended on by another item, then this property indicates if it should be considered mandatory. Default value is false.
A knowledge accelerator can contain 1 or more items. Also in theory a knowledge accelerator item itself, can contain other items and so on
Possible values: 0 ≤ number of items ≤ 30
If an item depends on one or more items within the same knowledge accelerator, this holds those item ids
Possible values: 0 ≤ number of items ≤ 10
If an item is derived from one or more items within the same knowledge accelerator, this holds those item ids
Possible values: 0 ≤ number of items ≤ 10
Status Code
Success
Unauthorized
Not found
{"id":"kaeu20","name":"Knowledge Accelerators","definition":"A category that ..etc.","type":"knowledge_accelerator","format":"wkc_glossary","version":"2.0.20231004","stats":{"terms":11425,"categories":502,"policy":57,"rule":30,"reference_data":297,"reference_data_value":2292,"data_class":284}}
Import specified Knowledge Accelerator items into the glossary
Import the specified Knowledge Accelerator items into glossary. By default this will import all dependent items
POST /v1/knowledge_accelerators/{ka_id}/import_itemsRequest
Path Parameters
The Knowledge Accelerator id
Possible values: 4 ≤ length ≤ 7
Query Parameters
The ids of the Knowledge Accelerator items to import, for example 'base'. Use the comma delimiter when listing multiple item ids, for example 'ccpa,gdpr'. Only one item allowed if item is of type glossary_scope
Possible values: 2 ≤ length ≤ 200
The merge option to be used when importing into the glossary, valid values:
all - imported values will replace existing values in catalog
specified - imported values that are not empty replace existing values in catalog
empty - imported values replace only empty values in catalogPossible values: 3 ≤ length ≤ 12
Indicates which dependencies of the item ids specified should also be imported, valid values:
all - imports the specified items that the user selects, imports all the items that the selected item depends on, irrespective of whether they already exist in glossary (Note, this may overwrite user made changes in the glossary).
necessary - imports specified items that the user selects, imports items that are considered mandatory for the specified item, and imports other related items the specified items depend on that are not already imported.
mandatory - imports the specified items that the user selects, and items that are considered mandatory for the specified item.Possible values: 3 ≤ length ≤ 12
Default:
necessaryIndicates whether the import should be done, valid values:
false - will do all the logic checking and indicate what is going to be imported, useful for checking in advance of actually doing the import
true - at the end of logic checking will trigger the import and return a process id to the userDefault:
false
curl -k -X POST 'https://{cpd_cluster_host}/v1/knowledge_accelerators/{ka_id}/import_items?ids={ids}&merge_option={merge_option}&dependencies={dependencies}&do_import={do_import}' -H 'accept: application/json' -H 'Authorization: Bearer {token}' -d ''
Response
An import response holds information related to an attempted or dry run of import of Knowledge Accelerator content. In a dry run scenario there will be no process id, as the import was not actually triggered.
A summary message of the import status
A URI for checking the status of the import process
An import evaluation for a specific Knowledge Accelerator.
Status Code
Accepted
Bad Request
Unauthorized
Not found
{"message":"The import has been submitted. To check the status ...","process_id":"b3ae3db2-6da1-447d-aaf7-4dde46dcbd1d","import_evaluation":{"knowledge_accelerator":"kain20","items":[{"id":"base","evaluation":"import","reason":"user_selected"}]}}
Get what Knowledge Accelerator items are currently imported into glossary
Information on what Knowledge Accelerator items are imported into glossary if any; this will include information as to whether imported version is current
GET /v1/knowledge_accelerators/import_items
Request
No Request Parameters
curl -k -X GET 'https://{cpd_cluster_host}/v1/knowledge_accelerators/import_items' -H 'accept: application/json' -H 'Authorization: Bearer {token}'
Response
Represents information as to what Knowledge Accelerators and associated items are installed in the IKC glossary.
A summary message of the import status
An import evaluation for a specific Knowledge Accelerator.
Possible values: 0 ≤ number of items ≤ 20
Status Code
Success
Unauthorized
{"message":"KA008I: The following knowledge accelerator items are imported","import_evaluation":[{"knowledge_accelerator":"kain20","items":[{"id":"base","evaluation":"imported"}]}]}
Get all Knowledge Accelerators
Detailed information on each Knowledge Accelerator, including contained items that can be imported, statistics and dependencies
GET /v1/knowledge_accelerators
Request
No Request Parameters
curl -k -X GET 'https://{cpd_cluster_host}/v1/knowledge_accelerators' -H 'accept: application/json' -H 'Authorization: Bearer {token}'
Response
A listing of the Knowledge Accelerators
A count of the Knowledge Accelerators that are available
A listing of the Knowledge Accelerators and their contained items that are available for importing into the IKC glossary
Possible values: 0 ≤ number of items ≤ 40
Status Code
Success
Unauthorized
{"count":1,"knowledge_accelerators":[{"id":"kahc20","name":"Knowledge Accelerator for Healthcare","definition":"IBM Knowledge Accelerator for ...etc..","type":"knowledge_accelerator","format":"wkc_glossary","version":"2.0.20230726","stats":{"terms":22385,"categories":1071,"policy":32,"rule":10,"reference_data":1169,"reference_data_value":22624,"data_class":208}}]}
retrieve a governanceType
Retrieves detailed information on a governance type. This includes all of the operations defined for the governance type and the allowed and default outcomes of each operation.
GET /v3/enforcement/governance_types/{governance_type_name}Response
Response for the /v3/enforcement/governance_types/{governanceTypeId} API
metadata object for policy API responses that have no metadata
entity object within the response for the /v3/enforcement/governance_types/{governanceTypeId} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
create user defined left hand side term
Create a left hand side term to be used in rules defined in the policy engine.
POST /v3/enforcement/lhs/udp
Request
LHS RuleTerm JSON
Name of the custom LHS.
Display name of the custom LHS.
Property name of the LHS references. For Asset properties, use the path of the property in asset json. For user property, use the name of the mapped User SCIM attribute. (Custom user predicates are not supported in CPDaaS).
Source for the LHS reference. For custom asset predicate, use 'ASSET'. For custom user predicate use 'CONTEXTUAL' (Custom user predicates are not supported in CPDaaS).
Allowable values: [
ASSET, CONTEXTUAL]Description of the custom LHS.
Response
Response for the /v3/enforcement/udp/{termName} API
metadata object used in responses returned from policy management related APIs
entity object within the response for the /v3/enforcement/udp/{termName} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
get a user defined left hand side term
Get the user defined left hand side term in the term cache of the policy engine.
GET /v3/enforcement/lhs/udp/{lhsTermId}Response
Response for the /v3/enforcement/udp/{termName} API
metadata object used in responses returned from policy management related APIs
entity object within the response for the /v3/enforcement/udp/{termName} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
delete a user defined left hand side term
Delete a left hand side term in the term cache of the policy engine. This cache is maintained for performance and is used for evaluating policies. It is refreshed periodically from technical terms maintained in the glossary.
DELETE /v3/enforcement/lhs/udp/{lhsTermId}retrieve and aggregate policy related metrics
This API retrieves policy enforcement metrics based on query parameters, which include metric type, date range, policy, user, rule, governanceType, outcome, host type, cached, context operation, context location, asset type and asset location. It then sums these metrics according to a specified aggregation type.
GET /v3/enforcement/policy_metrics/analysis/3d
Request
Query Parameters
The type of metrics to return
Allowable values: [
enforcements,denials,operational_policies,operational_rules]The type of aggregation to perform on the selected metrics (days, months, years, policies, rules, users, governanceTypes, outcomes)
Allowable values: [
days,months,years,policies,rules,users,outcomes,governance_type,pep_host_types,is_pep_cache,context_operations,context_locations,asset_types,asset_locations]The type of aggregation to perform on the selected metrics (days, months, years, policies, rules, users, governanceTypes, outcomes)
Allowable values: [
days,months,years,policies,rules,users,outcomes,governance_type,pep_host_types,is_pep_cache,context_operations,context_locations,asset_types,asset_locations]ISO 8601 date/time specifying the starting time to return metrics data
ISO 8601 date/time specifying the ending time to return metrics data
The policy to return metrics of, or all policies if not specified
The rule to return metrics of, or all rules if not specified
The user to return metrics about, or all users if not specified
The governanceType to return metrics about, or all governanceTypes if not specified
Allowable values: [
Access,Classification,Curation,Lifecycle,ResourceControl,DMR,AIGovernance,DLR]The enforcement outcome to return metrics about, or all outcomes if not specified
The PEP host type to return metrics about, or all PEP host types if not specified
Metrics on decisions retrieved from cache versus from server, or both if not specified
The context operation to return metrics about, or all context operations if not specified
The context location to return metrics about, or all context locations if not specified
The asset type to return metrics about, or all asset types if not specified
The asset location to return metrics about, or all asset locations if not specified
The order to sort the metrics. The following values are allowed:
- aggregate, -aggregate -- ascending or descending order by the aggregate
- count, -count -- ascending or descending order by enforcement count
retrieve and aggregate policy related metrics
This API retrieves policy enforcement metrics based on query parameters, which include metric type, date range, policy, user, rule, governanceType, outcome, host type, cached, context operation, context location, asset type and asset location. It then sums these metrics according to a specified aggregation type.
GET /v3/enforcement/policy_metrics
Request
Query Parameters
The type of metrics to return
Allowable values: [
enforcements,denials,operational_policies,operational_rules]The type of aggregation to perform on the selected metrics (days, months, years, policies, rules, users, governanceTypes, outcomes)
Allowable values: [
days,months,years,policies,rules,users,outcomes,governance_type,pep_host_types,is_pep_cache,context_operations,context_locations,asset_types,asset_locations]ISO 8601 date/time specifying the starting time to return metrics data
ISO 8601 date/time specifying the ending time to return metrics data
The policy to return metrics of, or all policies if not specified
The rule to return metrics of, or all rules if not specified
The user to return metrics about, or all users if not specified
The governanceType to return metrics about, or all governanceTypes if not specified
Allowable values: [
Access,Classification,Curation,Lifecycle,ResourceControl,DMR,AIGovernance,DLR]The enforcement outcome to return metrics about, or all outcomes if not specified
The PEP host type to return metrics about, or all PEP host types if not specified
Metrics on decisions retrieved from cache versus from server, or both if not specified
The context operation to return metrics about, or all context operations if not specified
The context location to return metrics about, or all context locations if not specified
The asset type to return metrics about, or all asset types if not specified
The asset location to return metrics about, or all asset locations if not specified
The order to sort the metrics. The following values are allowed:
- aggregate, -aggregate -- ascending or descending order by the aggregate
- count, -count -- ascending or descending order by enforcement count
create a custom role
Creates a cusotm role. This will include a list of existing permissions to be associated with the role. Maximum length allowed for 'name' parameter: 80 characters, maximum length allowed for 'description' parameter: 1000 characters. Allowed characters for the 'name' parameter: letters from any language, numbers in any script, space, dot, underscore, hyphen. Strings with characters other than these are rejected (only for the name parameter).
POST /v3/enforcement/roles
update a custom category role
Updates a custom category role. This API is also used to add and remove permissions from the custom category role. The permissions should be passed as an array of string that has permissions ids.Maximum length allowed for 'name' parameter: 80 characters, maximum length allowed for 'description' parameter: 1000 characters. If the parameter 'name' is modified, allowed characters for the 'name' parameter: letters from any language, numbers in any script, space, dot, underscore, hyphen. Strings with characters other than these are rejected (only for the name parameter).
PUT /v3/enforcement/roles/{role_id}Sync a rule
Syncs a rule in DPS with its global search index. If rule is found in DPS, its global search index is updated. If rule is not found in DPS, its global search index is removed.
PUT /v3/enforcement/rules/sync/{rule_id}Response
Response for the /v3/enforcement/rules/{ruleId} API
metadata object used in responses returned from policy management related APIs
entity within the response for the /v3/enforcement/rules/{ruleId} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
retrieve a rule
Retrieves detailed information on a rule given the rule's identifier.
GET /v3/enforcement/rules/{rule_id}Response
Response for the /v3/enforcement/rules/{ruleId} API
metadata object used in responses returned from policy management related APIs
entity within the response for the /v3/enforcement/rules/{ruleId} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
update a rule
Updates a rule. Maximum length allowed for 'name' parameter: 80 characters, maximum length allowed for 'description' parameter: 1000 characters. If the parameter 'name' is modified, allowed characters for the 'name' parameter: letters from any language, numbers in any script, space, dot, underscore, hyphen. Strings with characters other than these are rejected (only for the name parameter). The governance_type_id cannot be modified.
PUT /v3/enforcement/rules/{rule_id}Request
Path Parameters
Rule ID
Rule json
the displayed name for the rule
the name of a governance type of this rule
nested arrays representing an expression that is evaluated to determine if the action on the rule should be performed or enforced. See the description on the POST /v3/enforcement/rules for more details.
the action to perform or enforce when the rule triggers
a more detailed description of the rule
the state of the rule. Only the rules of policies in active are enforced.
Allowable values: [
draft,active,archived]
Response
Response for the /v3/enforcement/rules/{ruleId} API
metadata object used in responses returned from policy management related APIs
entity within the response for the /v3/enforcement/rules/{ruleId} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
list all rules
Lists all defined rules. This includes all rules associated with policies and rules not associated with any policy. When more than one filter criteria is specified, the resulting collection satisfies all the criteria.
GET /v3/enforcement/rules
Request
Query Parameters
Specify name of the rule to search for or use filter of the form 'contains:xx' to search for rules containing provided phrase as part of name or use filter of the form 'exact:xx' to search for rules with exact name.
Specify description of the rule to search for or use filter of the form 'contains:xx' to search for rules containing provided phrase as part of description.
If specified, only rules with a matching trigger expression will be returned.
If specified, only rules with a matching action will be returned.
If specified, only rules in the matching state will be returned.
Allowable values: [
draft,active,archived]If speficied, only rules with the matching governance type/types will be returned.
The order to sort the rules. The following values are allowed:
- name, -name -- ascending or descending order by the name
- modified_date, -modified_date -- ascending or descending order by modified date
Allowable values: [
name,-name,modified_date,-modified_date]The maximum number of Rules to return. The default value is 50.
Default:
50The index of the first matching Rule to include in the result. The default value is 0.
Default:
0
Response
Response for the /v3/enforcement/rules API
the limit as specified on the query or defaulted
the offset as specified on the query or the default value 0
total number of resources in the collection
link to the previous page of resources, if available
link to the previous page of resources, if available
link to the previous page of resources, if available
link to the previous page of resources, if available
list of rules
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
create a rule
Creates a rule. A rule has two key properties:
- a trigger defining when the rule should be enforced, and
- an action describing what operations to perform or outcome to enforce.
Trigger
A trigger is a boolean expression represented using nested arrays. The following describes the syntax:
Expression:
[ -conditions- ]
Conditions:
-predicate-
"NOT", -predicate-
-predicate-, "AND"|"OR", -conditions-
"NOT", -predicate-, "AND"|"OR", -conditions-
Predicate:
[ "$-term-", "EXISTS" ]
[ "$-term-", "EQUALS"|"LESS_THAN"|"GREATER_THAN"|"CONTAINS", "#-literal-"|"$-term-" ]
-expression-
where:
- -term- is a technical term defined in the term glossary.
- -literal- is a literal. For numerics a string representation of the number should be specified. For times, milliseconds are used (from Unix epoch). For boolean, #true and #false are used.
The definition of the operators in a predicate:
- EXISTS -- means that the term has a value of some kind.
- EQUALS -- evaluates to true if the left and right sides are equal.
- LESS_THAN -- evaluates to true if the left is less in numeric value than the right.
- GREATER_THAN -- evaluates to true if the left is greater in numeric value than the right.
- CONTAINS -- is meant to test an array term (such as Asset.Tags) with a single value. It evaluates to true if the value on the right side equals one of the values on the array on the left side.
However it will also supports a single value on the left, in which case it behaves just like EQUALS -- regular expressions or wildcards are not supported.
For all of the operators (except EXISTS), if the right hand side evaluates to an array, each value of the array is compared to the left side, according to the operator definition, and if any comparison is true then the result of the evaluation is true.
Examples:
[["$Asset.Type", "EQUALS", "#Project"]]
["NOT", ["$Asset.Tags", "CONTAINS", "#sensitive"], "AND", ["NOT", "$Asset.Tags", "CONTAINS", "#confidential"]]
[["$User.Name", "EQUALS", "$Asset.Owner"]]
Action
The action is an name with optional parameters or subaction describing an operation to perform. For simple actions like Deny, only the action name will be provided. For actions such as Transform, a subaction with parameters describing the type of transform is also provided. The allowed actions depends on the governance type.
Examples:
{"name": "Deny"}
{"name": "Transform", "subaction": {"name": "anonymizeColumns", "parameters": [{"name": "column_name", "value": "CCN"}]}}
The maximum length allowed for 'name' parameter is 80 characters, maximum length allowed for 'description' parameter: 1000 characters. Allowed characters for the 'name' parameter: letters from any language, numbers in any script, space, dot, underscore, hyphen. Strings with characters other than these are rejected (only for the name parameter).
POST /v3/enforcement/rules
Request
Rule json
the displayed name for the rule
the name of a governance type of this rule
nested arrays representing an expression that is evaluated to determine if the action on the rule should be performed or enforced. See the description on the POST /v3/enforcement/rules for more details.
the action to perform or enforce when the rule triggers
a more detailed description of the rule
the state of the rule. Only the rules of policies in active are enforced.
Allowable values: [
draft,active,archived]
Response
Response for the /v3/enforcement/rules/{ruleId} API
metadata object used in responses returned from policy management related APIs
entity within the response for the /v3/enforcement/rules/{ruleId} API
Status Code
Merged with an existing 'ResourceControl' rule.
Created
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
export all rules
Export all defined rules as JSON.This includes all rules associated with policies and rules not associated with any policy.
GET /v3/enforcement/rules/export
Request
Query Parameters
The maximum number of Rules to return. The default value is 50.
Default:
50The index of the first matching Rule to include in the result. The default value is 0.
Default:
0For export between two different systems. If specified as true, the ids in rules will be converted to names and added as export_components in the exported file
Default:
false
import rules
Imports rules using content recieved as application/octet-stream media type. Assumes content to be in UTF-8 charset. Expects "rules" JSON array contained in a JSON objects. Ignores other fields. Rule GUID is prerserved. Retruns JSON array containing GUIDs of newly imported rules.
POST /v3/enforcement/rules/import
Request
Query Parameters
For import between two different systems. If specified as true, the names in export_components of the import file will be matched and converted to the target system's ids.
Default:
falseFor external imports, if specified as true, the whole import will fail if there are any rules that fail to match ids in the target system. If specified as false, an analysis report will be returned.
Default:
false
The input stream for reading imported terms
Response
Response for the /v3/enforcement/rules/export API and /v3/enforcement/rules/import
List containing details of rules that are successfully imported.
List containing details of rules that are failed to import.
List containing details of rules that are successfully matched.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Content cannot be more than 1MB
Internal Server Error
No Sample Response
retrieve tenant settings
Retrieves governance information and settings about a particular tenant given the tenant identifier.
GET /v3/enforcement/settings
Response
Response for the /v3/enforcement/settings/{tenantId} API
metadata object used in responses returned from policy management related APIs
entity object within the response for the /v3/enforcement/settings/{tenantId} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
update tenant settings
Updates governance information and settings for the given tenant.
PUT /v3/enforcement/settings
Request
governedTenant json
Data protection rules convention. Choose DEAA for 'Locked' convention and AEAD for 'Unlocked' convention.
Allowable values: [
DEAA, AEAD]Data location rules convention. Choose DEAA for 'Locked' convention and AEAD for 'Unlocked' convention.
Allowable values: [
DEAA, AEAD]Default sovereignty to assign to assets if sovereignty is missing in data assets.
Enable data location rules enforcement.
Oldest - by creation date, Latest - by modified date, columns, Merge - merge annotations (terms and tags) of all aliases
Allowable values: [
Oldest, Latest, Merge]The rule action precedence for data protection rules. The actions, in order of leniency, are: Allow access, Mask and Filter, Deny access.
Allowable values: [
RESTRICTIVE, PERMISSIVE, HIERARCHICAL]The rule action precedence for data location rules. The actions, in order of leniency, are: Allow access, Mask and Filter, Deny access.
Allowable values: [
RESTRICTIVE, PERMISSIVE]The masking method precedence for data protection rules. The masking methods, in privacy order, are: Redact, Substitute, Obfuscate. The masking methods, in utility order, are: Obfuscate, Substitute, Redact.
Allowable values: [
RESTRICTIVE, PERMISSIVE]The masking method precedence for data location rules. The masking methods, in privacy order, are: Redact, Substitute, Obfuscate. The masking methods, in utility order, are: Obfuscate, Substitute, Redact.
Allowable values: [
RESTRICTIVE, PERMISSIVE]enable/disable business glossary terms inheritance for DPR/DLR enforcement
enable/disable dataclass terms inheritance for DPR/DLR enforcement
enable/disable classification terms inheritance for DPR/DLR enforcement
enable/disable business glossary term 1 level synonym relationship for DPR/DLR enforcement
Enable evaluation based on asset's lineage
This flag indicates if transform deep enforcement process using 'advanced' or 'classic'. The default value is advanced.
Allowable values: [
advanced, classic]Maximum combined number of DPR and DLR rules supported.
Enable/disable audit log for evaluation
Allowable values: [
false]
Response
Response for the /v3/enforcement/settings/{tenantId} API
metadata object used in responses returned from policy management related APIs
entity object within the response for the /v3/enforcement/settings/{tenantId} API
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
List projects
Returns a list of projects filtered by the specified query parameters. By default, only projects that the authenticated user is a member of are returned. In IBM Cloud Pak for Data (CPD), all projects in the cluster are returned (regardless of project membership) if the authenticated user is assigned either the "Manage projects" or "Monitor project workloads" CPD permission. In IBM Cloud Pak for Data (CPDaaS), all projects associated with an IBM Cloud Account are returned (regardless of project membership) if the authenticated user is added to the IBM Cloud Account and assigned the IAM "Manager" role.
GET /v2/projects
Request
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Query Parameters
The BSS Account ID.
Possible values: Value must match regular expression
^[0-9a-f]{32}$Example:
0821fa9f9ebcc7b7c9a0d6e9bfa72aa4The project type.
Allowable values: [
cpd,wx,wca,dpx,wxbi]A project member to use to filter the query results.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.comA list of comma-separated project roles to use to filter the query results. Must be used in conjunction with the "member" query parameter.
Allowable values: [
admin,editor,viewer]Default:
[]A list of comma-separated tags to use to filter the query results. If multiple tags are specified, the query results will be filtered to show projects matching any of the tags. (e.g. tag1 OR tag2 OR... tagN).
Example:
development,test,productionA full or partial project name to use to filter the query results. This query parameter must be used in conjunction with the 'bss_account_id' query parameter. Use the 'match' query parameter to control they type of text matching performed. Project names are not unique and should not be used in place of project IDs.
Possible values: 1 ≤ length ≤ 100
Example:
Sentiment AnalysisThe type of text matching to perform. This query parameter must be used in conjunction with the 'name' query parameter. The 'exact' value will match projects if the specified text matches the exact project name. The 'keyword' value will match projects if the specified text matches any keyword parsed from the project name.
Allowable values: [
exact,keyword]Default:
exactA list of comma-separated project IDs to use to filter the query results. This query parameter only works in conjunction with the 'member' query parameter.
Example:
d122ffba-de9e-4c67-89c4-0091f1610076,deb5b1d8-5fd4-486c-92ef-12e90959dbf1A list of comma-separated project metadata sections to include in the query results.
Allowable values: [
name,fields,members,tags,settings,everything,nothing]Default:
["fields"]The limit used to specify the maximum number of projects returned in the query results. Used for pagination in conjunction with the "bookmark" query parameter.
Possible values: 0 ≤ value ≤ 100
Default:
10The bookmark is an opaque key returned in the query results set that serves as a reference to the next page of query results. Specify the bookmark on subsquent query requests to retrieve the next page of query results. Used for pagination in conjunction with the "limit" query parameter.
Possible values: Value must match regular expression
^[0-9A-Za-z_-]{1,1000}$Example:
g1AAAAE6eJzLYWBgYMlgTmHQTElKzi9KdUhJMtdLytVNTtYtLdYtzi8tydA1MNVLzskvTUnMK9HLSy3JAWphSnIAkkn-____z8pgcrP_afo-ASiQyIhqlAlRRoF0JuXDjPrBf0cBZBQzGa7KYwGSDAeAFNC082DjvnclHgAZx4RqnAXxxl2AGHcfxaNMWQBvIGVgDeprecated. Use of this query parameter exhibits poor performance characteristics. Use the more efficient "bookmark" query parameter instead. The offset to use to define the starting index of projects to return in the query results. Used for pagination in conjunction with the "limit" query parameter.
Possible values: value ≥ 0
Default:
0
Response
A list of projects.
The total number of project returned in the query results.
Possible values: value ≥ 0
Example:
1The bookmark is an opaque key returned in the query results set that serves as a reference to the next page of query results.
Possible values: Value must match regular expression
^[0-9A-Za-z_-]{1,1000}$Example:
g1AAAAE6eJzLYWBgYMlgTmHQTElKzi9KdUhJMtdLytVNTtYtLdYtzi8tydA1MNVLzskvTUnMK9HLSy3JAWphSnIAkkn-____z8pgcrP_afo-ASiQyIhqlAlRRoF0JuXDjPrBf0cBZBQzGa7KYwGSDAeAFNC082DjvnclHgAZx4RqnAXxxl2AGHcfxaNMWQBvIGVgA list of projects returned in the query results.
Status Code
OK
Unauthorized
Forbidden
Too Many Requests
{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 61. Limit: 60. Category: query. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Get project total
Returns the total number of projects associated with the authenticated user in a BSS account. In IBM Cloud Pak for Data (CPDaaS), specifying the BSS account ID is required. In IBM Cloud Pak for Data (CPD), specifying the BSS account ID is optional. Default is "999". The maximum total number of projects returned will be capped at 2,000 projects (for database performance reasons).
GET /v2/projects/total
Request
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Query Parameters
The BSS Account ID.
Possible values: Value must match regular expression
^[0-9a-f]{32}$Example:
0821fa9f9ebcc7b7c9a0d6e9bfa72aa4The project type.
Allowable values: [
cpd,wx,wca,dpx,wxbi]A project member to use to filter the query results.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.comA list of comma-separated tags to use to filter the query results. If multiple tags are specified, the query results will be filtered to show projects matching any of the tags. (e.g. tag1 OR tag2 OR... tagN).
Example:
development,test,production
Response
The project total.
The project total.
Possible values: value ≥ 0
Example:
10
Status Code
OK
Bad Request
Unauthorized
Forbidden
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
A list of comma-separated project metadata sections to include in the query results.
Allowable values: [
name,fields,members,tags,settings,integrations,storage,credentials,everything,nothing]Default:
["fields"]
Response
A project object.
The metadata containing information about the project.
- metadata
The project ID represented as a version 4 UUID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The project URL.
Example:
/v2/projects/46a19524-bfbf-4810-a1f0-b131f12bc773The date and time the project was created in UTC (ISO 8601)
Example:
2019-03-05T23:15:36.175ZThe date and time the project was last updated in UTC (ISO 8601)
Example:
2019-10-02T19:26:49.684Z
The entity payload representing the core project attributes.
- entity
The name of the project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote ("), percentage sign (%)
Possible values: 1 ≤ length ≤ 100
Example:
Project NameA description for the new project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote (")
Possible values: 0 ≤ length ≤ 1000
Example:
A project description.The project type. The "cpd" project type is used to classify IBM Cloud Pak for Data (CPD) projects. The "wx" project type is used to classify IBM watsonx projects. The "wca" project type is used to classify IBM watsonx Code Assistant projects. The "dpx" project type is used to classify IBM Data Product Exchange projects. The "wxbi" project type is used to classify IBM watsonx BI Assistant projects.
Possible values: [
cpd,wx,wca,dpx,wxbi]A value of "true" makes the project public.
The username of the user that created the project.
Example:
zapp.brannigan@ibm.comThe IAM ID of the user that created the project.
Example:
IBMid-55000353XFThe project scope definition.
A list of tags associated with the project.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$The storage associated with the project.
A catalog associated with the project.
A list of computes associated with the project.
The GitHub repository associated with the project.
The project settings.
The members associated with the project.
The tools associated with the project.
Possible values: [
jupyter_notebooks,watson_visual_recognition,dashboards,streams_designer,spss_modeler,experiments,data_refinery]
Status Code
OK
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Update project
Partially updates the project with only a subset of properties.
PATCH /v2/projects/{project_id}Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
The request body for updating an existing project.
The name of the project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote ("), percentage sign (%)
Possible values: 1 ≤ length ≤ 100
Example:
Project NameA description for the new project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote (")
Possible values: 0 ≤ length ≤ 1000
Example:
A project description.The project type. The "cpd" project type is used to classify IBM Cloud Pak for Data (CPD) projects. The "wx" project type is used to classify IBM watsonx projects. The "wca" project type is used to classify IBM watsonx Code Assistant projects. The "dpx" project type is used to classify IBM Data Product Exchange projects. The "wxbi" project type is used to classify IBM watsonx BI Assistant projects.
Allowable values: [
cpd,wx,wca,dpx,wxbi]A value of "true" makes the project public.
Default:
falseA catalog associated with the project.
A list of computes associated with the project.
The tools associated with the project.
Allowable values: [
jupyter_notebooks,watson_visual_recognition,dashboards,streams_designer,spss_modeler,experiments,data_refinery]The GitHub repository associated with the project.
Response
A project object.
The metadata containing information about the project.
- metadata
The project ID represented as a version 4 UUID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The project URL.
Example:
/v2/projects/46a19524-bfbf-4810-a1f0-b131f12bc773The date and time the project was created in UTC (ISO 8601)
Example:
2019-03-05T23:15:36.175ZThe date and time the project was last updated in UTC (ISO 8601)
Example:
2019-10-02T19:26:49.684Z
The entity payload representing the core project attributes.
- entity
The name of the project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote ("), percentage sign (%)
Possible values: 1 ≤ length ≤ 100
Example:
Project NameA description for the new project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote (")
Possible values: 0 ≤ length ≤ 1000
Example:
A project description.The project type. The "cpd" project type is used to classify IBM Cloud Pak for Data (CPD) projects. The "wx" project type is used to classify IBM watsonx projects. The "wca" project type is used to classify IBM watsonx Code Assistant projects. The "dpx" project type is used to classify IBM Data Product Exchange projects. The "wxbi" project type is used to classify IBM watsonx BI Assistant projects.
Possible values: [
cpd,wx,wca,dpx,wxbi]A value of "true" makes the project public.
The username of the user that created the project.
Example:
zapp.brannigan@ibm.comThe IAM ID of the user that created the project.
Example:
IBMid-55000353XFThe project scope definition.
A list of tags associated with the project.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$The storage associated with the project.
A catalog associated with the project.
A list of computes associated with the project.
The GitHub repository associated with the project.
The project settings.
The members associated with the project.
The tools associated with the project.
Possible values: [
jupyter_notebooks,watson_visual_recognition,dashboards,streams_designer,spss_modeler,experiments,data_refinery]
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
A list of comma-separated project roles to use to filter the query results.
Allowable values: [
admin,editor,viewer]Default:
[]A list of comma-separated usernames corresponding to project members that are used to filter the query results.
Possible values: 1 ≤ length ≤ 100
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Create members
Adds new project members with the provided roles. A project must always have at least one admin.
POST /v2/projects/{project_id}/membersRequest
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
A list of project members.
A list of project members.
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Delete members
Deletes members from the project that match the provided usernames.
DELETE /v2/projects/{project_id}/membersRequest
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
A list of comma-separated usernames corresponding to project members to remove from the project.
Possible values: 1 ≤ length ≤ 100
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
The request body for updating project members.
A list of project members to update.
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Get member
Returns the project member with the specified 'user_name' if any.
GET /v2/projects/{project_id}/members/{user_name}Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The username of the project member.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.com
Query Parameters
A flag indicating whether to return a derived project member based on resolving user groups.
Default:
true
Response
A project member.
The username of the project member. If the member type is "service" or "group", then the "user_name" and "id" fields must match.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.comThe IAM ID of the project member. This field is required for project members with the "ACTIVE" state.
Possible values: 1 ≤ length ≤ 100, Value must match regular expression
^[0-9a-zA-Z-]$Example:
IBMid-55000353XFThe role of the project member.
Possible values: [
admin,editor,viewer]Example:
adminThe state of the project member. This field is only supported for members of type "user".
Possible values: [
ACTIVE,PENDING]The project member type.
Possible values: [
user,group,service]A flag indicating whether the project member is derived from a resolved user group.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Delete member
Deletes a member with a given user name from a project with the given username.
DELETE /v2/projects/{project_id}/members/{user_name}Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The username of the project member.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.com
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Response
A list of tags associated with the project.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
A tag associated with the project. The tag cannot contain a comma (,). The tag cannot contain any of the following characters unless escaped by character entities - left angle bracket (<)(<), right angle bracket (>)(>), single-quote (')('), double quote (")("), ampersand (&)(&).
Response
A list of tags associated with the project.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "422", "error": "Unprocessable Entity", "reason": "The number of projects created by the authenticated user exceeds the designated limit. Projects created by user (101) > Projects per user limit (100).", "message": "The request was well-formed but was unable to be followed due to semantic errors.", "id": "WSCPA0001E" }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Delete tags
Delete existing tags in a project. If no 'tag_names' are specified, then delete all existing tags in a project.
DELETE /v2/projects/{project_id}/tagsRequest
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
A list of comma-separated tags to use to filter the query results. If multiple tags are specified, the query results will be filtered to show projects matching any of the tags. (e.g. tag1 OR tag2 OR... tagN).
Example:
development,test,production
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Update tags
Adds new tags and removes existing tags from a project via a single bulk update operation.
PATCH /v2/projects/{project_id}/tagsRequest
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
An operation to add or remove project tags.
[
{
"op": "add",
"tags": [
"development",
"test"
]
},
{
"op": "remove",
"tags": [
"production"
]
}
]The tag operation.
Allowable values: [
add,remove]Example:
addA list of tags associated with the project.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$
Response
A list of tags associated with the project.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "422", "error": "Unprocessable Entity", "reason": "The number of projects created by the authenticated user exceeds the designated limit. Projects created by user (101) > Projects per user limit (100).", "message": "The request was well-formed but was unable to be followed due to semantic errors.", "id": "WSCPA0001E" }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The tag name.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$Example:
development
Response
A list of tags associated with the project.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "422", "error": "Unprocessable Entity", "reason": "The number of projects created by the authenticated user exceeds the designated limit. Projects created by user (101) > Projects per user limit (100).", "message": "The request was well-formed but was unable to be followed due to semantic errors.", "id": "WSCPA0001E" }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The tag name.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$Example:
development
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Response
The folders settings group.
The enablement flag for the folders feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
The folders settings group.
The enablement flag for the folders feature.
Response
The folders settings group.
The enablement flag for the folders feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Create project as a transaction
Creates a new project with the provided parameters, including all the storage and credentials in a single transaction. This endpoint will create a new COS bucket using generated unique name, all credentials, asset container and call all the required atomic APIs to fully configure a new project. Attempts to use the duplicate project names will result in an error. NOTE: when creating projects programmatically, always use this endpoint, not /v2/projects.
This endpoint can also be used to create a project from an exported Watson Studio .zip file. In this case, a new transaction is initiated to create assets under the project. A Transaction ID along with a URL is returned as a response of this API. As this transaction can take time, you can view the current status of the transaction using the returned URL.
NOTE: This feature is only available in the private cloud.
POST /transactional/v2/projects
Request
Custom Headers
Allowable values: [
application/json,multipart/form-data]
Query Parameters
If enabled, the transaction fails if the project name is not unique.
Default:
true
Project metadata required to create a project.
The name of the new project. The name must be a non-empty String. This does not need to be unique.
Example:
Project NameA tag to indicate where this project was generated. This is only intended for use in metrics. It does not need to be unique and all consumers of this API should use a consistent string for their 'generator' field. The value is stored in the project metadata for future consumption in metrics.
Example:
DAP-ProjectsObject storage properties to be associated with the project.
A description for the new project.
Example:
A project description.The project type. The "cpd" project type is used to classify IBM Cloud Pak for Data (CPD) projects. The "wx" project type is used to classify IBM watsonx projects. The "wca" project type is used to classify IBM watsonx Code Assistant projects. The "dpx" project type is used to classify IBM Data Product Exchange projects. The "wxbi" project type is used to classify IBM watsonx BI Assistant projects.
Allowable values: [
cpd,wx,wca,dpx,wxbi]Default:
cpdA value of
truemakes the project public.Default:
falseList of user defined tags that are attached to the project.
Set to true of project members should be scoped to the account and/or SAML of the creator
Default:
falseList of computes to be associated with the project.
List of tools to be associated with the project.
Allowable values: [
watson_visual_recognition,jupyter_notebooks,dashboards,streams_designer,spss_modeler,experiments,data_refinery]
Response
Description of create transactional project API response body.
API to access the newly created project.
Status Code
Created
Accepted
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "location": "/v2/projects/b2549f22-7565-4193-9434-9b77e15757cc" }{ "location": "/v2/projects/b2549f22-7565-4193-9434-9b77e15757cc", "transaction_detail": { "id": "dcff12a9-3f9e-4d10-b4c4-f121f681d81b", "links": { "self": "/transactional/v2/projects/b2549f22-7565-4193-9434-9b77e15757cc/transactions/dcff12a9-3f9e-4d10-b4c4-f121f681d81b" } } }{ "code": "400", "error": "Bad Request", "reason": "Error fetching projects. Status code: 400", "message": "The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax).", "description": "[400] Bad Request: Error fetching projects. Status code: 400. The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax)." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed.", "description": "[401] Unauthorized: Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Invalid bearer token: Access token is invalid.", "message": "The target operation is strictly forbidden due to schema constraints.", "description": "[403] Forbidden: Invalid bearer token: Access token is invalid. The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "Resource requested by the client was not found.", "description": "[404] Not Found: Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76. Resource requested by the client was not found." }{ "code": "500", "error": "Internal Server Error", "reason": "Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "The API encountered an unexpected condition which prevented it from fulfilling the request.", "description": "[500] Internal Server Error: Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76." }
Delete project as a transaction
Deletes a project with a given ID, deletes COS bucket and all the files in it, all credentials and asset container in the order reverse from the project creation transaction. When deleting projects programmatically, always use this endpoint, not /v2/projects/{project_id}.
DELETE /transactional/v2/projects/{project_id}Request
Path Parameters
The ID of the project to be deleted.
Example:
6ee2c24f-d0a9-4e30-b0fc-5ae36a66c1a8
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "code": "400", "error": "Bad Request", "reason": "Error fetching projects. Status code: 400", "message": "The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax).", "description": "[400] Bad Request: Error fetching projects. Status code: 400. The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax)." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed.", "description": "[401] Unauthorized: Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Invalid bearer token: Access token is invalid.", "message": "The target operation is strictly forbidden due to schema constraints.", "description": "[403] Forbidden: Invalid bearer token: Access token is invalid. The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "Resource requested by the client was not found.", "description": "[404] Not Found: Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76. Resource requested by the client was not found." }{ "code": "500", "error": "Internal Server Error", "reason": "Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "The API encountered an unexpected condition which prevented it from fulfilling the request.", "description": "[500] Internal Server Error: Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76." }
Get status of import transaction
Status of import transaction created using create project as a transaction API
GET /transactional/v2/projects/{project_id}/transactions/{transaction_id}Request
Path Parameters
The ID of the project on which transaction was created.
Example:
6ee2c24f-d0a9-4e30-b0fc-5ae36a66c1a8The transaction ID provided by create project as a transaction endpoint.
Example:
dcff12a9-3f9e-4d10-b4c4-f121f681d81b
Response
Description of import transactional status API response.
Project GUID.
Name of the project.
The date and time the status was created in UTC (ISO 8601)
The date and time the status was last updated in UTC (ISO 8601)
Last known status of the transaction
Description of the last know transaction status
Description of all last know import status.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "code": "400", "error": "Bad Request", "reason": "Error fetching projects. Status code: 400", "message": "The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax).", "description": "[400] Bad Request: Error fetching projects. Status code: 400. The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax)." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed.", "description": "[401] Unauthorized: Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Invalid bearer token: Access token is invalid.", "message": "The target operation is strictly forbidden due to schema constraints.", "description": "[403] Forbidden: Invalid bearer token: Access token is invalid. The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "Resource requested by the client was not found.", "description": "[404] Not Found: Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76. Resource requested by the client was not found." }{ "code": "500", "error": "Internal Server Error", "reason": "Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "The API encountered an unexpected condition which prevented it from fulfilling the request.", "description": "[500] Internal Server Error: Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76." }
Request
Query Parameters
Return results starting at this offset
Allowable values: [
range[0, 2147483647]]Maximum number of results
Allowable values: [
range[1, 2147483647]]Only return workflows related to the artifact with the given artifact id
Default:
Only return workflows related to the artifact with the given version id
Default:
Only return workflows started by the given user id (only administrators can query for users other than themselves)
Default:
Only return workflows from the given workflow type id(s)
Maximum number of artifacts to include in the result
Default:
10Include variables in the result
Default:
falseInclude user tasks in the result
Default:
falseOnly return user tasks assigned to the given user_id (only administrators can specify a different id than their own), requires include_user_tasks=true
Default:
Include start form properties in the results
Default:
falseReturn active workflows
Default:
trueReturn completed workflows
Default:
false
Request
Query Parameters
Return results starting at this offset
Allowable values: [
range[0, 2147483647]]Maximum number of results
Allowable values: [
range[1, 2147483647]]Maximum number of artifacts to include in the result
Default:
10Include variables in the results
Default:
falseInclude user tasks in the results
Default:
falseOnly return user tasks assigned to the given user_id (only administrators can specify a different id than their own), requires include_user_tasks=true
Default:
Include start form properties in the results
Default:
false
Query conditions
Request
Custom Headers
Allowable values: [
application/hal+json,application/json]
Path Parameters
The workflow id
Query Parameters
Maximum number of artifacts to include in the result
Default:
10Include variables in the result
Default:
falseInclude user tasks in the result
Default:
falseOnly return user tasks assigned to the given user_id (only administrators can specify a different id than their own), requires include_user_tasks=true
Default:
Include start form properties in the result
Default:
false
Get all user tasks that involve the current user
Administrators can see all tasks
GET /v3/workflow_user_tasks
Request
Query Parameters
Return results starting at this offset
Allowable values: [
range[0, 2147483647]]Maximum number of results
Allowable values: [
range[1, 2147483647]]specify the ordering of returning resources. it can contain any one of the valid sort fields or a combination of these fields. prepend a field with a '+' or '-' character to indicate ascending or descending, if neither of '+' or '-' are provided, ascending is used. e.g. 'field1', '-field1', or '+field1,-field2'.
Valid sort fields are 'created_at', 'due_date' and 'completed_at'.
Default:
created_atOnly return tasks assigned to the given user ID (only administrators can specify IDs different from their own)
Default:
Only return tasks not assigned to any user ID (only administrators may specify this filter parameter)
Default:
falseInclude completed tasks
Default:
falseOnly return tasks with the given status (only applies when 'completed' is set to false)
Allowable values: [
created, assigned]Only return tasks with the given urgency (only applies when 'completed' is set to false)
Allowable values: [
overdue, due_soon, due_later]Only return tasks from the given workflow type id(s)
Default:
[]Only return tasks of the given task categories
Default:
[]Only return tasks related to the artifact with the given artifact id
Default:
Only return tasks related to the artifact with the given version id
Default:
Only return tasks due before the given date, e.g.: 1979-01-22T01:23:45.000Z
Hide authoring tasks
Default:
falseOnly return the total count
Default:
false
Request
Custom Headers
Allowable values: [
application/hal+json,application/json]
Query Parameters
Only return tasks from the given workflow type id(s)
Default:
[](May only be provided in combination with parameter 'process_variable_value'). See description of parameter 'process_variable_value'
(May only be provided in combination with parameter 'process_variable_name'). Only return tasks for which the given process variable has the given string as value
Hide authoring tasks
Default:
false