Write File

Summary

• Internal name: WriteFile
• Category: File System
• Purpose: Write or append text content to a file inside the AndroMate file sandbox.
• Task type: Normal

---

Compatibility

• Minimum AndroMate version: 1.1.0

• Maximum AndroMate version: 1.1.0

• Minimum Android: Android 13 (API 33)

• Maximum Android tested: Android 16 (API 36)

• Required permissions: MANAGE_EXTERNAL_STORAGE

---

Detailed description

The Write File task writes text to a file. The file (and its parent directories) is created automatically if it does not exist. Three write modes are available: overwrite, append, or append with a trailing newline.

All File System tasks are confined to the AndroMate sandbox: /sdcard/AndromateFileTask. A path escaping the sandbox is rejected with FILE-TASK-001. The sandbox directory is created automatically on first use.

---

Input parameters

Parameter	Type	Required	Possible values / Rules	Android Compatibility	AndroMate Compatibility	Default
file_path	String	Yes	File path inside the sandbox (supports interpolation)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	""
content	String	Yes	Text to write (supports interpolation)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	""
mode	Enum / String	No	Overwrite, Append, Append Line	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	Overwrite

---

Output parameters

This task produces no output variable. It returns a VoidResult on success.

---

Exceptions

Code	Trigger condition
FILE-TASK-001	Path is outside the AndroMate sandbox
FILE-TASK-002	File system operation failed (I/O error)

---

Execution flowchart

flowchart TD
    Start([▶ WriteFile]) --> Jail[📂 Ensure sandbox exists]

    Jail --> Validate{Path inside sandbox ?}

    Validate -->|No| Throw([❌ FILE-TASK-001])
    Validate -->|Yes| Mode{Mode ?}

    Mode -->|Overwrite| W1[✍️ writeText replace]
    Mode -->|Append| W2[➕ writeText append]
    Mode -->|Append Line| W3[↵ writeLine append + newline]

    W1 --> Success([✅ VoidResult])
    W2 --> Success
    W3 --> Success

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Throw fill:#ffcdd2
    style Jail fill:#fff9c4
    style Mode fill:#fff9c4

How it works:

1. Sandbox: the sandbox directory is created if missing
2. Validate: the resolved path is checked to be inside the sandbox
3. Write: the content is written according to the selected mode (the file is created if missing)
4. Result: returns VoidResult

---

Code examples

Example 1 — Overwrite a file

{
  "WriteFile": [
    {
      "id": "1",
      "title": "Save config",
      "file_path": "config.json",
      "content": "{ \"enabled\": true }",
      "mode": "Overwrite"
    }
  ]
}

---

Example 2 — Append a log line

{
  "WriteFile": [
    {
      "id": "2",
      "title": "Log step",
      "file_path": "logs/run.log",
      "content": "Step $i done",
      "mode": "Append Line"
    }
  ]
}

---

Input parameter details

file_path — Target file

Path inside the sandbox. Created automatically (with parents) if missing. Supports interpolation.

content — Text to write

The text written to the file. Supports $variable and ${SPECIAL_VAR} interpolation.

mode — Write mode

• Overwrite → replaces the whole file content
• Append → adds the content at the end (no newline)
• Append Line → adds the content at the end plus a trailing newline (ideal for logs)

---

Output parameter details

This task produces no output variable.

---

Complete JSON example

{
  "WriteFile": [
    {
      "id": "1",
      "title": "Write File",
      "file_path": "logs/result.log",
      "content": "Job $job_name finished",
      "mode": "Append Line"
    }
  ]
}