Manage asset READMEs¶
READMEs can only be added to assets after an asset exists. (The asset itself must be created first.)
README content is written in HTML
The content of a README needs to be HTML. The HTML should be everything that would be inside the <body></body>
tags, but not include the <body></body>
tags themselves. (So it should also exclude the outer <html></html>
tags.)
Add to an existing asset¶
Each README can be assigned to only a single asset. To create a README and assign it to an asset:
Add to an existing asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
- Pick up your HTML content from somewhere (here it is defined directly in the code).
- The README must be attached to some asset. You could either first search for or retrieve that asset, or build up a reference directly (as in this example).
- The asset you send to the README creation must have its name populated, not only its GUID or qualifiedName.
- Use the
creator()
method to initialize the README with all necessary attributes for creating it. - For a README, you need to send the asset to attach it to and the content for the README itself (the HTML).
- Call the
save()
method to actually create the README and attach it to the asset. Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include that single asset that was created (the README).
- The response will also include a single asset that was updated (the asset to which we've attached the README).
Add to an existing asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
- Pick up your HTML content from somewhere (here it is defined directly in the code).
- Use the
create()
method to initialize the README with all necessary attributes for creating it. - We need to give the asset to attach the README to.
- The content for the README itself (the HTML).
- The name of the asset to which we want to attach the README.
- Note: The name is only required because we are using the
ref_by_guid
method to create theAtlasGlossaryTerm
consequently it will not have a name. If we had an asset we had previosly retrieved via a search or using theasset.get_by_guid
method we could leave theasset_name
parameter out and the name from the givenasset
would be used.
- Note: The name is only required because we are using the
- Call the
save()
method to actually create the README and attach it to the asset. - Assert that the README was created.
- Assert a GlossaryTerm was updated (the asset to which we've attached the README).
Add to an existing asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
- Pick up your HTML content from somewhere (here it is defined directly in the code).
- The README must be attached to some asset. You could either first search for or retrieve that asset, or build up a reference directly (as in this example).
- The asset you send to the README creation must have its name populated, not only its GUID or qualifiedName.
- Use the
creator()
method to initialize the README with all necessary attributes for creating it. - For a README, you need to send the asset to attach it to and the content for the README itself (the HTML).
- Call the
save()
method to actually create the README and attach it to the asset. Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include that single asset that was created (the README).
- The response will also include a single asset that was updated (the asset to which we've attached the README).
Note that you are actually creating a new README asset
When adding a README through the API, you are really creating a new instance of a README asset. At the same time, you're attaching this new object to an existing asset.
POST /api/meta/entity/bulk | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
- All assets must be wrapped in an
entities
array. - You must provide the exact type name for the README asset, which will always be
Readme
(case-sensitive). - You must also provide a name for the README. This will not show up on the UI, but should be a concatenation of the name of the asset the README will be attached to and
Readme
. - You must also provide a unique
qualifiedName
for the README. This will not show up on the UI, but should be a concatenation of the GUID of the asset the README will be attached to and/readme
. -
The content of the README should be provided in the
description
field. Note that this must be HTML, which must further be url-encoded.Use a library
Most languages will provide a library to url-encode and url-decode strings. Use this, wherever possible. For an example of translating raw HTML into url-encoded form (or decoding an encoded form) you can also try urlencoder.org and urldecoder.org , respectively.
-
Finally, you need to include the reference information for the asset the README should be attached to.
Retrieve a README from an existing asset¶
To retrieve a README and its content for an existing asset:
Retrieve README's content from an existing asset | |
---|---|
1 2 3 4 5 6 7 8 |
|
- Store the qualified name of the asset (GlossaryTerm) connected to the README in the termQn variable.
- Configure the search to match the qualified name, include the README, and fetch its description.
- Extract and print the README's content.
Retrieve README's content from an existing asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
- Store the asset's qualified name in the term_qn variable.
- Filter by asset type, match the qualified name, include the README, and fetch its description.
- Extract and print the README's content.
Retrieve README's content from an existing asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
- Store the qualified name of the asset in the assetQualifiedName variable.
- Search for the asset, include the README, and fetch its description.
- Extract and print the README's content.
GET /api/meta/entity/bulk?guid=b4113341-251b-4adc-81fb-2420501c30e6 | |
---|---|
1 |
|
- When retrieving the README, you need to use the README's GUID, not the GUID of the asset to which it is attached.
Update a README attached to an existing asset¶
To update a README and its content for an existing asset:
Updating README's content | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
- Store the qualified name of the asset (GlossaryTerm) connected to the README in the termQn variable.
- Use Readme.updater() to update the README's description.
- Save the updated README. Because this operation will persist the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant.
Updating README's content | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
- Store the asset's qualified name in the term_qn variable.
- Use Readme.creator() to create a new README for the same asset (AtlasGlossaryTerm).
- Save the updated README.
Updating README's content | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
- Store the asset's qualified name in the assetQualifiedName variable.
- Use Readme.updater() to update the README's description.
- Save the updated README. Because this operation will persist the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant.
1 |
|
- REST API for updating a README is not available
Remove a README from an Existing Asset¶
To remove a README from an existing asset, delete the README itself. (A README is treated as a separate asset with its own GUID.)
To hard-delete (purge) a README, provide the README's GUID:
Hard-delete (purge) a README asset | |
---|---|
1 2 3 4 5 6 7 |
|
- Call the purge() method with the README's GUID to remove it permanently. Because this operation will persist the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - You can distinguish what was purged through the
getDeletedAssets()
method. This lists only the assets deleted by the operation. - If the deleted asset is a README, cast it to the Readme type.
Hard-delete (purge) a README asset | |
---|---|
1 2 3 4 5 6 7 |
|
- Use the asset.purge_by_guid() method with the README's GUID to perform the hard-delete.
- Use the assets_deleted(asset_type=Readme) method to filter for deleted READMEs.
- If a README was deleted, access its details through the returned response.
Hard-delete (purge) a README asset | |
---|---|
1 2 3 4 |
|
- Call the purge() method with the README's GUID to permanently remove. Because this operation will persist the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - You can distinguish what was purged through the
deletedAssets
method. This lists only the assets deleted by the operation. - Verify and cast the deleted asset to the README type
DELETE /api/meta/entity/bulk?guid=b4113341-251b-4adc-81fb-2420501c30e6&deleteType=PURGE | |
---|---|
1 |
|
- When deleting a README via the API, specify its GUID in the URL and use a deleteType of PURGE.
For more options on deleting README assets: Deleting an asset.
The README will have its own GUID, separate from the asset to which it is attached
When deleting the README, you need to use the README's GUID, not the GUID of the asset to which it is attached.