files.md

Files

The Files action evaluates its options using file generators, temporarily storing the resulting files and making them available via a randomized Mechanic URL.

This action is most useful in concert with mechanic/actions/perform, by which a task may take the resulting file URLs and pass them on to another service. Used by itself, this action can also be useful for quickly testing file generators.

Options

This action accepts a JSON object, whose keys are filenames and whose values are file generators. In this way, many files may be defined and generated by a single Files action.

Result

{% hint style="info" %} In Mechanic, actions are performed after their originating task run concludes. Actions are not performed inline during the task's Liquid rendering.

To inspect and respond to the results of an HTTP action, add a task subscription to mechanic/actions/perform, allowing the action to re-invoke the task with the action result data.

Learn more: Responding to action results {% endhint %}

A Files action returns an object having the same keys (i.e. filenames) as its input. Each value is an object, having the following properties:

File property	Description
expires_at	An ISO8601 timestamp, specifying when the file will expire
mime_type	The MIME type of the generated file
name	The filename, as given in the original action options
size	The size of the generated file, in bytes
url	The URL at which this file will be available, until it expires

Example

This task generates a variety of files. It then re-invokes itself (via mechanic/actions/perform), sending an email containing links to each of the generated files.

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

mechanic/user/trigger
mechanic/actions/perform

{% endtab %}

{% tab title="Code" %}

{% raw %}
{% if event.topic == "mechanic/user/trigger" %}
  {% action "files" %}
    {
      "journal.txt": "hello world!",
      "table.csv": "Title,SKU\nRed T-Shirt,TEE-R",
      "invoice.pdf": {
        "pdf": {
          "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
        }
      },
      "secure.zip": {
        "zip": {
          "password": "opensesame",
          "files": {
            "confirmations.txt": "this data is protected with zipcrypto encryption"
          }
        }
      },
      "external.jpg": {
        "url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
      }
    }
  {% endaction %}
{% elsif event.topic == "mechanic/actions/perform" and action.type == "files" %}
  {% capture email_body %}
    <p>The following file(s) have been generated:</p>
    <ul>
      {% for keyval in action.run.result %}
        {% assign filename = keyval[0] %}
        {% assign file = keyval[1] %}
        <li><a href="{{ file.url }}">{{ filename }}</a> ({{ file.size }} bytes)</li>
      {% endfor %}
    </ul>
    <p>-Mechanic</p>
  {% endcapture %}

  {% action "email" %}
    {
      "to": "[email protected]",
      "subject": {{ action.run.result | size | append: " file(s) generated" | json }},
      "body": {{ email_body | json }}
    }
  {% endaction %}
{% endif %}
{% endraw %}

{% endtab %} {% endtabs %}