netorca_change_instance - Transition change instances in NetOrca¶

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

Synopsis¶

Move a change instance through its lifecycle (approve, reject, complete, error, close, re-open) and optionally attach a deployed item and an operator log message.
This is the reporting half of the canonical service-owner workflow. After polling work with netautomate.netorca.netorca_change_instance_info, approve PENDING changes that pass your validation (or reject them with a log explaining why); after deploying APPROVED changes, mark them COMPLETED - ideally with deployed_item recording what was deployed - or ERROR with the failure detail in log. Never mark a change COMPLETED when the deployment failed; the consumer sees the state you report.
The module is idempotent - if the change instance is already in the requested state and no other field differs, nothing is sent and the task reports no change.
Illegal state transitions fail before any API call, listing the transitions that are legal from the current state. The platform's lifecycle is PENDING -> APPROVED -> COMPLETED, with PENDING -> REJECTED (and back to PENDING), APPROVED -> ERROR, and CLOSED reachable from any non-final state.

Requirements¶

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

netorca-sdk >= 1.0.9, < 2.0.0

Parameters¶

Parameter	Comments
deployed_item `dict`	Deployed item data to attach to the change instance, recording what was actually deployed - for example the tenant, virtual server and pool that now serve the request. Typically supplied together with `state=COMPLETED`. The consumer sees this as the deployed state of their service item. Compared against the currently deployed data first, so resubmitting the same content does not report a change.
id `int` required	ID of the change instance, usually taken from a netautomate.netorca.netorca_change_instance_info result.
log `str`	Operator log message recorded on the change instance, for example the reason for a rejection or the error trace of a failed deployment.
state `str` required	Desired state of the change instance. `APPROVED` accepts a pending request for deployment; `REJECTED` declines it; `COMPLETED` records a successful deployment; `ERROR` records a failed one; `CLOSED` retires the change; `PENDING` re-opens a rejected change. Choices: `PENDING`, `APPROVED`, `REJECTED`, `COMPLETED`, `ERROR`, `CLOSED`

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`
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	The transition is validated and the result projected without calling the API.
diff_mode	full	Returns before/after for the fields being changed.

Notes¶

API transitions like the ones this module performs are always available to the service-owning team. The service's allow_manual_approval / allow_manual_completion flags govern only whether humans may approve/complete from the GUI - they do not affect this module.
An HTTP 403 here therefore means the API key's team does not own the service, or the context is wrong.
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.

Examples¶

- name: Approve a pending change
  netautomate.netorca.netorca_change_instance:
    id: 987
    state: APPROVED

- name: Complete a change and record the deployed item
  netautomate.netorca.netorca_change_instance:
    id: 987
    state: COMPLETED
    deployed_item:
      fqdn: app01.example.com
      record_id: 5541

- name: Reject with a reason
  netautomate.netorca.netorca_change_instance:
    id: 988
    state: REJECTED
    log: "Address range collides with the transfer network."

- name: Report a failed deployment
  netautomate.netorca.netorca_change_instance:
    id: 989
    state: ERROR
    log: "{{ ansible_failed_result.msg | default('deployment failed') }}"

Return values¶

change_instance¶

The change instance after the operation (or the projected result in check mode).

Returned: always
Type: dict
Sample:

{
  "change_type": "CREATE",
  "id": 987,
  "state": "COMPLETED"
}

msg¶

Human-readable summary of what happened.

Returned: always
Type: str
Sample:

"state APPROVED -> COMPLETED"

Authors¶

NetAutomate (@netautomate)