Getting Started with the Catalog
This page walks you through the very first interactions with the Catalog, from opening the Catalog App to your first item, first relationship and first compliance check. It assumes the catalog is already provisioned for your tenant; if it is not, contact your platform administrator.
Prerequisites
To get started you need:
- access to the Catalog App — the web UI is the easiest entry point;
- a tenant in which to operate (the catalog isolates everything per tenant, see Items);
- optionally, credentials for the Catalog API if you plan to script ingestion or queries.
1. Explore what is already there
When you open the Catalog App you land on the Homepage: a dashboard that gives you an at-a-glance overview of your catalog. From here you can see counters for total items, item types, connectors and items added in the current month. Below them, the AI Assistant lets you ask questions about items, scorecards, campaigns, or anything else in the Catalog, starting from a few suggested prompts. Pick up where you left off lists your recent conversations with the assistant, and Your catalog resources collects useful links for your Catalog.
From the left sidebar, you can browse the following:
- Items → filter by kind to see what already exists.
- Configuration → Item Types to see which kinds are registered in your tenant.
- Configuration → Relationship Types to see the connection types you can use to wire items together (see Relationships).
- Configuration → Connectors to see if any external system is already feeding the catalog automatically (see step 6 below).
- Governance to manage rules, scorecards, and campaigns (see step 5 below).
- Activity → Audit Logs to review every action performed on the Catalog (see Audit Logs).
2. Create your first custom Item Type
Most useful catalogs start by introducing a few custom item types specific to your domain. For example, you may want to track Docker images with their registry and tag.
From the Catalog App, go to Configuration → Item Types → Create item type and fill in:
- Group — a DNS-like name your team owns, e.g.
stable.acme.com. - Scope —
Organization, the only value currently supported. Whatever the value, items are always isolated per tenant (projects exist only in Console). - Kind and Plural — e.g.
DockerImageanddockerimages. - Version name — e.g.
v1, following thev<number>(optionallyalpha<number>/beta<number>) pattern. - Validation Schema — the OpenAPI-style JSON schema for the
specof the items (see Item Types). - Selectable fields — the
specfields you want to filter on later (see Selectable Fields).
Creating an ITD provisions a brand-new REST endpoint at /{group}/{version}/items/{plural}.
3. Create your first item
From Items → Create item, pick the type you just defined, and fill in:
- metadata:
title,name,description,tags, owner spec(the type-specific payload validated against the ITD's schema).
The wizard validates the spec against the ITD schema as you type.
You can do the same thing via API by sending a POST request to the resource path; see Catalog API.
4. Connect items with a relationship
Open the detail page of an item, jump to the Relationships tab, and link it to another item using one of the built-in relationship types (e.g. part-of, dependency) or one you have defined yourself. From now on, you can navigate that connection from either endpoint, both in the table view and in the graph view.
5. Run a compliance check
Once you have a few items, you can express compliance rules over them.
- Go to Governance → Evaluation Criteria → Create evaluation criteria and write a rule (e.g. "every DockerImage must have a tag"). The rule body can be authored visually, as JSON, or in CEL — see Evaluation Criteria.
- On the rule detail page, click Evaluate to trigger an ad-hoc run against your items. The run appears in the Runs tab and is polled to completion.
To go further, bundle multiple rules into a Scorecard to express a multi-level compliance posture, or into a Campaign to drive a time-bounded compliance program with notifications.
6. Plug in external data with connectors
Most catalogs are not populated by hand: they are kept in sync with the systems where the entities already live (source-code hosting, the Mia-Platform Console, cloud providers, artifact registries, security tools). The Catalog ingests data from dedicated connectors — see the Connectors Overview for the full picture. Our connector implementation is called ibdm.
In short, Mia-Platform connectors:
- are deployed alongside your platform and run in sync mode (a one-off pull from the upstream REST APIs) or run mode (an event-stream integration that, depending on the source, either listens for webhooks or polls the upstream system);
- transform upstream payloads into Catalog items through mappings (YAML with Go templates): the internal mappings built into
ibdmfor the Catalog's built-in Item Types, and mapping files of your own; - write into the Catalog authenticated with a Client ID and a private key.
The high-level setup is:
-
Register a matching service account. The key pair used for
private_key_jwtis not set in the Catalog App — a platform Super Admin registers it separately, with the same Client ID, as a service account in Platform Administration. See Registering a service account. -
Register the connector in the Catalog App. Open Configuration → Connectors → Add connector to create a Connector item and give it a Client ID — every item it later syncs in will be attributed to this ID (see Connectors section of the Catalog App reference). This step is only about attribution/labeling; it does not create any credential.
-
Configure
ibdm. SetMIA_CATALOG_ENDPOINT,MIA_CATALOG_CLIENT_ID(matching the Client ID from step 1) andMIA_CATALOG_PRIVATE_KEY_PATHfor the destination, together with the token endpoint settings described in Wiringibdmto the Catalog, plus the source-specific variables documented on each connector page. -
Choose the mappings. Each source ships internal mappings for the built-in Item Types:
ibdm mappings list <source>prints their names, and--include-internal-mappings=allselects all of them. Add mapping files of your own with--mapping-file, as described in Mappings. -
Launch
ibdm. Eitheribdm sync <source> --include-internal-mappings=allfor a one-off pull, oribdm run <source> --include-internal-mappings=allto start the event-stream integration. -
Inspect what came in. Open the connector's detail page in the Catalog App and switch to the Imported items tab to browse the items it has synchronized.
-
Wire compliance on top. Point your Evaluation Criteria, Scorecards, and Campaigns at the ingested items just like at hand-created items.
The available sources and the upstream system each one targets are listed in the Connectors Overview.
Where to go next
- Items and Item Types — the data model.
- Relationships — the graph layer.
- Query Language — how to search and scope.
- Connectors — feed the catalog from external systems through
ibdm. - Catalog API — when you graduate from clicks to scripts.
- Catalog App — the UI reference.