Build and run a workflow guide

What we’re going to build

We’ll start with a small workflow: receive HTML, turn it into a PDF, and return that PDF. Keeping it to one action lets us focus on how information moves through the builder.

Sign in to LongRun. You’ll also need an API key and a Bash terminal for the last part, where we call the workflow from outside the editor.

1. Give the workflow something to receive

Open Workflows → New workflow and name it Create a PDF. Select Workflow inputs, choose Add input, and create a Text input named html.

This is the place where new content will enter the workflow. We’ve chosen html as its name, so our app will send a value under that exact key. Keep the spelling and lowercase letters the same.

2. Pass that input into an action

Use the plus connector to add HTML to PDF. Now select the action and find its HTML field. Open the data picker and choose Workflow inputs → html.

That connection is the important part. We’re telling the action to use whatever HTML arrives with this run. If we typed a fixed heading into the field instead, every run would use that same heading.

Check the connection: the action’s HTML field should use Workflow inputs → html.

3. Decide what your app gets back

Select Return outputs. Add an output named pdf, then use the data picker to select the HTML-to-PDF step’s file output.

We’ve now connected the whole path: html goes in, the action makes a file, and pdf is the name we give that file on the way out. Our response will therefore contain outputs.pdf.

Check the return value: the output named pdf should point to the action’s file.

4. Try it before publishing

Open Test and put the HTML below into the html input. Run the test and open the PDF it produces. You should see Invoice 1042 and Customer: Ada.

If Issues reports a missing binding, go back to Build and check the connections we made. Don’t move on until the test produces the document you expect.

Test input

{
  "html": "<h1>Invoice 1042</h1><p>Customer: Ada</p>"
}

You should see Invoice 1042 and Customer: Ada in the test PDF.

5. Let your app call it

Click Publish workflow, then open API endpoint and copy the workflow URL. Use its workflow ID in place of WORKFLOW_ID below, and replace API_KEY with your key.

This time we’ll send Invoice 1043 for Sam. The process is the same; only the input changes. Publishing makes this version available to callers. If you edit the workflow later, publish again when you’re ready for callers to use those changes.

Run the published workflow

curl --request POST "https://api.uselongrun.app/v1/workflows/${WORKFLOW_ID}/runs" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "inputs": {
    "html": "<h1>Invoice 1043</h1><p>Customer: Sam</p>"
  }
}'

Accepted response · illustrative

{
  "id": "run_example",
  "status": "queued",
  "outputs": null,
  "error": null
}

6. Follow the run to its PDF

Copy the run id from the response and use it in the status request below. Wait a few seconds between checks while the status is queued or running; stop when it is completed, failed, or cancelled.

When it completes, look inside outputs.pdf. Remember the name we chose in Return outputs? This is where it appears. Put its file id in place of FILE_ID, download the file, and open result.pdf. This one should contain Sam’s invoice.

Check the run

curl --request GET "https://api.uselongrun.app/v1/runs/${RUN_ID}" \
  --header "Authorization: Bearer ${API_KEY}"

Completed workflow · relevant fields only

{
  "id": "run_example",
  "status": "completed",
  "outputs": {
    "pdf": {
      "id": "file_result",
      "name": "result.pdf",
      "mime_type": "application/pdf"
    }
  },
  "error": null
}

Download the result

curl --fail-with-body "https://api.uselongrun.app/v1/files/${FILE_ID}/content" \
  --header "Authorization: Bearer ${API_KEY}" \
  --output result.pdf

Docs

Build and run a workflow