netorca_change_instance_info - Query change instances in NetOrca¶

Part of the netautomate.netorca collection (version 2.0.0). Added in version 2.0.0.

Synopsis¶

Retrieve change instances from NetOrca, with every filter the platform supports exposed as a validated module parameter.
A change instance represents one requested change on a service item - a CREATE, MODIFY or DELETE - and moves through the lifecycle PENDING -> APPROVED -> COMPLETED, with REJECTED, ERROR and CLOSED as the exception paths. The requested state is carried in each change's new_declaration.
This module is the polling half of the canonical service-owner workflow. Fetch PENDING changes to validate and approve, fetch APPROVED changes to deploy, then report the outcome with netautomate.netorca.netorca_change_instance.
Consumers use it (with context=consumer) to track the state of their own requests - a request is live on the infrastructure once its change instance reaches COMPLETED.

Requirements¶

The below requirements are needed on the host that executes this module.

netorca-sdk >= 1.0.9, < 2.0.0

Parameters¶

Parameter	Comments
application_id `list` / elements=`int`	Filter by ID of the consumer application the change belongs to.
change_type `list` / elements=`str`	Filter by type of change. A `DELETE` change that completes moves its service item to the `DECOMMISSIONED` runtime state - poll for these to decommission infrastructure. Choices: `CREATE`, `MODIFY`, `DELETE`
commit_id `str`	Filter by the Git commit ID recorded on the submission (substring match) - traces a merge in the consumer's repository to the changes it produced.
consumer_team_id `list` / elements=`int`	Filter by ID of the consuming team that requested the change.
declaration `dict`	Filter by exact match on fields of the change's new declaration, for example `{"partition": "prod"}`.
declaration_contains `dict`	Filter by containment match on fields of the change's new declaration.
declaration_regex `dict`	Filter by regular expression match on fields of the change's new declaration, for example `{"name": "^prod-.*"}`.
dependant `bool`	Query the dependant view (`change_instances/dependant`) instead of the plain listing. Lists the dependant copies of change instances assigned to your team because the service declares your team in its `dependant_teams` (see the NetOrca documentation on dependant teams). Default: `false`
exclude_referenced `bool`	Exclude referenced change instances - `MODIFY` changes raised on a service item only because another service item its declaration references was changed. Enable this to list just the changes consumers made directly.
id `int`	Return only the change instance with this ID. When set, all other filters are ignored. If the ID does not exist, an empty list is returned.
include_history `bool`	Also return the state history of the change instance selected by `id` - the audit trail of every transition the change went through, with actor and timestamp. Default: `false`
modified_after `str`	Only return change instances modified at or after this ISO 8601 timestamp, for example `2026-07-01T00:00:00Z`. Useful for incremental polling - fetch only what moved since the previous run.
referenced `bool`	Query the referenced view (`change_instances/referenced`) instead of the plain listing, returning only the referenced change instances described under `exclude_referenced`. Default: `false`
service_id `list` / elements=`int`	Filter by service ID.
service_item_id `list` / elements=`int`	Filter by ID of the service item the change applies to.
service_name `list` / elements=`str`	Filter by exact service name, for example `LOAD_BALANCER`. Usually the first filter a service owner sets when polling their work queue.
service_owner_team_id `list` / elements=`int`	Filter by ID of the team that owns the service.
state `list` / elements=`str`	Filter by change instance state. Any combination can be requested - for example `PENDING` plus `APPROVED` is everything still open. Choices: `PENDING`, `APPROVED`, `REJECTED`, `COMPLETED`, `ERROR`, `CLOSED`
submission_id `list` / elements=`int`	Filter by ID of the consumer submission that created the change.

Common parameters¶

Connection and query parameters shared by every module in the collection. See Authentication for the environment-variable pattern.

Parameter	Comments
context `str`	Point of view for the request. The same query returns different data depending on which side of the service relationship your team is on. `serviceowner` operates on the services your team offers - the requests made against them, their service items and deployed items. This is the side that validates, approves, deploys and completes changes. `consumer` operates on what your team consumes - the service items your applications declared and the change instances tracking your own requests. If not set, the value of the `NETORCA_CONTEXT` environment variable is used. Choices: `serviceowner`, `consumer` Default: `serviceowner`
limit `int`	Maximum number of results to return. Results are auto-paginated, so by default all matching records are returned regardless of the API's page size.
ordering `str`	Server-side field to order results by, for example `created` or `modified`. Prefix with `-` for descending order - `-modified` returns the most recently changed records first.
api_url `str` required	Base URL of the NetOrca API, for example `https://api.example.netorca.io`. The URL is normalised to end in a single `/v1`, so passing it with or without the suffix both work. If not set, the value of the `NETORCA_API_URL` environment variable is used.
api_key `str` required	API key of your NetOrca team. The NetOrca API supports API-key authentication only - there is no username/password mode. Treat the key like a password - supply it via the `NETORCA_API_KEY` environment variable (for example from a CI/CD secret) or from Ansible Vault, never as a literal in a playbook. If not set, the value of the `NETORCA_API_KEY` environment variable is used.
validate_certs `bool`	Whether to validate TLS certificates when talking to the API. Only disable this for lab instances with self-signed certificates. If not set, the value of the `NETORCA_VALIDATE_CERTS` environment variable is used. Default: `true`

Attributes¶

Attribute	Support	Description
check_mode	full	This module is read-only and runs identically with and without check mode.
diff_mode	N/A	This module never changes anything, so there is nothing to diff.

Notes¶

All modules talk to the NetOrca REST API and are typically executed on the controller (hosts=localhost with gather_facts=false, or delegate_to=localhost).
Module parameters take precedence over their NETORCA_* environment variable fallbacks.
Info modules never change anything and always return changed=false.
When nothing matches - including a lookup by ID that does not exist - info modules return an empty list rather than failing.
Filter options that accept a list match records with any of the given values (an OR filter, the platform's in lookup).

Examples¶

- name: Validation queue - pending LOAD_BALANCER changes to review
  netautomate.netorca.netorca_change_instance_info:
    service_name: [LOAD_BALANCER]
    state: [PENDING]
  register: pending

- name: Deployment queue - approved changes ready to fulfil
  netautomate.netorca.netorca_change_instance_info:
    service_name: [LOAD_BALANCER]
    state: [APPROVED]
  register: approved

- name: Everything still open across my services
  netautomate.netorca.netorca_change_instance_info:
    state: [PENDING, APPROVED]
    exclude_referenced: true
  register: open_changes

- name: Deletions requested since yesterday
  netautomate.netorca.netorca_change_instance_info:
    change_type: [DELETE]
    modified_after: "2026-07-02T00:00:00Z"
  register: deletions

- name: One change instance with its full state history
  netautomate.netorca.netorca_change_instance_info:
    id: 987
    include_history: true
  register: change

Return values¶

change_instances¶

List of matching change instances as returned by the NetOrca API.

Returned: always
Type: list / elements=dict
Sample:

[
  {
    "change_type": "CREATE",
    "id": 987,
    "new_declaration": {
      "declaration": {
        "fqdn": "app01.example.com"
      }
    },
    "service_item": {
      "id": 1234,
      "name": "dns-item-0001"
    },
    "state": "APPROVED"
  }
]

count¶

Number of returned change instances.

Returned: always
Type: int
Sample:

history¶

State history of the change instance, when include_history=true.

Returned: when id and include_history are set
Type: list / elements=dict

Authors¶

NetAutomate (@netautomate)