Interface Problem<T>Alpha

Represents a problem reported by a ProblemProvider.

Problems are system-level issues that require manual intervention, such as:

  • Failed email delivery or validation errors
  • Integration sync failures with external systems
  • Background task configuration errors
  • Data import issues with corrupt records

Each problem belongs to a provider which owns the problem's lifecycle, storage, and available actions. Problems can optionally be linked to a specific LimeObject via the context property.

The platform aggregates problems from all registered providers, allowing authorized users to view and manage issues across the system.

The generic type parameter T allows providers to define strongly-typed metadata for their specific problem types.

Example

Basic problem with required fields only

const problem: Problem = {
    id: 'prob-001',
    providerId: 'email-integration',
    type: 'delivery-failed',
    description: 'Email to john@example.com bounced with error: mailbox full',
    createdAt: '2024-01-15T10:30:00Z'
};

Example

Problem with typed metadata

interface EmailProblemMetadata {
    recipientEmail: string;
    bounceType: 'permanent' | 'temporary';
    smtpCode: number;
}

const problem: Problem<EmailProblemMetadata> = {
    id: 'email-123',
    providerId: 'email-integration',
    type: 'delivery-failed',
    description: 'Email bounced',
    createdAt: '2024-01-15T10:30:00Z',
    metadata: {
        recipientEmail: 'john@example.com',
        bounceType: 'permanent',
        smtpCode: 550
    }
};

Example

Problem with error details

const problem: Problem = {
    id: 'sync-error-042',
    providerId: 'external-crm-sync',
    type: 'connection-error',
    description: 'Failed to sync deal with external CRM',
    createdAt: '2024-01-15T14:22:00Z',
    severity: ProblemSeverity.High,
    status: 'pending-retry',
    context: { limetype: 'deal', id: 98765 },
    error: {
        message: 'ETIMEDOUT: connection timed out after 30000ms',
        code: 'ETIMEDOUT',
        stack: 'Error: ETIMEDOUT\n    at TCPConnectWrap.afterConnect...'
    }
};

See

Type Parameters

  • T = unknown

    The type of the metadata object. Defaults to unknown.

Hierarchy

  • Problem

Properties

context? createdAt description error? id metadata? providerId severity? status? tags? type updatedAt? userId?

Properties

Optional context

context?: ProblemContext

Link to a related LimeObject.

When a problem is directly related to a specific business object, the context provides navigation and filtering capabilities.

See

ProblemContext

createdAt

createdAt: string

ISO 8601 timestamp when the problem was first detected.

Example

createdAt: '2024-01-15T10:30:00Z'
createdAt: new Date().toISOString()

description

description: string

Human-readable description of what went wrong.

The description should be clear enough for users to understand the issue without needing technical knowledge. Include relevant details like affected entities, error messages, or suggested actions.

Example

// Good descriptions
description: 'Email to john@example.com could not be delivered: mailbox is full'
description: 'Failed to sync deal "Big Corp Renewal" with external system: connection timeout'

// Avoid overly technical descriptions
description: 'SMTP 452 4.2.2 error' // Too technical

Optional error

error?: ProblemError

Technical error details for debugging.

While description provides a user-friendly explanation, error captures the underlying technical details. The platform may display this in an expandable "Technical Details" section.

See

ProblemError

id

id: string

Unique identifier for the problem within the provider.

The id only needs to be unique within a single provider. The combination of providerId and id uniquely identifies a problem across the system.

Optional metadata

metadata?: T

Additional provider-specific data.

Metadata allows providers to attach arbitrary data to problems that may be useful for debugging, displaying additional details, or powering actions. Values should be JSON-serializable.

Use the generic type parameter to get type safety for your metadata.

Example

metadata: {
    originalEmailId: 'msg-123',
    recipientEmail: 'john@example.com',
    bounceType: 'permanent',
    smtpCode: 550
}

providerId

providerId: string

Identifier of the ProblemProvider that reported this problem.

This links the problem back to its owning provider, which controls the problem's lifecycle and available actions.

This property is set automatically by the platform when problems are returned from the ProblemRepository. Providers should not include this property when returning problems from their methods.

Optional severity

severity?: ProblemSeverity

Severity level indicating the problem's urgency and impact.

Use severity to help users prioritize which problems to address first.

See

ProblemSeverity

Optional status

status?: string

Current status in the problem's lifecycle.

Status is provider-defined. Each provider can define their own status values that make sense for their workflow (e.g., 'open', 'in-progress', 'pending-retry', 'resolved').

Status is optional. Some providers may choose to simply remove problems when they're resolved rather than tracking status transitions.

Optional tags

tags?: string[]

Tags for additional categorization and filtering.

Tags provide flexible categorization beyond the type field. They can represent things like affected systems, error categories, or custom classifications specific to your domain.

Example

tags: ['email', 'bounce', 'permanent']
tags: ['sync', 'external-system', 'timeout']
tags: ['import', 'validation', 'required-field']

type

type: string

Type identifier for categorizing the problem.

Types are provider-specific and allow grouping similar problems together. Use a consistent naming convention, typically with a prefix indicating the domain (e.g., 'email.delivery-failed', 'sync.connection-error').

The provider's getType method returns display information (title, description, icon) for each type.

Example

// Email integration provider types
type: 'email.delivery-failed'
type: 'email.validation-error'
type: 'email.attachment-too-large'

// Sync provider types
type: 'sync.connection-error'
type: 'sync.data-conflict'
type: 'sync.rate-limited'

Optional updatedAt

updatedAt?: string

ISO 8601 timestamp when the problem was last modified.

Updated when status changes, metadata is modified, or any other property is updated after initial creation.

Optional userId

userId?: string

Identifier of the user associated with this problem.

This could be the user who triggered the action that failed, or the user responsible for the affected data. The exact meaning depends on the provider's context.

Settings

Member Visibility

Theme