Skip to content

netorca_ai_document_info - Query NetOrca Pack knowledge documents

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

Synopsis

  • Retrieve the knowledge documents attached to services in NetOrca Pack.
  • Documents are per-service reference text (runbooks, standards, device inventories) that the Pack framework retrieves into AI processor prompts when the processor sets enable_pack_context - the retrieval-augmented-generation (RAG) side of Pack.
  • The platform chunks and embeds each document on upload; the read-only checksum, num_chunks, num_chars and preview fields describe the indexed result. Retrieval behaviour (chunking, top-k, similarity threshold) is tuned per service with netautomate.netorca.netorca_pack_profile.

Requirements

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

  • netorca-sdk >= 1.0.9, < 2.0.0

Parameters

Parameter Comments
id
int		 Return only the document with this ID.
When set, all other filters are ignored. If the ID does not exist, an empty list is returned.
service_id
list / elements=int		 Filter by ID of the service the documents are attached to.

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: All knowledge documents my team can see
  netautomate.netorca.netorca_ai_document_info:
  register: documents

- name: The knowledge base of one service
  netautomate.netorca.netorca_ai_document_info:
    service_id: [49]
  register: service_docs

- name: One document in full (including raw_content)
  netautomate.netorca.netorca_ai_document_info:
    id: 143
  register: doc

- name: Fail the play if a service has no knowledge documents at all
  ansible.builtin.assert:
    that: service_docs.count > 0
    fail_msg: "service 49 has no documents - its processors run without context"

Return values

count

Number of returned documents.

  • Returned: always
  • Type: int
  • Sample:
1

documents

List of matching documents as returned by the NetOrca API.

  • Returned: always
  • Type: list / elements=dict
  • Sample:
[
  {
    "checksum": "12dd539f30619999b3ef9b9ba349afea6b1cbdeaaeb8f920340bbda4f638dc1b",
    "enabled": true,
    "filename": "bigip-standards.md",
    "id": 143,
    "num_chars": 2048,
    "num_chunks": 4,
    "preview": "# Load balancer standards",
    "raw_content": "# Load balancer standards\n...",
    "service": {
      "id": 49,
      "name": "VIRTUAL_SERVER"
    }
  }
]

See also

Authors

  • NetAutomate (@netautomate)