devguard
Collections

Collections

Keep the terms, tags, places, review cycles and fixed values your organization reuses in one place, so every policy and register uses the same words.

Collections are short lists of facts that the rest of devguard reuses: terms, tags, places, cycles and fixed values. You keep each item once, for example the company's legal name or the "every quarter" review cycle. Policies, registers and reports point to that item. When you change it, every place that uses it shows the new version.

The tasks below follow the order of the work:

Each collection has its own guide: acronyms, definitions, labels, locations, schedules and variables. Scripts and integrations: see API below.

Choose the right collection

You want toUse
Print the same value in many policies, such as the legal name or a retention period, and change it in one placeVariables
Explain a term your documents rely onDefinitions
Spell out short forms such as ISMS, and link them to a definitionAcronyms
Tag risks, assets, vendors, evidence, incidents and processes, and filter lists by the tagLabels
Say where assets and vendors are, with an addressLocations
Set how often something is reviewed, repeated or run, such as "every quarter"Schedules

Every collection item can also be mentioned in a policy or record. The difference that matters most: a variable holds a value that the PDF prints, a definition holds an explanation that readers look up.

Mention an item in a policy or record

A mention is a link to a collection item inside the text. The editor always shows the item's current name. When someone changes the item, every mention shows the change.

  1. Open a policy or a record in the editor and click in the text.
  2. Type : and the first letters of the item, for example :cadence. A menu lists the matching items, grouped by type, such as Variables or Policies. Each match shows its type and, for a variable, its value.
  3. Choose the item with the mouse or with Enter. It appears as a small badge in the text.
  4. Choose Save.
Typing ":cadence" offers the variable, Enter inserts it as a badge, and a click on the badge opens its card.

To check a mention, click the badge. A card shows the type, the name and the details, such as a variable's value or an acronym's full form. Open details opens the item.

The badge Access review cadence in the policy text, with its card open: Variable, the value "Quarterly for privileged access, semi-annually otherwise" and Open details.
The card shows the value that the policy PDF prints in place of the badge.
The same policy section in the generated PDF: the badge is replaced by the text "Quarterly for privileged access, semi-annually otherwise", underlined with dots.
In the PDF, the variable's value stands in the sentence. A dotted underline marks it.

In the policy PDF, a mention prints as text:

Mention ofThe PDF prints
VariableThe value
AcronymThe full form (Extended)
LocationThe address
LabelThe scope and the name, such as privacy:Personal data
Definition, scheduleThe name

If the item has no value of that kind, the PDF prints its name.

Import or export a collection

Each collection list has a menu at the top right (...).

  1. To start a new list, choose Download CSV template. The file has one column for each field.
  2. Fill in one row per item and save the file as CSV.
  3. Choose Import CSV and select the file. If the slug column is empty, devguard makes the slug from the name.
  4. Read the result. Rows with an error are listed with the row number and the reason. The other rows are added.

To export, choose Export all. If filters are set, Export n filtered entries exports only the rows that match them. To export some rows, select them and use the bulk action.

The Labels list filtered by Scope classification, three of twelve labels, with the menu open: Import CSV, Download CSV template, Export 3 filtered entries and Export all.
With the Scope filter set, the menu offers to export the three matching labels or all twelve.

The column names for each collection are on its page, under CSV columns.

Archive or delete an item

Archive an item you no longer use. Delete it only when you are sure no one needs it again.

Archive

  1. In the list, open the row menu (...) and choose Archive.
  2. The item leaves the list, the : menu and the pickers. Risks, assets, policies and other entries that already use it keep it.

Restore

  1. Turn on Archived above the list.
  2. Open the row menu and choose Restore.

Delete

  1. Open the row menu, or select rows, and choose Delete.
  2. The item and its comments are deleted. You cannot undo it.

Watch out: a deleted label disappears from every entry that had it. A deleted location or schedule leaves the field empty where it was used. A mention of a deleted item stays in the text, and its card says the item no longer exists. The PDF prints the item's old name instead of its value.


Reference

Fields every collection has

FieldRequiredNotes
Name (Acronym for acronyms)yes2 to 255 characters.
SlugyesThe item's address, for example /collections/labels/detail/quick-win/. Lowercase letters, numbers and hyphens. devguard makes it from the name. The form shows it only in Expert Mode. It must be unique in the collection, archived items included.

Each item has three tabs: Detail, Comments (type @ to mention a colleague) and History, which shows its audit log. On a location or a schedule, the Detail tab also lists what uses it, under Related Data. On an acronym or a definition, it lists the linked definition and acronyms.

Each list has a name filter, a Last updated filter and the Archived switch. Collection items also appear in search.

Permissions

RoleCollections
Owner, adminCreate, edit, archive, delete, import
MemberRead and comment
AuditorRead
Organization tokenCreate, edit, archive and delete over the API
EmployeeNo access

A member's own API token can only read collections. An API token with limited scopes needs this scope family:

CollectionScope family
Acronyms, definitions, variablesControls & frameworks
LabelsOrganization structure
LocationsAssets
SchedulesTasks

API

  • Base URL: https://app.devguard.ch/api.
  • Authentication: an API token, sent as Authorization: Bearer <token>. Send JSON with Content-Type: application/json.
  • Collection paths: acronyms, definitions, labels, locations, schedules and variables. All six have the same calls. The create fields are on each collection's page.
CallEndpointOrganization id
ListGET /<collection>/query, required
CreatePOST /<collection>/body, required
ReadGET /<collection>/{id}/not used
UpdatePATCH /<collection>/{id}/not used
ArchivePOST /<collection>/{id}/archive/not used
RestorePOST /<collection>/{id}/restore/not used
DeleteDELETE /<collection>/{id}/not used

The list takes page, limit (5 to 100, default 100), filterByName, filterByArchived (active, the default, or archived), sort and filters. It returns { "items": [...], "total": 12, "page": 1, "limit": 100 }.

filters and sort are JSON, sent as one query value each:

  • sort: a list such as [{"id":"name","desc":true}]. The sortable column is name (acronym for acronyms).
  • filters: an object. Every collection has updatedAt, as {"type":"date","preset":"last30"} or with from and to dates. Acronyms add definition, labels scope, and schedules frequency, each as {"type":"in","values":[...]}. Frequency values are DAILY, WEEKLY, MONTHLY, YEARLY, HOURLY and MINUTELY.

A single item comes back without the wrapper. All collections return id, slug, organizationId, createdAt, updatedAt and archivedAt (null unless archived) next to their own fields:

GET /variables/{id}/
{
  "id": "e50abdd5-1b15-42b5-a4e0-7e9a23488e79",
  "slug": "access-review-cadence",
  "name": "Access review cadence",
  "value": "Quarterly for privileged access, semi-annually otherwise",
  "createdAt": "2026-10-20T09:12:44.000Z",
  "updatedAt": "2026-10-20T09:12:44.000Z",
  "archivedAt": null,
  "organizationId": "<organization id>"
}

PATCH needs these fields even when you change something else:

  • every collection: slug and the name field (acronym for acronyms);
  • variables: also value;
  • schedules: also ruleSet.

Optional fields you leave out keep their value. Send null to clear one. An empty string also clears a text field, but not latitude, longitude or definitionId. There is no bulk delete in the API.

This call lists all variables with their values. DG_TOKEN is your API token and DG_ORG is your organization id:

List variables
API=https://app.devguard.ch/api

curl -sS -G "$API/variables/" \
  -H "Authorization: Bearer $DG_TOKEN" \
  --data-urlencode "organizationId=$DG_ORG" \
  | jq '.items[] | {name, value}'

Errors: 400 when a field is not valid or the slug is already used (the message says if the other item is archived). 401 without a valid token. 403 when the id belongs to another organization or your role cannot write. 404 when the id does not exist.

How is this guide?

On this page