Skip to main content

​
Recommendation

Represents a maintenance recommendation with severity level, attachments, and status tracking. 
export interface Recommendation {
  id: string;
  title: string;
  severity: "low" | "medium" | "high" | "critical";
  description: string;
  attachments: RecommendationAttachment[];
  site: {
    id: string;
    name?: string;
  };
  asset: {
    id: string;
    name?: string;
  };
  sampling_point: {
    id: string;
    name?: string;
  };
  recommender: {
    id: string;
    name?: string;
  };
  status?: "open" | "in_progress" | "completed" | "overdue";
  created_at_datetime: string;
  updated_at_datetime: string;
}

​
Fields

​
id
string
required
Unique identifier for the recommendation
​
title
string
required
Short title summarizing the recommendation
​
severity
'low' | 'medium' | 'high' | 'critical'
required
Severity level indicating urgency of the recommendation
  • "low": Minor issue, can be addressed during routine maintenance
  • "medium": Moderate issue, should be addressed soon
  • "high": Significant issue, requires prompt attention
  • "critical": Critical issue, immediate action required
​
description
string
required
Detailed description of the recommendation, including:
  • Problem identified
  • Recommended actions
  • Expected outcomes
  • Any relevant technical details
​
attachments
RecommendationAttachment[]
required
Array of attached files (images, PDFs, documents) supporting the recommendation
​
site
object
required
Reference to the site where action is needed
​
asset
object
required
Reference to the asset requiring attention
​
sampling_point
object
required
Reference to the sampling point related to this recommendation
​
recommender
object
required
User who created the recommendation
​
status
'open' | 'in_progress' | 'completed' | 'overdue'
Current status of the recommendation
  • "open": New recommendation, no action taken yet
  • "in_progress": Work has started on the recommendation
  • "completed": Recommendation has been fully addressed
  • "overdue": Recommendation has passed its due date without completion
​
created_at_datetime
string
required
ISO 8601 timestamp when recommendation was created
​
updated_at_datetime
string
required
ISO 8601 timestamp when recommendation was last updated

​
RecommendationAttachment

Represents a file attachment associated with a recommendation. 
export interface RecommendationAttachment {
  type: string;
  url: string;
  name: string;
}

​
Fields

​
type
string
required
MIME type or file type (e.g., “application/pdf”, “image/jpeg”, “image/png”)
​
url
string
required
URL to access the attachment file
​
name
string
required
Original filename of the attachment

​
AddRecommendationPayload

Payload for creating a new recommendation. 
export interface AddRecommendationPayload {
  title: string;
  severity: "low" | "medium" | "high" | "critical";
  description: string;
  attachments?: RecommendationAttachment[];
  site: {
    id: string;
  };
  asset: {
    id: string;
  };
  sampling_point: {
    id: string;
  };
  recommender: {
    id: string;
  };
}

​
Fields

All fields match the Recommendation type except:
  • id, created_at_datetime, updated_at_datetime are auto-generated
  • status is automatically set to "open"
  • attachments is optional
  • Entity references require only id field

​
EditRecommendationPayload

Payload for updating an existing recommendation. 
export interface EditRecommendationPayload {
  title: string;
  severity: "low" | "medium" | "high" | "critical";
  description: string;
  attachments?: RecommendationAttachment[];
  site: {
    id: string;
  };
  asset: {
    id: string;
  };
  sampling_point: {
    id: string;
  };
  recommender: {
    id: string;
  };
}
The EditRecommendationPayload has the same structure as AddRecommendationPayload. The recommendation ID is passed separately to the update function.

​
RecommendationAnalytics

Analytics data for recommendations over time. 
export interface RecommendationAnalytics {
  month: string;
  total_count: number;
  total_trend_percentage: number;
  overdue_count: number;
  overdue_trend_percentage: number;
  open_overdue_count: number;
  open_overdue_trend_percentage: number;
}

​
Fields

​
month
string
required
Month identifier (e.g., “2024-01”, “January 2024”)
​
total_count
number
required
Total number of recommendations in this period
​
total_trend_percentage
number
required
Percentage change in total recommendations compared to previous period
​
overdue_count
number
required
Number of overdue recommendations
​
overdue_trend_percentage
number
required
Percentage change in overdue recommendations
​
open_overdue_count
number
required
Number of recommendations that are both open and overdue
​
open_overdue_trend_percentage
number
required
Percentage change in open/overdue recommendations

​
Usage Example

import type { 
  Recommendation, 
  AddRecommendationPayload,
  RecommendationAttachment 
} from '@/types';
import { createRecommendation } from '@/actions/recommendations';

// Create a new recommendation
const payload: AddRecommendationPayload = {
  title: 'Replace main bearing due to elevated copper levels',
  severity: 'high',
  description: `
    Oil sample analysis shows copper levels at 85 ppm, significantly above 
    the 50 ppm warning threshold. This indicates accelerated bearing wear.
    
    Recommended actions:
    1. Schedule immediate bearing inspection
    2. Replace bearing if wear is confirmed
    3. Investigate root cause of accelerated wear
    4. Re-sample 100 hours after replacement
  `,
  attachments: [
    {
      type: 'application/pdf',
      url: 'https://example.com/sample-report.pdf',
      name: 'Sample Report S-2024-001.pdf'
    },
    {
      type: 'image/jpeg',
      url: 'https://example.com/bearing-photo.jpg',
      name: 'bearing-inspection.jpg'
    }
  ],
  site: { id: 'site_123' },
  asset: { id: 'asset_456' },
  sampling_point: { id: 'sp_789' },
  recommender: { id: 'user_001' }
};

const result = await createRecommendation(payload);

if (result.success) {
  const recommendation: Recommendation = result.data;
  console.log(`Created: ${recommendation.title}`);
  console.log(`Severity: ${recommendation.severity}`);
  console.log(`Status: ${recommendation.status}`);
}

​
Severity Guidelines

Low Severity
  • Minor issues detected
  • Can wait for scheduled maintenance
  • No immediate risk to operations
  • Examples:
    • Slight increase in wear metals within acceptable range
    • Cosmetic issues
    • Documentation updates

​
Status Workflow

  1. open: Recommendation created, awaiting assignment or action
  2. in_progress: Work has started on addressing the recommendation
  3. completed: All recommended actions have been completed
  4. overdue: Recommendation has passed its target completion date
An overdue recommendation can still be marked as completed once the work is finished. The overdue status serves as a tracking metric for maintenance KPIs.

Alarm Types

Recommendations are often linked to alarms

Sample Types

Sample results trigger recommendations

Build docs developers (and LLMs) love

Get started for freeTalk to us