Zum Hauptinhalt springen

Export Records from CertHub

This guide walks you through pulling records out of CertHub so your downstream tools can use them. This is the main pattern for synchronizing controlled product data from CertHub into an engineering environment.

The same procedure works for any knowledge topic, not only V-model content.

Prerequisites​

Step 1: Get the KT schema​

Before you read records, fetch the KT metadata. The schema tells you what each form field means.

curl "https://techdoc.prod.certhub-containers.containers.certhub.tech/kt/YOUR_KT_REVISION_ID" \
  -H "X-API-Key: YOUR_API_KEY"

The response includes knowledge_topic_schema, whose components list describes the form fields. Each component has a key (the opaque form key) and may have a properties["certhub-key"] that gives the field a stable semantic name.

Save this schema. You will use it to map opaque form keys to meaningful names.

For the full explanation of opaque form keys versus certhub-key, see Form field keys.

Step 2: List records​

curl "https://records.prod.certhub-containers.containers.certhub.tech/records/?context__knowledge_unit_topic_id=YOUR_KT_REVISION_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Each record in the response has:

  • _id, the record identifier
  • name, the human-readable record name
  • data, the field values keyed by opaque form keys

Step 3: Map form keys to semantic names​

Do not hardcode form keys. Use the schema from Step 1 to map those keys to stable semantic names.

# pip install requests
import requests

API_KEY = "YOUR_API_KEY"
TECHDOC_BASE = "https://techdoc.prod.certhub-containers.containers.certhub.tech"
RECORDS_BASE = "https://records.prod.certhub-containers.containers.certhub.tech"
HEADERS = {"X-API-Key": API_KEY}

KT_REVISION_ID = "YOUR_KT_REVISION_ID"

resp = requests.get(f"{TECHDOC_BASE}/kt/{KT_REVISION_ID}", headers=HEADERS)
resp.raise_for_status()
kt = resp.json()
schema = kt.get("knowledge_topic_schema", {})
components = schema.get("components", [])

key_map = {}
for component in components:
    form_key = component.get("key")
    if not form_key:
        continue
    props = component.get("properties", {})
    semantic = props.get("certhub-key") or component.get("label") or form_key
    key_map[form_key] = semantic

resp = requests.get(
    f"{RECORDS_BASE}/records/",
    params={"context__knowledge_unit_topic_id": KT_REVISION_ID},
    headers=HEADERS,
)
resp.raise_for_status()
records = resp.json()

for record in records:
    mapped = {key_map.get(k, k): v for k, v in record.get("data", {}).items()}
    print(record["name"], mapped)

Step 4: Retrieve traces if needed​

If you also need the links between records, continue with Work with tracer. That guide covers the POST /traces/batch/list flow in detail.

What to do with the export​

You now have a complete snapshot of the records with semantic field names. Cadence turns this export into a Sphinx-Needs catalog under sphinx/source/generated/. Other typical uses include synchronizing requirements into engineering tools, feeding a custom traceability database, or driving test case management.

Working example

Cadence (CertHub’s public engineering example) implements this exact export pattern to sync seven Requirements Engineering knowledge topics into Sphinx-Needs. See Working example.

Repeating the export​

This export is a point-in-time snapshot. For ongoing synchronization:

  • run the export on a schedule or trigger it on relevant events
  • compare against a previous export to detect changes
  • remember that CertHub currently relies on polling rather than push events
  • if a knowledge topic was re-approved, re-fetch its revision ID before listing records again (Versioning)

Next steps​