Roles

A business role is a job in your company, such as "Head of IT" or "Data Protection Officer". In devguard, records are owned by business roles, not by people. A risk, an asset, a vendor or an evidence record names a role as its owner, approver or coordinator. When a person leaves, you put someone else into the role, and every record keeps its owner.

A business role gives no access in devguard. What a person may open and change comes from their app role (Owner, Admin, Member, Auditor, Employee or External), which you set on People.

The tasks below follow the order of the work:

• Create a business role
• Change who is in a role
• See what a role is responsible for
• Archive a role
• Delete a role

Scripts and integrations: see API below.

Create a business role

You need the app role Owner or Admin.

1. Open People, then Roles, and choose Add role.
2. Enter the Name, for example "Data Protection Officer". devguard makes a slug from it, a short unique name for addresses and the API.
3. In Description, write what the role is accountable for.
4. In Required competence, write the education, training or experience the role needs. The competence matrix of trainings shows it.
5. In Members, choose the people who hold the role. One person or several.
6. Choose Save.

Now you can choose the role as an owner, an approver or a coordinator in the registers. For example, choose it as the Owner of a risk, or as the Approver of an evidence record.

Change who is in a role

1. Open the … menu at the end of the role's row and choose Edit.
2. Add or remove people under Members and save.

You can also add one person from People: open the … menu on the person's row and choose Assign Role. Deactivated people are not added to a role. When a person is deactivated later, they no longer count as a member.

See what a role is responsible for

The Responsible for column counts the open work of each role. It counts:

• what the role owns, such as vendors, risks, assets, treatment actions and evidence;
• what the role approves, such as policies and evidence;
• what the role coordinates, such as risk, asset and vendor reviews;
• the policy and training assignments its members must complete.

Each count matches what the register shows. Archived records are not counted.

To see the roles of one person, use the People filter above the list. To see all records of one role, open the register, for example Risks, and filter by owner.

Archive a role

Archive a role that is no longer used, but that old records still name.

1. Open the … menu on the role's row and choose Archive.
2. The menu shows how many people and assignments this affects. These people no longer have to complete the role's policies and trainings. If no one is affected, the menu says so.
3. Choose Archive again to confirm.

The records that name the role keep it. The members of an archived role get no more reminders for the role's policies and trainings. They are also removed from the lists of open policies and trainings, unless another role or a direct assignment still includes them. To see archived roles, choose Archived in the toolbar. Restore in the row menu brings a role back with its assignments.

Delete a role

1. Open the … menu on the role's row and choose Delete.
2. Choose Delete again to confirm. A deleted role cannot be restored.

devguard refuses to delete a role that is still the owner, approver or coordinator of any record, archived records included. It also refuses when the role is the only audience of a process. Give those records another role first, or archive the role instead.

Reference

Fields

Permissions

Employees and external contacts do not see the app, but they can be members of a business role.

API

• Base URL: https://app.devguard.ch/api.
• Authentication: an API token, sent as Authorization: Bearer <token>.
• Member ids: memberIds holds member ids, not user ids. A member id is the last part of a person's page address, /people/detail/<member id>/.

Create needs organizationId, name and slug. description, requiredCompetence and memberIds are optional.

Update needs name, slug and memberIds. memberIds replaces the whole member list, so send everyone who should stay in the role. To add one person, read the role first and send its memberIds plus the new id.

The list returns { "items": [...], "total": 14, "page": 1, "limit": 100 }. limit is 100 at most. Send includeResponsibilities=true to fill each item's responsibilities counts; without it they are all 0.

In the examples, DG_TOKEN is your API token and DG_ORG your organization id. This call lists the roles with their members:

API=https://app.devguard.ch/api
curl -sS -G "$API/business-roles/" \
  -H "Authorization: Bearer $DG_TOKEN" \
  --data-urlencode "organizationId=$DG_ORG" \
  | jq '.items[] | {name, slug, memberIds}'

This call creates a role with two members. The member ids are examples:

curl -sS -X POST "$API/business-roles/" \
  -H "Authorization: Bearer $DG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "'"$DG_ORG"'",
    "name": "Works Council",
    "slug": "works-council",
    "memberIds": ["<member id 1>", "<member id 2>"]
  }'

The response is the new role. memberIds holds only the active members you sent:

{
  "id": "5f0c2a9e-3b1d-4c7e-9a40-2d6e8f1b7c35",
  "slug": "works-council",
  "name": "Works Council",
  "description": null,
  "requiredCompetence": null,
  "archivedAt": null,
  "organizationId": "<your organization id>",
  "memberIds": ["<member id 1>", "<member id 2>"]
}