Policies
Write or import a policy, map it to controls, approve a version, collect acknowledgements, and give an auditor its history and PDF.
A policy in devguard is a document plus the records an auditor asks for. You write it in sections, as you would in Word. Next to the text, devguard keeps which control each section meets, who approved which version and when, who has acknowledged it, and when it was last reviewed.
You can write a policy in the editor or import the Word file you already have. You can map each section to the controls of the frameworks you have adopted, so coverage shows on the framework and not in a spreadsheet. When you approve a policy, devguard freezes a version. Your people acknowledge that version in the portal, and an auditor can compare it with the next one.

Find your task
| I want to | Read |
|---|---|
| Set up categories and write the first policy | Create a policy |
| Bring in a policy we already have in Word or PDF | Import a Word or PDF document |
| Write, structure or format the text | The policy editor |
| Show which controls a policy satisfies | Map a policy to controls |
| Get a policy signed off | Approve and publish a version |
| Make staff read and confirm it | Have people acknowledge it |
| Make sure it is reviewed every year | Review on a schedule |
| Show an auditor what changed | Compare versions |
| Hand over a PDF | Generate the PDF |
| Check we are ready for the audit | Before your audit |
| Move, retire or remove a policy | Reorder, archive and delete |
| Read or write policies from another system | For developers |
Create a policy
Every policy belongs to a category, so start an empty list with a category. A category is a heading in the list. It groups the policies an auditor reads together and sets their order.
Add a category
- Open Policies and press Add category.
- Enter a name, such as Information Security or Human Resources. Names are unique within your organization.
- Save. The category appears at the end of the list. To move it, drag the handle at the start of its row.
Write a new policy
- On the category's row, press Add policy.
- Enter the Title. The Slug derives from it and becomes the policy's address.
- Choose the Approver: the business role whose members may approve the policy. It is a role, not a person, so a change of staff does not affect it. The list shows this role in its Owner column.
- Optionally choose a Review schedule. You can also set it later in the editor.
- Save. The policy opens in the editor as a Draft, and the members of the approver role are notified.
The category is fixed when you create the policy. To move the policy later, drag it into another category in the list.
Start from a template
devguard comes with a catalog of policy templates. It has the documents an ISO/IEC 27001 management system needs, such as the scope and context, risk management, objectives and the legal register, and the topic policies that ISO/IEC 27002 expects, such as access control, incident response, backup and secure operations. For ISO 9001, ISO 14001, ISO 45001 and ISO/IEC 42001 it has the top-level policy of each standard, shared documents such as scope and context, objectives, and internal audit and management review, and documents for one standard, such as environmental aspects or hazard identification. A shared document leaves out the sections of standards you have not adopted. Each template is a complete draft in English and German.
To start one policy from a template:
- On the category's row, press Add policy.
- Under Policy template, choose a template. The Title fills in.
- Choose the Approver and save. The Draft opens with the template's sections and text, in your language, in the category you started from.
You can also start on Frameworks → Templates: read the template there and press Create. The same form opens with the template chosen, and the policy goes into the template's own category. devguard creates that category if you have none of that name.
To start several at once, open the setup wizard from the dashboard, tick the policies you want and choose the business role that approves all of them. Each template becomes a Draft in its own category.
Templates that fit your adopted frameworks come first. A template that is already in your policy set says so. devguard copies a template and does not link it, so a later change to the catalog does not change your copy.
Fill in a template
A template is a starting point. Change any rule that does not match how you work: an auditor checks your organization against what your policies say. Two kinds of fields are highlighted in the editor:
- Text in square brackets, such as
[3 years], belongs to this policy. Click it and type over it. - Highlighted badges are variables, such as ISMS owner. They hold what several policies must say the same way. Creating a policy from a template adds the variables it uses, with a proposed value in square brackets. A variable you already have keeps its value. Change the value once under Collections, then Variables, and remove the brackets to confirm it.
You can't approve a policy while a field is open. The approval dialog lists the fields that remain.
Import a Word or PDF document
- On the category's row, press Import.
- Drop a
.docxor.pdffile of up to 20 MB and press Continue. Your browser reads the file. devguard stores only the policy made from it. - Check the title, choose the approver and, if you like, a review schedule, then save. The policy opens in the editor as a Draft.
What comes across:
- Headings become sections, nested by their level. A lone heading at the top becomes the title. In a document without heading styles, short bold lines count as headings, and numbering such as 2.1 decides the nesting.
- Paragraphs, lists, tables and bold or italic text come across from Word. Merged cells stay merged. Text in a text box follows the paragraph that holds the box.
- Images in a Word file are added to the draft: JPEG, PNG, GIF, WebP and BMP up to 10 MB each. Drawings stored as EMF or WMF are left out, and a message says how many. Add them again in the editor as PNG or JPEG.
- Words hyphenated at a line end are joined again (Informa- tionssicherheit becomes Informationssicherheit). Real hyphens stay (Ein- und Ausgang).
- A PDF keeps its text and its bordered tables. devguard finds headings by their larger type, or by bold type at the size of the body text, and turns indented lines into lists. Page headers, footers and page numbers are dropped. A table with cell borders becomes a table again, also across a page break. A table without borders comes across only when its columns line up over at least three lines. Images, colors and shading do not come across, so import the Word original if you have it.
- AI can read a PDF instead. If AI is turned on for your organization and its AI model can read PDFs, tick Use AI to import for better results before choosing a PDF or with it chosen; the box is not offered for a Word file. AI finds headings, lists and tables more reliably than the rules above and copies the text word for word; check the draft all the same. The import counts as one AI request, and the PDF may be up to 4.5 MB. It is sent to devguard's AI provider to be read and is not stored.
A scanned PDF holds pictures of pages rather than text, so there is nothing to import. Export it again with text recognition first.
Map a policy to controls
A mapping says that a section of the policy meets a control of a framework you have adopted. It is one of the signals that changes the control's coverage from Unknown.
- Open the policy and click the section that implements the control. The right panel shows that section's Controls card.
- Under Framework, keep All frameworks or pick one.
- Under Select Control, search by identifier or name and choose the control.
- Press Map Control. devguard saves the policy and records the mapping. The control appears as a badge under the section's heading and as a row under Mapped Controls.
- To record your verdict, expand the row and press Edit Coverage. Choose the Coverage Status: Full Coverage, Partial Coverage, No Coverage, or Automatic, which lets the control's linked items set the status. Optionally describe the Coverage Gap, then save.

To link a control to the whole policy and not to one section, open the ⋯ menu by the title and choose Link a control. Linked controls show as badges under the title. Link control adds another, and × removes one.
The control's own page shows the result: its Links tab lists the policy, and the section, under Policies.

A version also freezes the mappings. If you add or remove a mapping on a published policy, it returns to Draft until the next approval.
Let the AI assistant map a first pass
Ask the AI assistant to map the matching controls to a policy. It reads the policy section by section and checks every control of your adopted frameworks against the text. It writes only the mappings it is sure of, each marked AI with its reason. The coverage of those mappings stays Unknown until someone reviews it. If you ask it to undo the automatic mapping, it removes only the mappings it made. You need a role that may edit policies, and the work counts toward your organization's AI usage.
Approve and publish a version
Approval turns the draft into a version. A version is a frozen copy of the title, the text, the images and the control mappings, with a number, a changelog, the approver and the time. Only members of the policy's approver role can approve. When the button is disabled, its tooltip says why.
- Open the policy and press Approve. The dialog lists what changed since the last version: sections added, removed, renamed or moved, and control mappings added or removed.
- Choose the Change Scope. Patch, Minor and Major suggest the next number. A first version starts at 1.0.0. You can type any unused number in the form
x.y.z. - Write the Changelog. It is required and appears in the version history and the PDF.
- Decide whether to Require everyone to acknowledge again, and by when. The box shows once a previous version exists. It is ticked in advance for a major number, but the choice is yours. Re-acknowledgement explains what it does to people's status.
- Press Approve Policy. The status turns Published and the version appears in Version History. If the policy has a review schedule, its next review date moves on. The approver role is notified.

If you then edit the title or text, or change a control mapping, the policy returns to Draft. The published version stays as it was. The list shows its number until the next approval.
Have people acknowledge it
Assignment and acknowledgement work the same way for policies and trainings. Trainings describes audiences, cycles and statuses in full.
- Open the published policy with no section selected and find the Assignment card in the right panel. Before the first version, the card says Not assignable yet.
- Choose the Members and Roles who must acknowledge it. The audience follows the roles: someone who joins a role gets its assignments, and someone who leaves it loses them.
- Set the First due date and, for a recurring cadence, a schedule under Repeats on. Press Save assignment.
- Follow up. The card counts who is Completed, Pending and Overdue. The dashboard counts the policies with an overdue acknowledgement, and People lists who owes what.
What your people see. In the employee portal they open the policy and press View policy document. They read the PDF of the latest published version to the last page, tick I have read and understood this policy and press Acknowledge. The record keeps the version they acknowledged.
Review on a schedule
Auditors often find policies that were approved once and never reviewed again.
- In the editor's Periodic Review card, choose a Review schedule: any schedule your organization defines.
- devguard shows the Next review date and lists it under Deadlines. Once the date passes, the card shows Overdue and the members of the approver role get a reminder.
- When the review is due, edit the policy and approve a new version, which counts as the review. If the text is still right, press Mark as reviewed instead. This records a review that found nothing to change, and creates no version.
Only members of the approver role can mark a policy reviewed. You cannot mark an archived policy reviewed.
Compare versions
The Version History card lists the versions, newest first, each with its number, changelog, date and approver. View Details opens one version. Compare Versions compares it with the latest. The top shows who approved each version and why, with a one-line summary of what changed. Below it, devguard compares the stored record line by line. Change either side with From and To, and switch between a unified and a split view.
In the demo organization, version 1.2.0 of the Access Control Policy adds one sentence to Review of entitlements: Access held by former staff is revoked within one working day. Compare 1.1.0 with 1.2.0. You see the summary content modified and the changelog of each version. The new sentence is green in the stored record.

Generate the PDF
- Press Generate Report in the editor. When the editor is narrow, it shows only as a pie-chart icon beside Approve.
- Reports opens with the policy selected. Choose Latest (Current Draft) or a published version and generate.
The PDF starts with a cover: the category, the owner (the approver role), the status and, for a published version, the version. If the policy has a review schedule, the cover also shows the Review schedule and the Next review date. A table of contents follows. For a published version, the changelog history up to that version comes next. Then come the sections with their formatting and images. If your plan includes branding, the PDF uses your brand colors. On any plan, you can add a custom footer (see Reports).
Your people read a different copy in the portal: always the latest published version, with no brand colors, no custom footer and no changelog history.
Before your audit
Check each policy in scope against this list:
- It has a published version, and the list shows no Draft you meant to approve.
- Its sections are mapped to the controls they satisfy, with a coverage verdict.
- It is assigned, and the Assignment card shows no one Overdue.
- It has a review schedule, and its next review is not overdue.
- You can produce the PDF of the current version and, if asked, of earlier ones.
Reorder, archive and delete
Drag the handle at the start of a row to reorder categories, to reorder policies in a category, or to move a policy into another category. You cannot drag while a search or filter is active, or in the archived view.
Archive, in a policy's ⋯ menu, takes the policy out of the list and out of use. Its assignment is archived with it. Switch the list to Archived to see archived policies and Restore one. A restored policy counts toward your plan limit again. Its assignment stays archived, so set it up again if needed.
Delete is permanent. It removes the policy with its versions, control mappings, action and evidence links, comments, and its assignment with every acknowledgement. Tasks that referred to it remain, without the link. Archive instead if an audit may still need the record.
You can delete a category only when no policy, archived or not, is in it. Otherwise the deletion fails with a general error, so move or delete its policies first.
Reference
Policy fields
| Field | Description |
|---|---|
| Title | Required, 2 to 255 characters. Edited inline or under ⋯ → Edit Settings. |
| Slug | Required. Lowercase letters, digits and hyphens, unique in the organization. Changed under Edit Settings; renaming does not unpublish. |
| Category | Set at creation; changed by dragging in the list. A category name is unique in the organization. |
| Approver | Required. The business role whose members approve and mark reviewed. Changed under Edit Settings; the new role is notified. |
| Review schedule | Optional. Drives the next review date. Changed in Periodic Review; deleting the schedule clears the date. |
| Status | Derived, see below. |
| Version | The latest published version. The list's tooltip adds the approval date and approver. |
Status
| Status | Meaning |
|---|---|
| Draft | Nothing published yet, or the title, text or control mappings differ from the latest version. |
| Published | Title, text and control mappings match the latest version. |
| Archived | A second badge on an archived policy, shown in the archived view. |
Who can do what
| Action | Owner, admin | Member | Auditor | Employee |
|---|---|---|---|---|
| View policies, versions, mappings | ✓ | ✓ | ✓ | ✗ |
| Create, edit, import, reorder, archive, delete | ✓ | ✗ | ✗ | ✗ |
| Map controls, set the coverage verdict | ✓ | ✗ | ✗ | ✗ |
| Approve, mark as reviewed | if in the approver role | if in the approver role | ✗ | ✗ |
| Comment | ✓ | ✓ | ✗ | ✗ |
| Acknowledge in the portal | ✓ | ✓ | ✓ | ✓ |
An auditor stays read-only even in an approver role. devguard refuses every change from an auditor, approval included.
Plan limits
The Free plan allows 10 policies. Business plans have no limit. Archived policies do not count. A batch of templates is checked as a whole. At the limit, Add policy and Import open the upgrade dialog.
Where policies appear elsewhere
- The dashboard's Policies card shows the total and the number of approved policies, with a bar for published, needs-approval and draft policies. Its Policies overdue tile counts the policies with an overdue acknowledgement.
- Deadlines lists each policy's next review and its assignment's due dates. Archived policies are left out.
- In an audit, the Review period tab lists, per control, the policy versions in effect during the period.
- A task can name a policy in its Policy field. You set the task's status by hand.
- An evidence record can link to a policy from its Links tab. The link covers the whole policy.
- An integration action can be mapped to a section from the editor's Actions card.
- Another policy or a record can reference a policy, or one of its sections, with
:. The editor's Comments card keeps the discussion on the policy. - Search (⌘K) finds policies by title.
- The audit log records who created, edited, approved, archived, restored, reordered, reviewed, mapped, deleted or acknowledged a policy.
Behind the workflow
Status is computed, not set. After each save and each change to a control mapping, devguard compares the title, the text and the mappings with the latest published version. If they are equal, the status is Published. Otherwise it is Draft. A new slug or a new approver keeps a policy published. One corrected sentence does not.
A version is a frozen copy. It copies the policy as it was, so a later edit cannot change what was approved. The PDF of version 1.0.0 reads the same in five years. devguard only adds versions. A correction is a new version with a changelog, and that is what an auditor expects to see.
A review is not a new version. Both move the next review date on. A new version says the text changed. Mark as reviewed says someone read the text carefully and found nothing to change. Because of this, the version history holds only real changes.
Re-acknowledgement is its own dated obligation
When an approval requires everyone to acknowledge again, earlier acknowledgements stay on the record. They no longer count for the current cycle. The schedule itself does not change: no cycle is added, skipped or moved. Until a person acknowledges again, they are Pending until the date you picked and Overdue after it. Deadlines, the dashboard and the reminders all show that date.
The date must be in the future. It can never give anyone more time than a deadline they already have. If you pick a date on or after the next scheduled due date, the dialog says so and the earlier date applies.
For developers
The public API speaks JSON at https://app.devguard.ch/api/, authenticated with a bearer token from Account → Tokens or Settings → Tokens. Every parameter and response is in the API reference.
Endpoints
| Method and path | Purpose | Needs |
|---|---|---|
GET /policies/ | Paginated list. | read |
POST /policies/ | Create a draft. | create |
PATCH /policies/{id}/ | Change title, slug, order, approver, content or review schedule. | update |
DELETE /policies/{id}/ | Delete permanently. | delete |
POST /policies/{id}/archive/, .../restore/ | Archive, restore. | update |
POST /policies/{id}/approve/ | Publish a version. | approver role |
POST /policies/{id}/mark-reviewed/ | Record a review without a version. | approver role |
GET /policies/{policyId}/versions/, .../versions/{version}/ | List versions, read one. | read |
GET /policies/{policyId}/versions/compare/ | Diff fromVersion and toVersion; latest is the current draft. | read |
GET /policies/{policyId}/changelog/ | Changelog history up to upToVersion. | read |
POST /policies/reorder/, /policies/categories/reorder/ | Move a policy (also across categories) or a category. | update |
/policies/categories/ and /policies/categories/{id}/ | Categories: list, create, read, rename, delete. | read to delete |
GET /policies/templates/, POST /policies/from-templates/ | Template catalog; up to 40 drafts per call. | read, create |
/policy-control/map/, unmap/, mappings/, search/ | Control mappings per section (sectionUid), or the whole policy (sectionUid null). | update, read |
/policy-action/map/, unmap/, mappings/, search/ | Action mappings per section. | update, read |
GET /policies/ takes organizationId (required), filterByTitle, matchSectionTitles, category (a category id), filterByArchived (active or archived), page (from 1) and limit (5 to 100, default 100). It returns { items, total, page, limit }; a page past the end is a 400. The versions list pages differently: limit 1 to 100 with a default of 10, a response of { versions, total, page, limit }, and an empty list past the end.
A first request
curl -H "Authorization: Bearer dvg_…" \
"https://app.devguard.ch/api/policies/?organizationId=<org id>&limit=5"A personal token starts with dvg_, an organization token with dvgo_. Each item in items is the full policy row; content is trimmed here:
{
"items": [{
"id": "<uuid>",
"title": "Access Control Policy",
"slug": "access-control-policy",
"status": "PUBLISHED",
"currentVersion": "1.2.0",
"approverId": "<business role id>",
"categoryId": "<category id>",
"nextReviewAt": null,
"archivedAt": null,
"content": { "type": "doc" }
}],
"total": 1, "page": 1, "limit": 5
}The other fields are order, organizationId, lastApprovedAt, lastApprovedBy, reviewScheduleId, lastReviewedAt, createdAt and updatedAt.
status is DRAFT or PUBLISHED. The data model also has NEEDS_APPROVAL, which the app never sets. The status filter and the dashboard still count it, so a policy written with that value outside the app shows it.
Request bodies
A policy's content is a document of sections, each with a name and a uid unique within the policy; control mappings point at that uid.
{
"title": "Access Control Policy",
"slug": "access-control-policy",
"categoryId": "<category id>",
"approverId": "<business role id>",
"organizationId": "<organization id>",
"content": {
"type": "doc",
"content": [{
"type": "PolicySection",
"attrs": {
"name": "Purpose and scope",
"uid": "purpose-and-scope"
},
"content": [{
"type": "paragraph",
"content": [{
"type": "text",
"text": "Access is granted on request."
}]
}]
}]
}
}{
"version": "1.2.0",
"changelog": "Former staff lose access.",
"requireReacknowledgment": true,
"reacknowledgmentDueAt": "2026-12-31T00:00:00.000Z"
}Mapping controls
{
"policyId": "<policy id>",
"controlId": "<control id>",
"sectionUid": "purpose-and-scope",
"organizationId": "<organization id>"
}Leave out sectionUid, or send null, to link the control to the whole policy. Two optional fields record where a mapping came from. source is MANUAL (the default) or AI, which shows the AI badge. rationale holds up to 1,000 characters and shows as the badge's tooltip. When the AI assistant undoes its automatic mapping, it removes every mapping with source AI, also the ones you sent that way.
The response is the control's coverage record for that section, not the link. It has id, controlId, policyId, sectionUid and coverageStatus, plus controlIdentifier and policyTitle. A control that is already mapped to the section returns 409.
To unmap a control:
- Call
GET /policy-control/mappings/withpolicyId,organizationIdand an optionalsectionUid. Each item'sidis acontrolPolicyLinkId. - Call
DELETE /policy-control/unmap/withcontrolPolicyLinkIdandorganizationIdas query parameters.
GET /policy-control/search/ takes organizationId and an optional query and frameworkId. The action endpoints work the same way, with actionId and actionPolicyLinkId.
Where organizationId goes
GET and DELETE /policy-control/unmap/ take organizationId as a query parameter. The create calls (POST /policies/, /policies/categories/, /policies/from-templates/, /policy-control/map/) carry it in the JSON body. Calls on one existing record (PATCH, DELETE, archive, restore, approve, mark-reviewed, reorder) take no organizationId: devguard reads it from the record.
POST /policies/{id}/approve/ returns the new version: id, version, policyId, title, content, status (PUBLISHED), approvedAt, approvedBy (a user id), changelog, the snapshots of category, control coverage and images, organizationId and createdAt.
curl -X POST \
"https://app.devguard.ch/api/policies/<policy id>/approve/" \
-H "Authorization: Bearer dvg_…" \
-H "Content-Type: application/json" \
-d '{"version": "1.2.0",
"changelog": "Former staff lose access."}'The policy id goes in the path only. The body takes no organizationId.
Errors
Errors come back as { message, code }. A validation failure reads Input validation failed with details in issues.
| Situation | Status | Message |
|---|---|---|
| Approve by someone outside the approver role | 403 | Only the assigned approver can approve this policy. |
| Mark reviewed by someone outside the approver role | 403 | Only the assigned approver can mark this policy reviewed. |
| Any change by an auditor | 403 | Your role can read this organization but not change it. |
| Approve with a version number already used | 409 | Version 1.2.0 already exists for this policy |
| Re-acknowledgement without a date, or with a past one | 400 | Input validation failed |
| Mark reviewed on an archived policy | 400 | An archived policy cannot be marked as reviewed. |
| Create at the plan limit | 403 | LIMIT_REACHED:policies |
| Slug already taken | 400 | A policy with the slug "…" already exists. (or names the archived policy holding it) |
| Category name already taken | 400 | A policy category named "…" already exists. |
| Delete a category that still holds policies | 500 | a general error |
AI assistant and MCP
The AI assistant has these policy tools: listPolicies, getPolicy (full text by section, with each uid), createPolicy, listPolicyCategories, createPolicyCategory, listPolicyTemplates, createPoliciesFromTemplates, getPolicyControlMappings, mapControlToPolicy, unmapControlFromPolicy, autoMapControls and undoAutoMapControls. The MCP server gives a connected assistant the reading tools only (listPolicies, getPolicy, listPolicyCategories, listPolicyTemplates, getPolicyControlMappings), each policy as the resource devguard://policy/<slug>, and a policy-review prompt. The CLI has no policy commands; it serves evidence.
How is this guide?
Templates
Every built-in template in one place, those for your frameworks first; read one before you add it, and adding it creates an editable copy in your organization.
The policy editor
How the policy editor works, with sections, the contents list, the block and reference menus, images, tables, and the cards on the right.