Formwork

What the Formwork integration is for

Formwork is OpenRegulatory's quality management system for medical-device software. Your regulatory team keeps the software requirements there, release by release, and needs evidence that each one was built and tested.

Connecting Formwork to DevStride closes that loop without copying anything by hand:

• You import a Formwork requirement as a Knowledge Base spec, and build from it like any other spec (see Specs and work items).
• DevStride checks the requirement in Formwork every 15 minutes and flags the spec when its wording changes.
• You send implementation evidence (the linked work items with their pull requests, commits and check runs) back to Formwork as a record.
• You file test results for the Formwork tests linked to the requirement.

Formwork stays the system of record. DevStride never decides a test result for you, and never rewrites a spec when the requirement changes: a person checks the spec against the new wording.

Connecting your workspace

Each workspace connects to one Formwork company and works against one Formwork product. Connecting needs the Manage Integrations permission (Owner and Admin have it by default).

1. In Formwork, open your personal API access page and create a token with read and write access.
2. In DevStride, go to Settings → Integrations → Formwork.
3. Paste the token into Formwork API token and click Connect.

When it works you see Formwork connected, and the page shows Formwork is connected with the Company the token belongs to and its Access (Read and write).

• A read-only token is refused, because it could not send evidence back: This Formwork token is read-only. Create a read-and-write token in Formwork (Settings → API access) and paste that instead.
• The token is stored securely and never shown again. The field is cleared as soon as you click Connect, whatever the answer.
• One company per workspace. Pasting a token for a different company is refused: This workspace is already connected to {company}. Disconnect it before connecting a different Formwork company. Pasting a new token for the same company simply replaces the old one.

Choosing the Formwork product

Under Formwork product, choose the product DevStride works against. Specs are imported from it, and evidence is sent back to it. If the company has none, the page says There are no products in this Formwork account.

Once a requirement has been imported, the product is locked: Specs have already been imported from {product}, so the Formwork product can no longer be changed.

Disconnecting

Click Disconnect, then Disconnect again to confirm. The stored token is removed. Specs imported from Formwork stay in DevStride, but lose their link to Formwork and stop tracking changes.

Importing a requirement as a spec

Once Formwork is connected and a product is chosen, Manage articles shows an Import from Formwork button.

1. On Manage articles, pick the category the spec should go in from the category tree (optional).
2. Click Import from Formwork. The picker lists the Requirements in {release}, the newest draft release. Each row shows the requirement's ID, title and Formwork status.
3. Type in Find a requirement to narrow the list by ID or title.
4. Click a requirement.

DevStride creates the spec and opens it. The spec:

• is titled with the requirement's ID and title (for example SWR-12 Export audit log),
• holds the requirement's description, a line saying where it was Imported from Formwork, and its Linked Formwork tests,
• is Internal, so customers never see it, and
• is filed in the category you picked, or left uncategorized.

A requirement that has already been imported is marked Already imported; clicking it opens the existing spec instead of making a second copy. If that spec is one you cannot open, the picker says was already imported as a spec you cannot open. Ask its author to share it with you.

Importing needs Create knowledge-base articles. If the product has no draft release, the picker says has no draft release to import requirements from.

The Quality system panel

An imported spec has a Quality system panel in the article editor's right-hand column, its header showing the requirement's ID. It has four parts.

The requirement. Its ID and Formwork status, the Release it belongs to, when it was Last synced, and Open in Formwork.

A change to review, when there is one (see When the requirement changes).

Formwork tests. The tests linked to the requirement in Formwork, with their steps and expected results, read live from Formwork (see Filing test results).

Implementation evidence. When evidence was Last sent, to which Reviewers, and a link to the record in Formwork; or Not sent to Formwork yet.

Sync now and the automatic check

DevStride checks every imported requirement in Formwork every 15 minutes. To check one straight away, click Sync now in the panel. Last synced updates either way.

When the requirement changes

When a check finds that the requirement's title or description changed in Formwork, the spec is flagged. The panel says Formwork changed this requirement on {date}. Check the spec against the new wording. and shows the wording Before and Now. An internal comment on the spec says the same, so the spec's watchers and reviewers see it too.

The spec's own text is not changed. Read the new wording, update the spec if it needs it, then click Mark as reviewed.

If the requirement changes again several times before anyone reviews it, Before stays the wording last reviewed, so you always compare against what your team last agreed.

If it changed again in Formwork after you opened the page, marking it reviewed is refused: The requirement changed again in Formwork since this page showed it. Check the newest wording, then mark it reviewed. The panel reloads with the newest wording; review that, then click Mark as reviewed again.

Test results cannot be filed while a change is waiting for review.

When the requirement leaves the release

If a check cannot find the requirement in the newest draft release any more, the panel says This requirement is no longer in the Formwork release. The values shown are the last ones DevStride read. and an internal comment on the spec says so. Test results are refused until it is back: The requirement is no longer in the Formwork release. Press Sync now once it is back, then record the results.

Sending implementation evidence

1. In the Quality system panel, click Send implementation evidence.
2. Under Send for review to, choose the Formwork roles who should review the record, or leave it empty (No one: keep it a draft).
3. If you chose reviewers, optionally add a Comment for the reviewers (under 2,000 characters).
4. Click Send.

DevStride files a new draft record in the requirement's Formwork release. It lists each work item linked to the spec (that you can read) with its pull requests (number, title, status, merge date and link), commits and check runs. If no work items are linked, the record says so. Each send makes a new record; the panel shows the latest.

• If the evidence is longer than Formwork accepts (200 KB), the record is cut short and the panel says The evidence was longer than Formwork accepts, so the record was cut short.
• If the record was filed but Formwork would not send it to the reviewers, the panel says The record was filed as a draft, but Formwork did not send it for review: followed by Formwork's reason.

Filing test results

DevStride never decides a result from CI: a person chooses each one.

1. In the Quality system panel, under Formwork tests, choose a result for each test you ran: Success, Partial success, Failure or Skipped. Leave a test on Not filed to skip it this time.
2. Add Notes. Notes are required for Failure and Partial success: Say what failed: notes are required for this result. (up to 4,000 characters).
3. Click File in Formwork.
4. Check the summary (DevStride files 3 results in a Formwork test run set for release {release}, with the build evidence attached.) and click File results.

Each filing creates one Formwork test run set. Every chosen test gets a run with its result, your notes and one evidence file: the results table, then the linked work items' pull requests, commits and check runs. Records created in Formwork cannot be removed from DevStride.

Your choices are kept only until you leave the page. Once filed, each test shows Filed: {result}, and Last filed shows when and by whom, with a link to the run set in Formwork.

When only some results were recorded

If Formwork records some results but not others, the panel says Formwork did not record every result. Choose again for the tests marked not filed, then retry. Each test that failed shows Not filed: and the reason. Choose again for those tests only and click Retry failed: the results go into the same run set, not a new one.

Who can do what

See Knowledge Base permissions.

If something goes wrong

Related

• Specs and work items: link the spec to the work that builds it, which is what the evidence lists.
• Spec stages: track where each spec has got to.
• Watching articles and categories: be told when a spec changes.
• Knowledge Base permissions: who can import, review and file.