Communication Module — User Guide

1. Overview

The Communication module provides dual-channel messaging inside Vertex ERP: internal messages between users and groups, and external email via SMTP/IMAP, plus search, audit, and operational monitoring.

Internal messages use numeric enums for type, priority, and delivery status. External mail uses folder and queue statuses. UI labels may appear in Arabic or English depending on language settings.

Cross-module note: Compose and groups load users from Identity. ERP link search is a placeholder. A notification bridge toward HR internal notifications exists in code but is not actively pushed from send/read today.

2. Getting started

2.1 Recommended setup order

1. Grant Communication permissions to roles (admin seed may already grant all).
2. Configure tenant SMTP/IMAP under Email SMTP/IMAP settings.
3. Create email accounts used as From identities.
4. Create groups and members before group messaging.
5. Use internal compose, inbox, and sent for day-to-day messaging.
6. Use external compose and inbox after SMTP works; watch the queue and logs.
7. Optionally maintain email templates for reuse.
8. Treat ERP links and email policies as not ready for production use.

2.2 Main navigation

Thread detail opens at /communication/threads/:id when you open a message.

2.3 Host setting

Confirm this is off in environments that must deliver real mail.

3. Dashboard

Requires Communication.Dashboard.

Shows live KPIs such as:

• Unread internal messages (non-archived)
• Messages you sent today
• Active groups
• Pending and failed email queue items
• Total internal messages

Quick links jump to inbox, compose, groups, and related screens. Use the dashboard as a daily pulse, not as a full mailbox replacement.

4. Internal messaging

4.1 Capabilities

4.2 Message model

4.3 Internal send and read flow

1. Choose recipients (users) and/or a group.
2. Enter subject, body, and priority.
3. Attach files if needed (requires Attach permission).
4. Send — recipients appear in their inbox with delivery status Delivered.
5. Opening / marking read sets delivery status to Read.

Group sends also require SendGroup when a group is selected.

4.4 What is not available in the UI yet

• Forward and archive actions (backend exists; no primary UI)
• Soft delete of messages (permissions exist; no delete API/UI)
• Export of messages

5. Groups

Requires CreateGroup and/or ManageGroup.

Key data

Membership flow

1. Create the group and set type.
2. Add members (ManageGroup).
3. Compose with the group selected — each member receives the message.
4. Update or deactivate groups when membership changes.

6. Attachments

Files are stored by the Communication file storage service. Admins with Communication.Admin can follow elevated access paths where implemented.

Keep attachments within your organizational size and sensitivity policies even if email policy entities are not yet enforced in the UI.

7. External email

External mail is stored separately from internal messages (email message, recipients, attachments, folders).

7.1 Folders and statuses

7.2 Send flow

1. Open Compose email and choose From account, To/Cc/Bcc, subject, and body.
2. Send — an email message is created as Queued and a queue item as Pending.
3. Background worker processes the queue about every 30 seconds.
4. Success → Sent; failure → Failed (retries up to the configured max, typically 3).
5. Use Email queue to retry or cancel failed/pending items.

Reply and forward are supported by the email APIs and permissions (Email.Reply, Email.Forward). Prefer reply from the open message when the screen offers it.

7.3 Receive flow

IMAP must be configured (tenant settings and/or per-account API). The sync worker runs per tenant on a fixed interval.

8. Email accounts and server settings

8.1 Email accounts

Path: /communication/email-accounts
Permission: Email.ManageAccounts

Create mailbox identities (address, display name, optional linked user, default/active flags). These identities appear as From options when composing external mail and can be targets for sync.

The accounts screen focuses on identity fields. Per-account SMTP/IMAP can be saved via API; most deployments configure tenant-wide settings first.

8.2 Tenant SMTP / IMAP settings

Path: /communication/email-smtp-settings
Permission: Email.ManageSmtp (IMAP save also uses ManageImap on account APIs)

Configure:

• SMTP host, port, security, authentication
• Auth mode: Basic or Microsoft OAuth
• Default From address
• Optional IMAP for inbound sync
• App public URL when using Microsoft OAuth callback

Resolution order: per-account SMTP/IMAP if present, otherwise tenant settings.

8.3 Microsoft OAuth

When using Microsoft OAuth:

1. Complete OAuth connect from the SMTP settings screen.
2. Ensure the host public URL matches the OAuth callback registered for the app.
3. Disconnect and reconnect if tokens expire or the tenant changes.

9. Email templates

Path: /communication/email-templates
Permission: Email.Templates

Maintain named HTML templates (create, update, delete). Templates are stored for reuse; automatic insertion into compose is not wired as a mandatory step — copy or apply manually until compose integration is extended.

10. Email queue and logs

Email queue

Path: /communication/email-queue
Permissions: Email.ViewLogs to list; Email.Retry to retry or cancel

Email logs

Path: /communication/email-logs
Permission: Email.ViewLogs

Operational history of email actions for troubleshooting (send, sync, failures). Use together with the queue when diagnosing delivery problems.

11. Unified search

Path: /communication/search
Permission: Communication.Search

Search accessible internal messages by subject and body (you are sender or recipient). An optional type filter may appear; System and Email message types are uncommon for internal records.

Despite “unified” naming in some UI copy, external email is not fully covered by this search today. Use External inbox/sent for mail lookup.

12. Audit log

Path: /communication/audit
Permission: Audit.View

Records module actions such as send, reply, forward, and mark-as-read, with success/failure/denied results. Filter by action, user, and date as offered on the screen.

Audit.Export exists as a permission but has no export UI yet.

13. ERP links

ERP-style links can associate a message with a document in another module (module name, entity type/id, optional URL).

Do not rely on ERP linking for production document trails until the search/resolve integration is completed for Sales, Finance, Manufacturing, HR, and related modules.

Email policies (attachment size, recipient limits, approval) exist as domain concepts and a permission (Email.Policies) but have no user-facing management screen yet.

14. Permissions summary

Permission group: Communication.

Messages and collaboration

Email

Other

Parent menu opens with Dashboard, Inbox, or View.

Appendix A — Quick procedures

A.1 First internal message

1. Grant SendInternal and Inbox to the roles involved.
2. Optionally create a group and add members.
3. Compose → select users or group → send.
4. Recipient opens inbox → mark as read → reply from the thread.

A.2 Enable outbound email

1. Turn off Communication:UseMockEmail if real delivery is required.
2. Configure SMTP on /communication/email-smtp-settings.
3. Create at least one email account.
4. Compose email → send → confirm queue moves Pending → Sent.
5. Check Email logs if the item fails.

A.3 Enable inbound email

1. Configure IMAP on tenant settings (or per-account via API).
2. Wait for the sync worker cycle.
3. Confirm messages appear under External inbox.

A.4 Troubleshoot failed mail

1. Open Email queue → locate Failed.
2. Verify SMTP credentials, From address, and network access.
3. Retry; if it fails again, review Email logs and cancel if obsolete.

Appendix B — Operating notes

Appendix C — Document control

This guide describes functional capabilities of the Communication module as implemented in the Vertex ERP codebase. UI labels may appear in English or Arabic depending on language settings.