Job Notification Mutations

Overview

Job notification mutations handle sending alerts to team members when jobs are created, updated, or rescheduled. The system automatically determines who should be notified based on job assignments and company settings, ensuring the right people stay informed about work changes.

How Job Notifications Work

Automatic Notifications

When jobs are created or updated, BlueClerk sends notifications to:

• Assigned technicians - The user assigned to the job receives updates
• Additional crew members - Any crew added to help with the job
• Subcontractors - If the job is assigned to a subcontractor company
• Admins - Depending on company notification settings

Input Requirements

Job notification mutations require:

• jobId - The ID of the job to send notifications about
• companyId - The company the job belongs to
• Notification type - Created, updated, rescheduled, completed, or cancelled
• Actor information - Who triggered the change (for context in notifications)

Notification Content

Job notifications include:

• Job number and title - So recipients know which job changed
• Customer name and address - Property location for the work
• Scheduled date/time - When the work is happening (formatted in company timezone)
• Description - What work needs to be done
• Status change - What changed (rescheduled, completed, etc.)

Types of Job Notifications

Job Created

Sent when a new job is scheduled:

• Notifies assigned technician or subcontractor
• Includes all job details and scheduled time
• Only sent if job has an assigned user or subcontractor

Job Rescheduled

Sent when a job's date or time changes:

• Notifies assigned technician or subcontractor
• Shows both old and new scheduled times
• Only sent if the assignee is different from the user making the change

Job Updated

Sent when job details change (description, notes, etc.):

• Notifies assigned technician or subcontractor
• Highlights what changed
• Skipped if only minor fields changed

Job Completed

Sent when work is marked complete:

• Notifies admins and relevant team members
• Includes completion notes and photos
• Can trigger follow-up workflows

Job Cancelled

Sent when a job is cancelled:

• Notifies assigned technician or subcontractor
• Includes cancellation reason if provided
• Frees up the technician's schedule

Technical Details

Input Validation

The system validates:

• Job exists and belongs to the specified company
• User making changes has permission
• Notification recipients exist and are active
• Required fields are present (jobId, companyId, type)

Notification Delivery

Notifications are sent via:

• In-app notifications - Always sent
• Email - Based on user preferences
• SMS - For urgent updates if phone number is configured
• Push notifications - To mobile devices if app is installed

Rate Limiting

To prevent notification spam:

• Duplicate notifications within 5 minutes are suppressed
• Batch updates only send one notification per job
• Notifications are queued and sent asynchronously

Common Issues

Notifications Not Sending

If notifications aren't being sent:

1. Check job assignment - Job must have an assigned user or subcontractor
2. Verify actor is different - System doesn't notify you about your own changes
3. Check user preferences - Recipient may have disabled job notifications
4. Review company settings - Notification features may be disabled

Wrong People Getting Notified

If the wrong team members receive notifications:

1. Review job assignment - Only assigned users get notifications
2. Check additional crew - Crew members are notified of changes
3. Verify subcontractor assignment - Subcontractors receive notifications for their jobs
4. Review company hierarchy - Admin notifications may be enabled

Related Features

• Job Assignment - How to assign jobs to team members
• Team Permissions - Control who can create and update jobs
• Notification Settings - Configure notification preferences per user
• Mobile Push Notifications - Enable push alerts on mobile devices