Migrating from netautomate.netorca 1.x to 2.0

Version 2.0.0 is a full rewrite on top of netorca-sdk ≥ 1.0.9 (the SDK v2 architecture). All v1 modules were removed — there are no aliases or redirects. This guide maps every v1 module and pattern to its v2 replacement.

Staying on v1: pin the collection in requirements.yml:

collections:
  - name: netautomate.netorca
    version: "<2.0.0"

Note that v1 depends on netorca_sdk==0.2.4, whose API architecture no longer exists in current SDK releases — v1 is frozen, not maintained.

Breaking changes at a glance

1. Authentication: username/password is gone — the NetOrca API is API-key only. The username and password parameters no longer exist.
2. Parameter names: url → api_url, verify_ssl → validate_certs. Both (plus api_key and context) can now come from environment variables: NETORCA_API_URL, NETORCA_API_KEY, NETORCA_CONTEXT, NETORCA_VALIDATE_CERTS.
3. Filters: the opaque filters: dict is replaced by explicit, documented, validated module parameters (e.g. state, service_name, runtime_state).
4. Check mode is now honoured. v1 modules declared check-mode support but the update modules performed real API writes during --check. v2 write modules never mutate in check mode (netorca_submission calls the server-side validate endpoint instead — documented on the module).
5. changed is now meaningful. v1 update_change_instances reported changed incorrectly and update_charges never reported it at all. v2 modules fetch-compare-write and report changed/diff accurately.
6. Return shapes: info modules always return a list under a resource key (service_items, change_instances, …) plus count. A lookup by id that matches nothing returns an empty list instead of failing.
7. State vocabulary: change-instance states are the platform's real ones — PENDING, APPROVED, REJECTED, COMPLETED, ERROR, CLOSED. (v1 documentation advertised ACCEPTED, which the API never accepted.) Illegal transitions fail client-side with the list of legal targets.

Module mapping

v1 module	v2 replacement	Notes
get_services	netorca_service_info	explicit filters; list_tags, include_docs, dependant options
get_service_items	netorca_service_item_info	explicit filters incl. declaration/declaration_regex/declaration_contains
get_service_items_dependant	netorca_service_item_info with dependant: true	dedicated module removed
get_change_instances	netorca_change_instance_info	filter by every state (state: [PENDING, APPROVED, …]), history, referenced
update_change_instances	netorca_change_instance	transition-validated; log and deployed_item supported; real check mode
get_deployed_items	netorca_deployed_item_info	explicit filters + dependant
get_charges	netorca_charge_info	explicit filters + accumulated: true
update_charges	netorca_charge	fetch-compare-write; accurate changed

New in v2 with no v1 counterpart: the complete NetOrca Pack/AI family (AI processors, knowledge documents, pack profiles, pipeline runs, stage data, triggers) - v1 never covered these endpoints. See the Pack and AI guide.

Before / after

v1:

- name: Get service items of firewall service
  netautomate.netorca.get_service_items:
    url: https://app.netorca.io
    api_key: "{{ api_key }}"
    filters:
      service_name: Firewall
  register: results

- name: Complete a change instance
  netautomate.netorca.update_change_instances:
    url: https://app.netorca.io
    api_key: "{{ api_key }}"
    id: "{{ change_id }}"
    state: COMPLETED

v2 (with NETORCA_API_URL / NETORCA_API_KEY set in the environment):

- name: Get service items of firewall service
  netautomate.netorca.netorca_service_item_info:
    service_name: Firewall
  register: results

- name: Complete a change instance
  netautomate.netorca.netorca_change_instance:
    id: "{{ change_id }}"
    state: COMPLETED
    deployed_item: "{{ my_deployed_config }}"

Pagination

v1 returned only the first API page (issue #8). v2 info modules auto-paginate and return everything by default; use limit to cap the number of results.