acute/cloud.sr2.uk
1
0
Fork 0
forked from sr2/cloud.sr2.uk
Code Pull requests Activity

Integrate Admin Docs from notion

Browse source
This commit is contained in:
Ana Custura 2026-05-06 13:31:23 +01:00
parent a9728926f9
commit bb4049db1a
26 changed files with 309 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

54
docs/link/autoresponders.md Normal file
View file

@ -0,0 +1,54 @@
---
title: Autoresponders
sidebar_position: 103
---
# Setting up an autoresponder (WhatsApp/Signal auto reply)
In order to setup automatic replies for WhatsApp or Signal you need to:
1. use Zammad in version 6.1.0 or newer
2. have previously created WhatsApp/Signal bot
3. create a webhook:
- go to Settings → Webhook → New Webhook
- give it any name
- the endpoint is (for link based instances):
```
http://link:3000/link/api/whatsapp/bots/<bot-token>/send
http://link:3000/link/api/signal/bots/<bot-token>/send
```
where the \<bot-token\> can be found in admin panel of your helpdesk (helpdesk-name-admin.cdr.link) - go to WhatsApp/Signal, click on the bot, copy the token
- HMAC SHA1 SIGNATURE TOKEN - leave empty
- SSL VERIFY - no
- HTTP BASIC AUTHENTICATION USERNAME - empty
- HTTP BASIC AUTHENTICATION PASSWORD - empty
- CUSTOM PAYLOAD - use json below, you can modify it in order to create more customised message body:
```json
{
"to": "#{ticket.customer.phone}",
"message": "Your ticket has been received."
}
```
- set the Webhook to active and press ‘Submit’
4. now you need to create a Trigger:
- go to Settings → Trigger → New Trigger
- set the name
- ACTIVATED BY - Action
- ACTION EXECUTION - Selective (default)
- CONDITIONS FOR AFFECTED OBJECTS*:
- Action is Created
- State is not closed
- (Article) Type is cdr_signal/cdr_whatsapp
- EXPERT MODE - off
- EXECUTE CHANGES ON OBJECTS: Webhook: webhook created in point 3
- optional note
- set to active and Submit
<aside>
🤩 Thats it!
</aside>

25
docs/link/google_channel.md Normal file
View file

@ -0,0 +1,25 @@
---
title: Setting up a Google channel
sidebar_position: 102
---
# Setting up a Google channel
1. Create a new project called "Zammad" under the desired Google account from [https://console.cloud.google.com/apis/dashboard](https://console.cloud.google.com/apis/dashboard) (a new project is required to create the secure Google App that is linked to the helpdesk).
2. Enable the Gmail API for this project by going to [https://console.cloud.google.com/apis/library/browse](https://console.cloud.google.com/apis/library/browse), selecting Gmail API and then enabling it. This is the API needed for communication between the helpdesk and Google.
3. Create a Google Application called "Zammad", by going to [https://console.cloud.google.com/apis/credentials/consent](https://console.cloud.google.com/apis/credentials/consent).
Give this application permissions to read, write and modify (but not delete) emails in the inbox for the Google account that needs to be linked to the helpdesk, by granting it the Gmail API "modify" scope. We created this application as it will be used by the helpdesk to receive and send emails.
4. Create OAuth credentials by going to [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials). Here configure the permitted callback url to be [https://\<instance-name\>/api/v1/external_credentials/google/callback](https://demo.cdr.link/api/v1/external_credentials/google/callback). This will create a Google client ID and secret.
5. Finally, link the helpdesk (Zammad) to the Google application by configuring a Google channel in [https://\<instance-name\>/#channels/google](https://cchub.cdr.link/#channels/google). Select "Configure App", where you can introduce the OAuth credentials (client ID and secret) created in the previous step.
6. Select "Add account" from [https://\<instance-name\>/#channels/google](https://demo.cdr.link/#channels/google)
from a browser session where you are logged into Google with the same email address that will be linked to the helpdesk. When prompted, opt to keep all messages on the server; otherwise Zammad will try to delete them.
## Troubleshooting
1. If the final step fails with a ‘403 forbidden’ error, it may be necessary to log into the helpdesk as the user, go to ‘Profile’:
![Untitled](/docs/link/admin/google_channel/Untitled.png)
From there, navigate to ‘linked accounts’, and select ‘remove’:
![Untitled](/docs/link/admin/google_channel/Untitled1.png)

96
docs/link/pgp.md Normal file
View file

@ -0,0 +1,96 @@
---
title: PGP plugin usage
sidebar_position: 100
---
# PGP plugin usage
## Enabling the PGP plugin
1. To check whether the PGP plugin is installed, check the Integrations tab in Zammad. This should show ‘PGP’ in the list of integrations. A green dot will appear next to its name if the plugin is enabled - here the plugin is not yet enabled:
![Untitled](/docs/link/admin/pgp/Untitled.png)
1. To enable the plugin, open the settings for ‘PGP’, and toggle the switch in the top left corner of the page:
![Untitled](/docs/link/admin/pgp/Untitled1.png)
## Sending encrypted email to a user
1. The ‘Public and Private Keys’ section will display all the known encryption keys and associated emails. To be able to send encrypted email to an email address, it is necessary to upload the public key associated with that email address. Usually the public keys will be sent from the PGP users themselves, as attachments to tickets created via email. Here’s an example of such a ticket:
![Untitled](/docs/link/admin/pgp/Untitled2.png)
1. To be able to reply to this user using encrypted email, download this attachment and upload it to the ‘Public and Private Keys’ section of the PGP integrations, by selecting ‘Add Public Key’, and then ‘Browse’:
![Untitled](/docs/link/admin/pgp/Untitled3.png)
1. The PGP key fingerprint and email will now show up in the list:
![Untitled](/docs/link/admin/pgp/Untitled4.png)
1. Replying on the ticket will now show the option to ‘Encrypt’, enabled by default. This means the reply will be sent encrypted. The padlock can be clicked to disable encryption.:
![Untitled](/docs/link/admin/pgp/Untitled5.png)
## Receiving encrypted email from a user:
1. To receive encrypted email, a PGP key must be generated for the helpdesk email. For example, on Linux systems, this can be done using the `gpg` command, and filling in the name and email address for the new key. In this example, we create a key for ‘helpdesk’ with email address ‘help@cdr.link’:
```ruby
gpg --gen-key  ✔  8074  13:16:03
gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
```
```ruby
Note: Use "gpg --full-generate-key" for a full featured key generation dialog.
GnuPG needs to construct a user ID to identify your key.
Real name: helpdesk
Email address: help@cdr.link
You selected this USER-ID:
"helpdesk [help@cdr.link](mailto:help@cdr.link)"
Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key 032591C6B1918366 marked as ultimately trusted
gpg: revocation certificate stored as '/home/helpdesk/.gnupg/openpgp-revocs.d/78A30920D68F5F1A6C6912D4032591C6B1918366.rev'
public and secret key created and signed.
pub rsa3072 2022-07-27 [SC] [expires: 2024-07-26]
78A30920D68F5F1A6C6912D4032591C6B1918366
uid helpdesk [help@cdr.link](mailto:help@cdr.link)
sub rsa3072 2022-07-27 [E] [expires: 2024-07-26]
```
1. Export both the public and private keys just created.
```ruby
gpg --export -a helpdesk > helpdesk.pub
gpg --export-secret-key -a helpdesk > helpdesk.priv
```
1. The next step is to upload the helpdesk’s public and private keys to Zammad. The private key will be used to decrypt messages that were sent encrypted to the helpdesk. The public key will be distributed to the helpdesk users who wish to send encrypted email. First, upload the public key to the ‘Public and Private Keys’ section of the PGP integrations, by selecting ‘Add Public Key’, and then ‘Browse’ and selecting the public key exported in the previous step:
![Untitled](/docs/link/admin/pgp/Untitled6.png)
1. Now add the private key, by selecting ‘Add Private Key’, and then ‘Browse’ and selecting the private key exported in the previous step:
![Untitled](/docs/link/admin/pgp/Untitled7.png)
The display should now indicate the private key was uploaded
![Untitled](/docs/link/admin/pgp/Untitled8.png)
1. Ticket replies will now be sent signed by default. When an encrypted email is sent by a user, its contents will automatically be decrypted and displayed in a ticket.
⚠ Note: for a user to be able to send encrypted email to the helpdesk, the helpdesk public key must first be distributed to that user.

134
docs/link/project_separation.md Normal file
View file

@ -0,0 +1,134 @@
---
title: Setting up projects in CDR Link
sidebar_position: 101
---
# Setting up projects in CDR Link
Setting up separate Projects in CDR link relies on groups, roles and also channel setup. This document details a minimal configuration for setting up such a Project that uses a simple email channel to receive notifications from customers.
## Terminology
`Link Instance Admin` = person with full admin rights over a link instance
`Link Instance Customer`= any person that submits a message via any of the configured channels of a Link instance
`Link Instance Agent` = a person specifically set up in Link to work on tickets submitted by Customers
`Channel Admin` = person responsible for setting up and administering the infrastructure that will be used to receive and send email messages and notifications for a specific project.
- in the case of email, this will be a mailbox
- in the case of whatsapp and signal, it will be a handset and sim card
- in the case of sms, this will be a twilio account and number
- in the case of telegram, this will be a telegram bot
## Prerequisites
Before adding a project to CDR link, the following must be decided:
- which channels will this project use?
Once channels are decided on, the Link Instance Admin can liaise with the Channel Administrator to set up the required channels and configure them in Link.
- what will be the project name?
Once the project name is known, groups, roles and overviews may be set up as per steps 1, 2, 3 below. Once a group is created, channels will require a modification as per step 4 below.
- who will be the project agents?
Once the agents are decided on, the Link Instance Admin can add them in Link, as described in step 5 below.
If an email signature is desired for the project, it can be configured prior to the steps below according to [https://admin-docs.zammad.org/en/latest/channels/email/signatures.html](https://admin-docs.zammad.org/en/latest/channels/email/signatures.html)
## 1. Create the required group
Groups are the main ways to differentiate between projects. Each CDR channel will add new incoming tickets to an associated group; and agents working on tickets can be given group permissions to work on them.
In the Admin panel, go the Groups tab, and select New Group.
Add the group name to match the name of the project. The “Assignment timeout” can be left blank. If a signature is already configured it can be selected under “Signature”. If this project uses an Email channel - select it from the drop-down menu under “Email”, then hit Submit.
![Untitled](/docs/link/admin/projects/Untitled.png)
## 2. Create an associated Agent Role
Roles are required to separate permissions between the groups, as they allow custom permissions for agents.
In the Admin panel, go the Roles tab, and select New Role.
![Untitled](/docs/link/admin/projects/Untitled1.png)
Add the name of the new role, then scroll down to select the permissions for this role. Scroll over “admin”, “chat”, “cti”, “knowledge base” and “report” without making selecting them. Do select “agent”, and in the group table below it select only “full” for the group created above. Also select “user_preferences”.
Under permissions, “Default at signup” should be left to “no”.
Apply the changes by hitting “Submit”.
![Untitled](/docs/link/admin/projects/Untitled2.png)
## 3. Create overviews for the new role
By default, Zammad comes with the following Overviews:
![Untitled](/docs/link/admin/projects/Untitled3.png)
The default “Unassigned and Open” and “Open” overviews that come with Zammad allow all agents to see unassigned and open tickets, regardless of their group, even if agents do not have permissions for that group. Agents would not be able to modify tickets without the necessary permissions, however to “hide” the incoming tickets of a group from agents not belonging to that group, new Overviews must be created to take the place of the default “Unassigned and Open” and “Open” overviews that come with Zammad.
3.1 Create a new overview for unassigned and open tickets:
In the Admin panel, go the Overviews tab, and select New Overview. Give it the name “Unassigned & Open - \<project-name\>” and then make the overview available for the role created in the previous step:
![Untitled](/docs/link/admin/projects/Untitled4.png)
Scroll down, and under “Conditions for shown tickets”, select “State” new and open; and use the “+” button on the right to add another condition. Change the condition to limit the shown tickets to the group created in the first step. Ensure the group is highlighted as selected before hitting “Submit”, as in the example below:
![Untitled](/docs/link/admin/projects/Untitled5.png)
3.2 Creating a new overview for open tickets:
If you want to add a second overview for only open tickets, repeat the previous two steps to create an overview called “Open - Group \<your-group-name\>” - which restricts shown tickets by group (once more, ensure the group is highlighted as selected before hitting “Submit”, as in the example above), and only displays tickets in the ’open’ state. Ensure you make the overview available for the role previously created.
3.3 Allow the other default overviews in link to be used by the role previously created.
Edit the “My Assigned Tickets”, “My Subscribed Tickets” and optionally the “My Pending Reached Tickets” default overviews to make them available to the role created earlier:
![Untitled](/docs/link/admin/projects/Untitled6.png)
<aside>
💡 Note that we did not discuss the “Pending reached” or “Escalated” overviews, but the same principles apply - as they have the option of “leaking” information about tickets for other groups new overviews must be created in their place.
</aside>
## 4. Check the email channel setup
Select the Email channel from the Admin panel. Click the group shown under “Destination Group”, and change it to match the group created above.
In the screenshot below we show the email channel for this helpdesk is configured to send tickets straight to group “Demo group 1”:
![Untitled](/docs/link/admin/projects/Untitled7.png)
<aside>
💡 Note: A ticket can be added to a group by default if the channel is configured to do so. Another way that a ticket may be added to a group is manually, by changing the “Group” tab of a ticket by an agent with appropriate permissions.
</aside>
## 5. Adding Agents and verifying the configuration
Agents are added by selecting ‘New Users’ from the ‘Users’ admin tab. When adding a new agent user, ensure to only give assign them the role created in step 2, and untick the default “Agent” and “Customer” roles. Moreover, in the group table underneath, only select “Full” permissions for the group created in step 1. The screenshot below shows a configuration example:
![Untitled](/docs/link/admin/projects/Untitled8.png)
### Finishing and checking agent configurations
To check the configuration for an agent, an administrator can view the helpdesk from that user’s perspective. In the Users tab, click the 3 dots on the right of the target user, and select “View from user’s perspective”:
![Untitled](/docs/link/admin/projects/Untitled9.png)
This will allow you to view the helpdesk as the user - and going to overviews, only the overviews defined in step 3 should be visible.
In this mode, you can also modify that user’s notification preferences.
Access the user’s Profile from the bottom left corner panel, then navigate to Notifications to customize their notification settings. To ensure no notifications are received for any new tickets received in the system for this user, untick all the boxes in the “Not Assigned” column. The user will now only receive notifications whenever a ticket assigned to them is updated.
![Untitled](/docs/link/admin/projects/Untitled10.png)