diff --git a/CHANGELOG.md b/CHANGELOG.md index a940048..4d2600a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,28 @@ is the error. Tags carry no `v` prefix. ## [Unreleased] +## [0.6.0] - 2026-11-16 + +One more of the ticket's workflow-moving writes, named by the guard. + +### Added + +- **`requalify_ticket(rfc_number, *, allow_workflow_effect, catalog_id=None, + catalog_code=None, catalog_guid=None)`**: `PUT requests/{rfc}` with a + `requalified` body holding exactly one catalog key (zero or several raise + `ValueError` before any request). The vendor documents a requalification as + starting a new workflow (`action.md`). The method never re-reads: the caller + confirms a landing with `get_ticket`, because one instance answered HTTP 590 + on an incident requalification that had landed (measured 2026-11-16, tier 4, + may not generalise). + +### Changed + +- **BREAKING:** `requalified` is now a workflow envelope (`UNKNOWN`), matched as a + top-level body key in any casing on any path. A raw `send` of a `requalified` + body is refused unless the call allows `WorkflowEffect.UNKNOWN`. Before, the + nested catalog key passed the guard unseen. + ## [0.5.0] - 2026-11-10 Two more of the vendor's ticket requests, and a guard that names one more diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 87a8be4..86e913d 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -459,11 +459,19 @@ the API offers three things that touch it: page's ``end_date`` row rather than an explicit sentence, and the page documents final statuses only, so do not read ``status_guid`` as a way to pick an in-progress status. It needs ``allow_workflow_effect=WorkflowEffect.INTERRUPTS``. -* Suspend and reopen are documented by the vendor but not wrapped here; their - pages say only that a suspend, or a reopening, action is created, and their - effect on the open actions is unmeasured. - :meth:`~easyvista_python_client.EasyvistaClient.send` reaches them with - ``allow_workflow_effect=WorkflowEffect.UNKNOWN``. +* :meth:`~easyvista_python_client.EasyvistaClient.suspend_ticket` and + :meth:`~easyvista_python_client.EasyvistaClient.restart_ticket` wrap the + vendor's suspend and reopen requests; their pages say only that a suspend, or a + reopening, action is created, and their effect on the open actions is + unmeasured. They need ``allow_workflow_effect=WorkflowEffect.UNKNOWN``. +* :meth:`~easyvista_python_client.EasyvistaClient.requalify_ticket` sends a + ``requalified`` body naming exactly one of ``catalog_id``, ``catalog_code`` and + ``catalog_guid``. The vendor says a requalification starts a new workflow + ("Requalify the category of the object. A new workflow will then start.", + tier 1, https://docs.easyvista.com/docs/action.md). It needs + ``allow_workflow_effect=WorkflowEffect.UNKNOWN`` and never re-reads: confirm a + landing with ``get_ticket`` (measured on one instance on 2026-11-16, so it may + not generalise: an incident landed even when the server answered 590). The vendor documents no REST write that sets a ticket's status outside those (tier 1, ``docs/vendor-api-reference.md``, "Ticket workflow"), so this package diff --git a/docs/vendor-api-reference.md b/docs/vendor-api-reference.md index 2ee044c..85a2c3e 100644 --- a/docs/vendor-api-reference.md +++ b/docs/vendor-api-reference.md @@ -260,6 +260,7 @@ https://docs.easyvista.com/docs/references-tables.md, Statuses section (where al | `PUT /requests/{rfc}` `{"closed": …}` | **interrupts** it, whatever status is sent | "1. The workflow of the ticket is interrupted." (sub-bullet: "workflowstop function, with **rfc_number** passed as a parameter"); then status = "the final status of the ticket"; "The unfinished actions associated with the ticket are deleted." (`end_date_ut = NULL` iff `delete_actions = True`; otherwise `end_date` is the "Closing date of open actions"); "An anticipated closing action associated with the ticket is inserted."; "Any further modification is impossible." — rest-api-close-an-incident-request.md. An omitted `status_GUID` defaults to the Closed meta-status (same page). | | `PUT /actions/{rfc}` `{"end_action": …}` | **advances** it when the action is a workflow step | REST page: "If the action_id is not specified, all the ongoing actions associated with the rfc_number are ended." — rest-api-finish-an-action-attached-to-an-incident-request.md; it never mentions the workflow. UI Finish wizard: "The workflow will proceed to the next step." — action.md. Tier 4, one instance, may not generalise: 2026-09-01, 2/2 (step ended → ticket Résolu); a caller's own action, 3/3 across 2026-09-01 and 2026-09-02, no change. | | `PUT /requests/{rfc}` `{"suspended"…}` / `{"restarted"…}` | not documented | "A suspend action for the ticket is created." / "Create a reopening action for the ticket." — nothing on open actions or status. rest-api-suspend-an-incident-request.md, rest-api-reopen-an-incident-request.md | +| `PUT /requests/{rfc}` `{"requalified"…}` | **starts a new one** (UI wording) | "Requalify the category of the object. A new workflow will then start." — action.md (tier 1). The vendor index lists no REST page for this body; the inner key and value type are measured on one instance (2026-11-16, tier 4, may not generalise). | | Update a ticket, update an action (any body not named above) | not documented | Each page accepts "all the fields from the SD_REQUEST table except those mentioned below" / "…from the AM_ACTION table…", has no processing section and does not contain the word "workflow". rest-api-update-an-incident-request.md, rest-api-update-an-action.md | | Create an action | not documented | Processing section: "An action is created for the ticket." then conditional logic on `parent_action_id` (which action the new one attaches to); the page does not contain the word "workflow". rest-api-create-an-action-for-an-incident-request.md | | Create a task | not documented | Processing section: "A task associated with the ticket is created."; the page does not contain the word "workflow". rest-api-create-a-task-for-an-incident-request.md | @@ -313,7 +314,7 @@ top-level body keys): | --- | --- | --- | | any path | body keys `closed` | `INTERRUPTS` | | any path | body keys `end_action` | `ADVANCES` | -| any path | body keys `suspended`, `restarted` | `UNKNOWN` | +| any path | body keys `suspended`, `restarted`, `requalified` | `UNKNOWN` | | `requests/{rfc}` | body keys `status_id`, `status_guid`, `sd_catalog_id`, `initial_sd_catalog_id`, `catalog_guid`, `catalog_code`, `parent_request_id`; and a `DELETE` of the ticket | `UNKNOWN` | | `requests/without-workflow` | the route itself | `UNKNOWN` | | `requests/{rfc}/`, `` not `actions`, `tasks` or `documents` | the route itself: `close` is `INTERRUPTS`; any other (`suspend`, `restart`, `workflowstart`, or one a deployment adds) is `UNKNOWN` | as stated | diff --git a/easyvista_python_client/_async/client.py b/easyvista_python_client/_async/client.py index 98d8c0c..97c8041 100644 --- a/easyvista_python_client/_async/client.py +++ b/easyvista_python_client/_async/client.py @@ -202,11 +202,11 @@ async def send( ``allow_workflow_effect`` is the way past the workflow guard. A write whose content may change a ticket's workflow -- a ``closed``, - ``end_action``, ``suspended`` or ``restarted`` body on any path, a - status or catalog column on a ticket, an end date or type on an action, - any write to ``actions/{rfc_number}`` (the vendor's end-action route; an - integer id addresses an action instead), a ``requests/{rfc}/close``-style - route -- is refused with + ``end_action``, ``suspended``, ``restarted`` or ``requalified`` body + on any path, a status or catalog column on a ticket, an end date or + type on an action, any write to ``actions/{rfc_number}`` (the vendor's + end-action route; an integer id addresses an action instead), a + ``requests/{rfc}/close``-style route -- is refused with :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused` before anything is sent, unless this argument names every :class:`~easyvista_python_client.WorkflowEffect` it carries. See @@ -659,6 +659,54 @@ async def suspend_ticket( ) return parse(await self._transport.send(spec.allowing(allow_workflow_effect))) + async def requalify_ticket( + self, + rfc_number: str, + *, + allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect], + catalog_id: int | None = None, + catalog_code: str | None = None, + catalog_guid: str | None = None, + ) -> Request: + """Requalify a ticket to another catalog. + + Sends ``PUT requests/{rfc}`` with a ``requalified`` body holding exactly + one of ``catalog_id``, ``catalog_code`` and ``catalog_guid``; zero or + several raise :class:`ValueError` before any request. The id is sent as + a decimal string. + + The vendor documents requalifying a category as starting a new + workflow: "Requalify the category of the object. A new workflow will + then start." (https://docs.easyvista.com/docs/action.md, tier 1, re-read + 2026-11-16). The vendor's index lists no REST page for this body, so + its key spelling and value types are measured, not documented. + + Measured on one instance on 2026-11-16 (tier 4, may not generalise): + on an incident the requalification lands even when the server answers + HTTP 590; a request (not an incident) is refused with 400 and code + 2117; a request sent to an incident catalog entry is refused with 400 + and code 2119. Because the answer is not a receipt, the caller confirms + a landing by re-reading with :meth:`get_ticket`; this method never + re-reads. + + ``allow_workflow_effect`` is **required** and is + ``WorkflowEffect.UNKNOWN``, as for :meth:`suspend_ticket`: refused + before any request unless allowed, and sent once, never retried. The + return value is parsed like :meth:`close_ticket`'s (an ``HREF`` only):: + + client.requalify_ticket( + rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN, catalog_code=code + ) + """ + spec, parse = requests_res.build_requalify_ticket( + rfc_number, + catalog_id=catalog_id, + catalog_code=catalog_code, + catalog_guid=catalog_guid, + context=self._validation_context, + ) + return parse(await self._transport.send(spec.allowing(allow_workflow_effect))) + async def restart_ticket( self, rfc_number: str, diff --git a/easyvista_python_client/_async/tests/test_client.py b/easyvista_python_client/_async/tests/test_client.py index 5417b95..c476c5c 100644 --- a/easyvista_python_client/_async/tests/test_client.py +++ b/easyvista_python_client/_async/tests/test_client.py @@ -3073,6 +3073,83 @@ async def test_state_request_is_sent_once_on_a_transient_failure( assert route.call_count == 1 +# --- requalify_ticket ---------------------------------------------------------- + + +@pytest.mark.parametrize( + ("kwargs", "inner"), + [ + ({"catalog_id": 3}, {"catalog_id": "3"}), + ({"catalog_code": "C1"}, {"catalog_code": "C1"}), + ({"catalog_guid": "{G}"}, {"catalog_guid": "{G}"}), + ], +) +@respx.mock +async def test_requalify_sends_the_requalified_body(config, kwargs, inner): + route = respx.put(f"{ROOT}/requests/I1").mock( + return_value=httpx.Response(201, json={"HREF": f"{ROOT}/requests/I1"}) + ) + async with AsyncEasyvistaClient(config) as client: + result = await client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN, **kwargs + ) + assert route.call_count == 1 + assert json.loads(route.calls.last.request.content) == {"requalified": inner} + assert result.rfc_number == "I1" + assert result.href == f"{ROOT}/requests/I1" + + +@pytest.mark.parametrize( + "kwargs", + [ + {}, + {"catalog_id": 3, "catalog_code": "C1"}, + {"catalog_code": "C", "catalog_guid": "G"}, + ], +) +@respx.mock +async def test_requalify_refuses_zero_or_several_targets(config, kwargs): + route = respx.route().mock(return_value=httpx.Response(201, json={})) + async with AsyncEasyvistaClient(config) as client: + with pytest.raises(ValueError, match="exactly one"): + await client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN, **kwargs + ) + assert not route.called + + +async def test_requalify_requires_the_opt_in_keyword(config): + async with AsyncEasyvistaClient(config) as client: + with pytest.raises(TypeError): + await client.requalify_ticket("I1", catalog_id=3) + + +@respx.mock +async def test_requalify_is_refused_without_unknown_in_the_opt_in(config): + route = respx.route().mock(return_value=httpx.Response(200, json={})) + async with AsyncEasyvistaClient(config) as client: + with pytest.raises(EasyvistaWorkflowEffectRefused): + await client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.INTERRUPTS, catalog_id=3 + ) + with pytest.raises(EasyvistaWorkflowEffectRefused): + await client.requalify_ticket("I1", allow_workflow_effect=(), catalog_id=3) + assert not route.called + + +@respx.mock +async def test_requalify_is_sent_once_on_a_transient_failure(config): + route = respx.put(f"{ROOT}/requests/I1").mock( + return_value=httpx.Response(503, json={}) + ) + async with AsyncEasyvistaClient(config) as client: + with pytest.raises(EasyvistaError): + await client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN, catalog_id=3 + ) + assert route.call_count == 1 + + # --- the guard names STATUS_ID_ON_CREATE on an existing action ---------------- diff --git a/easyvista_python_client/_sync/client.py b/easyvista_python_client/_sync/client.py index 11e4177..9bbaf11 100644 --- a/easyvista_python_client/_sync/client.py +++ b/easyvista_python_client/_sync/client.py @@ -202,11 +202,11 @@ def send( ``allow_workflow_effect`` is the way past the workflow guard. A write whose content may change a ticket's workflow -- a ``closed``, - ``end_action``, ``suspended`` or ``restarted`` body on any path, a - status or catalog column on a ticket, an end date or type on an action, - any write to ``actions/{rfc_number}`` (the vendor's end-action route; an - integer id addresses an action instead), a ``requests/{rfc}/close``-style - route -- is refused with + ``end_action``, ``suspended``, ``restarted`` or ``requalified`` body + on any path, a status or catalog column on a ticket, an end date or + type on an action, any write to ``actions/{rfc_number}`` (the vendor's + end-action route; an integer id addresses an action instead), a + ``requests/{rfc}/close``-style route -- is refused with :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused` before anything is sent, unless this argument names every :class:`~easyvista_python_client.WorkflowEffect` it carries. See @@ -659,6 +659,54 @@ def suspend_ticket( ) return parse(self._transport.send(spec.allowing(allow_workflow_effect))) + def requalify_ticket( + self, + rfc_number: str, + *, + allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect], + catalog_id: int | None = None, + catalog_code: str | None = None, + catalog_guid: str | None = None, + ) -> Request: + """Requalify a ticket to another catalog. + + Sends ``PUT requests/{rfc}`` with a ``requalified`` body holding exactly + one of ``catalog_id``, ``catalog_code`` and ``catalog_guid``; zero or + several raise :class:`ValueError` before any request. The id is sent as + a decimal string. + + The vendor documents requalifying a category as starting a new + workflow: "Requalify the category of the object. A new workflow will + then start." (https://docs.easyvista.com/docs/action.md, tier 1, re-read + 2026-11-16). The vendor's index lists no REST page for this body, so + its key spelling and value types are measured, not documented. + + Measured on one instance on 2026-11-16 (tier 4, may not generalise): + on an incident the requalification lands even when the server answers + HTTP 590; a request (not an incident) is refused with 400 and code + 2117; a request sent to an incident catalog entry is refused with 400 + and code 2119. Because the answer is not a receipt, the caller confirms + a landing by re-reading with :meth:`get_ticket`; this method never + re-reads. + + ``allow_workflow_effect`` is **required** and is + ``WorkflowEffect.UNKNOWN``, as for :meth:`suspend_ticket`: refused + before any request unless allowed, and sent once, never retried. The + return value is parsed like :meth:`close_ticket`'s (an ``HREF`` only):: + + client.requalify_ticket( + rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN, catalog_code=code + ) + """ + spec, parse = requests_res.build_requalify_ticket( + rfc_number, + catalog_id=catalog_id, + catalog_code=catalog_code, + catalog_guid=catalog_guid, + context=self._validation_context, + ) + return parse(self._transport.send(spec.allowing(allow_workflow_effect))) + def restart_ticket( self, rfc_number: str, diff --git a/easyvista_python_client/_sync/tests/test_client.py b/easyvista_python_client/_sync/tests/test_client.py index c9bf691..e5da030 100644 --- a/easyvista_python_client/_sync/tests/test_client.py +++ b/easyvista_python_client/_sync/tests/test_client.py @@ -3073,6 +3073,83 @@ def test_state_request_is_sent_once_on_a_transient_failure( assert route.call_count == 1 +# --- requalify_ticket ---------------------------------------------------------- + + +@pytest.mark.parametrize( + ("kwargs", "inner"), + [ + ({"catalog_id": 3}, {"catalog_id": "3"}), + ({"catalog_code": "C1"}, {"catalog_code": "C1"}), + ({"catalog_guid": "{G}"}, {"catalog_guid": "{G}"}), + ], +) +@respx.mock +def test_requalify_sends_the_requalified_body(config, kwargs, inner): + route = respx.put(f"{ROOT}/requests/I1").mock( + return_value=httpx.Response(201, json={"HREF": f"{ROOT}/requests/I1"}) + ) + with EasyvistaClient(config) as client: + result = client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN, **kwargs + ) + assert route.call_count == 1 + assert json.loads(route.calls.last.request.content) == {"requalified": inner} + assert result.rfc_number == "I1" + assert result.href == f"{ROOT}/requests/I1" + + +@pytest.mark.parametrize( + "kwargs", + [ + {}, + {"catalog_id": 3, "catalog_code": "C1"}, + {"catalog_code": "C", "catalog_guid": "G"}, + ], +) +@respx.mock +def test_requalify_refuses_zero_or_several_targets(config, kwargs): + route = respx.route().mock(return_value=httpx.Response(201, json={})) + with EasyvistaClient(config) as client: + with pytest.raises(ValueError, match="exactly one"): + client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN, **kwargs + ) + assert not route.called + + +def test_requalify_requires_the_opt_in_keyword(config): + with EasyvistaClient(config) as client: + with pytest.raises(TypeError): + client.requalify_ticket("I1", catalog_id=3) + + +@respx.mock +def test_requalify_is_refused_without_unknown_in_the_opt_in(config): + route = respx.route().mock(return_value=httpx.Response(200, json={})) + with EasyvistaClient(config) as client: + with pytest.raises(EasyvistaWorkflowEffectRefused): + client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.INTERRUPTS, catalog_id=3 + ) + with pytest.raises(EasyvistaWorkflowEffectRefused): + client.requalify_ticket("I1", allow_workflow_effect=(), catalog_id=3) + assert not route.called + + +@respx.mock +def test_requalify_is_sent_once_on_a_transient_failure(config): + route = respx.put(f"{ROOT}/requests/I1").mock( + return_value=httpx.Response(503, json={}) + ) + with EasyvistaClient(config) as client: + with pytest.raises(EasyvistaError): + client.requalify_ticket( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN, catalog_id=3 + ) + assert route.call_count == 1 + + # --- the guard names STATUS_ID_ON_CREATE on an existing action ---------------- diff --git a/easyvista_python_client/_version.py b/easyvista_python_client/_version.py index aaff85a..d69faf2 100644 --- a/easyvista_python_client/_version.py +++ b/easyvista_python_client/_version.py @@ -5,4 +5,4 @@ live only in ``__init__``. """ -__version__ = "0.5.0" +__version__ = "0.6.0" diff --git a/easyvista_python_client/resources/requests.py b/easyvista_python_client/resources/requests.py index 1adfa27..66e0057 100644 --- a/easyvista_python_client/resources/requests.py +++ b/easyvista_python_client/resources/requests.py @@ -188,6 +188,42 @@ def build_suspend_ticket( ) +def build_requalify_ticket( + rfc_number: str, + *, + catalog_id: int | None = None, + catalog_code: str | None = None, + catalog_guid: str | None = None, + context: dict[str, Any] | None = None, +) -> tuple[RequestSpec, Callable[[Any], Request]]: + """Build the ``{"requalified": {...}}`` PUT spec -- a requalification. + + Exactly one of ``catalog_id``, ``catalog_code`` and ``catalog_guid`` names + the target catalog; zero or several raise :class:`ValueError`. The id goes + on the wire as a decimal string, the form measured to land on one + instance (tier 4, 2026-11-16, may not generalise). + """ + keyed = { + "catalog_id": None if catalog_id is None else str(catalog_id), + "catalog_code": catalog_code, + "catalog_guid": catalog_guid, + } + inner = {key: value for key, value in keyed.items() if value is not None} + if len(inner) != 1: + raise ValueError( + "requalify needs exactly one of catalog_id, catalog_code and catalog_guid" + ) + spec = RequestSpec("PUT", f"requests/{rfc_number}", json={"requalified": inner}) + + def parse(data: Any) -> Request: + records = extract_records(data, REQUESTS.envelope_key) + return Request.model_validate( + records[0] if records else data, context=context + ) + + return spec, parse + + def build_restart_ticket( rfc_number: str, *, diff --git a/easyvista_python_client/resources/tests/test_requests.py b/easyvista_python_client/resources/tests/test_requests.py index 3b7300f..ea2fb81 100644 --- a/easyvista_python_client/resources/tests/test_requests.py +++ b/easyvista_python_client/resources/tests/test_requests.py @@ -201,3 +201,15 @@ def test_build_suspend_and_restart_ticket_bodies(): assert spec.json == {wrapper: {}} spec, _ = build("I1", comment="c", done_by_id=3) assert spec.json == {wrapper: {"comment": "c", "done_by_id": 3}} + + +def test_build_requalify_ticket_bodies(): + for kwargs, inner in ( + ({"catalog_id": 3}, {"catalog_id": "3"}), + ({"catalog_code": "C1"}, {"catalog_code": "C1"}), + ({"catalog_guid": "{G}"}, {"catalog_guid": "{G}"}), + ): + spec, parse = r.build_requalify_ticket("I1", **kwargs) + assert (spec.method, spec.path) == ("PUT", "requests/I1") + assert spec.json == {"requalified": inner} + assert parse({"HREF": "https://x/requests/I1"}).rfc_number == "I1" diff --git a/easyvista_python_client/testing/test_method_invocation.py b/easyvista_python_client/testing/test_method_invocation.py index b58e1ad..7e4e233 100644 --- a/easyvista_python_client/testing/test_method_invocation.py +++ b/easyvista_python_client/testing/test_method_invocation.py @@ -83,6 +83,10 @@ "close_ticket": (("I1",), {"allow_workflow_effect": WorkflowEffect.INTERRUPTS}), "suspend_ticket": (("I1",), {"allow_workflow_effect": WorkflowEffect.UNKNOWN}), "restart_ticket": (("I1",), {"allow_workflow_effect": WorkflowEffect.UNKNOWN}), + "requalify_ticket": ( + ("I1",), + {"allow_workflow_effect": WorkflowEffect.UNKNOWN, "catalog_id": 3}, + ), "count_tickets": ((), {}), "create_action": (("I1", PostAction(action_type_id=94, group_id=3)), {}), # action_id named explicitly: omitted, the vendor form ends EVERY open diff --git a/easyvista_python_client/testing/test_public_api.py b/easyvista_python_client/testing/test_public_api.py index 321e40b..2f3552f 100644 --- a/easyvista_python_client/testing/test_public_api.py +++ b/easyvista_python_client/testing/test_public_api.py @@ -60,7 +60,7 @@ def _run_python(code: str) -> subprocess.CompletedProcess[str]: def test_package_imports_and_has_version(): - assert easyvista_python_client.__version__ == "0.5.0" + assert easyvista_python_client.__version__ == "0.6.0" def test_public_exports_available(): diff --git a/easyvista_python_client/tests/test_workflow.py b/easyvista_python_client/tests/test_workflow.py index 2d00230..efe493f 100644 --- a/easyvista_python_client/tests/test_workflow.py +++ b/easyvista_python_client/tests/test_workflow.py @@ -25,6 +25,9 @@ ("PUT", "actions/I1", {"end_action": {"action_id": 1}}, {A}), ("PUT", "requests/I1", {"suspended": {}}, {U}), ("PUT", "requests/I1", {"restarted": {}}, {U}), + ("PUT", "requests/I1", {"requalified": {"catalog_id": 3}}, {U}), + ("PUT", "requests/I1", {"Requalified": {}}, {U}), + ("PUT", "requests/I1", [{"requalified": {"catalog_code": "C"}}], {U}), # ... matched case-insensitively, on any path, and inside a list body. ("PUT", "requests/I1", {"Closed": {}}, {I}), ("PUT", "actions/60350", {"END_ACTION": {}}, {A}), diff --git a/easyvista_python_client/workflow.py b/easyvista_python_client/workflow.py index f040f2f..cc9addb 100644 --- a/easyvista_python_client/workflow.py +++ b/easyvista_python_client/workflow.py @@ -32,12 +32,13 @@ site allowed it explicitly, with ``allow_workflow_effect=``. **What gets named.** (1) The vendor's workflow-control bodies -- ``closed``, -``end_action``, ``suspended``, ``restarted`` -- as a top-level body key, in any -casing, on any path. (2) On ticket and action routes, the columns that hold or -select workflow state: a status, a catalog (which selects the workflow), the -workflow, stage and step links, and on an existing action its end date, the -statuses it sets (``status_id_on_terminate``, ``status_id_on_create``), type, -parent or ticket (creating an action or a task names a narrower set, below). +``end_action``, ``suspended``, ``restarted``, ``requalified`` -- as a top-level body +key, in any casing, on any path. (2) On ticket and action routes, the columns +that hold or select workflow state: a status, a catalog (which selects the +workflow), the workflow, stage and step links, and on an existing action its +end date, the statuses it sets (``status_id_on_terminate``, +``status_id_on_create``), type, parent or ticket (creating an action or a task +names a narrower set, below). (3) Ticket sub-routes that are workflow commands rather than records, and ``requests/without-workflow`` and the deletion of a ticket. (4) A write to ``actions/`` where ```` is not an integer id: ``PUT @@ -91,6 +92,7 @@ class WorkflowEffect(enum.Enum): "end_action": WorkflowEffect.ADVANCES, "suspended": WorkflowEffect.UNKNOWN, "restarted": WorkflowEffect.UNKNOWN, + "requalified": WorkflowEffect.UNKNOWN, } #: Columns on ``requests/{rfc}`` that hold or select workflow state. The vendor @@ -101,7 +103,9 @@ class WorkflowEffect(enum.Enum): #: category as starting a new workflow: "Requalify the category of the object. #: A new workflow will then start." (https://docs.easyvista.com/docs/action.md, #: tier 1, read 2026-10-02). Reading the catalog columns as that category is -#: this module's inference, not a measurement. +#: this module's inference, not a measurement. The ``requalified`` body nests +#: its catalog key one level down, where this column check does not look, so +#: the body is named as an envelope above. _REQUEST_COLUMNS = frozenset( { "status_id", diff --git a/pyproject.toml b/pyproject.toml index c3e103b..ec54722 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,7 +44,7 @@ exclude = [ [project] name = "easyvista-python-client" -version = "0.5.0" +version = "0.6.0" description = "Typed Python client for the EasyVista Service Manager REST API" readme = "README.md" requires-python = ">=3.11" diff --git a/skills/easyvista-asset-workflow/SKILL.md b/skills/easyvista-asset-workflow/SKILL.md index b077771..68d6457 100644 --- a/skills/easyvista-asset-workflow/SKILL.md +++ b/skills/easyvista-asset-workflow/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the assets resource." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, diff --git a/skills/easyvista-client-setup/SKILL.md b/skills/easyvista-client-setup/SKILL.md index a379bd9..188d94e 100644 --- a/skills/easyvista-client-setup/SKILL.md +++ b/skills/easyvista-client-setup/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and valid EasyVista credentials." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- `easyvista_python_client` ships both clients over one surface: diff --git a/skills/easyvista-directory/SKILL.md b/skills/easyvista-directory/SKILL.md index 3ca68c5..0f4ca93 100644 --- a/skills/easyvista-directory/SKILL.md +++ b/skills/easyvista-directory/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the departments and employees resources (writes are additionally profile-gated)." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, diff --git a/skills/easyvista-document-workflow/SKILL.md b/skills/easyvista-document-workflow/SKILL.md index 67f1a5c..a947ab1 100644 --- a/skills/easyvista-document-workflow/SKILL.md +++ b/skills/easyvista-document-workflow/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the documents sub-resource." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, diff --git a/skills/easyvista-instance-discovery/SKILL.md b/skills/easyvista-instance-discovery/SKILL.md index e664a12..8afdb62 100644 --- a/skills/easyvista-instance-discovery/SKILL.md +++ b/skills/easyvista-instance-discovery/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, and network access to an EasyVista Service Manager REST API. Every call here is a GET; nothing is created, updated or deleted." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, diff --git a/skills/easyvista-reporting-and-context/SKILL.md b/skills/easyvista-reporting-and-context/SKILL.md index a2b970f..7cfb152 100644 --- a/skills/easyvista-reporting-and-context/SKILL.md +++ b/skills/easyvista-reporting-and-context/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, and network access to an EasyVista Service Manager REST API." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, diff --git a/skills/easyvista-search-syntax/SKILL.md b/skills/easyvista-search-syntax/SKILL.md index c3e9a39..7641870 100644 --- a/skills/easyvista-search-syntax/SKILL.md +++ b/skills/easyvista-search-syntax/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, and network access to an EasyVista Service Manager REST API." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, diff --git a/skills/easyvista-ticket-actions/SKILL.md b/skills/easyvista-ticket-actions/SKILL.md index 5099a8a..64af4e8 100644 --- a/skills/easyvista-ticket-actions/SKILL.md +++ b/skills/easyvista-ticket-actions/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the actions sub-resource." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, diff --git a/skills/easyvista-ticket-workflow/SKILL.md b/skills/easyvista-ticket-workflow/SKILL.md index a496ce7..84928c1 100644 --- a/skills/easyvista-ticket-workflow/SKILL.md +++ b/skills/easyvista-ticket-workflow/SKILL.md @@ -1,11 +1,11 @@ --- name: easyvista-ticket-workflow -description: "Create, read, search, paginate, update and close EasyVista tickets (requests) with easyvista_python_client — PostRequest, Request, RequestUpdate, create_ticket, create_tickets, get_ticket, search_tickets, iter_tickets, count_tickets, update_ticket and close_ticket. Use for any ticket/incident/request operation, including discovering the instance-specific catalog codes and ids a create needs." +description: "Create, read, search, paginate, update and close EasyVista tickets (requests) with easyvista_python_client — PostRequest, Request, RequestUpdate, create_ticket, create_tickets, get_ticket, search_tickets, iter_tickets, count_tickets, update_ticket, close_ticket, suspend_ticket, restart_ticket and requalify_ticket. Use for any ticket/incident/request operation, including discovering the instance-specific catalog codes and ids a create needs." license: MIT compatibility: "Requires Python 3.11+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the requests resource." metadata: package: easyvista-python-client - version: "0.5.0" + version: "0.6.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, @@ -363,3 +363,28 @@ with EasyvistaClient.from_env() as client: is also absent: it raised HTTP 590 while still changing the stored value on the verified instance, so it is not offered until that is resolved (open item `O-590-PARTIAL`). + +### Requalify + +`requalify_ticket` sends a `requalified` body naming exactly one target catalog: +`catalog_id`, `catalog_code` or `catalog_guid` (zero or several raise `ValueError` +before any request). The vendor says a requalification starts a new workflow (tier 1: +`action.md`), so it requires `allow_workflow_effect` and is refused unless it +includes `WorkflowEffect.UNKNOWN`; an allowed request is sent once, never retried. + +```python +from easyvista_python_client import EasyvistaClient, WorkflowEffect + +with EasyvistaClient.from_env() as client: + client.requalify_ticket( + "YOUR_RFC_NUMBER", + allow_workflow_effect=WorkflowEffect.UNKNOWN, + catalog_code="YOUR_CATALOG_CODE", + ) + # The answer is not a receipt: re-read to confirm the landing. + print(client.get_ticket("YOUR_RFC_NUMBER").sd_catalog_id) +``` + +Measured on one instance on 2026-11-16 (tier 4, may not generalise): an incident +lands even when the server answers HTTP 590; a request is refused with 400 and code +2117; a request sent to an incident catalog entry is refused with 400 and code 2119.