Admin & instance configuration

This page covers Alces's tools for Jira Data Center system administration: server and cluster health, search-index status and reindexing, cluster upgrades, workflow schemes, screens, instance-wide configuration (avatars, email templates, custom fields, application properties and roles, dashboard/comment properties, issue navigator columns, personal preferences, password policy, license, base URL, and upgrades), and monitoring (app/diagnostics monitoring, JMX metrics). This is a large surface — 130 tools in total. Only some of them are gated behind the separate JIRA_ADMIN_TOKEN credential: those tools only work, and only even appear to the agent, when your Alces deployment has JIRA_ADMIN_TOKEN configured, and if it isn't set they don't exist as far as the agent can tell. The rest of this page's tools run on your own regular Jira permissions (the same identity behind your normal Alces access) — Jira itself will reject a call if your account doesn't have the rights for it, but Alces doesn't require the extra token to expose them. See Admin access below for exactly which tools fall into each group.

Example prompts

• "What version of Jira are we running, and what's the build number?"
• "Are all our cluster nodes healthy right now?"
• "Is the search index in sync with the database?"
• "Trigger a background reindex" (the agent will ask you to confirm first — this is a cluster-wide operation with real cost)
• "Create a new workflow scheme called 'Support Escalation'"
• "Add the 'Story Points' field to the default screen"
• "List the tabs on the Bug screen and show me what fields are on each"
• "What's our current password policy?"
• "Is JMX metrics exposure turned on?"
• "Show me the available email notification template types"
• "Create a custom field for 'Customer Tier'"
• "What application roles do we have, and how many seats are used on each?"
• "Check whether an index snapshot is currently running"
• "Approve the in-progress cluster upgrade"
• "Change my personal issue-navigator column preference"

What's available

Server & cluster status

Tool	What it does	Admin?
admin_server_info	Get server/node version, build number, deployment type	Yes
admin_cluster_status	List Data Center cluster nodes and their alive/offline state	Yes
admin_get_cluster_zdu_state	Get the cluster's zero-downtime-upgrade (ZDU) state	Yes
admin_index_status	Compare database vs. search-index issue counts on the current node	Yes
admin_check_index_snapshot_running	Check whether an index snapshot is currently being created	Yes
admin_list_index_snapshots	List available search-index snapshots	Yes
admin_create_index_snapshot	Create an index snapshot, if one isn't already in progress. Requires confirm:true	Yes

Reindexing

Tool	What it does	Admin?
admin_trigger_reindex	Start a full Jira reindex — cluster-wide, real cost. Requires confirm:true	Yes
admin_reindex_issues	Reindex one or more individual issues synchronously. Requires confirm:true	Yes
admin_execute_pending_reindex_requests	Run all pending (queued/delayed) reindex requests. Requires confirm:true	Yes
admin_get_reindex_info	Get info on the most recent or currently running reindex	Yes
admin_get_reindex_progress	Get the progress of the most recent or currently running reindex	Yes
admin_get_reindex_request	Get the progress of a single reindex request by ID	Yes
admin_get_reindex_requests_bulk	Get the progress of multiple reindex requests by ID	Yes

Cluster node & upgrade operations

Tool	What it does	Admin?
admin_request_node_index_snapshot	Request a fresh index snapshot from a cluster node (runs in the background)	Yes
admin_set_cluster_node_offline	Mark a cluster node OFFLINE, removing it from cluster traffic. Requires confirm:true	Yes
admin_delete_cluster_node	Permanently remove an already-OFFLINE cluster node. Requires confirm:true	Yes
admin_start_cluster_upgrade	Mark a multi-node cluster ready-to-upgrade, starting a zero-downtime upgrade. Requires confirm:true	Yes
admin_approve_cluster_upgrade	Approve an in-progress zero-downtime cluster upgrade. Requires confirm:true	Yes
admin_cancel_cluster_upgrade	Cancel an in-progress zero-downtime cluster upgrade. Requires confirm:true	Yes
admin_retry_cluster_upgrade	Retry a failed zero-downtime cluster upgrade. Requires confirm:true	Yes

Assets search index

Tool	What it does	Admin?
get_assets_index_path	Get the filesystem path of the Assets search index	No
check_assets_index_integrity	Check the integrity of the Assets search index	No
persist_assets_index	Persist the Assets search index to disk. Requires confirm:true	Yes
reindex_assets_current_node	Start an Assets reindex on the current node only. Requires confirm:true	Yes
reindex_assets_cluster	Start an Assets reindex across the entire cluster. Requires confirm:true	Yes

Workflow schemes

Tool	What it does	Admin?
admin_get_workflow_scheme	Get a workflow scheme by ID, including its issue-type-to-workflow mappings	Yes
admin_create_workflow_scheme	Create a new workflow scheme	Yes
admin_update_workflow_scheme	Update a workflow scheme's name/description. Requires confirm:true	Yes
admin_delete_workflow_scheme	Permanently delete a workflow scheme. Requires confirm:true	Yes
admin_get_workflow_scheme_default	Get a workflow scheme's default workflow	Yes
admin_update_workflow_scheme_default	Update a workflow scheme's default workflow. Requires confirm:true	Yes
admin_delete_workflow_scheme_default	Remove a scheme's explicit default workflow (resets to Jira's system default). Requires confirm:true	Yes
admin_get_workflow_scheme_issue_type	Get the workflow mapped to a specific issue type in a scheme	Yes
admin_set_workflow_scheme_issue_type	Set the workflow mapped to a specific issue type in a scheme. Requires confirm:true	Yes
admin_delete_workflow_scheme_issue_type	Delete an issue type's mapping from a scheme (falls back to the default). Requires confirm:true	Yes
admin_get_workflow_scheme_workflow_mappings	Get all workflow-to-issuetype mappings for a scheme	Yes
admin_update_workflow_scheme_workflow_mapping	Replace the issue-type list mapped to a workflow in a scheme. Requires confirm:true	Yes
admin_delete_workflow_scheme_workflow_mapping	Delete a workflow's mapping from a scheme. Requires confirm:true	Yes
admin_create_workflow_scheme_draft	Create a draft copy of a scheme for safe editing	Yes
admin_get_workflow_scheme_draft	Get a workflow scheme's draft, if one exists	Yes
admin_update_workflow_scheme_draft	Update a draft scheme's name/description. Requires confirm:true	Yes
admin_delete_workflow_scheme_draft	Permanently delete a scheme's entire draft. Requires confirm:true	Yes
admin_get_workflow_scheme_draft_default	Get a draft scheme's default workflow	Yes
admin_update_workflow_scheme_draft_default	Update a draft scheme's default workflow. Requires confirm:true	Yes
admin_delete_workflow_scheme_draft_default	Remove a draft scheme's explicit default workflow. Requires confirm:true	Yes
admin_get_workflow_scheme_draft_issue_type	Get the workflow mapped to an issue type in a scheme's draft	Yes
admin_set_workflow_scheme_draft_issue_type	Set the workflow mapped to an issue type in a scheme's draft. Requires confirm:true	Yes
admin_delete_workflow_scheme_draft_issue_type	Delete an issue type's mapping from a scheme's draft. Requires confirm:true	Yes
admin_get_workflow_scheme_draft_workflow_mappings	Get all workflow-to-issuetype mappings for a scheme's draft	Yes
admin_update_workflow_scheme_draft_workflow_mapping	Replace the issue-type list mapped to a workflow in a scheme's draft. Requires confirm:true	Yes
admin_delete_workflow_scheme_draft_workflow_mapping	Delete a workflow's mapping from a scheme's draft. Requires confirm:true	Yes

Screens (reads open; 9 write tools require JIRA_ADMIN_TOKEN)

Tool	What it does	Admin?
list_screens	List field screens on this instance	No
get_screen_available_fields	Get the fields available to add to a screen	No
add_field_to_default_screen	Add a field to the single, instance-wide default field screen	Yes
get_screen_tabs	Get all tabs on a screen	No
create_screen_tab	Create a new tab on a screen	Yes
rename_screen_tab	Rename a tab on a screen	Yes
move_screen_tab	Move a tab to a new position on a screen	Yes
delete_screen_tab	Permanently delete a tab and any fields on it. Requires confirm:true	Yes
get_screen_tab_fields	Get all fields currently on a screen tab	No
add_screen_tab_field	Add a field to a screen tab	Yes
move_screen_tab_field	Move a field to a new position within a screen tab	Yes
remove_screen_tab_field	Remove a field from a screen tab. Requires confirm:true	Yes
set_screen_tab_field_show_when_empty	Update whether a field shows its "empty" indicator when unset	Yes

Custom fields

Tool	What it does	Admin?
list_custom_fields	List custom fields, paginated	No
create_field	Create a custom field from a name, type, and optional searcher	Yes
delete_custom_fields	Delete custom fields in bulk (1-50 at a time). Requires confirm:true	Yes
get_custom_field_options	Get a custom field's configured select/checkbox-style options	No
get_custom_field_option	Get a single custom field option by its numeric ID	No

Application config & properties

Tool	What it does	Admin?
get_configuration	Get instance-wide config flags (voting, watching, sub-tasks, attachments, time tracking)	Yes
get_application_property	Get an application property by key, or all of them if key is omitted	No
update_application_property	Update an application property's value by ID	Yes
get_advanced_settings	Get all advanced-settings application properties	No
list_application_roles	List application roles (e.g. Jira Software, JSM) with seat usage	No
get_application_role	Get a single application role by key	No
update_application_role	Update a single application role — instance-wide licensing config	Yes
update_application_roles	Bulk-update all application roles at once — instance-wide licensing config	Yes
get_group_members	List the members of a group	No
get_upgrade_result	Get the result of the last Jira upgrade task run	No
run_upgrade	Run any pending Jira upgrade tasks (safe no-op if nothing is pending). Requires confirm:true	Yes
update_base_url	Change the base URL this Jira instance considers itself reachable at. Requires confirm:true	Yes
validate_license	Validate a Jira license string without applying it	Yes

Priority schemes

Tool	What it does	Admin?
list_priority_schemes	List all priority schemes on this instance	No
get_priority_scheme	Get a single priority scheme by ID	No
create_priority_scheme	Create a new priority scheme	Yes
update_priority_scheme	Update a priority scheme	Yes
delete_priority_scheme	Delete a priority scheme. Requires confirm:true	Yes

Avatars

Tool	What it does	Admin?
get_system_avatars	Get all system avatars for an avatar type (e.g. project, issue type)	No
get_universal_avatars	Get all system and custom avatars for a given owner of a given type	No
create_temp_avatar	Upload a temporary avatar image, the first step before finalizing it	No
create_avatar_temporary	Upload a temporary avatar image via the legacy generic avatar route	No
update_avatar_temporary_crop	Finalize a temporary avatar upload by supplying crop instructions	No
create_avatar_from_temporary	Create a real avatar from a previously-uploaded temporary avatar	No
delete_universal_avatar	Delete an avatar by ID. Requires confirm:true	No

Email templates

Tool	What it does	Admin?
list_email_template_types	Get available email notification template types	No
get_email_templates	Get the instance's email notification templates as a zip file (metadata only)	No
update_email_templates	Upload a zip file of custom email notification templates. Requires confirm:true	Yes
apply_email_templates	Apply a previously-uploaded email templates pack, making it live. Requires confirm:true	Yes
revert_email_templates	Reset all custom email templates to Jira's built-in defaults. Requires confirm:true	Yes

Issue links (config-adjacent)

Tool	What it does	Admin?
get_issue_link	Get a single issue link by ID	No
create_issue_link	Create an issue link between two issues	No
delete_issue_link	Delete an issue link by ID. Requires confirm:true	No

Attachments (instance-level)

Tool	What it does	Admin?
get_attachment_meta	Get instance-wide attachment capabilities (enabled, upload size limit)	No
get_attachment	Get metadata for a single attachment by ID	No
get_attachment_human_expansion	Get a human-readable expansion of an attachment's contents	No
get_attachment_raw_expansion	Get a raw expansion of an attachment's contents	No
delete_attachment	Delete an attachment from an issue. Requires confirm:true	No

Dashboard & comment properties

Tool	What it does	Admin?
get_dashboard_item_properties	Get the property keys for a dashboard item	No
get_dashboard_item_property	Get a single dashboard item property's value by key	No
set_dashboard_item_property	Set a property on a dashboard item (gadget instance)	No
delete_dashboard_item_property	Delete a property from a dashboard item. Requires confirm:true	No
get_comment_properties	Get the property keys stored on a comment	No
get_comment_property	Get a single comment property's value by key	No
set_comment_property	Set a property on a comment	No
delete_comment_property	Delete a property from a comment. Requires confirm:true	No

Personal preferences & display settings (not admin-gated)

Tool	What it does	Admin?
get_my_preference	Get one of your own preferences by key	No
set_my_preference	Set a preference for your own account	No
delete_my_preference	Delete a preference for your own account. Requires confirm:true	No
get_issue_navigator_columns	Get the default system columns shown in the issue navigator	No
set_issue_navigator_columns	Set the default issue navigator columns for every user on the instance	Yes
get_password_policy	Get the instance's current password policy requirements	No

Monitoring & JMX metrics

Tool	What it does	Admin?
get_app_monitoring_status	Get whether App Monitoring is enabled on this instance	No
update_app_monitoring_status	Enable or disable App Monitoring on this instance	No
get_ipd_monitoring_status	Get whether IPD (In-Product Diagnostics) Monitoring is enabled	No
update_ipd_monitoring_status	Enable or disable IPD Monitoring on this instance	No
get_jmx_metrics_exposed	Check whether JMX (Java Management Extensions) metrics are exposed	No
start_exposing_jmx_metrics	Start exposing JMX metrics on this instance	No
stop_exposing_jmx_metrics	Stop exposing JMX metrics on this instance	No
list_available_jmx_metrics	List the JMX metric names available on this instance	No

Admin access

Of the 130 tools on this page, 75 require JIRA_ADMIN_TOKEN to be configured on your Alces deployment — they don't appear in the agent's tool list at all otherwise. The other 55 run on your regular Jira permissions through Alces's normal access; no extra token is needed, though Jira will still reject the call if your account lacks the underlying permission. (This count grew from an earlier 56/74 split: as of this project's 1.0 release, 19 previously non-admin sysadmin-only write tools were re-tiered to require JIRA_ADMIN_TOKEN — see the groups below.)

The admin-gated (JIRA_ADMIN_TOKEN-required) groups are:

• All server/cluster status, reindexing, and cluster node/upgrade operations
• The Assets index's persist_assets_index, reindex_assets_current_node, and reindex_assets_cluster (but not get_assets_index_path or check_assets_index_integrity)
• All workflow scheme tools, live and draft
• get_configuration, update_application_property, update_application_role, update_application_roles, validate_license
• set_issue_navigator_columns (setting the instance-wide default — but not get_issue_navigator_columns, which any user can read)
• The 9 screen-tab write tools — create_screen_tab, add_screen_tab_field, add_field_to_default_screen, delete_screen_tab, rename_screen_tab, remove_screen_tab_field, move_screen_tab_field, set_screen_tab_field_show_when_empty, move_screen_tab — though screen reads (list_screens, get_screen_tabs, get_screen_available_fields, get_screen_tab_fields) remain open
• create_field and delete_custom_fields (custom field creation and bulk deletion) — but not list_custom_fields/get_custom_field_options/get_custom_field_option
• create_priority_scheme, update_priority_scheme, and delete_priority_scheme — but not list_priority_schemes/get_priority_scheme
• update_email_templates, apply_email_templates, and revert_email_templates — but not list_email_template_types/get_email_templates
• update_base_url and run_upgrade

Everything else — screen reads, custom field listing/reading, priority scheme listing/reading, avatars, email template listing/reading, issue links, instance-level attachment metadata, dashboard/comment properties, personal preferences, password policy, get_upgrade_result, and all of monitoring & JMX — works without JIRA_ADMIN_TOKEN, gated only by your own Jira permissions.

Destructive & high-impact actions

The following 44 tools require an explicit confirm:true argument and will refuse to run without it. A well-behaved agent always asks you to confirm before calling one of these — treat a silent call to any of them as a bug.

Reindexing, cluster & upgrade (10):

Tool	Why it needs confirmation
admin_trigger_reindex	Cluster-wide, real-cost reindex operation
admin_reindex_issues	Real, resource-intensive reindex of the given issues
admin_execute_pending_reindex_requests	Resource-intensive reindex of every pending request
admin_set_cluster_node_offline	Removes a live cluster node from cluster traffic
admin_delete_cluster_node	Permanently removes a node from the cluster; cannot be undone
admin_create_index_snapshot	Real-cost disk I/O operation
admin_start_cluster_upgrade	Genuinely changes cluster state on a real multi-node ZDU
admin_approve_cluster_upgrade	Advances a real multi-node zero-downtime cluster upgrade
admin_cancel_cluster_upgrade	Cancels an in-progress zero-downtime cluster upgrade
admin_retry_cluster_upgrade	Retries a failed zero-downtime cluster upgrade

Operating safely: reindexing is resource-intensive and can degrade search/performance instance-wide while it runs — prefer a low-traffic window. For the cluster node operations, confirm which node you're targeting via Jira's own cluster admin UI first; node IDs in a tool response aren't always obviously mapped to hostnames, and admin_delete_cluster_node is irreversible. Cluster upgrade tools are only meaningful on a real multi-node cluster running a zero-downtime upgrade.

Assets index (3):

Tool	Why it needs confirmation
persist_assets_index	Real-cost indexing operation
reindex_assets_current_node	Real-cost indexing operation
reindex_assets_cluster	Cluster-wide, real-cost indexing operation

Operating safely: same low-traffic-window guidance as reindexing above. Prefer reindex_assets_current_node over the cluster-wide variant when only local recovery is needed — no reason to pay the cluster-wide cost for a single node's problem.

Workflow schemes (16): any update or delete on a live scheme changes how in-flight issues route through workflows; any update or delete on a draft is a step toward that same live change.

Tool	Why it needs confirmation
admin_update_workflow_scheme	Can affect a scheme already assigned to projects
admin_delete_workflow_scheme	Permanently deletes the scheme
admin_update_workflow_scheme_default	Changes how live issues route through workflows
admin_delete_workflow_scheme_default	Changes how live issues route through workflows
admin_set_workflow_scheme_issue_type	Changes how live issues of that type route
admin_delete_workflow_scheme_issue_type	Changes how live issues of that type route
admin_update_workflow_scheme_workflow_mapping	Changes how live issues route through workflows
admin_delete_workflow_scheme_workflow_mapping	Changes how live issues route through workflows
admin_update_workflow_scheme_draft	Edits a draft on its way to being published live
admin_delete_workflow_scheme_draft	Permanently deletes the entire draft
admin_update_workflow_scheme_draft_default	Edits a draft on its way to being published live
admin_delete_workflow_scheme_draft_default	Edits a draft on its way to being published live
admin_set_workflow_scheme_draft_issue_type	Edits a draft on its way to being published live
admin_delete_workflow_scheme_draft_issue_type	Edits a draft on its way to being published live
admin_update_workflow_scheme_draft_workflow_mapping	Edits a draft on its way to being published live
admin_delete_workflow_scheme_draft_workflow_mapping	Edits a draft on its way to being published live

Operating safely: check which projects use a live scheme before updating or deleting it — a change lands on every in-flight issue in every associated project immediately. Where the operation supports a draft, make and verify the change there first, then publish, rather than editing the live scheme directly. Deletions here (scheme, mapping, issue-type association) are permanent — confirm nothing still references what you're deleting.

Screens (2):

Tool	Why it needs confirmation
delete_screen_tab	Permanently deletes a tab and every field on it
remove_screen_tab_field	Removes a field from a screen tab

Operating safely: a screen is often shared across multiple issue-type screen schemes, so a change can ripple to more projects than the one you have in mind — check screen-scheme associations before deleting a tab or removing a field, not just the screen itself.

Instance configuration (13):

Tool	Why it needs confirmation
delete_priority_scheme	Permanently deletes the scheme
delete_universal_avatar	Permanently deletes the avatar
update_email_templates	Uploads a new custom email template pack instance-wide
apply_email_templates	Makes an uploaded template pack live for every outbound email
revert_email_templates	Resets all custom email templates instance-wide to Jira's defaults
delete_comment_property	Permanently deletes the property
delete_dashboard_item_property	Permanently deletes the property
delete_issue_link	Permanently deletes the link
delete_my_preference	Permanently deletes your stored preference
delete_attachment	Permanently deletes the attachment
delete_custom_fields	Permanently deletes up to 50 custom fields at once
update_base_url	Instance-wide; affects every absolute link Jira generates (emails, webhooks, OAuth callbacks) immediately
run_upgrade	Runs any pending Jira upgrade tasks instance-wide

Operating safely: update_base_url and revert_email_templates are the two to treat as maintenance-window operations communicated in advance, not casual changes — the former changes every absolute link Jira generates the moment it runs, the latter resets all custom email templates instance-wide with no per-template undo. The remaining delete_* tools in this group are simple, permanent, single-item deletes with no scheme-wide ripple like workflow schemes above — still no undo, but the blast radius is contained to the one item.

Things to know

• These tools reuse the same PAT-based (Personal Access Token) identity model as the rest of Alces: whatever Jira identity backs JIRA_ADMIN_TOKEN is what shows up in Jira's own audit log for every admin action taken here, and whatever identity backs your regular access shows up for the non-admin-gated tools.
• Being logged into Jira with admin rights in a browser doesn't matter here — Alces only knows what JIRA_ADMIN_TOKEN (and your regular token) can do via the PATs configured for it.
• Cluster upgrade and cluster node operations are only meaningful on a real, multi-node Data Center cluster running a zero-downtime upgrade (ZDU) — a rolling upgrade process that keeps the instance available while nodes are upgraded one at a time. On a single-node instance, these will generally be rejected or no-ops.
• A missing tool from the agent's list is often just JIRA_ADMIN_TOKEN not being configured, not a bug — check Admin access above to see which group a tool falls into before assuming something's broken.

See docs/api-catalog.md for the complete technical reference (every field, every parameter). For errors, see Troubleshooting.