Skip to content

Add 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

1.4.0 1.0.0

Each README can be assigned to only a single asset. To create a README and assign it to an asset:

Managing READMEs for assets is currently not possible via dbt.

Add to an existing asset
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
final String readmeContent = "<h1>Overview</h1><p>Details about this term...</p>"; // (1)
GlossaryTerm term = GlossaryTerm.refByGuid("b4113341-251b-4adc-81fb-2420501c30e6")  // (2)
    .toBuilder()
    .name("Example Term")  // (3)
    .build();
Readme readme = Readme.creator( // (4)
        term, // (5)
        readmeContent)
    .build();
AssetMutationResponse response = readme.save(); // (6)
assert response.getCreatedAssets().size() == 1 // (7)
assert response.getUpdatedAssets().size() == 1 // (8)
  1. Pick up your HTML content from somewhere (here it is defined directly in the code).
  2. 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).
  3. The asset you send to the README creation must have its name populated, not only its GUID or qualifiedName.
  4. Use the creator() method to initialize the README with all necessary attributes for creating it.
  5. For a README, you need to send the asset to attach it to and the content for the README itself (the HTML).
  6. Call the save() method to actually create the README and attach it to the asset.
  7. The response will include that single asset that was created (the README).
  8. 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
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Readme, AtlasGlossaryTerm

client = AtlanClient()
content = "<h1>Overview</h1><p>More Details about this term...</p>"  # (1)
readme = Readme.create( # (2)
    asset=AtlasGlossaryTerm.ref_by_guid(guid="b4113341-251b-4adc-81fb-2420501c30e6"), # (3)
    content=content, # (4)
    asset_name="Example Term") # (5)
response = client.asset.save(readme) # (6)
assert (readmes := response.assets_created(asset_type=Readme)) # (7)
assert (glossaries := response.assets_updated(asset_type=AtlasGlossaryTerm)) # (8)
  1. Pick up your HTML content from somewhere (here it is defined directly in the code).
  2. Use the create() method to initialize the README with all necessary attributes for creating it.
  3. We need to give the asset to attach the README to.
  4. The content for the README itself (the HTML).
  5. 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 the AtlasGlossaryTerm consequently it will not have a name. If we had an asset we had previosly retrieved via a search or using the asset.get_by_guid method we could leave the asset_name parameter out and the name from the given asset would be used.
  6. Call the save() method to actually create the README and attach it to the asset.
  7. Assert that the README was created.
  8. 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
val readmeContent = "<h1>Overview</h1><p>Details about this term...</p>"  // (1)
val term = GlossaryTerm.refByGuid("b4113341-251b-4adc-81fb-2420501c30e6")  // (2)
    .toBuilder()
    .name("Example Term")  // (3)
    .build()
val readme = Readme.creator(  // (4)
        term,  // (5)
        readmeContent)
    .build()
val response = readme.save()  // (6)
assert(response.createdAssets.size == 1)  // (7)
assert(response.updatedAssets.size == 1)  // (8)
  1. Pick up your HTML content from somewhere (here it is defined directly in the code).
  2. 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).
  3. The asset you send to the README creation must have its name populated, not only its GUID or qualifiedName.
  4. Use the creator() method to initialize the README with all necessary attributes for creating it.
  5. For a README, you need to send the asset to attach it to and the content for the README itself (the HTML).
  6. Call the save() method to actually create the README and attach it to the asset.
  7. The response will include that single asset that was created (the README).
  8. 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
{
  "entities": [ // (1)
    {
      "typeName": "Readme", // (2)
      "attributes": {
        "name": "Example Term Readme", // (3)
        "qualifiedName": "900d7201-4dec-45bf-bbaf-ab5001093302/readme", // (4)
        "description": "%3Ch1%3EOverview%3C%2Fh1%3E%3Cp%3EDetails%20about%20this%20term...%3C%2Fp%3E", // (5)
        "asset": [ // (6)
          {
            "typeName": "AtlasGlossaryTerm",
            "guid": "b4113341-251b-4adc-81fb-2420501c30e6"
          }
        ]
      }
    }
  ]
}
  1. All assets must be wrapped in an entities array.
  2. You must provide the exact type name for the README asset, which will always be Readme (case-sensitive).
  3. 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.
  4. 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.

  5. 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.

  6. Finally, you need to include the reference information for the asset the README should be attached to.

Remove from an existing asset

To remove a README from an existing asset you only need to delete the README itself. (The README is itself an asset.)

See 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.