From 581aa9a9b6fe0228440926380fd8f38b5f316989 Mon Sep 17 00:00:00 2001
From: Aaron Sheah <aaronsheah@gmail.com>
Date: Wed, 15 Jan 2025 14:29:21 +0000
Subject: [PATCH] add documentation and examples to describe how the feature
 works

---
 docs/outputs.md              | 69 ++++++++++++++++++++++++++++++++++++
 docs/simple/catalog.jsonnet  |  3 ++
 docs/simple/importer.jsonnet | 12 +++++++
 3 files changed, 84 insertions(+)

diff --git a/docs/outputs.md b/docs/outputs.md
index dd2d37a..bc949d0 100644
--- a/docs/outputs.md
+++ b/docs/outputs.md
@@ -91,3 +91,72 @@ given a single attribute:
 For more information on how to use filter expressions, read [Using
 expressions](expressions.md) or look at the [Backstage](backstage) example for
 real-life use cases.
+
+### Enum attribute
+
+Enums are useful when you have an attribute of 'String' type (both array and non-array), that you'd like to have as as separate catalog type, such as tags. Using the above example of `BackstageAPIType`, we can instead generate it from `BackstageAPI`
+
+```jsonnet
+{
+  sync_id: 'example-org/example-repo',
+  pipelines: [
+    // Backstage API
+    {
+      sources: [
+        {
+          inline: {
+            entries: [
+              {
+                name: "Payments API",
+                external_id: "payments"
+                type: "grpc",
+              }
+            ],
+          },
+        },
+      ],
+      outputs: [
+        {
+          name: 'Backstage API',
+          description: 'APIs that we have',
+          type_name: 'Custom["BackstageAPI"]',
+          source: {
+            name: 'name',
+            external_id: 'external_id',
+          },
+          categories: ['service'],
+          attributes: [
+            {
+              id: "type",
+              name: "API type",
+              array: false,
+              source: "$.type"
+              enum: {
+                name: 'Backstage API Type',
+                description: 'Type or format of the API.',
+                type_name: 'Custom["BackstageAPIType"]',
+                enable_backlink: true,
+              },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+}
+```
+
+The above we generate the following catalog types:
+
+- `BackstageAPI` with attributes:
+  - `Name`
+  - `API type`
+- `BackstageAPIType` with attributes:
+  - `Name`
+  - `Backstage API`
+
+The `enable_backlink` option allows you to specify if the created enum should have an attribute pointing back to the 
+attribute that created it. If disabled, the `BackstageAPIType` above will not have a `Backstage API` attribute.
+
+
+See [simple/importer.jsonnet](https://github.com/incident-io/catalog-importer/blob/bbb659c312af7c45a626a68643e1cd4e890376d5/docs/simple/importer.jsonnet#L161-L166) for a working example
\ No newline at end of file
diff --git a/docs/simple/catalog.jsonnet b/docs/simple/catalog.jsonnet
index 25b38e4..bb2a61d 100644
--- a/docs/simple/catalog.jsonnet
+++ b/docs/simple/catalog.jsonnet
@@ -627,6 +627,9 @@
         name: 'Zoom',
         description: 'Use Zoom to automatically start call links for your incident channels, and more.',
         owner: 'response',
+        contacts: [
+          'support@zoom.com',
+        ]
       },
     ]
   ],
diff --git a/docs/simple/importer.jsonnet b/docs/simple/importer.jsonnet
index d2dd8c0..87b18c8 100644
--- a/docs/simple/importer.jsonnet
+++ b/docs/simple/importer.jsonnet
@@ -153,6 +153,18 @@ local catalog = import 'catalog.jsonnet';
               type: 'Text',
               source: '$.description',
             },
+            {
+              id: 'contacts',
+              name: 'Contacts',
+              array: true,
+              source: '$.contacts',
+              enum: {
+                name: 'Integration Contact',
+                type_name: 'Custom["IntegrationContact"]',
+                description: 'Contact we have in the company for this integration.',
+                enable_backlink: true,
+              }
+            }
           ],
         },
       ],