How I work with Pia: habits that save me from myself
Most of what I've learned about Pia isn't syntax. It's habits. After enough packages, the same handful of things kept saving me, so here they are.
Test where the context actually exists
Some built-in tasks, like the one that fetches ticket data, throw errors if there's no ticket context behind them. Running the package from the editor just gives you a confusing failure. Run it from the same place real engineers will, the chatbot or pod on an actual ticket, and the error goes away because it was never a bug in your package.
Be careful about copying packages around
If you copy a package between sandboxes, it keeps the same package ID and the same activity static names. Push it, and you overwrite what's live. Read that twice. If another region or team needs their own version, make a genuinely new package with new IDs and new static names rather than a copy.
Same idea with shared activities. If something is tagged as shared, check with whoever owns it before you change it. If it's tagged as locked, don't touch it at all. Make a new activity with a new name and use that.
Small packages, chained
I used to try to do everything in one package. Now I'd rather have a threat-detail package that does the enrichment and a separate verdict package that does the decision, and chain from one to the other:
- task: start_package
inputs:
mode: 'detached'
package_id: '<the-other-package-id>'
handle_errors_in_package: 'true'It's easier to test, easier to rerun just the part that failed, and easier to explain to someone else. The catch is the detached-mode quirk with skip conditions I wrote about separately, so make your decisions before the chain step.
Gate risky stuff on who's running it
Pia gives you the email of the engineer running the package in $Pia_Chat_User_Email. I use it to look the person up in the PSA, pull their skills, and only continue if they have the right one. You can even gate on level instead of just presence. It's not a security boundary on its own, but it stops the "oops, wrong person clicked it" kind of mistake, and it costs one small inline script.
Put reminders in the chat
When a step has to stay manual (something an engineer should think about before they continue), I don't build a prompt that blocks. I put a plain chat message that says what to check. People read it. A blocking dialog gets clicked through.
Look at the error output first
When an activity "succeeds" but nothing happened, I open the error output before I touch the code. More than once I'd written a perfectly reasonable error handler that wrote the real reason somewhere I wasn't looking.
Keep your own notes
Pia has quirks, and they don't change on any schedule I can predict. I keep a plain text file of every weird thing I hit, with the fix next to it. Most of this blog started there.