Filtering, ordering and pagination¶

Every filter the NetOrca platform supports for an endpoint is an explicit, validated module parameter - no opaque filters: dict (that was v1). A typo'd parameter fails at the module boundary before any API call, and an invalid value comes back with the server's own validation message. The per-module reference pages list each module's full filter surface; this page explains the mechanics they share.

List filters are OR¶

Filter parameters typed as lists match records with any of the given values (the platform's in lookup):

- name: Changes that are either pending or approved, for two services
  netautomate.netorca.netorca_change_instance_info:
    service_name: [LOAD_BALANCER, DNS_RECORD]     # this service OR that one
    state: [PENDING, APPROVED]                    # open = either of these

Different parameters combine as AND: the example reads "(LOAD_BALANCER or DNS_RECORD) and (PENDING or APPROVED)".

Exact, substring, and ID filters¶

Naming is consistent across modules: plain names are exact matches (service_name, application_name), *_contains are case-insensitive substring matches (application_name_contains, and name on service items is a substring match by platform convention), *_id match numeric IDs. When you already know the record, id fetches exactly that one - and returns an empty list rather than failing if it does not exist.

Searching inside declarations¶

Service items and change instances can be filtered by the content of the consumer declaration - the platform's advanced search as first-class parameters. Each takes a dict of field: value:

Parameter	Match	Example
`declaration`	field equals value exactly	`declaration: {partition: prod}`
`declaration_contains`	value contained in the field	`declaration_contains: {comments: web}`
`declaration_regex`	field matches the regex	`declaration_regex: {name: "^prod-.*"}`

- name: Which load balancers are declared in the prod partition?
  netautomate.netorca.netorca_service_item_info:
    service_name: [LOAD_BALANCER]
    declaration:
      partition: prod

- name: Changes that would touch anything with a 10.1.10.x virtual server
  netautomate.netorca.netorca_change_instance_info:
    state: [PENDING]
    declaration_regex:
      virtual_server: "10\\.1\\.10\\."

This is the tool for validation-stage checks ("does anything already claim this IP?") and estate queries ("everything consuming the legacy datacenter") - see it used in the load balancer scenario. A runnable demo ships as declaration_search.yml.

Ordering¶

ordering sorts server-side by any field; prefix - for descending:

- name: Five most recently modified completed changes
  netautomate.netorca.netorca_change_instance_info:
    state: [COMPLETED]
    ordering: -modified
    limit: 5

Pagination and limit¶

Info modules auto-paginate: by default you get every matching record, regardless of the API's page size (v1 silently returned only the first page - issue #8). limit caps the total when you only need the top of an ordered list, and stops fetching pages as soon as it is reached.

For repeated polling, don't re-read the world - ask for what moved:

- name: Changes since the last run (incremental polling)
  netautomate.netorca.netorca_change_instance_info:
    modified_after: "{{ last_run_timestamp }}"

The platform's vocabularies¶

Every enum the parameters accept, in one place. These are validated as choices, so a typo fails before any API call.

Change instance state (the lifecycle is diagrammed in Check mode and idempotency):

Value	Meaning
`PENDING`	raised, awaiting the service owner's validation/approval
`APPROVED`	accepted, waiting to be deployed
`REJECTED`	declined by the service owner (reason in the change's log)
`COMPLETED`	deployed; for a `DELETE`, the item is now decommissioned
`ERROR`	deployment failed (detail in the change's log)
`CLOSED`	retired without completion

change_type: CREATE, MODIFY, DELETE - what the consumer's submission did to the declaration.

Service item runtime_state:

Value	Meaning
`REQUESTED`	declared, but the CREATE change has not completed yet
`IN_SERVICE`	live
`DECOMMISSIONED`	a DELETE change completed; hidden from listings unless you filter for it

Service item change_state (aggregate over the item's changes): ALL_CHANGES_COMPLETED, CHANGES_PENDING, CHANGES_APPROVED, CHANGES_REJECTED, CHANGES_ERRORED.

context: serviceowner, consumer - not a filter but a scope; see Authentication.