Workflow 7: Admin Settings — Gateways, Permissions & Templates
This workflow covers the administrative setup process that underpins all other workflows. Correct gateway credentials, properly scoped role permissions, and well-configured message templates are the invisible infrastructure that makes every other process work reliably. Changes to admin settings affect every user and every transaction — approach this workflow with appropriate care, one change at a time.
Admin Access Required: This workflow requires Administrator or Super Admin role. All changes should be tested in a non-production environment or with test accounts where possible before affecting live operations. Every change must be documented with what changed, when, and who made it.
Quick Steps Summary
- Configure SMTP and run test email to confirm delivery
- Configure SMS gateway and send test SMS
- Set payment gateway keys in test mode — run end-to-end test transaction
- Switch to live mode only after all tests pass
- Review and update role permissions, then validate with a test account
- Update message templates to approved content
- Document all changes in the settings change log
Step-by-Step Workflow
- Configure SMTP Email: Navigate to Setup > Email Settings. Enter: SMTP host, port (587 for TLS recommended), username (sending email address), password or app password, and encryption type. Click Send Test Email. Enter a test recipient email and confirm receipt before saving. If the test fails, review the SMTP error code — common causes are incorrect port, wrong encryption type, or an app password being required instead of the account password.
- Configure SMS Gateway: Navigate to Setup > SMS Settings. Select your provider (Twilio, Nexmo, Africa's Talking, or a configured custom provider). Enter the API key, API secret, and sender ID (or approved sender phone number). Click Send Test SMS to a verified number. Confirm the SMS is received with the correct sender ID and message content.
- Configure Payment Gateways: Navigate to Setup > Finance > Payment Gateways. Enable your payment provider. Enter the sandbox/test API keys first. Create a test invoice for a test client and complete a test checkout to verify: the payment page loads, a test transaction completes, and the invoice status in the CRM updates to Paid via the webhook callback.
- Switch to Live Mode: Only after a full end-to-end sandbox test, replace the test keys with your live production credentials. Run a real low-value transaction to confirm live mode is functioning. Never operate with test keys in a live production environment.
- Review Role Permissions: Navigate to Setup > Staff > Roles. Review each active role profile against your team's current structure. For any staff role change (new joiner, promotion, departure), update the role assignment immediately. Apply the principle of least privilege — users should only have access to modules and actions required for their job function.
- Validate with Test Account: After any permission change, log in with a test account assigned to the modified role. Verify the expected modules are accessible and no unintended modules or actions are available. This step prevents access errors from being discovered by staff during live operations.
- Update Message Templates: Navigate to Setup > Email Templates and Setup > SMS Templates. Review all templates used in automations and campaigns. Update any template that contains outdated branding, incorrect contact details, or superseded information. Send a test dispatch for each modified template to verify formatting and merge field resolution before saving.
- Document All Changes: After each change, record the following in your settings change log: date, setting changed, previous value, new value, reason for change, and the name of the person who made it. This log is essential for diagnosing issues later and for governance audits.
Best Practice: Make one settings change at a time, test it immediately, then move to the next. Never make multiple simultaneous changes — if something breaks, you will not know which change caused it.
Expected Outcomes
- SMTP, SMS, and payment gateway connections are validated and functioning reliably.
- Each staff role has the minimum permissions required for their function — no more, no less.
- All message templates reflect current branding and approved content.
- A complete settings change log is maintained and accessible to senior team members and auditors.
Common Errors
| Issue | Likely Cause | Fix |
|---|---|---|
| Staff lost access to a module | Permission change was too broad or wrong role edited | Restore the role's baseline and re-apply only the intended targeted change. |
| Live payments failing | Test/sandbox keys still active | Replace with live production keys and verify with a real low-value transaction. |
| Email not sending from system | SMTP credentials expired or app password needed | Re-enter credentials and run the built-in test email. Enable 2FA app passwords if required by provider. |
| Templates not updating after edit | Cache or wrong template assigned in the automation rule | Clear application cache and verify the automation or trigger is pointing to the updated template. |