Skip to main content

Configure and manage action items

At the organization level, you decide what kinds of action items developers can work with and how they move through their lifecycle. This page covers both paths: driving it from the Platform Settings UI, or automating it with the np-governance agent plugin.

info

You need an Admin or Ops role to access this section.

Manage with the np-governance agent plugin​

The np-governance plugin lets you manage action items, categories, and AI suggestions through natural-language prompts from any compatible AI coding assistant (Claude Code, Factory AI, Codex CLI, Kiro, and more). It wraps the same API endpoints used throughout this page, but handles authentication, pagination, and deduplication for you.

For step-by-step examples of what you can do with the plugin, see the tutorials:

Managing categories​

Categories are the backbone of action items. They classify what each item tracks, how it appears in the UI, and what governance rules apply when developers triage it.

From Settings > Action Items > Categories, you see every category available in your organization, the NRN it applies to, and its status:

Categories list view in Platform Settings showing name, unit, status, and created date

Create a category​

Click New Category and fill in the form:

New category form in Platform Settings showing name, description, color, icon, unit, parent, and governance controls

Most fields are self-explanatory. A few to note:

FieldBehavior
Resource (NRN)Categories inherit down the NRN hierarchy, so a category defined at the organization level is available to every account and application below it.
Color / IconColor takes a hex code, icon takes an iconify name. Both determine how items in the category render in the UI.
Unit name / symbolDefines what "value" means on items in this category, for example "Dollars" / "$" or "Hours" / "h". The unit combines with priority to compute each item's score.
Parent categoryOptional. Supports up to two levels of nesting.

The same action is available via a POST request to /action_item_category.

curl -L -X POST 'https://api.nullplatform.com/action_item_category' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "nrn": "organization=1:account=2",
    "name": "Cost optimization",
    "description": "Tracks opportunities to reduce cloud spending",
    "color": "#38A169",
    "icon": "mdi:cash",
    "unit_name": "Dollars",
    "unit_symbol": "$",
    "config": {
        "max_deferral_days": 60,
        "max_deferral_count": 2
    }
}'

Deferral limits​

Each category carries a configuration block with two limits on how items can be deferred:

SettingEffect
Max deferral daysLimits how far into the future an item can be deferred.
Max deferral countLimits how many times an item can be deferred.

Approval gating for resolve, defer, and reject is no longer part of the category. It now lives in nullplatform's approvals engine, which gives you the same governance through policies and notification channels you already use for deployments and scopes. The next section walks through it.

Category inheritance​

Categories follow the NRN hierarchy. A category defined at organization=1 is available to every account, namespace, and application below it. If a more specific category with the same name exists at a lower level, the more specific one takes precedence.

This means you can set an organization-wide policy once, then override it for a specific account or application when needed.

Require approval to transition items​

Resolving, deferring, and rejecting an item are governed by nullplatform's approvals engine, the same one that gates deployments, scopes, and services. You create an approval action for the action_item entity, attach a policy that decides when a request needs review, and route notifications through your existing channels (Slack, a webhook, or the approval request page).

Create the approval action​

The action_item entity supports three actions: action_item:resolve, action_item:defer, and action_item:reject. To require review before any item can be rejected at a given NRN, create an approval action:

curl -L -X POST 'https://api.nullplatform.com/approval/action' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "nrn": "organization=1:account=2",
    "entity": "action_item",
    "action": "action_item:reject",
    "on_policy_success": "approve",
    "on_policy_fail": "manual"
}'

Unlike deployments or scopes, action item approvals don't take dimensions: scope them through the NRN alone.

Add a policy​

A policy decides when a request needs manual review. Action item requests expose the item's fields to policy conditions, including action_item.priority, action_item.category, and action_item.status, so you can auto-approve low-stakes transitions and reserve manual review for the rest. For example, this policy passes (auto-approves) only when the item isn't critical:

{
    "nrn": "organization=1:account=2",
    "name": "Manual review for rejecting critical items",
    "conditions": {
        "action_item.priority": { "$ne": "critical" }
    }
}

With on_policy_success: "approve" and on_policy_fail: "manual", rejecting a non-critical item goes through automatically, while rejecting a critical one waits for a reviewer. Associate the policy with the action to put it into effect.

Managing action items​

From Settings > Action Items > Items, you see every item across the organization, not just the ones attached to a single application.

Action items list in Platform Settings with filters for status, priority, category, and NRN

The list view supports the same filters as the developer list, plus NRN filtering so you can slice by account, namespace, or application.

Create an item manually​

Click New Action Item to create an item by hand. This is useful when you want to track improvements that aren't surfaced by an agent, such as manual audit findings or planned migrations.

New action item form in Platform Settings with fields for title, description, NRN, category, priority, value, due date, labels, affected resources, and references

The equivalent API call is a POST request to /action_item.

curl -L -X POST 'https://api.nullplatform.com/action_item' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "title": "Upgrade base image to fix CVE-2026-1234",
    "description": "The current base image has a critical vulnerability that allows remote code execution.",
    "category_slug": "security-vulnerabilities",
    "priority": "critical",
    "value": 500,
    "due_date": "2026-05-01T00:00:00Z",
    "labels": {
        "source": "container-scan",
        "cve": "CVE-2026-1234"
    }
}'

Review pending requests​

When a developer triggers a transition that an approval action gates, the item lands in a pending_* state and an approval request goes out to your reviewers. You don't approve or deny from this list. That happens in the approvals flow: from the notification channel or the approval request page, where you can also see who requested the transition and the reason they gave.

Once the request is decided, the item advances to its final state or returns to open automatically. You can track its current state from this list or the item's Activity tab.

Close, reopen, or delete​

Beyond configuring approvals, you have a few direct actions on items:

  • Close: close an item without resolution. Closed items are terminal. Use this for items that no longer apply, such as agent-generated items whose underlying issue has disappeared.
  • Reopen: bring a closed, rejected, or deferred item back to open.
  • Delete: permanently remove an item and its suggestions.

Admin workflow​

The admin role is to set the rules, not to triage items. You configure categories, decide which transitions need approval, and create items manually when something isn't surfaced by an agent. Developers do the resolving, deferring, and rejecting; reviewers act on the approval requests those transitions generate.

A transition only passes through a pending_* state when an approval action gates it. Otherwise the item moves straight to its final state. Deferred items auto-reopen when their target date passes, and admins can close, reopen, or delete items at any point.

Next steps​