From 47023136c0b55731f091cea80bc99ba1ac6f12eb Mon Sep 17 00:00:00 2001 From: Isaac Seymour Date: Mon, 14 Aug 2023 15:04:56 +0100 Subject: [PATCH] Document how attribute relations & external IDs work --- docs/aliases-and-external-ids.md | 36 ++++++++++++++++++++++++++++++++ docs/outputs.md | 4 +++- 2 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 docs/aliases-and-external-ids.md diff --git a/docs/aliases-and-external-ids.md b/docs/aliases-and-external-ids.md new file mode 100644 index 0000000..bd03c17 --- /dev/null +++ b/docs/aliases-and-external-ids.md @@ -0,0 +1,36 @@ +# External IDs + +In your Catalog, entries have an ID, but they also have an external ID. The ID +is a unique reference in our system, generated automatically for each entry, +which cannot be set or changed. If you ever have something (say the +catalog-importer) sync an entry into a type with an external ID, we’ll interpret +that as the same entry as whatever already exists under that external ID. + +In practice, this means: +* You can change the name and any attributes: we attach these to either the + external ID or the ID of the entry (whichever is available) and any renames + will transparently apply to custom field values and anywhere else the entry + was used. +* If you happen to delete an entry but then try recreating it with the same + external ID, we’ll bring back the archived entry so you preserve any old + references such as incident custom field values. + +# Aliases + +The aliases are just about how you might reference a catalog entry via an +attribute on some other entry. + +Say you have a team catalog type with a “Slack group” attribute which is of type +“SlackUserGroup”. You could set that value of that attribute to either: +* The ID of the Slack user group catalog entry (e.g. 01H4GFQPTNGNF0FFEGX2BT8811) +* The external ID of the Slack user group catalog entry (e.g. S043VBNSBC3) +* Or any of the aliases (e.g. my-user-group-handle) + +Then when you view that team entry in the dashboard or try navigating to its +Slack group attribute, we’ll follow the above rules to find you the match. + +Aliases are *only* used for this matching, and nothing else, so: +* They don't show up when you're searching for a catalog entry, either in the + catalog or to assign it to a custom field +* They can't be edited via the Dashboard UI, only via the API, catalog-importer, + or Terraform. diff --git a/docs/outputs.md b/docs/outputs.md index 73b898f..2d7670b 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -69,7 +69,9 @@ The `source` config for the output: - And similar that `external_id` should come from the `external_id` field. It's worth reading our guide on [expressions](expressions.md) to understand the -syntax and what is possible in these fields. +syntax and what is possible in these fields, and our guide on [external IDs and +aliases](aliases-and-external-ids.md) to understand how these special fields +work. The Backstage API Type (the catalog type we're creating for this output) will be given a single attribute: