> For the complete documentation index, see [llms.txt](https://docs.rierino.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rierino.com/devops/api-event-and-process-flows/configuring-saga-steps/event-step/core-actions/perform-file-operation.md).

# Perform File Operation

These actions provide ability to interact with local and remote file systems for directory and file operations.

## Perform File Operation Actions

`ReadFile` supports [Event Step](https://docs.rierino.com/devops/api-event-and-process-flows/configuring-saga-steps/event-step.md). It uses **Use Cache** and **Cache State**.

### MakeDir

Creates a new directory in given file system. Event metadata fields applicable for this action are as follows:

{% tabs %}
{% tab title="Table" %}

| Field        | Definition                     | Example | Default |
| ------------ | ------------------------------ | ------- | ------- |
| Domain       | Name of the file system to use | imageFs | -       |
| {% endtab %} |                                |         |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "MakeDir action eventMeta fields",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "definition": "Name of the file system to use",
          "example": "imageFs"
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

With event metadata parameters as:

{% tabs %}
{% tab title="Table" %}

| Parameter    | Definition                                        | Example  | Default |
| ------------ | ------------------------------------------------- | -------- | ------- |
| Path Path    | Json path in payload for directory path to create | filePath | path    |
| {% endtab %} |                                                   |          |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "MakeDir action eventMeta.parameters",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties": {
            "pathPath": {
              "type": "string",
              "definition": "Json path in payload for directory path to create",
              "default": "path",
              "example": "filePath"
            }
          }
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### List / ListPath

Lists files and directories for given path. Event metadata fields applicable for this action are as follows:

{% tabs %}
{% tab title="Table" %}

| Field        | Definition                     | Example | Default |
| ------------ | ------------------------------ | ------- | ------- |
| Domain       | Name of the file system to use | imageFs | -       |
| {% endtab %} |                                |         |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "List action eventMeta fields",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "definition": "Name of the file system to use",
          "example": "imageFs"
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

With event metadata parameters as:

{% tabs %}
{% tab title="Table" %}

| Parameter      | Definition                                                 | Example  | Default |
| -------------- | ---------------------------------------------------------- | -------- | ------- |
| Path Path      | Json path in payload for directory path to list            | filePath | path    |
| Skip           | Files to skip in list results                              | 10       | -       |
| Limit          | Number of files to return in results                       | 10       | -       |
| Search         | Term to search in file names                               | pdf      | -       |
| Order By       | Sort field (date, name, size)                              | date     | -       |
| Ascending      | Whether to sort ascending                                  | false    | true    |
| Detect Type    | Whether to detect content type (single file only)          | true     | -       |
| Parse Meta     | Whether to detect analyze file metadata (single file only) | true     | -       |
| Produce Hash   | Whether to produce content hash (single file only)         | true     | -       |
| Output Pattern | Jmespath for producing list results                        | -        | -       |
| {% endtab %}   |                                                            |          |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "List action eventMeta.parameters",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties": {
            "pathPath": {
              "type": "string",
              "definition": "Json path in payload for directory path to list",
              "default": "path",
              "example": "filePath"
            },
            "skip": {
              "type": "integer",
              "definition": "Files to skip in list results",
              "example": 10
            },
            "limit": {
              "type": "integer",
              "definition": "Number of files to return in results",
              "example": 10
            },
            "search": {
              "type": "string",
              "definition": "Term to search in file names",
              "example": "pdf"
            },
            "orderBy": {
              "type": "string",
              "definition": "Sort field (date, name, size)",
              "enum": [
                "date",
                "name",
                "size"
              ],
              "example": "date"
            },
            "ascending": {
              "type": "boolean",
              "definition": "Whether to sort ascending",
              "default": true,
              "example": false
            },
            "detectType": {
              "type": "boolean",
              "definition": "Whether to detect content type (single file only)",
              "example": true
            },
            "parseMeta": {
              "type": "boolean",
              "definition": "Whether to analyze file metadata (single file only)",
              "example": true
            },
            "produceHash": {
              "type": "boolean",
              "definition": "Whether to produce content hash (single file only)",
              "example": true
            },
            "outputPattern": {
              "type": "string",
              "definition": "Jmespath for producing list results"
            }
          }
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Delete / DeletePath

Deletes a file or directory in given file system. Event metadata fields applicable for this action are as follows:

{% tabs %}
{% tab title="Table" %}

| Field        | Definition                     | Example | Default |
| ------------ | ------------------------------ | ------- | ------- |
| Domain       | Name of the file system to use | imageFs | -       |
| {% endtab %} |                                |         |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Delete action eventMeta fields",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "definition": "Name of the file system to use",
          "example": "imageFs"
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

With event metadata parameters as:

{% tabs %}
{% tab title="Table" %}

| Parameter    | Definition                                             | Example  | Default |
| ------------ | ------------------------------------------------------ | -------- | ------- |
| Path Path    | Json path in payload for file/directory path to delete | filePath | path    |
| {% endtab %} |                                                        |          |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Delete action eventMeta.parameters",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties": {
            "pathPath": {
              "type": "string",
              "definition": "Json path in payload for file/directory path to delete",
              "default": "path",
              "example": "filePath"
            }
          }
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Rename / RenamePath

Renames a file or directory in given file system. Event metadata fields applicable for this action are as follows:

{% tabs %}
{% tab title="Table" %}

| Field        | Definition                     | Example | Default |
| ------------ | ------------------------------ | ------- | ------- |
| Domain       | Name of the file system to use | imageFs | -       |
| {% endtab %} |                                |         |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Rename action eventMeta fields",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "definition": "Name of the file system to use",
          "example": "imageFs"
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

With event metadata parameters as:

{% tabs %}
{% tab title="Table" %}

| Parameter    | Definition                                        | Example  | Default |
| ------------ | ------------------------------------------------- | -------- | ------- |
| Path Path    | Json path in payload for file/directory to rename | filePath | path    |
| To Path      | Json path in payload for new file/directory name  | newPath  | to      |
| {% endtab %} |                                                   |          |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Rename action eventMeta.parameters",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties": {
            "pathPath": {
              "type": "string",
              "definition": "Json path in payload for file/directory to rename",
              "default": "path",
              "example": "filePath"
            },
            "toPath": {
              "type": "string",
              "definition": "Json path in payload for new file/directory name",
              "default": "to",
              "example": "newPath"
            }
          }
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### CopyFile

Copies or moves a file from one file system to another. Event metadata fields applicable for this action are as follows:

{% tabs %}
{% tab title="Table" %}

| Field        | Definition                            | Example | Default |
| ------------ | ------------------------------------- | ------- | ------- |
| Domain       | Name of the source file system to use | imageFs | -       |
| {% endtab %} |                                       |         |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CopyFile action eventMeta fields",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "definition": "Name of the source file system to use",
          "example": "imageFs"
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

With event metadata parameters as:

{% tabs %}
{% tab title="Table" %}

| Parameter    | Definition                                      | Example  | Default |
| ------------ | ----------------------------------------------- | -------- | ------- |
| target       | Name of the target file system                  | cdnFs    | -       |
| Path Path    | Json path in payload for file/directory to copy | filePath | path    |
| To Path      | Json path in payload for target file/directory  | newPath  | to      |
| Move         | Whether file should be deleted from the source  | true     | false   |
| {% endtab %} |                                                 |          |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CopyFile action eventMeta.parameters",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties": {
            "target": {
              "type": "string",
              "definition": "Name of the target file system",
              "example": "cdnFs"
            },
            "pathPath": {
              "type": "string",
              "definition": "Json path in payload for file/directory to copy",
              "default": "path",
              "example": "filePath"
            },
            "toPath": {
              "type": "string",
              "definition": "Json path in payload for target file/directory",
              "default": "to",
              "example": "newPath"
            },
            "move": {
              "type": "boolean",
              "definition": "Whether file should be deleted from the source",
              "default": false,
              "example": true
            }
          }
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Write / WriteFile

Writes contents to a single file or a set of files for a given file system:

{% tabs %}
{% tab title="Table" %}

| Field        | Definition                          | Example    | Default |
| ------------ | ----------------------------------- | ---------- | ------- |
| Domain       | Name of the file system to write to | dataLakeFs | -       |
| {% endtab %} |                                     |            |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Write action eventMeta fields",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "definition": "Name of the file system to write to",
          "example": "dataLakeFs"
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

With event metadata parameters as:

{% tabs %}
{% tab title="Table" %}

| Parameter     | Definition                                                                                               | Example                                              | Default |
| ------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------- |
| Path Path     | Json path in payload for file path to write (from payload root)                                          | parameters.id                                        | path    |
| Mode          | Type of file(s) to output (sequence[^1], single[^2])                                                     | sequence                                             | single  |
| Prefix        | Prefix to add to each file's name (for sequence mode output)                                             | tracking/views                                       | -       |
| Suffix        | Suffix to add to each file's name (for sequence mode output)                                             | \_out.json                                           | -       |
| Content       | Event contents to write to file (for sequence mode, event[^3], request[^4] or payload[^5])               | request                                              | payload |
| Overwrite     | Whether to overwrite or append contents to output (for single mode output)                               | true                                                 | false   |
| Base64        | Whether the input should be treated as base64 text and decoded for generating the file (e.g. image, PDF) | true                                                 | false   |
| Input Pattern | JMESPath pattern applied to the data input                                                               | {path: parameters.path, content: parameters.content} | -       |
| {% endtab %}  |                                                                                                          |                                                      |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Write action eventMeta.parameters",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties": {
            "pathPath": {
              "type": "string",
              "definition": "Json path in payload for directory path to list (from payload root)",
              "default": "path",
              "example": "parameters.id"
            },
            "mode": {
              "type": "string",
              "definition": "Type of file(s) to output (sequence, single)",
              "enum": [
                "sequence",
                "single"
              ],
              "default": "single",
              "example": "sequence"
            },
            "prefix": {
              "type": "string",
              "definition": "Prefix to add to each file's name (for sequence mode output)",
              "example": "tracking/views"
            },
            "suffix": {
              "type": "string",
              "definition": "Suffix to add to each file's name (for sequence mode output)",
              "example": "_out.json"
            },
            "content": {
              "type": "string",
              "definition": "Event contents to write to file (for sequence mode, event, request or payload)",
              "enum": [
                "event",
                "request",
                "payload"
              ],
              "default": "payload",
              "example": "request"
            },
            "overwrite": {
              "type": "boolean",
              "definition": "Whether to overwrite or append contents to output (for single mode output)",
              "default": false,
              "example": true
            },
            "base64": {
              "type": "boolean",
              "definition": "Whether the input should be treated as base64 text and decoded for generating the file (e.g. image, PDF)",
              "default": false,
              "example": true
            },
            "inputPattern": {
              "type": "string",
              "definition": "JMESPath pattern applied to the data input",
              "example": "{path: parameters.path, content: parameters.content}"
            }
          }
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>Example</summary>

Input

```json
{
    "customerId": "customer-1",
    "productId": "product-1",
    "pageId": "product-detail"
}
```

Event Metadata

![](https://1659095931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcnDk3J1AzTgg2NFrGPlh%2Fuploads%2FPj6tjZ009IHXHSpJtOcf%2Fimage.png?alt=media\&token=0317221c-cf25-44c2-aef7-aa1e57f4aaa3)

</details>

For sequence output mode, this handler uses a path writer, which is responsible for generating unique sequence file paths/names for writing contents to. The writer can be configured by adding path.\* parameters to file system definition.

{% hint style="info" %}
Using "\[uuid]" in prefix or suffix allows generation of globally unique paths and file names, as this entry is replaced with a UUID value generated.
{% endhint %}

### Read / ReadFile

Reads and returns contents of a file (in a cachable manner):

{% tabs %}
{% tab title="Table" %}

| Field        | Definition                           | Example    | Default |
| ------------ | ------------------------------------ | ---------- | ------- |
| Domain       | Name of the file system to read from | contentsFs | -       |
| {% endtab %} |                                      |            |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Read action eventMeta fields",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "definition": "Name of the file system to read from",
          "example": "contentsFs"
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

With event metadata parameters as:

{% tabs %}
{% tab title="Table" %}

| Parameter      | Definition                                          | Example  | Default |
| -------------- | --------------------------------------------------- | -------- | ------- |
| Path Path      | Json path in payload for file path to read          | id       | path    |
| Format         | Format of the file contents to retrieve (json,text) | json     | text    |
| Max Length     | Maximum file size in bytes allowed to read          | 10000000 | -       |
| Output Pattern | JMESPath pattern applied to the data output         | -        | -       |
| {% endtab %}   |                                                     |          |         |

{% tab title="JSON Schema" %}

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Read action eventMeta.parameters",
  "type": "object",
  "properties": {
    "eventMeta": {
      "type": "object",
      "properties": {
        "parameters": {
          "type": "object",
          "properties": {
            "pathPath": {
              "type": "string",
              "definition": "Json path in payload for directory path to list",
              "default": "path",
              "example": "id"
            },
            "format": {
              "type": "string",
              "definition": "Format of the file contents to retrieve (json, text)",
              "enum": [
                "json",
                "text"
              ],
              "default": "text",
              "example": "json"
            },
            "maxLength": {
              "type": "integer",
              "definition": "Maximum file size in bytes allowed to read",
              "example": 10000000
            },
            "outputPattern": {
              "type": "string",
              "definition": "JMESPath pattern applied to the data output"
            }
          }
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

[^1]: Series of files (mostly used for data lakes)

[^2]: Single file

[^3]: Full event contents including metadata

[^4]: Event payload and request metadata

[^5]: Input payload with input pattern applied


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rierino.com/devops/api-event-and-process-flows/configuring-saga-steps/event-step/core-actions/perform-file-operation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
