Neo4j Set Staff Availability icon

Neo4j Set Staff Availability

設定或更新指定員工的可用時間。此操作會 **完全覆蓋** 該員工所有舊的可用時間設定。 通過 'Availability Data' (JSON 陣列) 提供時間段: 每個時間段物件需包含 'start_time' (HH:MM), 'end_time' (HH:MM)。 必須指定 'type' (SCHEDULE 或 EXCEPTION，預設 SCHEDULE)。 - **type: "SCHEDULE"**: 設定常規每週排班。 - 需要 'day_of_week' (數字 1-7 或英文星期名)。 - 範例: {"type": "SCHEDULE", "day_of_week": 1, "start_time": "09:00", "end_time": "17:00"} - **type: "EXCEPTION"**: 設定特定日期例外，會覆蓋當天的 SCHEDULE。 - 需要 'date' (YYYY-MM-DD)。 - 可選 'reason' (字串，僅供參考，不影響可用時段計算邏輯)。 - **用法區分 (基於 start_time/end_time)**: - **表示請假/全天不可用**: 將 'start_time' 設為 "00:00"，'end_time' 設為 "23:59"。FindAvailableSlots 將無法在此範圍內找到可用時段。 範例: {"type": "EXCEPTION", "date": "2025-12-25", "start_time": "00:00", "end_time": "23:59", "reason": "休假"} - **表示特殊可用時段**: 設定實際的 'start_time' 和 'end_time'。FindAvailableSlots 將只在此範圍內查找可用時段。 範例: {"type": "EXCEPTION", "date": "2025-12-31", "start_time": "13:00", "end_time": "17:00", "reason": "僅下午"} **重要**: 請確保 start_time 早於 end_time。

Neo4j Set Staff Availability

AI-generated

Overview

This node sets or updates the availability schedule for a specified staff member in a Neo4j database. It completely replaces all existing availability records for that staff member with new data provided as JSON input.

Typical use cases include managing employee work schedules and exceptions such as holidays or special availability changes. For example, you can define regular weekly working hours (SCHEDULE) and specify particular dates when the employee is unavailable or has modified hours (EXCEPTION).

Practical examples:

  • Setting a staff member’s normal weekly schedule to Monday-Friday, 9 AM to 5 PM.
  • Marking December 25th as a full-day holiday exception where the staff member is not available.

Properties

Name Meaning
Staff ID The unique identifier (UUID) of the target staff member whose availability is being set or updated.
Availability Data A JSON array describing the staff member's availability periods. Each entry must be either a SCHEDULE or an EXCEPTION type:
- SCHEDULE: Defines recurring weekly availability with day_of_week (1-7 or weekday name), start_time and end_time in "HH:MM" format.
- EXCEPTION: Defines specific date exceptions with date (YYYY-MM-DD), start_time, end_time, and optional reason. Full-day unavailability is represented by "00:00" to "23:59".

Output

The node outputs JSON objects for each processed input item containing:

  • success: Boolean indicating if the operation succeeded.
  • staffId: The staff member’s ID for whom availability was set.
  • deletedCount: Number of previous availability records deleted.
  • availabilitySetCount: Number of new availability records created.
  • processedEntries: Number of availability entries processed from the input.

If errors occur and the node is configured to continue on failure, the output includes error details with messages and expected input format guidance.

No binary data is produced.

Dependencies

  • Requires a Neo4j database connection with credentials including host, port, username, password, and optionally database name.
  • The node uses the official Neo4j driver to connect and run Cypher queries.
  • Proper configuration of the Neo4j API credentials in n8n is necessary.

Troubleshooting

Common Issues

  • Invalid JSON in Availability Data: The input must be a valid JSON array. Errors parsing this will cause the node to fail.
  • Missing or Incorrect Fields: Each availability entry must have required fields (type, day_of_week or date, start_time, end_time). Missing or invalid values trigger errors.
  • Time Format Errors: start_time and end_time must be in "HH:MM" format, and start_time must be earlier than end_time.
  • Day of Week Errors: For SCHEDULE entries, day_of_week must be an integer 1-7 or a valid English weekday name.
  • Staff ID Not Found: If the specified staff ID does not exist in the database, the node throws an error.
  • Neo4j Connection Issues: Misconfigured credentials or unreachable database cause connection failures.

Error Messages and Resolutions

  • "Neo4j credentials are not fully configured."
    Ensure all required credential fields (host, port, username, password) are correctly set in n8n.

  • "Availability Data must be a valid JSON array."
    Check the JSON syntax and structure of the availability data input.

  • "Invalid availability type in entry X. Must be 'SCHEDULE' or 'EXCEPTION'."
    Correct the type field in the specified entry.

  • "Missing day_of_week in SCHEDULE availability entry X."
    Add a valid day_of_week field for that entry.

  • "Invalid time format in entry X. Use 'HH:MM' format."
    Fix the time strings to match the required format.

  • "Staff ID ... does not exist."
    Verify the staff ID exists in the Neo4j database before running the node.

  • "Failed to establish Neo4j connection."
    Check network connectivity and credential correctness.

Links and References

Discussion