All posts

Spooldoc 0.2.0: errors that say what to do

IBM i errors in plain words with the next step, a confirmation before a job deletes, and no failure that goes unseen.

Spooldoc 0.2.0 is out. It adds no new destinations or formats. Instead, it makes the app tell you more. When something fails, you can see it, and you can see what to do next. Before a job deletes anything on your IBM i, it asks first.

What changed

IBM i errors say what to do. A wrong password, a disabled profile, an unreachable host, a missing authority or an output queue that is not there now gets one line in plain words. The line names the host, the user profile or the object, and gives the next step, such as the CHGUSRPRF, STRHOSTSVR or GRTOBJAUT command to run. The system's own text and the message ID are under Details. When the IBM i says no has a table of the cases.

The Servers page with two servers: one connected, with its OS version and CCSID, and one that cannot be reached, with the reason and what to checkThe Servers page with two servers: one connected, with its OS version and CCSID, and one that cannot be reached, with the reason and what to check

A job asks before it starts deleting. Delete is the one action that removes something on the IBM i. When you save or activate a version that would start deleting spooled files, Spooldoc names the queue and asks you to confirm. The Jobs list marks every job whose active version deletes.

Failures no longer go unseen.

  • When the data queue reader fails, real-time queues fall back to polling. The error shows in Needs attention and on the job's Trigger step until reading works again.
  • A run that stops responding is marked failed after 3 minutes, not 6 hours.
  • Runs with warnings show in Needs attention next to failed ones.
  • The server writes one JSON line per event to stdout. Set the level with SPOOLDOC_LOG_LEVEL.
  • The list of a queue's spooled files says when it was cut off, and loads 200 more at a time.
  • A job whose saved settings no longer match the job format is listed as broken. It no longer breaks the Jobs page.

The app shows only what works. The cards for features not yet built are gone. A closed sign-up now says what is true: this Spooldoc has one account, and you sign in with it.

One way to do each thing. Empty lists, loading states, selects and toasts look and read the same everywhere. Each run in the Job log can be opened from the keyboard. Status icons have screen-reader text. Colors work in dark mode. Getting started has a step that checks that PDF output works.

All changes are in the release notes.

Upgrading

Take a pg_dump, then pull ghcr.io/strom-capital/spooldoc:0.2.0 and start it. The server applies the new migration, which adds a table for queue health and a heartbeat column on runs. Deployment has the steps.

If you call the API yourself, two things changed:

  • Activating a version that starts deleting answers 409 until you send confirmDelete: true.
  • IBM i errors answer { error, code, messageId, detail }. error is now the guidance line, and the system's text moved to detail.

Tell us

Questions go to Q&A, ideas to Ideas, bugs to the issues. If an IBM i error still reaches you without a next step, please tell us what it said. Replace real host, user and library names before you paste it.

The 0.2.0 release is on GitHub, and so is the announcement.

All changes in 0.2.0 are in the changelog.