x
"} + +# get_ticket_custom_fields / set_ticket_custom_fields -- NESTED, +# outer key is container.name: +values = {"extrainfo": {"extrainfofield": "new
"}} +``` + +## Procedure + +1. Create a client from the `glpi-client-setup` skill, adding `v1_base_url` and `v1_user_token`. +2. Discover containers with `list_plugin_fields_containers(itemtype="Ticket")`. `itemtype` is optional and filtered client-side. An uninstalled plugin does **not** return `[]`: it raises `GlpiStatusError` with `.status_code == 400` and `ERROR_RESOURCE_NOT_FOUND_NOR_COMMONDBTM` in `.response_text`. An installed-but-unused plugin returns `[]`. +3. Discover fields with `list_plugin_fields_fields(container_id=container.id)`. `field.name` is the key you put in a `values` dict; `field.type` (`string`, `text`, `richtext`, `dropdown`, `yesno`, `date`, `datetime`, `number`, `url`, `header`) tells you the value format. +4. Read the stored row with `list_item_plugin_field_rows(itemtype, items_id, container_name)` -- ordinary parameters, passable positionally or by keyword. It returns zero or one `GetPluginFieldsValueRow`; the values live in `row.extra_payload` and `row.id` is the `row_id` an update needs. +5. Write with `update_item_plugin_field_row(itemtype=..., container_name=..., row_id=..., values=...)` when a row exists, otherwise `create_item_plugin_field_row(itemtype=..., items_id=..., container_id=..., container_name=..., values=..., entities_id=...)`, which returns the new row id. Both are keyword-only. +6. On Tickets only, `get_ticket_custom_fields(ticket_id)` and `set_ticket_custom_fields(ticket_id, values)` fold steps 2-5 into one call each, using the nested mapping. For every other itemtype, drive steps 2-5 yourself. + +## Examples + +Discovery, including the branch that tells "plugin absent" apart from "plugin configured but empty": + +```python +import asyncio + +from glpi_python_client import AsyncGlpiClient, GlpiStatusError + +# GLPI answers 400 with this marker when the itemtype in the URL is not a +# known CommonDBTM subclass -- which is what an uninstalled plugin looks +# like from the outside. +PLUGIN_ABSENT = "ERROR_RESOURCE_NOT_FOUND_NOR_COMMONDBTM" + + +async def main() -> None: + async with AsyncGlpiClient( + glpi_api_url="https://glpi.example.com/api.php/v2", + client_id="oauth-client-id", + client_secret="oauth-client-secret", + v1_base_url="https://glpi.example.com/api.php/v1", + v1_user_token="legacy-user-token", + ) as client: + try: + containers = await client.list_plugin_fields_containers(itemtype="Ticket") + except GlpiStatusError as exc: + if exc.status_code == 400 and PLUGIN_ABSENT in (exc.response_text or ""): + print("the GLPI Fields plugin is not installed on this instance") + return + raise + + for container in containers: + if container.id is None or not container.name: + continue + # container.name is the internal key you reuse verbatim; + # container.label is the UI label and is never a valid key. + print(container.id, container.name, container.label, container.is_active) + fields = await client.list_plugin_fields_fields(container_id=container.id) + for field in fields: + print(" ", field.name, field.type, field.is_active, field.is_readonly) + + +asyncio.run(main()) +``` + +Read one ticket's custom fields. The result is the nested mapping, and a container with nothing saved is missing from it entirely: + +```python +from glpi_python_client import AsyncGlpiClient + + +async def ticket_note(client: AsyncGlpiClient, ticket_id: int) -> str | None: + """Return one ticket's `extrainfo.extrainfofield` value, if it has one.""" + values = await client.get_ticket_custom_fields(ticket_id) + # {'extrainfo': {'extrainfofield': 'test
'}} + + # Containers with no persisted row are ABSENT, not empty: `.get`, never []. + note = values.get("extrainfo", {}).get("extrainfofield") + + # The inner dict is the row's extra_payload -- dynamic columns only, so + # it carries no row id. For that, drop to the low-level row listing: + rows = await client.list_item_plugin_field_rows("Ticket", ticket_id, "extrainfo") + if rows: + print(rows[0].id, rows[0].items_id, rows[0].extra_payload) + return note +``` + +Write to a ticket with the high-level upsert. Values go over the wire verbatim, so a `richtext` field takes raw HTML: + +```python +from glpi_python_client import GlpiValidationError + +await client.set_ticket_custom_fields( + 1234, {"extrainfo": {"extrainfofield": "Handled by the NOC shift
"}} +) +# GET containers, GET fields, GET rows, then PUT {"input": {"id": 1, ...}} +# -- or POST with items_id/itemtype/plugin_fields_containers_id if no row exists. + +await client.set_ticket_custom_fields(1234, {}) # empty mapping: zero HTTP calls + +# Container names are matched EXACT-CASE against container.name. +try: + await client.set_ticket_custom_fields(1234, {"ExtraInfo": {"extrainfofield": "x"}}) +except GlpiValidationError as exc: + print(exc) # Unknown plugin-fields container(s) for Ticket: ExtraInfo + +# The call is not atomic across containers, so write one per call when a +# rejected field name must not leave the earlier container already written. +payload = { + "extrainfo": {"extrainfofield": "a
"}, + "secondary": {"othercolumn": "b"}, +} +for container_name, columns in payload.items(): + await client.set_ticket_custom_fields(1234, {container_name: columns}) +``` + +Upsert on any other itemtype, with the flat `values` dict and the low-level helpers: + +```python +from glpi_python_client import AsyncGlpiClient + + +async def upsert_plugin_field_row( + client: AsyncGlpiClient, + itemtype: str, # "Computer", "Problem", "Change", ... + items_id: int, + container_id: int, # container.id -- create needs it in the body + container_name: str, # container.name -- it builds the URL itemtype + values: dict[str, object], # FLAT: {field.name: value} +) -> int: + """Update this container's row for one item, creating it when absent.""" + # Positional is allowed here (ordinary parameters); the two writers + # below are keyword-only and raise TypeError if called positionally. + rows = await client.list_item_plugin_field_rows(itemtype, items_id, container_name) + if rows and rows[0].id is not None: + await client.update_item_plugin_field_row( + itemtype=itemtype, + container_name=container_name, + row_id=rows[0].id, + values=values, # only these columns are touched + ) + return rows[0].id + return await client.create_item_plugin_field_row( + itemtype=itemtype, + items_id=items_id, + container_id=container_id, + container_name=container_name, + values=values, + # `entities_id` is create-only and is omitted from the body unless + # you pass it, letting the server apply its default scope. Do NOT + # hardcode 0 here: 0 is not None, so it would pin every row you + # create to entity 0. Pass a real entity id only when you mean one. + ) +``` + +## Gotchas + +- **The two `values` shapes are the main trap.** `create_item_plugin_field_row` and `update_item_plugin_field_row` take a **flat** `dict[str, object]` of field name to value -- `values={"extrainfofield": "x
"}`. `get_ticket_custom_fields` returns, and `set_ticket_custom_fields` accepts, a **nested** `dict[str, dict[str, Any]]` keyed by container name -- `{"extrainfo": {"extrainfofield": "new
"}}`. Passing the nested shape to the low-level create sends the inner dict as a column value; passing the flat shape to `set_ticket_custom_fields` makes field names look like container names and raises `GlpiValidationError: Unknown plugin-fields container(s) for Ticket: ...`. +- `container_name` and `container_id` are not interchangeable, and `create_item_plugin_field_row` needs **both**. The name builds the URL itemtype, lowercased (`Ticket` + `extrainfo` gives `PluginFieldsTicketextrainfo`, and `Ticket/1234/PluginFieldsTicketextrainfo` for the row list). The id is a body column, `plugin_fields_containers_id`, and it is also what `list_plugin_fields_fields(container_id=...)` filters on. `update_item_plugin_field_row` needs only the name plus a `row_id`, which identifies the record on its own. `list_item_plugin_field_rows` needs only the name too, and has **no** `row_id` parameter -- its signature is exactly `(itemtype, items_id, container_name)`; it is what you call *to obtain* a `row_id`. +- Container-name matching in `set_ticket_custom_fields` is **exact-case** against `container.name`, while the URL derivation lowercases. So `{"ExtraInfo": {...}}` raises `GlpiValidationError` when the container is actually named `extrainfo`, even though the derived URL would have been identical. Copy `container.name` verbatim from discovery; never retype it and never substitute `container.label`. +- `set_ticket_custom_fields` is **not atomic across multiple containers**, despite a docstring claiming validation happens "before any write to keep the call atomic". Only the unknown-*container* check runs up front for the whole payload; the unknown-*field* check runs per container inside the write loop. With two containers where the second has a typo, the first is already written when the error raises. Write one container per call when you need all-or-nothing. +- `get_ticket_custom_fields` returns **only `extra_payload`** -- every *undeclared* key of the row, not a curated list of the plugin's fields. So the row's `id`, `items_id`, `itemtype`, `plugin_fields_containers_id` and `entities_id` are absent (use `list_item_plugin_field_rows` when you need the `row_id`), and any other bookkeeping column the v1 server returns appears alongside real values. Intersect against `list_plugin_fields_fields` names if you need only declared fields. +- A container that has never had a value saved for that ticket is **silently absent** from the `get_ticket_custom_fields` result -- you do not get `{"container": {}}`. Use `result.get(name, {})`, never `result[name]`. An empty overall dict is **ambiguous**: `get_ticket_custom_fields` builds its result by skipping every container with no persisted row, so `{}` comes back both when the instance declares no Ticket containers at all and when it declares several but this ticket has saved nothing in any of them. The return value cannot tell you which -- call `list_plugin_fields_containers(itemtype="Ticket")` if you need to know. +- Both discovery listings fetch **one fixed page, `range=0-999`**, with no pagination and no server-side filtering. The `itemtype` and `container_id` narrowing happens client-side *after* that cap, so an instance with more than 1000 containers or field declarations silently loses the tail -- possibly including the container you are looking for. +- Neither listing filters on `is_active`, so **disabled containers and disabled or read-only fields come back from discovery looking exactly like live ones**. `set_ticket_custom_fields` accepts a field whose `is_readonly` is `True`, because its guard only checks that the name is declared. Check `container.is_active`, `field.is_active` and `field.is_readonly` yourself. +- Values are transmitted **verbatim -- there is no HTML/Markdown conversion on this path**, unlike ticket and KB article content. A `richtext` field takes raw HTML (`"test
"`). Convert yourself if you want Markdown: `GlpiContentConverter` is not exported from the package root, import it from `glpi_python_client.content`. +- The two convenience helpers are **Ticket-only** -- the itemtype is hardcoded. There is no `get_item_custom_fields` and no `set_item_custom_fields`. For Computer, Problem, Change and the rest, drive the generic row helpers. +- Parameter-passing style is inconsistent across the family, and only one half of it is a rule. `list_item_plugin_field_rows(itemtype, items_id, container_name)` declares ordinary `POSITIONAL_OR_KEYWORD` parameters, so both `("Ticket", 1234, "extrainfo")` and `(itemtype="Ticket", items_id=1234, container_name="extrainfo")` are legal -- the examples above pass them positionally by choice, not by requirement. `create_item_plugin_field_row` and `update_item_plugin_field_row` are genuinely **keyword-only** (`*` in the signature): calling either writer positionally is a `TypeError`. +- Error taxonomy on the write path: an unknown container name or an unknown field name raises `GlpiValidationError`; a container the server returned without an `id`, or a create whose v1 reply carries no numeric row id, raises `GlpiProtocolError`. Both inherit `ValueError`. A missing v1 session raises a plain `RuntimeError`, and a non-success v1 status raises `GlpiStatusError` (with `.status_code`, `.url` and `.response_text`). +- `entities_id` exists on **create only**, and is left out of the body unless explicitly passed. `update_item_plugin_field_row` has no such parameter -- its body is exactly `{"input": {"id": row_id, **values}}`. `set_ticket_custom_fields` never passes it, so rows it creates take the GLPI server's default scope. +- Cost is **linear and sequential**; there is no concurrent fan-out in this family. `get_ticket_custom_fields` costs one container list plus one row list per Ticket container. `set_ticket_custom_fields` costs one container list plus, per container in the payload, one field list, one row list and one write -- and it re-reads discovery on every call, with no caching. Cache the container and field listings yourself when writing many tickets in a loop. +- `PostPluginFieldsValueRow` is exported at the package root but is **dead surface for callers**: no client method takes or returns it. `create_item_plugin_field_row` assembles the request body itself from a plain dict. Building this model and handing it to the client neither type-checks nor works. diff --git a/skills/glpi-reporting-and-context/SKILL.md b/skills/glpi-reporting-and-context/SKILL.md index 946a57d..db93bce 100644 --- a/skills/glpi-reporting-and-context/SKILL.md +++ b/skills/glpi-reporting-and-context/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.10+, glpi-python-client, network access to the GLPI v2 API, and credentials allowed to read tickets, tasks, users, entities, and timeline records." metadata: package: glpi-python-client - version: "0.4.0" + version: "0.4.1" --- # GLPI Reporting And Context @@ -14,10 +14,10 @@ metadata: Custom helpers on `GlpiClient` build on top of the contract-aligned API mixins: - `get_ticket_context(ticket_id)` returns one `GlpiTicketContext` bundling the primary ticket together with its tasks, followups, solutions, and timeline document links. The five underlying calls are independent and are issued through the library's internal `gather` helper, so they fan out concurrently on `AsyncGlpiClient` and run one after another on `GlpiClient`. Expect the synchronous call to take roughly five round trips. -- `get_ticket_statistics(...)` returns ticket counts grouped by entity, status, priority, and type over an ISO date window applied to GLPI `date_creation`. Accepts `entity_id`, `entity_name` (substring match resolved via `search_entities`), and `extra_filter` (raw RSQL AND-joined with the window). +- `get_ticket_statistics(...)` returns ticket counts grouped by entity, status, priority, and type over an ISO date window applied to GLPI `date_creation`. Accepts `entity_id`, `entity_name` (substring match resolved via `search_entities`), and `extra_filter` (raw RSQL AND-joined with the window). **It aggregates at most 200 tickets**: it issues a single `search_tickets(..., limit=200)` call and does not paginate, so any window matching more than 200 tickets is silently truncated and the counts are wrong. For windows that can exceed 200 tickets, page `iter_search_tickets` yourself and aggregate, or narrow the window/entity until the total is under the cap. The same 200-row cap applies to the `entity_name` lookup, so a substring matching more than 200 entities is truncated too. Every v2 ticket search in the statistics layer also pins `is_deleted==false`, so soft-deleted ("trashed") tickets are excluded from these aggregates and from `get_task_durations` / `get_user_activity` — a raw `search_tickets` call with the same filter will return more rows, because v2 includes the trash by default. - `get_task_statistics(ticket_ids)` returns task duration totals grouped by user and ticket for a caller-supplied list of ticket IDs. -- `get_task_durations(...)` is a higher-level helper that internally iterates `iter_search_tickets` with a date/entity/user filter, computes per-user and per-entity duration totals, and optionally returns a flat per-task list when `return_task_details=True`. -- `get_user_activity(...)` aggregates per-user activity (tickets as technician, tickets as recipient, task durations) over a date window; resolves users by `user_id`, `username`, `realname`, or `firstname` and merges users that share the same display key. +- `get_task_durations(...)` is a higher-level helper that internally iterates `iter_search_tickets` with a date/entity RSQL filter, computes per-user and per-entity duration totals, and optionally returns a flat per-task list when `return_task_details=True`. `user_id` is **not** part of the RSQL filter: the v2 `team` array cannot be joined by the RSQL engine, so the ticket ids for that actor are resolved through the legacy v1 search engine (searchOptions 5 `Technicien` and 4 `Demandeur`, OR-ed) and intersected client-side. Passing `user_id` therefore requires a client built with `v1_base_url` + `v1_user_token`, or the call raises `RuntimeError`; a non-positive or non-`int` id raises `GlpiValidationError`. Once the matched ticket set reaches 25 tickets and a v1 session is present, task aggregation switches from the per-ticket v2 fan-out to one bulk sweep of the v1 `TicketTask` collection (paged 1000 rows at a time); the aggregate is identical either way. +- `get_user_activity(...)` aggregates per-user activity (tickets as technician, tickets as recipient, task durations) over a date window; resolves users by `user_id`, `username`, `realname`, or `firstname` and merges users that share the same display key. The technician and recipient counts have **no v2 equivalent** and are resolved through the legacy v1 search engine (searchOption 5 `Technicien`, 4 `Demandeur`), intersected with the ids returned by a single walk of the date window. This helper therefore **always** requires a client built with `v1_base_url` + `v1_user_token` and raises `RuntimeError` naming the missing options when they are absent. - `iter_search_tickets`, `iter_search_users`, `iter_search_entities` yield successive `list[...]` batches of contract models and stop on the first short batch. They handle pagination so callers do not manage `start` cursors manually. Returned identifiers are raw GLPI numeric values; resolve them with the appropriate `search_*` helpers when human-readable labels are needed. @@ -25,12 +25,12 @@ Returned identifiers are raw GLPI numeric values; resolve them with the appropri ## Procedure 1. Create a client (`GlpiClient` or `AsyncGlpiClient`) with the correct entity/profile scope. -2. For one ticket, call `await client.get_ticket_context(ticket_id)` and read `bundle.ticket`, `bundle.tasks`, `bundle.followups`, `bundle.solutions`, and `bundle.documents`. +2. For one ticket, call `await client.get_ticket_context(ticket_id)` and read `bundle.ticket`, `bundle.tasks`, `bundle.followups`, `bundle.solutions`, and `bundle.documents`. To render the whole bundle as one Markdown transcript (ticket title, subtitle metadata, description, chronologically sorted timeline, linked documents), call `bundle.to_markdown()`. Pass a `TicketMarkdownOptions` to drop sections or metadata, e.g. `bundle.to_markdown(TicketMarkdownOptions(include_documents=False, show_dates=False))`; all 17 flags default to `True`, so a bare `to_markdown()` emits everything. Both `GlpiTicketContext` and `TicketMarkdownOptions` are exported from `glpi_python_client`. 3. For ticket counts, call `await client.get_ticket_statistics(start_date=..., end_date=..., default_days=..., entity_id=..., entity_name=..., extra_filter=...)`. All keyword arguments are optional; the default window is the last 30 days ending today. 4. For task duration totals on a known ticket list, call `await client.get_task_statistics(ticket_ids)`. For an end-to-end "duration over a window with filters" report, call `await client.get_task_durations(...)` instead; it gathers the ticket IDs internally. 5. For a per-user activity report, call `await client.get_user_activity(username=..., start_date=..., end_date=...)`. Supply at least one of `user_id`, `username`, `realname`, `firstname`. 6. For memory-bounded pagination over large result sets, iterate `iter_search_tickets` / `iter_search_users` / `iter_search_entities` with `async for batch in client.iter_search_*(...): ...`. -7. Use the public enums (`GlpiTicketStatus`, `GlpiTicketType`, `GlpiPriority`, ...) when composing additional RSQL filters. +7. Use the public enums when composing additional RSQL filters. There are eight, all exported from `glpi_python_client`, and this is the whole list: `GlpiTicketStatus` (`NEW = 1`, `ASSIGNED = 2`, `PLANNED = 3`, `PENDING = 4`, `SOLVED = 5`, `CLOSED = 6`, `VALIDATION = 10`), `GlpiTicketType` (`INCIDENT = 1`, `REQUEST = 2`), `GlpiPriority` (`VERY_LOW = 1` .. `VERY_HIGH = 5`, `MAJOR = 6`), `GlpiGlobalValidation` and `GlpiSolutionStatus` (both `NONE = 1`, `WAITING = 2`, `ACCEPTED = 3`, `REFUSED = 4`), `GlpiTaskState` (`INFORMATION = 0`, `TODO = 1`, `DONE = 2`), `GlpiTimelinePosition` (`INVALID = -1`, `NONE = 0`, `LEFT = 1`, `RIGHT = 2`, `LEFT_BIG = 3`, `RIGHT_BIG = 4`) and `GlpiUserAuthType` (`LOCAL = 1`, `LDAP = 2`, `MAIL = 3`, `CAS = 4`, `X509 = 5`, `EXTERNAL = 6`). All eight subclass `GlpiEnum`, which is exported too and is a plain `IntEnum` with two conveniences for filter building: `.glpi_id` returns the number, and `.rsql_equals("status")` returns the RSQL fragment, so `GlpiTicketStatus.NEW.rsql_equals("status")` replaces the hand-written `f"status=={int(GlpiTicketStatus.NEW)}"` below. ## Examples @@ -57,8 +57,10 @@ stats = await client.get_ticket_statistics( print(stats["entities"]) ``` -Aggregate task durations across the open tickets of an entity using -`get_task_durations` (no manual ticket-list gathering): +Aggregate task durations for one entity over the default 30-day window using +`get_task_durations` (no manual ticket-list gathering). `user_id` resolves +through the legacy v1 search engine, so the client must carry `v1_base_url` + +`v1_user_token` or this call raises `RuntimeError`: ```python durations = await client.get_task_durations( @@ -116,8 +118,8 @@ print(f"processed {total} tickets") ``` Measured against a 50 ms server, a fan-out of 16 took 350 ms unbounded and 108 ms capped at 16. This is a property of the HTTP layer, not of this library, and there is no version to upgrade to. -- `get_ticket_statistics`, `get_task_durations`, and `get_user_activity` validate their date window locally and raise `ValueError` when `default_days < 1` or `start_date > end_date`. The window is applied to `date_creation` server-side. +- `get_ticket_statistics`, `get_task_durations`, and `get_user_activity` validate their date window locally and raise `GlpiValidationError` when `default_days < 1`, when `start_date` / `end_date` is not a valid ISO `YYYY-MM-DD` string, or when `start_date > end_date`. `GlpiValidationError` is exported from the package root and inherits `ValueError`, so `except ValueError` still catches it. The window is applied to `date_creation` server-side. - `get_task_statistics(ticket_ids=[])` returns zeroed totals without any HTTP call. `get_task_durations` likewise returns zeroed totals when no tickets match the filter, and short-circuits with zeros when `entity_name` resolves to no entities. -- `get_user_activity` raises `ValueError` when no identifier is supplied and when the criteria match no users. Multiple users with the same `f"{firstname} {realname}"` display key are merged into one bucket. -- Returned counter keys are raw GLPI numeric identifiers (entity IDs, status numbers, user IDs as strings) for stable behaviour. Resolve to labels with `search_entities` / `get_user` or the appropriate enum. +- `get_user_activity` raises `GlpiValidationError` (a `ValueError` subclass, exported from the package root) when no identifier is supplied and when the criteria match no users. Multiple users with the same `f"{firstname} {realname}"` display key are merged into one bucket. +- Counter keys are raw GLPI numeric identifiers **only where a numeric id exists**: entity bucket keys and `by_status` keys are the numeric id as a string (falling back to the name, then `"unknown"` / `"UNKNOWN"`), and `duration_by_user` keys are user IDs as strings. `by_priority` and `by_type` keys are instead the **enum member names** — `"VERY_LOW"`, `"LOW"`, `"MEDIUM"`, `"HIGH"`, `"VERY_HIGH"`, `"MAJOR"` for `GlpiPriority` (GLPI's priority scale has six levels; `MAJOR = 6` exists even though the published contract advertises five), and `"INCIDENT"` / `"REQUEST"` for `GlpiTicketType`, with `"UNKNOWN"` when the field is absent. Resolve the numeric ids to labels with `search_entities` / `get_user`. - Extra ticket fields (plugin keys, custom dropdowns) flow through `ticket.extra_payload` and are visible on `context.ticket` as well. \ No newline at end of file diff --git a/skills/glpi-team-members/SKILL.md b/skills/glpi-team-members/SKILL.md index 871e832..f6777e9 100644 --- a/skills/glpi-team-members/SKILL.md +++ b/skills/glpi-team-members/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.10+, glpi-python-client, network access to the GLPI v2 API, and credentials allowed to manage ticket teams." metadata: package: glpi-python-client - version: "0.4.0" + version: "0.4.1" --- # GLPI Team Members @@ -57,6 +57,7 @@ await client.remove_ticket_team_member( ## Gotchas - The OpenAPI contract marks `PostTeamMember.id` as read-only, but the live GLPI server requires it on the `POST` body. The client honours the live behaviour and exposes `id` as a writable field; this is a deliberate "behaviour wins over the contract" decision. +- **There is no update method, and `PatchTeamMember` is dead surface for callers.** The family is exactly three methods -- `list_ticket_team_members(ticket_id)`, `add_ticket_team_member(ticket_id, member: PostTeamMember)`, `remove_ticket_team_member(ticket_id, member: PostTeamMember)` -- and both writers take a `PostTeamMember`, never a `PatchTeamMember`. `PatchTeamMember` *is* exported from `glpi_python_client` (it subclasses `PostTeamMember` and declares the same three optional fields, `id`, `type`, `role`, plus `extra_payload`), but no client method accepts or returns it, so building one and handing it to the client neither type-checks nor works. To change someone's role, remove the old entry and add the new one. - The server returns extra fields such as `display_name`, `firstname`, `realname`, and `href` on `GetTeamMember`. These flow into `member.extra_payload`. -- All methods are async; always `await` them. -- If the user provides a name rather than an ID, look the user or group up first with `search_users` (or the equivalent group search) and confirm the ID before changing membership. \ No newline at end of file +- The three methods are coroutines on `AsyncGlpiClient` and must be awaited; on the synchronous `GlpiClient` they are ordinary blocking methods with identical signatures (`_sync/` is generated from `_async/`, so the two surfaces cannot drift). Do not `await` the synchronous client. +- If the user provides a name rather than an ID, resolve it first with `await client.search_users(rsql_filter)` (or page through `client.iter_search_users(...)`) and confirm the ID before changing membership. The client exposes **no group search endpoint** — a `type="Group"` member's `id` has to come from elsewhere (a known id, or the GLPI UI); `search_users` only covers `type="User"`. \ No newline at end of file diff --git a/skills/glpi-ticket-timeline/SKILL.md b/skills/glpi-ticket-timeline/SKILL.md index 7d2e806..b1f65d0 100644 --- a/skills/glpi-ticket-timeline/SKILL.md +++ b/skills/glpi-ticket-timeline/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.10+, glpi-python-client, and network access to the GLPI v2 API." metadata: package: glpi-python-client - version: "0.4.0" + version: "0.4.1" --- # GLPI Ticket Timeline @@ -18,8 +18,14 @@ The ticket timeline is exposed by four resource families under `/Assistance/Tick 1. Create a `GlpiClient` from the `glpi-client-setup` skill. 2. Read collections with `list_ticket_followups`, `list_ticket_tasks`, `list_ticket_solutions`, and `list_ticket_timeline_documents`. 3. Read individual records with `get_ticket_followup`, `get_ticket_task`, `get_ticket_solution`, `get_ticket_timeline_document`. -4. Create entries with `create_ticket_followup`, `create_ticket_task`, `create_ticket_solution` or `link_ticket_timeline_document`. Each returns the new identifier as `int`. -5. Update entries with `update_ticket_followup`, `update_ticket_task`, `update_ticket_solution`, `update_ticket_timeline_document`. +4. Create entries with `create_ticket_followup(ticket_id, followup: PostFollowup)`, `create_ticket_task(ticket_id, task: PostTicketTask)` or `create_ticket_solution(ticket_id, solution: PostSolution)`. Each returns the new identifier as `int`. `link_ticket_timeline_document(ticket_id, document_link: PostTimelineDocument)` also returns an `int`, but it cannot be told *which* existing document to link -- see the note under "Attach a document" and prefer `upload_document(..., ticket_id=...)`. +5. Update entries with, exactly: + - `update_ticket_followup(ticket_id, followup_id, followup: PatchFollowup)` + - `update_ticket_task(ticket_id, task_id, task: PatchTicketTask)` + - `update_ticket_solution(ticket_id, solution_id, solution: PatchSolution)` + - `update_ticket_timeline_document(ticket_id, document_link_id, document_link: PatchTimelineDocument)` + + All four return `None`. `PatchFollowup`, `PatchTicketTask`, `PatchSolution` and `PatchTimelineDocument` are exported from `glpi_python_client`. Each *subclasses* its `Post*` counterpart and declares exactly the same fields, every one optional, so build one with only the fields you intend to change. The subclassing runs Patch-from-Post, which means a `Patch*` is accepted where a `Post*` is annotated but **not** the other way round: handing a `PostFollowup` to `update_ticket_followup` is a mypy error, so write the `Patch*` name. 6. Delete with `delete_ticket_followup`, `delete_ticket_task`, `delete_ticket_solution`, or `unlink_ticket_timeline_document`. Pass `force=True` to permanently delete instead of moving to the trash. ## Examples @@ -36,7 +42,13 @@ documents = await client.list_ticket_timeline_documents(321) Add a followup, a task, and a solution: ```python -from glpi_python_client import PostFollowup, PostSolution, PostTicketTask +from glpi_python_client import ( + GlpiSolutionStatus, + GlpiTaskState, + PostFollowup, + PostSolution, + PostTicketTask, +) followup_id = await client.create_ticket_followup( 321, @@ -44,29 +56,69 @@ followup_id = await client.create_ticket_followup( ) task_id = await client.create_ticket_task( 321, - PostTicketTask(content="On-site visit", duration=900), + # `state` is GlpiTaskState: INFORMATION = 0, TODO = 1, DONE = 2. + PostTicketTask(content="On-site visit", duration=900, state=GlpiTaskState.TODO), ) solution_id = await client.create_ticket_solution( 321, - PostSolution(content="Replaced the access point."), + # `status` is GlpiSolutionStatus: NONE = 1, WAITING = 2, ACCEPTED = 3, + # REFUSED = 4. + PostSolution( + content="Replaced the access point.", status=GlpiSolutionStatus.WAITING + ), +) +``` + +Update an entry. The third argument is always a `Patch*` model, never the `Post*` one: + +```python +from glpi_python_client import ( + GlpiTaskState, + PatchFollowup, + PatchSolution, + PatchTicketTask, +) + +await client.update_ticket_followup( + 321, followup_id, PatchFollowup(content="Triaged: root cause identified.") +) +await client.update_ticket_task( + 321, task_id, PatchTicketTask(state=GlpiTaskState.DONE, duration=1800) +) +await client.update_ticket_solution( + 321, solution_id, PatchSolution(content="Replaced the access point (AP-14).") ) ``` -Link an existing GLPI document to the ticket timeline: +Attach a document to the ticket timeline. Note `PostTimelineDocument` exposes only one typed field, `timeline_position` (every other `Document_Item` field is read-only on the contract), and the POST URL carries only the ticket id -- so there is no *typed* slot naming which existing document to link. `extra_payload` is merged into the request body verbatim, so `PostTimelineDocument(extra_payload={"documents_id": 654})` does put a document id on the wire; whether the server honours it is untested here. The supported way to put a file on a ticket is `upload_document(..., ticket_id=...)`, which creates the document and the ticket link in one call and requires `v1_base_url` + `v1_user_token` on the client (it raises `RuntimeError` otherwise): ```python -from glpi_python_client import PostTimelineDocument +from pathlib import Path + +from glpi_python_client import GlpiTimelinePosition, PatchTimelineDocument + +path = Path("diagnostic.png") +await client.upload_document( + filename=path.name, + content=path.read_bytes(), + mime_type="image/png", + ticket_id=321, +) -link_id = await client.link_ticket_timeline_document( +# Reposition an existing timeline link (document_link_id comes from +# list_ticket_timeline_documents, whose entries are GetDocument records): +await client.update_ticket_timeline_document( 321, - PostTimelineDocument(), + 654, + PatchTimelineDocument(timeline_position=GlpiTimelinePosition.LEFT), ) ``` ## Gotchas -- The live GLPI v2 server returns each timeline list entry wrapped in `{"type": ..., "item": {...}}` even though the OpenAPI contract documents a flat array. The client unwraps that envelope transparently for the four `list_*` helpers; you receive plain `GetHello world
").content == "Hello **world**"`). Authoring raw HTML is not an error but is round-tripped through the Markdown converter and can be reshaped; write Markdown. - Extra server fields (e.g. plugin keys) flow into `record.extra_payload` rather than raising. - `delete_ticket_*` and `unlink_ticket_timeline_document` accept a keyword-only `force` parameter; pass `force=True` to permanently delete. \ No newline at end of file diff --git a/skills/glpi-ticket-workflow/SKILL.md b/skills/glpi-ticket-workflow/SKILL.md index 5256019..2009c73 100644 --- a/skills/glpi-ticket-workflow/SKILL.md +++ b/skills/glpi-ticket-workflow/SKILL.md @@ -5,13 +5,13 @@ license: MIT compatibility: "Requires Python 3.10+, glpi-python-client, network access to the GLPI v2 API, and credentials accepted by GlpiClient." metadata: package: glpi-python-client - version: "0.4.0" + version: "0.4.1" --- # GLPI Ticket Workflow > The snippets below use `AsyncGlpiClient` (`async with` + `await`). Every method shown also exists on the synchronous `GlpiClient` with the same signature -- replace `async with` with `with`, drop the `await` keyword, and skip the surrounding `async def`/`asyncio.run` scaffolding. -Use this skill for ticket reads and writes through the public client. Tickets live under `/Assistance/Ticket` on the GLPI v2 API and are exposed by five methods, present on both `GlpiClient` and `AsyncGlpiClient` with identical signatures: `search_tickets`, `get_ticket`, `create_ticket`, `update_ticket`, and `delete_ticket`. +Use this skill for ticket reads and writes through the public client. Tickets live under `/Assistance/Ticket` on the GLPI v2 API and are exposed by six methods, present on both `GlpiClient` and `AsyncGlpiClient` with identical signatures: `search_tickets`, `iter_search_tickets`, `get_ticket`, `create_ticket`, `update_ticket`, and `delete_ticket`. ## Procedure @@ -27,7 +27,7 @@ Use this skill for ticket reads and writes through the public client. Tickets li Search open tickets: ```python -tickets = await client.search_tickets("status==1", limit=20) +tickets = await client.search_tickets("is_deleted==false;status==1", limit=20) # v2 search returns trashed tickets unless `is_deleted` is pinned ``` Create a ticket. Content fields accept Markdown and are converted to GLPI's HTML transport format transparently: @@ -69,8 +69,9 @@ ticket = PostTicket( ## Gotchas -- All ticket methods are async; always `await` them. -- `search_tickets` accepts a raw RSQL filter string; pagination is via `limit` and `start`. There is no batch iterator. +- On `AsyncGlpiClient` every ticket method is a coroutine and must be awaited; on `GlpiClient` the same methods are ordinary blocking calls and must not be awaited. `iter_search_tickets` is the exception to the shape: it is an async generator on `AsyncGlpiClient` (`async for`) and a plain generator on `GlpiClient` (`for`), so it is iterated, not awaited, on either surface. +- `search_tickets` accepts a raw RSQL filter string; pagination is via the keyword-only `limit` and `start` (it also takes `sort` and `fields`). To walk a whole result set use the batch iterator `iter_search_tickets(rsql_filter, batch_size=50, sort=..., fields=...)`, which advances `start` itself and yields one `list[GetTicket]` page per step, stopping when a page comes back shorter than `batch_size` — `async for batch in client.iter_search_tickets(...)` on `AsyncGlpiClient`, `for batch in client.iter_search_tickets(...)` on `GlpiClient`. +- **`search_tickets` swallows 4xx and returns `[]`.** This is a library-wide contract, not a ticket peculiarity: `_resource_list` checks the response status only when the caller passes a `failure_message`, and none of the seven `search_*` helpers (`search_tickets`, `search_users`, `search_locations`, `search_entities`, `search_documents`, `search_kb_articles`, `search_kb_categories`) passes one -- a GLPI error body is not a JSON list, so it is coerced to `[]`. A malformed RSQL filter, a 403, a missing route and a genuinely empty result set are therefore indistinguishable at the call site. `iter_search_tickets` inherits it: a swallowed 4xx yields a short first page, so the loop simply ends and you process nothing. `get_ticket` and every `list_*`/`get_*` helper do pass a `failure_message` and raise `GlpiStatusError` (narrowed to `GlpiAuthError` / `GlpiNotFoundError` / `GlpiServerError`) normally, so probe with one of those before believing an empty search -- and never treat `[]` as proof a ticket does not exist before creating a replacement. - `create_ticket` returns the new ticket ID. `update_ticket` and `delete_ticket` return `None`. - The GLPI server is the authoritative validator. Extra keys returned by the server flow into `ticket.extra_payload` rather than raising. Caller-provided `extra_payload` keys win on conflicts. -- Read-only fields such as `status` are intentionally absent from `PostTicket`/`PatchTicket`; the server controls those transitions. \ No newline at end of file +- Read-only fields such as `status` are intentionally absent from `PostTicket`/`PatchTicket`; the server controls those transitions. `global_validation` is the exception -- it *is* declared on both write models, typed `GlpiGlobalValidation | None`, whose members are `NONE = 1`, `WAITING = 2`, `ACCEPTED = 3`, `REFUSED = 4`. `GlpiGlobalValidation` is exported from the package root alongside `GlpiTicketStatus` (`NEW = 1`, `ASSIGNED = 2`, `PLANNED = 3`, `PENDING = 4`, `SOLVED = 5`, `CLOSED = 6`, `VALIDATION = 10`), `GlpiTicketType` (`INCIDENT = 1`, `REQUEST = 2`) and `GlpiPriority`; `status` and the rest stay readable on `GetTicket`. \ No newline at end of file diff --git a/skills/glpi-user-location-provisioning/SKILL.md b/skills/glpi-user-location-provisioning/SKILL.md index 6a3cbb1..2a17260 100644 --- a/skills/glpi-user-location-provisioning/SKILL.md +++ b/skills/glpi-user-location-provisioning/SKILL.md @@ -5,18 +5,18 @@ license: MIT compatibility: "Requires Python 3.10+, glpi-python-client, network access to the GLPI v2 API, and credentials allowed to read or write users, locations, and entities." metadata: package: glpi-python-client - version: "0.4.0" + version: "0.4.1" --- # GLPI User, Location, And Entity Provisioning > The snippets below use `AsyncGlpiClient` (`async with` + `await`). Every method shown also exists on the synchronous `GlpiClient` with the same signature -- replace `async with` with `with`, drop the `await` keyword, and skip the surrounding `async def`/`asyncio.run` scaffolding. -Users live under `/Administration/User`, entities under `/Administration/Entity`, and locations under `/Dropdown/Location`. Each resource family is exposed by the same `search_/get_/create_/update_/delete_` shape on `GlpiClient` with matching `Get`/`Post`/`Patch`/`Delete` Pydantic models. +Users live under `/Administration/User`, entities under `/Administration/Entity`, and locations under `/Dropdowns/Location`. Each resource family is exposed by the same `search_/get_/create_/update_/delete_` shape on `GlpiClient` with matching `Get`/`Post`/`Patch`/`Delete` Pydantic models. ## Procedure 1. Create a `GlpiClient` with the correct entity/profile scope. -2. Search before creating duplicates: `search_users(rsql_filter, limit=..., start=...)`, `search_locations(rsql_filter, limit=..., start=...)`, `search_entities(rsql_filter, limit=..., start=...)`. +2. Search before creating duplicates: `search_users(rsql_filter, limit=..., start=..., skip_entity=False)`, `search_locations(rsql_filter, limit=..., start=...)`, `search_entities(rsql_filter, limit=..., start=...)`. Scope matters here: `search_users` and `search_locations` are narrowed by the client's `GLPI-Entity` / `GLPI-Profile` headers, so pass `skip_entity=True` to `search_users` (the only one of the three `search_*` helpers that has the flag — `iter_search_users` takes it too) to look across every entity the caller can see before deciding a user does not exist; `search_entities` always bypasses those headers. 3. Fetch one record with `get_user(user_id)`, `get_location(location_id)`, or `get_entity(entity_id)`. 4. Create with `create_user(PostUser(...))`, `create_location(PostLocation(...))`, or `create_entity(PostEntity(...))`. Each returns the new ID. 5. Update with `update_user(user_id, PatchUser(...))`, `update_location(location_id, PatchLocation(...))`, or `update_entity(entity_id, PatchEntity(...))`. @@ -46,17 +46,45 @@ user_id = await client.create_user( ) ``` -Find or create a location: +Find or create a location. The obvious spelling -- `matches[0].id if matches else create_location(...)` -- is a duplicate generator, because `search_locations` returns `[]` for a rejected filter or a 403 exactly as it does for "no such location" (see the first gotcha). Two guards close that, and neither is optional. Both fail closed: when they cannot prove the record is absent they raise rather than create, so the one case they refuse -- the very first location on an instance whose dropdown is still empty -- is an explicit opt-in, not a silent duplicate: ```python -from glpi_python_client import PostLocation - -matches = await client.search_locations('name=="Paris HQ"') -location_id = ( - matches[0].id - if matches - else await client.create_location(PostLocation(name="Paris HQ")) -) +from glpi_python_client import AsyncGlpiClient, PostLocation + +#: Characters that terminate an RSQL token. A value carrying one produces a +#: filter the server rejects with a 400 -- which `search_locations` turns +#: into `[]`, i.e. into "create a duplicate". +_RSQL_UNSAFE = set("\"'();,=<>!~*") + + +async def find_or_create_location( + client: AsyncGlpiClient, name: str, *, dropdown_may_be_empty: bool = False +) -> int: + """Return the id of the location called `name`, creating it if absent.""" + if not name or _RSQL_UNSAFE & set(name): + # Guard 1. The canary below cannot catch this case: it does not + # carry this value, so it would come back healthy while the real + # query was being rejected. Reject the value here instead. + raise ValueError(f"value is not safe to interpolate into RSQL: {name!r}") + + matches = await client.search_locations(f'name=="{name}"') + if matches and matches[0].id is not None: + return matches[0].id + + # Guard 2. Empty is not proof of absence. Re-run the same route with no + # filter at all -- same URL, same auth, same entity scope, nothing to + # reject -- so a swallowed 403/404/5xx shows up here too. An empty + # answer here has exactly two causes: the search layer failed, or the + # Locations dropdown is genuinely empty (a fresh GLPI ships it empty). + # This cannot tell them apart either, so it fails closed and makes the + # second one something the caller states on purpose. + if not await client.search_locations("", limit=1) and not dropdown_may_be_empty: + raise RuntimeError( + "search_locations returned nothing even unfiltered: assume a failed " + "search, not a missing location. Pass dropdown_may_be_empty=True " + "only once you have confirmed this instance has no locations yet." + ) + return await client.create_location(PostLocation(name=name)) ``` Look entities up by name fragment: @@ -69,9 +97,10 @@ for entity in entities: ## Gotchas -- All methods are async; always `await` them. -- `PostUser` requires `username` and the GLPI server enforces the `password`/`password2` pair when creating local users. Tweak according to your auth backend. -- Search filters are raw RSQL strings; pagination is via `limit` and `start`. +- **`search_users`, `search_locations` and `search_entities` swallow 4xx and return `[]`, and this family is where that hurts most.** It is a library-wide contract, not a peculiarity of these three: `_resource_list` checks the response status only when the caller passes a `failure_message`, and none of the seven `search_*` helpers (`search_users`, `search_locations`, `search_entities`, `search_tickets`, `search_documents`, `search_kb_articles`, `search_kb_categories`) passes one -- a GLPI error body is not a JSON list, so it is coerced to `[]`. A malformed RSQL filter, a 403, a missing route and "no such record" are therefore indistinguishable. `iter_search_users` / `iter_search_entities` inherit it: a swallowed 4xx makes the first page short, so the loop ends having yielded nothing. **The find-or-create pattern is the trap**: `matches[0].id if matches else create(...)` provisions a duplicate user or location every time the search fails, and the duplicate is then a data-repair job, not an exception someone sees. Guard both halves as the example above does -- validate anything you interpolate into the filter, and corroborate an empty result with an unfiltered control search or with a `get_user`/`get_location`/`get_entity` on a known id, all of which do pass a `failure_message` and raise `GlpiStatusError` (narrowed to `GlpiAuthError` / `GlpiNotFoundError` / `GlpiServerError`) normally. +- On `AsyncGlpiClient` every method shown is a coroutine -- always `await` it -- and `iter_search_users` / `iter_search_entities` are async generators consumed with `async for`, not `await`. The generated `GlpiClient` carries the same names and signatures as ordinary blocking calls: no `await`, and a plain `for` over the iterators. +- `PostUser` has **no** client-side required fields: every declared field defaults to `None` (bar `extra_payload`, which defaults to an empty dict) and `model_dump(exclude_none=True)` strips the unset ones, so `PostUser()` validates fine and it is the GLPI server that rejects a create without `username` and enforces the `password`/`password2` pair for local accounts. Tweak according to your auth backend: `authtype` on `PostUser`/`PatchUser`/`GetUser` is typed `GlpiUserAuthType | None`, exported from the package root, with members `LOCAL = 1`, `LDAP = 2`, `MAIL = 3`, `CAS = 4`, `X509 = 5`, `EXTERNAL = 6` -- pass the member (`authtype=GlpiUserAuthType.LDAP`) rather than a bare integer. Like every public enum in the package it subclasses `GlpiEnum`, itself an `IntEnum`, so it serialises as its number and compares equal to one. `password`/`password2` are `SecretStr` (plain `str` is coerced) and are masked in `repr` and logs, unmasked only when the request body is serialised. +- Search filters are raw RSQL strings. `search_*` pages manually with `limit` and `start`, but for users and entities the client drives pagination for you: `async for page in client.iter_search_users(rsql_filter, batch_size=50, skip_entity=False)` and `iter_search_entities(rsql_filter, batch_size=50)` yield successive pages and stop on the first short page (plain `for` on `GlpiClient`). `iter_search_users` carries the same `skip_entity` flag as `search_users`, so pass `skip_entity=True` there too when paging across every entity; `iter_search_entities` has no such parameter and always spans them. There is no `iter_search_locations` -- page `search_locations` yourself with `limit`/`start`. - Extra keys returned by the live server (`display_name`, plugin fields, ...) flow into `record.extra_payload` rather than raising. - `delete_*(force=True)` permanently deletes the record; omit (or `False`/`None`) to move it to the trash. - If the user provides a name rather than an ID, search first and confirm the ID before changing or deleting records. \ No newline at end of file