Send Custom Event

Send Custom Event Mutation

Sends a custom event to the pyck event system for processing by workflows and external integrations.

Arguments

Name	Type	Description
input	SendCustomEventInput!	Input data for the custom event

Return Type

SendCustomEventResponse - Confirmation of the event submission.

Input Fields

SendCustomEventInput:

Field	Type	Description
type	String!	The type/category of the event
operation	String!	The operation being performed
payload	Map!	Event data and context information

Return Fields

SendCustomEventResponse:

Field	Type	Description
success	Boolean!	Whether the event was successfully submitted

Usage Example

mutation {
  sendCustomEvent(
    input: {
      type: "inventory"
      operation: "low_stock_alert"
      payload: {
        "itemId": "item_123456789",
        "itemName": "iPhone 13 Pro",
        "currentStock": 5,
        "minimumThreshold": 10,
        "locationId": "warehouse_main",
        "urgency": "high",
        "suggestedReorderQuantity": 50,
        "estimatedRunoutDate": "2024-02-15T10:00:00Z"
      }
    }
  ) {
    success
  }
}

mutation {
  # Send customer lifecycle event
  sendCustomEvent(
    input: {
      type: "customer"
      operation: "milestone_reached"
      payload: {
        "customerId": "cust_987654321",
        "customerName": "ACME Corp",
        "milestone": "first_anniversary",
        "totalOrderValue": 125000.00,
        "orderCount": 87,
        "loyaltyPoints": 12500,
        "accountManager": "[email protected]",
        "celebrationCampaign": "anniversary_rewards",
        "discountEligible": true
      }
    }
  ) {
    success
  }
}

mutation {
  # Send quality control event
  sendCustomEvent(
    input: {
      type: "quality"
      operation: "inspection_failed"
      payload: {
        "inspectionId": "qc_20240131_001",
        "itemId": "item_456789123",
        "batchNumber": "BATCH-2024-015",
        "inspectorId": "user_inspector_01",
        "failureReason": "dimension_out_of_tolerance",
        "measurements": {
          "length": 10.5,
          "expectedLength": 10.0,
          "tolerance": 0.2
        },
        "severity": "major",
        "quarantineRequired": true,
        "supplierNotificationRequired": true
      }
    }
  ) {
    success
  }
}

Event Types and Operations

Common Event Types

Inventory Events

• Type: "inventory"

• Operations:

  • "low_stock_alert" - Stock levels below threshold

  • "reorder_point_reached" - Time to reorder inventory

  • "excess_stock_detected" - Overstock situation

  • "item_expired" - Perishable items approaching expiration

Customer Events

• Type: "customer"

• Operations:

  • "milestone_reached" - Customer loyalty milestones

  • "payment_overdue" - Late payment notifications

  • "preference_updated" - Customer preference changes

  • "complaint_received" - Customer service issues

Order Events

• Type: "order"

• Operations:

  • "rush_order_received" - Expedited order processing

  • "bulk_order_discount" - Large order special handling

  • "order_modification" - Changes to existing orders

  • "delivery_delay" - Shipping delays and notifications

Quality Events

• Type: "quality"

• Operations:

  • "inspection_failed" - Quality control failures

  • "compliance_violation" - Regulatory compliance issues

  • "supplier_rating_changed" - Supplier performance updates

  • "recall_initiated" - Product recall procedures

Workflow Events

• Type: "workflow"

• Operations:

  • "manual_approval_required" - Human intervention needed

  • "process_exception" - Workflow exception handling

  • "sla_breach" - Service level agreement violations

  • "escalation_triggered" - Process escalation events

JavaScript Example

const SEND_CUSTOM_EVENT = gql`
  mutation SendCustomEvent($input: SendCustomEventInput!) {
    sendCustomEvent(input: $input) {
      success
    }
  }
`;

// Using the mutation
const [sendCustomEvent] = useMutation(SEND_CUSTOM_EVENT);

const handleLowStockAlert = async (item) => {
  try {
    const { data } = await sendCustomEvent({
      variables: {
        input: {
          type: "inventory",
          operation: "low_stock_alert",
          payload: {
            itemId: item.id,
            itemName: item.name,
            currentStock: item.stockLevel,
            minimumThreshold: item.minThreshold,
            locationId: item.locationId,
            urgency: item.stockLevel <= item.criticalThreshold ? "critical" : "high"
          }
        }
      }
    });
    
    if (data.sendCustomEvent.success) {
      console.log('Low stock alert sent successfully');
      // Show success notification to user
    }
  } catch (error) {
    console.error('Error sending custom event:', error);
  }
};

Event Processing

Workflow Integration

Custom events can trigger Temporal workflows:

• Inventory Management: Automatic reordering workflows

• Customer Service: Support ticket creation and routing

• Quality Control: Inspection and compliance workflows

• Notification Systems: Email, SMS, and push notifications

External System Integration

Events can be consumed by external systems:

• ERP Systems: Business process automation

• CRM Platforms: Customer relationship management

• Analytics Tools: Business intelligence and reporting

• Monitoring Systems: Alerting and dashboard updates

Event Routing

Events are routed based on:

• Event Type: Different handlers for different event categories

• Operation: Specific processing logic for each operation

• Payload Content: Conditional routing based on event data

• Tenant Configuration: Organization-specific event handling

Payload Guidelines

Required Fields

While the payload is flexible, consider including:

• Entity IDs: Reference to related entities (customer, item, order, etc.)

• Timestamp: When the event occurred

• Source: System or user that generated the event

• Priority/Urgency: Event importance level

• Context: Additional information for processing

Data Types

The payload Map supports:

• Strings: Text data and identifiers

• Numbers: Quantities, amounts, measurements

• Booleans: Flags and status indicators

• Objects: Nested data structures

• Arrays: Lists of related items

Best Practices

1. Consistent Naming: Use consistent field names across similar events

2. Complete Context: Include all necessary information for processing

3. Avoid Sensitive Data: Don't include passwords or API keys

4. Structured Data: Use nested objects for complex information

5. Documentation: Document payload structure for each event type

Error Handling

Events may fail to process due to:

• Invalid Type/Operation: Unknown event type or operation

• Malformed Payload: Invalid or missing required data

• System Overload: Event queue at capacity

• Permission Issues: Insufficient rights to send certain events

• Configuration Problems: Event routing or processing configuration errors

Monitoring and Observability

Event Tracking

Monitor custom events through:

• Event Logs: Detailed logs of all event processing

• Metrics Dashboards: Event volume and processing times

• Error Rates: Failed event processing statistics

• Workflow Triggers: Events that successfully triggered workflows

Performance Considerations

• Event Volume: Monitor event throughput and system capacity

• Processing Latency: Time from event submission to processing

• Queue Depth: Backlog of pending events

• Resource Usage: CPU and memory consumption during event processing

Notes

• Events are processed asynchronously - success indicates submission, not completion

• Event types and operations should be coordinated across teams

• Consider implementing event versioning for backwards compatibility

• Use meaningful, descriptive event types and operations

• Test event processing in development environments before production use