Working example
Cadence is CertHub’s public engineering example: a complete, runnable demonstration of connecting the system of record to an engineering environment. It is not a prescribed toolchain. You talk to CertHub through the API, in any language; how you implement the last hop into source is your choice. In this repo, useblocks (Sphinx-Needs / CodeLinks / Test-Reports) is the optional last-hop toolchain, not a CertHub product requirement.
The V-model records (including design outputs and the traces between them) stay in CertHub. Implementation and test execution stay outside. Why that split, and why you sync layers you never stamp on a function, is in Where does the V-model live when you develop software?.
Cadence maps that pattern onto a fictional SaMD (Sterilisator 20A) as two downstream applications of the same APIs: tracing requirements down to code at the tip of the V, and running tests plus writing selected records back on the right. The seven content layers below match CertHub’s Requirements Engineering use case; Cadence is the engineering twin of that matrix.
CertHub Cadence — SaMD use case walkthrough
Walkthrough of Cadence on Sterilisator 20A. Cadence is one example of the pattern — not a required toolchain.
API key and tenant
Generate your own API key in CertHub when you sync or push a Release Record.
The first local run (make show) does not need a key — the showcase
catalog and snapshot are committed. Never wait for a “showcase key.” Follow
Authentication (Settings → API Keys).
| Path | What you edit | Key |
|---|---|---|
| See the demo first | Nothing | None — make install && make show |
| Showcase Cadence as published | .env only (CERTHUB_API_KEY) for sync / write-back | Create your key; committed certhub.toml points at the showcase product. Your user must have access to that product (same inheritance as Permissions). |
| Your own tenant | Copy certhub.toml.example → certhub.toml and fill every ID | A key from your tenant that can read those products |
Showcase revision IDs in certhub.toml are pinned for the demo. On your own tenant, prefer history IDs in config and resolve revision IDs during sync (Versioning).
The V in this example
This layout is aligned with CertHub’s Requirements Engineering use case. Cadence syncs all seven content knowledge topics; code and tests stay on the engineering side; one Release Record is written back on full tags only.
Left of the V: trace down to code
Export the V-model records and Tracer edges from CertHub (Export Records). That copy is the matrix ISO 13485 7.3.2(e) asks you to maintain: user needs, design inputs (system / component / unit), design outputs, verification, validation.
The last hop into source is yours. Cadence’s method is narrow on purpose:
- Source comments are design-output IDs (
# @need-ids: DOUT_018). FDA GPSV §5.2.4 traces modules to the software design specification, not to the system requirement. - System requirements still close the engineering gate, but only through Tracer.
SYSREQdoes not appear insrc/. - Unlinked catalog rows still sync. They are the completeness check, not clutter.
Examples of engineer-side approaches:
- useblocks (this example). Sphinx-Needs, CodeLinks, and Test-Reports are open source (MIT); ubCode is the paid IDE. We find this the strongest docs-as-code option in that category, which is why Cadence is built this way.
- Doorstop
- Doxygen or other source-comment / API-doc generators
- Custom markers in comments (this example uses
@need-ids:onDOUT_*/VERIF_*) - A small script against the CertHub API in whatever language you already ship
Right of the V: tests and selected records
Run any tests you want, keep the full evidence where it was created, and write back only the records that belong in the technical file (Write Evidence Records). Which tests you run, and which records you file, is yours.
Cadence tags tests with verification IDs (# @need-ids: VERIF_* plus @pytest.mark.certhub_test("VERIF_*")). Validation protocols sync into the pack but stay manual: 21 CFR 820.30(g) / ISO 13485 7.3.7 are intended use, not unit tests.
This example uses pytest + JUnit and GitHub Actions: evidence on every PR (cadence-evidence.yml), one release record on full vX.Y.Z tags only (cadence-release.yml). Other runners (Go test, Catch2, Jest, lab/HIL) and other CI (GitLab CI, Jenkins) fit the same pattern.
Your choices, not ours
| Choice | Cadence (this example) | You can use |
|---|---|---|
| Language | Python | Anything that can call the API |
| Code-level traceability | useblocks (Sphinx-Needs / CodeLinks) | Doorstop, Doxygen, custom markers, your own script |
| Test runner | pytest + JUnit | Any automated or lab suite |
| CI | GitHub Actions | Any pipeline that can run tests and POST to CertHub |
| What you write back | One Release Record on full tags | Whatever depth your QM/RA process needs |
We built Cadence this way because this combination works well for us, not because CertHub requires it.
Try it locally
git clone https://github.com/CertHubCode/certhub-useblocks-example.git
cd certhub-useblocks-example
make install
make show # tests + gate + open dashboard — no API key
Expect VERIFIED and 4/4 SYSREQ PASS. The assurance dashboard opens at sphinx/build/html/dashboard.html.
When you want to refresh from CertHub or push a Release Record, create an API key (Settings → API Keys) and see Authentication:
cp .env.example .env # set CERTHUB_API_KEY
make sync # CertHub → Sphinx-Needs
make show
The repository README covers the guided path (show → sync → release → own tenant), the RED/GREEN demo (make break / make fix), and CI setup.
What it demonstrates
| API pattern | Where in Cadence |
|---|---|
Export records and map form keys via certhub-key | certhub/certhub_connector/sync/ and certhub/certhub_connector/sync/keys.py |
| Resolve KU and KT revision IDs from history IDs | certhub/certhub_connector/api/client.py |
| Batch-retrieve traces | certhub/certhub_connector/api/client.py → TracerClient.batch_list_records |
| Write a release-evidence record back | certhub/certhub_connector/evidence/push.py |