Documentation: ClientDesk
ClientDesk is a CRM plugin for Redmine. It manages clients, deals, and products inside a project, links requests to contacts, and handles email without a separate CRM.
The CRM interface opens inside the Redmine page. An open client, deal, or product is kept in the page URL, so you can refresh the link or share it with a colleague.
Key Features
What is added to Redmine
- Project module “ClientDesk” and a project menu item ClientDesk.
- Top menu and application menu. The ClientDesk item can be enabled separately. It opens CRM across all accessible projects.
- Administration menu. The ClientDesk item opens the plugin settings.
- Issue. Contact field, client card in the sidebar, reply to client, templates, rating, and AI suggestion.
- Issue list. Extra columns and filters for contact, company, channel, reaction time, response time, resolution time, and rating.
- Redmine search. The Clientdesk checkbox searches clients, deals, and products.
- Custom fields for clients, deals, and products.
Clients, deals, and products
- Clients — contacts and companies. A contact has a company, email, phone, address, country, language, assignee, and notes.
- Deals — status, amount, currency, due date, note, and line items from the catalog.
- Products — goods, service, or subscription, with prices in different currencies.
- Subscriptions — deal line items with a period of 1 month or 1 year. The card shows active and expired ones.
- Dashboard — summary of clients, deals, and products. The blocks depend on user permissions.
- Change journal for a client, deal, and product.
Email, replies, and rating
- IMAP — project inboxes. An email creates an issue or a comment on an already open issue.
- SMTP — outgoing profiles. The project selects a profile for replies to the client.
- Reply templates with placeholders for the client name, issue number, and other fields.
- Request rating. When an issue is closed, the author can receive an email with a link. The link opens without signing in to Redmine.
- Auto-closing requests after a set number of hours, with an email to the client.
- AI. On the issue page you can generate a reply from a short prompt.
- Import from RedmineUp — contacts, companies, deals, and products. Linking issues to new contacts is a separate action.
Who it is for
- Support — email requests, replies to clients, and quality ratings.
- Sales — clients, deals, catalog, and subscriptions.
- Redmine administrator — deal statuses, email, templates, and import.
Compatibility
Redmine: 6.0 - 7.0
Databases: MySQL, PostgreSQL, SQLite
REST web service must be enabled in Redmine settings. Otherwise the plugin settings page shows the warning “Enable REST web service”.
Installation and Update
-
Remove the old plugin version if it is installed.
cd redmine/plugins rm -r clientdesk -
Copy the
clientdeskfolder intoredmine/plugins/. -
Run migrations from the Redmine root.
bundle exec rake redmine:plugins:migrate RAILS_ENV=production NAME=clientdesk -
Stop and start Redmine. In some setups, for example Docker, a full stop and start is required, not a restart.
Uninstallation
-
From the Redmine root run:
bundle exec rake redmine:plugins:migrate RAILS_ENV=production NAME=clientdesk VERSION=0 -
Remove the plugin folder.
cd redmine/plugins rm -r clientdesk -
Stop and start Redmine.
Setup
- Enable REST web service in Redmine settings.
- Grant permissions in Administration → Roles and permissions, section ClientDesk.
- Enable the ClientDesk module in Project → Settings → Modules.
- Open the plugin settings and create deal statuses.
- If client replies are needed, create an SMTP profile and select it in the project settings.
- If incoming email is needed, add an IMAP mailbox and link it to the project.
Administration
Plugin settings are available to a Redmine administrator in two ways.
- Administration → Plugins → ClientDesk CRM plugin → Configure.
- Administration → ClientDesk.
General tab
- Show in top menu — ClientDesk item in the Redmine top menu.
- Show in application menu — ClientDesk item in the application menu.
- Contact name format — “First Last”, “First Middle Last”, “Last First”, or “Last First Middle”.
- Default country for new contacts.
- Default language for new contacts.
- Available currencies — the list used for deal currency and product prices.
- Automatically close requests after — number of hours. Closing is done by a background job, see below.
- Send an automatic email to the client — subject and body of the closing email. Both fields are required when the option is enabled.
You can insert into the closing email subject and body: %{ticket.id}, %{ticket.subject}, %{ticket.project}, %{ticket.author.name}, %{ticket.author.email}, %{client.name}, %{ticket.status}.
Mail tab
List of IMAP mailboxes. A mailbox is linked to a project.
For a mailbox you set host, port, username, password, authentication method, connection security, and SSL verification. Then you set the IMAP folder, the folder for successfully processed messages, and the folder for failed messages.
Issue creation rules:
- tracker and status of the new issue;
- Create contacts — a new contact for an unknown sender;
- Use issue number from the subject — if the subject contains an open issue number, the email becomes a comment instead of a new issue;
- Sender blacklist — one pattern per line; regular expressions are allowed.
The “Test connection” button shows the folder, message count, and new message count.
SMTP tab
Outgoing profiles: host, port, account, password, connection security, and sender address. One profile can be marked as the default. In a project you can select this profile, another profile, or the shared Redmine email settings.
Deal statuses tab
A shared directory for all projects. A status has a name, color, active flag, and type: Open, Won, or Lost. Order is changed by dragging rows. A status already used on a deal cannot be deleted.
Reply templates tab
A template is a name and text. Client, issue, and reply author fields can be inserted into the text:
%{client.name}, %{client.first_name}, %{client.last_name}, %{client.email}, %{ticket.id}, %{ticket.subject}, %{ticket.project}, %{ticket.tracker}, %{ticket.status}, %{response.author}, %{response.author.first_name}, %{response.author.last_name}.
On the issue page the template is selected from the “Insert template” list. This requires issue edit permission and client view permission.
Communications tab
A journal of incoming and outgoing messages. It shows which emails already created an issue or comment so the same email is not processed twice. This tab has no settings save button.
AI tab
Address of the service the plugin calls to generate a reply. Behavior on the issue page is enabled in the project settings.
Request rating tab
A shared email template asking to rate the request. The checkbox “When closing an issue, ask the author for a rating” enables the template. Subject and body are required.
Below is a table of projects with the ClientDesk module. For each project choose a mode: Disabled, Use admin template, or Project template. The admin template mode is available when the shared template is filled in and enabled.
On this tab, template variables use curly braces: {%ticket.id%}, {%ticket.subject%}, {%ticket.project%}, {%ticket.author.name%}, {%ticket.author.email%}, {%client.name%}, {%vote.url%}.
Import tab
Three actions, for administrators only.
- Import from RedmineUp — creates contacts, deals, and products. Issues are not linked at this step.
- Link issues to new contacts — takes links from helpdesk for already imported clients. An issue that already has a ClientDesk contact is skipped.
- Delete all — permanently deletes contacts, companies, deals, products, notes, and issue links. Deal statuses, mailboxes, and templates remain.
If RedmineUp tables are missing in the database, import reports this and creates nothing.
Roles and permissions
In the ClientDesk section:
- View clients — client list and card, notes, search, contact field on an issue.
- Manage clients — create, edit, and delete clients and notes; create a contact from the issue card.
- View deals — deals and subscriptions.
- Manage deals — create, edit, and delete deals.
- View products — catalog.
- Manage products — create, edit, and delete products.
Manage permission does not include view permission. Grant them separately.
The ClientDesk menu item is visible when the module is enabled and there is at least one view permission: clients, deals, or products. Tabs inside CRM are shown according to their permissions.
Project email settings are changed by a user with project edit permission. CRM permissions are not required for that.
Background jobs
Mail fetching can be started manually from the project settings. For scheduling, from the Redmine root:
bundle exec rake clientdesk:fetch_mail
Auto-closing requests runs only with this command:
bundle exec rake clientdesk:auto_close_issues
Project Settings
Project → Settings → ClientDesk.
IMAP
List of incoming mailboxes for this project. A project can have several mailboxes. From here you can also run “Test connection” and “Fetch mail”.
After fetching, the page shows how many emails were processed, how many issues were created, and how many comments were added.
SMTP
Outgoing profile for replies to clients. If no profile is selected, a reply shows a warning: set SMTP in Settings → ClientDesk → Mail.
Feedback
When closing an issue, ask the author for a rating:
- Disabled;
- Use admin template;
- Project template — custom subject and body. Both fields are required.
Project template placeholders: %{ticket.id}, %{ticket.subject}, %{ticket.project}, %{ticket.author.name}, %{ticket.author.email}, %{client.name}, %{vote.url}.
AI settings
- Enable AI suggestions for client replies and the system prompt.
- Enable a prefilled prompt for clients and the text of that prompt.
Usage
Opening CRM
Project → ClientDesk.
Tabs:
- Dashboard — client, deal, and product counters. With deal permission, currency totals and subscriptions are also shown.
- Clients.
- Deals.
- Products.
The CRM header has search across clients, deals, and products in the current context. Lists can be filtered and saved as a query.
The top menu or application menu item opens the same CRM without binding to one project. Lists include records from projects where the module is enabled and view permission exists.
Clients
List filter: All, Contacts, Companies.
The client card shows contact details, related deals, issues, notes, and custom fields. For a contact you can create a company directly in the company field. A company card shows its contacts.
Main contact fields: first name, middle name, last name, email, phone, job title, company, birthday, address, city, region, country, language, website, tax ID, source, assignee, and “Do not contact”. For a company — name, industry, and company size.
Files can be attached to a client through custom fields of type “file”. The journal shows who changed the record and when.
A client belongs to a primary project. It can also be made visible in other projects: parent and child projects of the primary one, all projects, or the “Additionally available in projects” list. Linking an issue or email to the client’s project does not add the client to that project by itself.
If an email already exists when creating a contact, the plugin does not create a second card. It offers to open the existing contact, add the project to visibility, or change the primary project. Available actions depend on permissions.
“Remove from project” hides the client in the current project and keeps it in the primary one. Deleting the card is done in the primary project. A client linked to issues or deals cannot be deleted.
Deals and subscriptions
A deal is linked to a client and a project. It has a name, status, amount, currency, due date, note, and line items. A line item is a product, quantity, price, and order number. The product comes from the selected project catalog. The price uses the deal currency.
From a client card you can create a deal with the client already selected. A deal can be moved to another project if manage deals permission exists in both projects and the client is visible there.
A subscription is a product of type “Subscription” with a period of 1 month or 1 year. The start date is set on the deal; the end date is calculated from the period. If the deal due date does not match subscription end dates, the plugin offers to replace the due date.
On the issue page, hovering the contact name opens a card: name, email, deals, and subscriptions. Active and expired subscriptions are shown separately. If the contact has a company, the card also shows its deals. Deals of other contacts of that company are grouped under “Other deals”.
Products
Project catalog. Product type: Goods, Service, or Subscription. A subscription requires a period. A product has a name, description, SKU, and prices. Price currency is chosen from “Available currencies”.
A product already used in a deal cannot be deleted. The product card shows deals where it is used.
Issues
If the module is enabled and “View clients” permission exists:
- In the issue form find the contact field and start typing a name. Search starts after two characters.
- Select a contact and save the issue.
- On the issue page the contact is shown in a block and in the sidebar card. You can change or clear the card without opening CRM.
- With “Manage clients” permission you can create a contact from that card.
An issue has one current contact. Changing the contact is stored in the request history.
You can add columns and filters to the issue list: contact, contact company, request channel, first reaction time, first response time, resolution time, client rating, last message and its date. Channels: email, phone, chat, API. Selected columns are included in the issue list export.
Reply to client
In a comment on an issue with a contact there is “Reply to client”. You can set To, Cc, and Bcc. The email is sent through the project SMTP. The issue journal notes that a reply was sent. A client reply from email arrives as a comment and is marked as a client reply.
Above the comment field there is “write a reply with AI” if suggestions are enabled in the project. A short prompt and issue data are sent to the AI service; the resulting text is placed in the comment field.
Request rating
If rating requests are enabled in the project, when an issue is closed the author receives an email with a link. The rating page opens without signing in. Ratings: Excellent, Normal, Poor. A comment is optional. The latest rating is stored. It is visible on the issue and in the issue list column.
Redmine search
On the search page and in the header quick search there is a Clientdesk checkbox. It searches clients, deals, and products as one group. The Clientdesk (N) counter keeps only those results.
In a single project the checkbox is shown when the module is enabled and view permission exists. When searching across multiple projects the checkbox is always shown, but records from inaccessible projects are not returned.
Search covers name, title, email, phone, job title, website, tax ID, deal name and note, product description, and custom fields marked “Searchable”. Notes and attachments are not searched. “Search titles only” keeps names and titles.
A result link opens the card in CRM.
Frequently Asked Questions
Why is the ClientDesk menu missing?
Check three conditions.
- The ClientDesk module is enabled in the project.
- The role has at least “View clients”, “View deals”, or “View products”.
- For the item outside a project, “Show in top menu” or “Show in application menu” is enabled, and the same view permission exists in at least one project.
Why does the settings page say “Enable REST web service”?
CRM works through the Redmine REST API. Enable the service in Administration → Settings → API.
Can I import CRM data and link issues immediately?
No. First “Import from RedmineUp”, review the cards, then “Link issues to new contacts”. If import failed, “Delete all” clears imported data and does not touch statuses, mail, or templates.
Why did an email not become a new issue?
If the subject contains an already open issue number and “Use issue number from the subject” is enabled, the email is added as a comment. An email from the blacklist does not create an issue. A repeated email is visible on the “Communications” tab.
Who can see the client rating?
The request author sets the rating via the email link. In Redmine it is visible on the issue and in the issue list column to users who can access the issue.