Skip to content

netorca_ai_document - Manage NetOrca Pack knowledge documents

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

Synopsis

  • Create, update or delete the knowledge documents attached to your services in NetOrca Pack - the reference text (runbooks, standards, inventories) retrieved into AI processor prompts (see netautomate.netorca.netorca_ai_document_info for the concept).
  • The target document is selected by id or by service_id plus filename. If none exists there, it is created; if one exists, its raw_content and enabled flag are compared and only updated on difference, so keeping a service's knowledge base in sync with files in your repository is a plain loop over this module.
  • The platform chunks and embeds content on write; indexing happens asynchronously, so num_chunks may read 0 immediately after a create.

Requirements

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

  • netorca-sdk >= 1.0.9, < 2.0.0

Parameters

Parameter Comments
enabled
bool		 Whether the document participates in retrieval.
filename
str		 The document's filename - its identity within the service alongside service_id.
id
int		 ID of an existing document.
With state=present the document must exist; use service_id plus filename to create one.
raw_content
str		 The document text. Compared verbatim against the stored content; the update is skipped when nothing differs.
Required when creating.
service_id
int		 ID of the service the document is attached to. Selects the document together with filename.
state
str		 Whether the document should exist.
Choices: present, absent
Default: present

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 Create, update and delete are predicted from the fetched state without writing.
diff_mode full Returns before/after of exactly the fields that change.

Notes

  • The platform rejects a second document with identical content on the same service; the server's message is returned verbatim as an api error.
  • 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: Keep the service knowledge base in sync with the repo
  netautomate.netorca.netorca_ai_document:
    service_id: 49
    filename: "{{ item | basename }}"
    raw_content: "{{ lookup('ansible.builtin.file', item) }}"
  loop: "{{ lookup('ansible.builtin.fileglob', 'knowledge/*.md', wantlist=true) }}"

- name: Take a document out of retrieval without deleting it
  netautomate.netorca.netorca_ai_document:
    service_id: 49
    filename: legacy-standards.md
    enabled: false

- name: Remove a document
  netautomate.netorca.netorca_ai_document:
    service_id: 49
    filename: outdated-runbook.md
    state: absent

Return values

document

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

  • Returned: when state=present
  • Type: dict
  • Sample:
{
  "enabled": true,
  "filename": "bigip-standards.md",
  "id": 143,
  "num_chunks": 4
}

msg

Human-readable summary of what happened.

  • Returned: always
  • Type: str
  • Sample:
"created bigip-standards.md on service 49"

See also

Authors

  • NetAutomate (@netautomate)