Scripting Fiedler Data Tools with an AI Agent

We built both command line clients for people first, with real output and clear exit codes. An agent needs the same things, in a form it can parse without guessing. We checked the behaviour on our test system, on the MAS 9.2 series.

Every command as JSON

#

fdi --json help and fde --json help print every command as JSON: its usage forms, its arguments and options, whether it needs the app, what it changes, and the keys of the JSON it prints. --json help <command> prints one command. Neither needs the app or a licence, so an agent can learn the tools before it signs in.

$ fdi --json help upload | jq -c '.command | {command, changes, prints}'
{"command":"upload","changes":["app"],"prints":["job"]}
$ fde --json help export | jq -c '.command | {command, changes, prints}'
{"command":"export","changes":["app","local"],"prints":["job","plan","file","path","bytes"]}

The field changes is the one an agent needs most. It names what a command changes: local for files on this machine, app for jobs and layouts in the app, and manage for records in Manage. An empty list means the command only reads. This line lists the import commands that write into Manage:

$ fdi --json help | jq -r '[.commands[] | select(.changes | index("manage")) | .command] | join(", ")'
run, import, test, resume, review

The export writes nothing into Manage, so no fde command has manage in its list.

Errors as JSON, and exit codes

#

With --json, a command prints one JSON document on standard output. An error goes to standard error, also as one JSON document:

$ fde --json status
{"error":{"exitCode":2,"code":null,"message":"usage: fde status <job>"}}

The agent decides by the exit code. code names the app’s reason when the app refused a request, such as NOT_SIGNED_IN, PLAN_CHANGED or LICENSE_REQUIRED. It is null for an error of the command line itself, as here. message is for the person. A few of the codes:

The rules an agent follows

#

The import writes into Manage, so a few rules keep the person in charge:

• The person approves every run. upload plans a workbook and writes nothing to Manage. The agent shows the person the plan and waits for their go before run.
• The run takes only the plan the person saw. upload prints the plan with its fingerprint, and run --plan <fingerprint> runs that plan and no other. When anything changed since, nothing runs, and the command ends with exit code 12.
• Only the person gives --yes. A production profile refuses every write without it, with exit code 7, before it sends anything.
• No key on the command line. A profile says where its Maximo API key lives: an environment variable, the keychain or a file only its owner can read. The clients print [redacted] in place of a key or a token, in JSON too.
• The agent works as the person. Every write runs as the signed-in user, and Manage checks that user’s rights on every record.

The documentation of each tool includes a guide for AI agents, SKILLS.md. It holds these rules, a recipe for each common task with jq, the JSON each command prints, and every exit code.

What comes next

#

Running Fiedler Data Import shows the command line client and the test suites, and Running Fiedler Data Export the nightly export. Both command line clients need a licence of Fiedler Data Tools.

Would you like an agent to run your imports? Get in touch.

IBM and Maximo are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide.