On this page

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 when you open Manage articles or the spec, and every 15 minutes besides, and flags the spec when its wording changes.
  • DevStride also flags a spec whose own wording no longer matches the requirement, and you can send the spec's wording to Formwork.
  • You send implementation evidence (the linked work items with their pull requests, commits and check runs) back to Formwork as a record.
  • You send a design output: the same write-up, filed as the requirement's design output and traced to the requirement and its tests.
  • 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. Edits to a spec stay in DevStride until someone sends them to Formwork.

Connecting your workspace#

Each workspace connects to one Formwork company, and works with as many of that company's products as you choose. 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 products#

Under Formwork products, choose every product this workspace works with, for example one per device. Each spec imported from Formwork stays tied to the product it came from, and its evidence, design output and test results go back to that product. If the company has none, the page says There are no products in this Formwork account.

You can add a product at any time. A product that specs have been imported from cannot be removed, and the page says why under the field: Specs have already been imported from {product}, so it cannot be removed from this workspace.

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.

When Formwork refuses the token

If the token expires or is revoked, the connection is kept but marked broken: Settings shows Formwork refused this workspace's token. It may have expired or been revoked. Paste a new token to reconnect. Paste a new token there to reconnect. Until then nothing reaches Formwork, and each imported spec says so in its Quality system panel.

Importing a requirement as a spec#

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

  1. On Manage articles, choose a tab, then pick the category the spec should go in from the category tree (optional).
  2. Click Import from Formwork. When the workspace works with more than one product, choose it under Product; the picker remembers your choice until you leave the page. It lists the Requirements in {release}, the newest draft release of that product. 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 if that category belongs on the tab you are on; otherwise it is left uncategorized, except on Specifications, where it goes into the first category in the tree that holds specs. If no category holds specs, the button is disabled on Specifications.

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 {ID} 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 {product} 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 five parts.

The requirement. Its ID and Formwork status, the Product it came from (shown when the workspace works with more than one), 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), or a wording difference (see When the spec's wording differs).

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.

Design output. When the design output was Last sent, its Formwork Status, and a link to open it in Formwork; or Not sent to Formwork yet. (see Sending a design output).

Sync now and the automatic check#

DevStride checks imported requirements in Formwork as soon as you look at them:

  • Opening Manage articles (the staff list of articles, behind the Manage articles button in the Knowledge Base) checks every Formwork spec in the workspace in the background. Each spec whose requirement changed, and whose change nobody has marked reviewed yet, shows an orange Changed in Formwork badge in the list, and each spec whose own wording no longer matches its requirement shows Differs from Formwork. The read-only article library, where the Knowledge Base opens, does not run this check.
  • Opening a spec checks that spec, so a change's Before and Now wording appears as the page loads.

A spec checked in the last minute is not read again, however many people open it. DevStride also checks every imported requirement every 15 minutes, and you can click Sync now in the panel to check one straight away. 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.

When the spec's wording differs#

A spec's wording is its title (without the requirement's ID) and the text above its Imported from Formwork line. When you change it so that it no longer matches the requirement, the panel says This spec's wording differs from {ID} in Formwork. and shows the wording In Formwork now. The spec shows Differs from Formwork in Manage articles too. This is not shown while a change from Formwork waits for review: review that first.

You then have two choices:

  • Keep Formwork's wording: change the spec back to match it.
  • Send the spec's wording: click Send wording to Formwork. DevStride first saves any edits you haven't saved yet, so Formwork gets the wording on your screen. The spec's title and text replace the requirement's title and description in Formwork. An internal comment on the spec quotes the wording Before and Now, and the spec stops being flagged.

A send is refused, with the reason in the panel, when:

  • the requirement changed in Formwork since the page showed it: The requirement changed in Formwork since this page showed it. Press Sync now and review the newest wording, then send again.
  • Formwork has a newer draft release: click Sync now so the spec follows its requirement there, then send again.
  • the requirement's release is no longer a draft in Formwork: change the wording there, through Formwork's own change control.
  • your latest edits could not be saved: Your latest changes could not be saved, so the wording was not sent. Nothing goes to Formwork.
  • the spec has no title (Give the spec a title before sending its wording to Formwork.), or the requirement is no longer in the release.

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.

Sending a design output#

In Formwork's design controls, a design output is the artifact that shows how a requirement was met. DevStride keeps one design output per spec.

  1. In the Quality system panel, under Design output, click Send design output.

DevStride writes the same summary the implementation evidence carries (each work item linked to the spec that you can read, with its pull requests, commits and check runs) into a draft design output in the requirement's Formwork release, titled with the requirement's ID and title, and links it to the requirement and its tests. The panel then shows when it was sent, its status and Open {ID} in Formwork, and the button reads Update design output.

  • Sending again updates the same design output while it is still a draft in the same release.
  • Once it has moved past draft in Formwork (for example, under review or approved), DevStride leaves it alone: This design output is {status} in Formwork, so DevStride no longer changes it. Change it there.
  • When Formwork has a newer draft release, click Sync now first so the spec follows its requirement there: Formwork has a newer draft release. Press Sync now so the spec follows its requirement there, then send the design output again. The next send creates a new design output in that release.
  • If the design output was deleted in Formwork, the next send creates a new one.

Design outputs must be switched on for the product in Formwork. If they are off, the panel says Design outputs are switched off for {product} in Formwork. Switch them on for the product there, then send again. Refusals show in the panel's Design output section, so you can act on them there.

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#

To You need
Connect, choose the products, or disconnect Manage Integrations
Import a requirement Create knowledge-base articles
See an imported spec's Quality system panel Any Knowledge Base permission, plus access to the spec
Click Sync now Create knowledge-base articles, plus access to the spec
Mark as reviewed, send the spec's wording, send implementation evidence or a design output, or file test results Edit access to the spec: Create knowledge-base articles plus your own spec, a Can edit share, or Edit any member's knowledge-base articles

See Knowledge Base permissions.

If something goes wrong#

You see What to do
Formwork refused this workspace's token. It may have expired or been revoked. Someone with Manage Integrations pastes a new token in Settings → Integrations → Formwork.
Choose the Formwork products in Settings → Integrations → Formwork first. Choose at least one product under Formwork products.
This requirement is not in {release}, the draft release DevStride imports from. The newest draft release changed while the picker was open. Close it and click Import from Formwork again.
The requirement changed in Formwork. Press Sync now and mark the change as reviewed on the spec, then record the results. Click Sync now, review the change, click Mark as reviewed, then file again.
Some of these tests are no longer linked to the requirement in Formwork. Reload the tests and record them again. Reload the page and choose the results again.
Results for this spec are already being filed in Formwork. Try again in a few minutes. Someone else is filing. Wait, then reload to see their filing.
Evidence for this spec is already being sent to Formwork. Try again in a minute. Wait a minute, then send again.
The design output for this spec is already being sent to Formwork. Try again in a minute. Wait a minute, then send again.
{product} has no draft release in Formwork to add a design output to. Create a draft release for the product in Formwork, then send again.
Powered by DevStride