diff --git a/CHANGELOG.md b/CHANGELOG.md index 42afa9a..a940048 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,46 @@ is the error. Tags carry no `v` prefix. ## [Unreleased] +## [0.5.0] - 2026-11-10 + +Two more of the vendor's ticket requests, and a guard that names one more +column. Neither new method takes a status: the package still has no status +setter. + +### Added + +- **`suspend_ticket(rfc_number, *, allow_workflow_effect, comment=None, + done_by_id=None)`** and **`restart_ticket(...)`** (same signature), the + vendor's suspend and restart requests + ([suspend](https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md), + [restart](https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md)): + `PUT requests/{rfc_number}` with a `suspended` / `restarted` object. The guard + already named both bodies `WorkflowEffect.UNKNOWN`, so + `allow_workflow_effect` is a required keyword and the call is refused before + any request unless it includes `UNKNOWN`; an allowed request is sent once, + never retried. `comment` and `done_by_id` are left out of the body when + `None`. The return value is parsed as `close_ticket`'s is. + +### Changed + +- **BREAKING:** the workflow guard now names `STATUS_ID_ON_CREATE` on an + existing action (`update_action`, or `PUT actions/{id}` through `send`), as + it does `STATUS_ID_ON_TERMINATE`. A write that passed before is refused + without `allow_workflow_effect=WorkflowEffect.UNKNOWN`. Measured 2026-11-09 + and 2026-11-10 on one instance (tier 4, may not generalise): a write to it + on an existing action changed where the ticket's status went. Creating an + action or a task is unchanged: the server overwrites the column on create. + +### Fixed + +- **The `reassign_action` documentation about `OWNING_GROUP_ID`.** It said the + ticket's owning group does not follow a reassigned step. Measured 2026-11-04 + to 2026-11-10 on one instance (several tickets, may not generalise): it + follows after a few seconds to about two minutes (consistent with a + server-side job; inferred, not observed), and `LAST_UPDATE` moves with it; + the first reading was taken too soon. The status still does not move, the + step is not started and no action row is added. + ## [0.4.3] - 2026-10-08 A patch release of the content reader: a caller can recognise the images a @@ -1690,7 +1730,8 @@ Initial public release. status/error code, with non-retryable validation errors (HTTP 590, code 2013). - `py.typed` marker — the package ships inline type information. -[Unreleased]: https://github.com/baraline/easyvista_python_client/compare/0.4.3...HEAD +[Unreleased]: https://github.com/baraline/easyvista_python_client/compare/0.5.0...HEAD +[0.5.0]: https://github.com/baraline/easyvista_python_client/compare/0.4.3...0.5.0 [0.4.3]: https://github.com/baraline/easyvista_python_client/compare/0.4.2...0.4.3 [0.4.2]: https://github.com/baraline/easyvista_python_client/compare/0.4.1...0.4.2 [0.4.1]: https://github.com/baraline/easyvista_python_client/compare/0.4.0...0.4.1 diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 3dfa03c..87a8be4 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -473,8 +473,9 @@ rule on your instance can run on any write. To escalate the open workflow step to another group without ending it, use :meth:`~easyvista_python_client.EasyvistaClient.reassign_action` (measured 2026-10-02, one instance, so it may not generalise: the step stays open and the -status does not move; the ticket's owning group, read on one ticket, did not -follow). +status does not move; measured 2026-11-04 to 2026-11-10, several tickets, the +ticket's owning group follows the step's new group after a few seconds to about +two minutes). Creating a ticket starts its workflow -- the vendor's create page lists "The workflow associated with the ticket is started." among what a create does (tier diff --git a/docs/vendor-api-reference.md b/docs/vendor-api-reference.md index 5f95160..2ee044c 100644 --- a/docs/vendor-api-reference.md +++ b/docs/vendor-api-reference.md @@ -287,10 +287,16 @@ again five seconds later); the step **stayed open** (`END_DATE_UT` empty); the t status and `END_DATE_UT` **did not move**; the open actions were unchanged; and **no new action rows** appeared. On the **first ticket only** the step was recorded as a type-20 action with `WORKFLOW_ID` set, its `WORKFLOW_ID` was unchanged, `DONE_BY_ID` stayed -empty and no ticket field changed; and that is also the only ticket on which the -ticket's own `OWNING_GROUP_ID` was read — it **stayed at the old group**, so the -ticket's owning group did not follow the action's. Reassigning to a person -(`done_by_id`) was **not measured**. Whether the UI wizard's notifications fire is not +empty and no ticket field changed. The ticket's own `OWNING_GROUP_ID` was read on +that ticket only, and had not moved; that reading was taken too soon. Measured +2026-11-04 to 2026-11-10 on one instance (several tickets, may not generalise): the +ticket's `OWNING_GROUP_ID` **follows the step's new group** after a delay of a few +seconds to about two minutes (consistent with a server-side job; inferred, not +observed), and `LAST_UPDATE` moves with it; the status still does not move, the step +is not started and no action row is added. Also measured 2026-11-04 on one ticket: +after `done_by_id` was written on the step, the ticket's `OWNER_ID` followed about +1 min 45 s later. The person's effect on the step was not measured beyond that one +`OWNER_ID` observation. Whether the UI wizard's notifications fire is not observable from the API. **Business rules can fire on any write** — "On Insert/On Update" of any record diff --git a/easyvista_python_client/_async/client.py b/easyvista_python_client/_async/client.py index ecde3df..98d8c0c 100644 --- a/easyvista_python_client/_async/client.py +++ b/easyvista_python_client/_async/client.py @@ -610,6 +610,99 @@ async def close_ticket( ) return parse(await self._transport.send(spec.allowing(allow_workflow_effect))) + async def suspend_ticket( + self, + rfc_number: str, + *, + allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect], + comment: str | None = None, + done_by_id: int | None = None, + ) -> Request: + """Suspend a ticket -- the vendor's suspend request. + + Sends ``PUT requests/{rfc}`` with a ``suspended`` body, as the vendor + documents it: + https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md + (tier 1, re-read 2026-11-10). The page documents two optional + parameters, ``comment`` and ``done_by_id`` (an employee id), and no + target status. Both are left out of the body when ``None``. A ticket + that is already suspended is refused by the server (400, "The request + is already suspended. Operation aborted."). + + Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not + generalise): the ticket moved to the instance's suspended status and + one already-ended suspension action carrying the comment was added; + the workflow step stayed open. A status key sent in the body was + ignored (measured 2026-11-04). The request takes no status, and the + package has no status setter. + + ``allow_workflow_effect`` is **required**: nothing documents what a + suspend does to the workflow, so the write is named + ``WorkflowEffect.UNKNOWN`` and refused with + :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused` + before any request is made unless the call allows it. The allowed + request is sent once, never retried. The return value is parsed like + :meth:`close_ticket`'s: the vendor answers 201 with an ``HREF`` only, so + re-read with :meth:`get_ticket` to see the status:: + + client.suspend_ticket( + rfc, + allow_workflow_effect=WorkflowEffect.UNKNOWN, + comment="Waiting for the requester", + ) + """ + spec, parse = requests_res.build_suspend_ticket( + rfc_number, + comment=comment, + done_by_id=done_by_id, + context=self._validation_context, + ) + return parse(await self._transport.send(spec.allowing(allow_workflow_effect))) + + async def restart_ticket( + self, + rfc_number: str, + *, + allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect], + comment: str | None = None, + done_by_id: int | None = None, + ) -> Request: + """Restart a suspended ticket -- the vendor's restart request. + + Sends ``PUT requests/{rfc}`` with a ``restarted`` body, as the vendor + documents it: + https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md + (tier 1, re-read 2026-11-10). The page documents two optional + parameters, ``comment`` and ``done_by_id`` (an employee id), and no + target status; its example marks ``comment`` as required while its + table lists it as optional, so this method leaves it out of the body + when ``None``. On a ticket that is not suspended the server answers + 400 with "The request is not suspended. Operation aborted.". + + Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not + generalise): the request added one end-of-suspension action and, in + the tested case, returned the ticket to the status it was suspended + from; a restart on a ticket that was not suspended was refused with + the documented message, as HTTP 590 rather than the documented 400. + A status key sent in the body was ignored + (measured 2026-11-04). The request takes no status, and the package + has no status setter. + + ``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.restart_ticket(rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN) + """ + spec, parse = requests_res.build_restart_ticket( + rfc_number, + comment=comment, + done_by_id=done_by_id, + context=self._validation_context, + ) + return parse(await self._transport.send(spec.allowing(allow_workflow_effect))) + # --- actions ------------------------------------------------------------- async def create_action( self, @@ -947,14 +1040,20 @@ async def reassign_action( the **first ticket only** the step was recorded as a type-20 action with ``WORKFLOW_ID`` set; its ``WORKFLOW_ID`` was unchanged, ``DONE_BY_ID`` stayed empty, and no ticket field changed. - **The ticket's own ``OWNING_GROUP_ID`` does not follow the action's - group** -- it stayed 57 on the first ticket, the only one read for it, - so reassigning a step is not reassigning the ticket. The lower-case - key ``group_id`` was the one sent; the upper-case spelling was never - needed. The person (``done_by_id``) was **not measured**: the same - body shape is sent, but nothing here shows what the instance does - with it. Whether the UI wizard's notifications fire is not observable - from the API. + The ticket's own ``OWNING_GROUP_ID`` was read at the time on one + ticket only and had not moved; that reading was taken too soon. + Measured 2026-11-04 to 2026-11-10 on one instance (several tickets, + may not generalise): the ticket's ``OWNING_GROUP_ID`` follows the + step's new group after a delay of a few seconds to about two minutes, + consistent with a server-side job (inferred, not observed), and + ``LAST_UPDATE`` moves with it. What still holds: the status does not + move, the step is not started and no action row is added. Also + measured 2026-11-04 on one ticket: after ``done_by_id`` was written on + the step, the ticket's ``OWNER_ID`` followed about 1 min 45 s later. + The lower-case key ``group_id`` was the one sent; the upper-case + spelling was never needed. The person's effect on the step was not + measured beyond that one ``OWNER_ID`` observation. Whether the UI + wizard's notifications fire is not observable from the API. Not refused by the workflow guard: the group and the person are data the workflow reads, not workflow state. Re-read with :meth:`get_action` diff --git a/easyvista_python_client/_async/tests/test_client.py b/easyvista_python_client/_async/tests/test_client.py index c045ba9..5417b95 100644 --- a/easyvista_python_client/_async/tests/test_client.py +++ b/easyvista_python_client/_async/tests/test_client.py @@ -2984,3 +2984,150 @@ async def test_end_action_compares_the_read_id_with_the_requested_id_as_integers assert json.loads(end.calls.last.request.content) == { "end_action": {"action_id": 42} } + + +# --- suspend_ticket / restart_ticket ------------------------------------------ + +_STATE_METHODS = [ + ("suspend_ticket", "suspended"), + ("restart_ticket", "restarted"), +] + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +async def test_state_request_sends_the_wrapper_with_comment_and_done_by( + config, method, wrapper +): + 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: + await getattr(client, method)( + "I1", + allow_workflow_effect=WorkflowEffect.UNKNOWN, + comment="note", + done_by_id=7, + ) + assert route.call_count == 1 + assert json.loads(route.calls.last.request.content) == { + wrapper: {"comment": "note", "done_by_id": 7} + } + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +async def test_state_request_omits_comment_and_done_by_when_none( + config, method, wrapper +): + 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 getattr(client, method)( + "I1", allow_workflow_effect=[WorkflowEffect.UNKNOWN] + ) + assert json.loads(route.calls.last.request.content) == {wrapper: {}} + # An HREF-only answer parses like close_ticket's: the model reads the RFC + # number off the href. + assert result.rfc_number == "I1" + assert result.href == f"{ROOT}/requests/I1" + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +async def test_state_request_requires_the_opt_in_keyword(config, method, wrapper): + async with AsyncEasyvistaClient(config) as client: + with pytest.raises(TypeError): + await getattr(client, method)("I1") + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +async def test_state_request_is_refused_without_unknown_in_the_opt_in( + config, method, wrapper +): + route = respx.route().mock(return_value=httpx.Response(200, json={})) + async with AsyncEasyvistaClient(config) as client: + with pytest.raises(EasyvistaWorkflowEffectRefused): + await getattr(client, method)( + "I1", allow_workflow_effect=WorkflowEffect.INTERRUPTS + ) + with pytest.raises(EasyvistaWorkflowEffectRefused): + await getattr(client, method)("I1", allow_workflow_effect=()) + assert not route.called + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +async def test_state_request_is_sent_once_on_a_transient_failure( + config, method, wrapper +): + 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 getattr(client, method)( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN + ) + assert route.call_count == 1 + + +# --- the guard names STATUS_ID_ON_CREATE on an existing action ---------------- + + +@pytest.mark.parametrize("key", ["STATUS_ID_ON_CREATE", "status_id_on_create"]) +@respx.mock +async def test_update_action_refuses_status_id_on_create_without_an_opt_in( + config, key +): + route = respx.route().mock(return_value=httpx.Response(200, json={})) + update = ActionUpdate(extra_payload={key: "12"}) + async with AsyncEasyvistaClient(config) as client: + with pytest.raises(EasyvistaWorkflowEffectRefused): + await client.update_action(60350, update) + assert not route.called + + +@respx.mock +async def test_update_action_sends_status_id_on_create_when_allowed(config): + route = respx.put(f"{ROOT}/actions/60350").mock( + return_value=httpx.Response(200, json={}) + ) + update = ActionUpdate(extra_payload={"STATUS_ID_ON_CREATE": "12"}) + async with AsyncEasyvistaClient(config) as client: + await client.update_action( + 60350, update, allow_workflow_effect=WorkflowEffect.UNKNOWN + ) + assert route.call_count == 1 + assert json.loads(route.calls.last.request.content)["STATUS_ID_ON_CREATE"] == "12" + + +@respx.mock +async def test_create_action_and_task_do_not_name_status_id_on_create(config): + """Pinned: on create the server overwrites the column, so it is not named.""" + action = respx.post(f"{ROOT}/requests/I1/actions").mock( + return_value=httpx.Response(200, json={}) + ) + task = respx.post(f"{ROOT}/requests/I1/tasks").mock( + return_value=httpx.Response(200, json={}) + ) + async with AsyncEasyvistaClient(config) as client: + await client.create_action( + "I1", + PostAction( + action_type_id=94, + group_id=3, + extra_payload={"STATUS_ID_ON_CREATE": "12"}, + ), + ) + await client.create_task( + "I1", + PostTask( + action_type_id=94, + group_id=3, + extra_payload={"STATUS_ID_ON_CREATE": "12"}, + ), + ) + assert action.call_count == 1 + assert task.call_count == 1 diff --git a/easyvista_python_client/_sync/client.py b/easyvista_python_client/_sync/client.py index 7ae7792..11e4177 100644 --- a/easyvista_python_client/_sync/client.py +++ b/easyvista_python_client/_sync/client.py @@ -610,6 +610,99 @@ def close_ticket( ) return parse(self._transport.send(spec.allowing(allow_workflow_effect))) + def suspend_ticket( + self, + rfc_number: str, + *, + allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect], + comment: str | None = None, + done_by_id: int | None = None, + ) -> Request: + """Suspend a ticket -- the vendor's suspend request. + + Sends ``PUT requests/{rfc}`` with a ``suspended`` body, as the vendor + documents it: + https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md + (tier 1, re-read 2026-11-10). The page documents two optional + parameters, ``comment`` and ``done_by_id`` (an employee id), and no + target status. Both are left out of the body when ``None``. A ticket + that is already suspended is refused by the server (400, "The request + is already suspended. Operation aborted."). + + Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not + generalise): the ticket moved to the instance's suspended status and + one already-ended suspension action carrying the comment was added; + the workflow step stayed open. A status key sent in the body was + ignored (measured 2026-11-04). The request takes no status, and the + package has no status setter. + + ``allow_workflow_effect`` is **required**: nothing documents what a + suspend does to the workflow, so the write is named + ``WorkflowEffect.UNKNOWN`` and refused with + :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused` + before any request is made unless the call allows it. The allowed + request is sent once, never retried. The return value is parsed like + :meth:`close_ticket`'s: the vendor answers 201 with an ``HREF`` only, so + re-read with :meth:`get_ticket` to see the status:: + + client.suspend_ticket( + rfc, + allow_workflow_effect=WorkflowEffect.UNKNOWN, + comment="Waiting for the requester", + ) + """ + spec, parse = requests_res.build_suspend_ticket( + rfc_number, + comment=comment, + done_by_id=done_by_id, + context=self._validation_context, + ) + return parse(self._transport.send(spec.allowing(allow_workflow_effect))) + + def restart_ticket( + self, + rfc_number: str, + *, + allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect], + comment: str | None = None, + done_by_id: int | None = None, + ) -> Request: + """Restart a suspended ticket -- the vendor's restart request. + + Sends ``PUT requests/{rfc}`` with a ``restarted`` body, as the vendor + documents it: + https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md + (tier 1, re-read 2026-11-10). The page documents two optional + parameters, ``comment`` and ``done_by_id`` (an employee id), and no + target status; its example marks ``comment`` as required while its + table lists it as optional, so this method leaves it out of the body + when ``None``. On a ticket that is not suspended the server answers + 400 with "The request is not suspended. Operation aborted.". + + Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not + generalise): the request added one end-of-suspension action and, in + the tested case, returned the ticket to the status it was suspended + from; a restart on a ticket that was not suspended was refused with + the documented message, as HTTP 590 rather than the documented 400. + A status key sent in the body was ignored + (measured 2026-11-04). The request takes no status, and the package + has no status setter. + + ``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.restart_ticket(rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN) + """ + spec, parse = requests_res.build_restart_ticket( + rfc_number, + comment=comment, + done_by_id=done_by_id, + context=self._validation_context, + ) + return parse(self._transport.send(spec.allowing(allow_workflow_effect))) + # --- actions ------------------------------------------------------------- def create_action( self, @@ -947,14 +1040,20 @@ def reassign_action( the **first ticket only** the step was recorded as a type-20 action with ``WORKFLOW_ID`` set; its ``WORKFLOW_ID`` was unchanged, ``DONE_BY_ID`` stayed empty, and no ticket field changed. - **The ticket's own ``OWNING_GROUP_ID`` does not follow the action's - group** -- it stayed 57 on the first ticket, the only one read for it, - so reassigning a step is not reassigning the ticket. The lower-case - key ``group_id`` was the one sent; the upper-case spelling was never - needed. The person (``done_by_id``) was **not measured**: the same - body shape is sent, but nothing here shows what the instance does - with it. Whether the UI wizard's notifications fire is not observable - from the API. + The ticket's own ``OWNING_GROUP_ID`` was read at the time on one + ticket only and had not moved; that reading was taken too soon. + Measured 2026-11-04 to 2026-11-10 on one instance (several tickets, + may not generalise): the ticket's ``OWNING_GROUP_ID`` follows the + step's new group after a delay of a few seconds to about two minutes, + consistent with a server-side job (inferred, not observed), and + ``LAST_UPDATE`` moves with it. What still holds: the status does not + move, the step is not started and no action row is added. Also + measured 2026-11-04 on one ticket: after ``done_by_id`` was written on + the step, the ticket's ``OWNER_ID`` followed about 1 min 45 s later. + The lower-case key ``group_id`` was the one sent; the upper-case + spelling was never needed. The person's effect on the step was not + measured beyond that one ``OWNER_ID`` observation. Whether the UI + wizard's notifications fire is not observable from the API. Not refused by the workflow guard: the group and the person are data the workflow reads, not workflow state. Re-read with :meth:`get_action` diff --git a/easyvista_python_client/_sync/tests/test_client.py b/easyvista_python_client/_sync/tests/test_client.py index 3010a8e..c9bf691 100644 --- a/easyvista_python_client/_sync/tests/test_client.py +++ b/easyvista_python_client/_sync/tests/test_client.py @@ -2984,3 +2984,150 @@ def test_end_action_compares_the_read_id_with_the_requested_id_as_integers( assert json.loads(end.calls.last.request.content) == { "end_action": {"action_id": 42} } + + +# --- suspend_ticket / restart_ticket ------------------------------------------ + +_STATE_METHODS = [ + ("suspend_ticket", "suspended"), + ("restart_ticket", "restarted"), +] + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +def test_state_request_sends_the_wrapper_with_comment_and_done_by( + config, method, wrapper +): + route = respx.put(f"{ROOT}/requests/I1").mock( + return_value=httpx.Response(201, json={"HREF": f"{ROOT}/requests/I1"}) + ) + with EasyvistaClient(config) as client: + getattr(client, method)( + "I1", + allow_workflow_effect=WorkflowEffect.UNKNOWN, + comment="note", + done_by_id=7, + ) + assert route.call_count == 1 + assert json.loads(route.calls.last.request.content) == { + wrapper: {"comment": "note", "done_by_id": 7} + } + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +def test_state_request_omits_comment_and_done_by_when_none( + config, method, wrapper +): + 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 = getattr(client, method)( + "I1", allow_workflow_effect=[WorkflowEffect.UNKNOWN] + ) + assert json.loads(route.calls.last.request.content) == {wrapper: {}} + # An HREF-only answer parses like close_ticket's: the model reads the RFC + # number off the href. + assert result.rfc_number == "I1" + assert result.href == f"{ROOT}/requests/I1" + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +def test_state_request_requires_the_opt_in_keyword(config, method, wrapper): + with EasyvistaClient(config) as client: + with pytest.raises(TypeError): + getattr(client, method)("I1") + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +def test_state_request_is_refused_without_unknown_in_the_opt_in( + config, method, wrapper +): + route = respx.route().mock(return_value=httpx.Response(200, json={})) + with EasyvistaClient(config) as client: + with pytest.raises(EasyvistaWorkflowEffectRefused): + getattr(client, method)( + "I1", allow_workflow_effect=WorkflowEffect.INTERRUPTS + ) + with pytest.raises(EasyvistaWorkflowEffectRefused): + getattr(client, method)("I1", allow_workflow_effect=()) + assert not route.called + + +@pytest.mark.parametrize(("method", "wrapper"), _STATE_METHODS) +@respx.mock +def test_state_request_is_sent_once_on_a_transient_failure( + config, method, wrapper +): + route = respx.put(f"{ROOT}/requests/I1").mock( + return_value=httpx.Response(503, json={}) + ) + with EasyvistaClient(config) as client: + with pytest.raises(EasyvistaError): + getattr(client, method)( + "I1", allow_workflow_effect=WorkflowEffect.UNKNOWN + ) + assert route.call_count == 1 + + +# --- the guard names STATUS_ID_ON_CREATE on an existing action ---------------- + + +@pytest.mark.parametrize("key", ["STATUS_ID_ON_CREATE", "status_id_on_create"]) +@respx.mock +def test_update_action_refuses_status_id_on_create_without_an_opt_in( + config, key +): + route = respx.route().mock(return_value=httpx.Response(200, json={})) + update = ActionUpdate(extra_payload={key: "12"}) + with EasyvistaClient(config) as client: + with pytest.raises(EasyvistaWorkflowEffectRefused): + client.update_action(60350, update) + assert not route.called + + +@respx.mock +def test_update_action_sends_status_id_on_create_when_allowed(config): + route = respx.put(f"{ROOT}/actions/60350").mock( + return_value=httpx.Response(200, json={}) + ) + update = ActionUpdate(extra_payload={"STATUS_ID_ON_CREATE": "12"}) + with EasyvistaClient(config) as client: + client.update_action( + 60350, update, allow_workflow_effect=WorkflowEffect.UNKNOWN + ) + assert route.call_count == 1 + assert json.loads(route.calls.last.request.content)["STATUS_ID_ON_CREATE"] == "12" + + +@respx.mock +def test_create_action_and_task_do_not_name_status_id_on_create(config): + """Pinned: on create the server overwrites the column, so it is not named.""" + action = respx.post(f"{ROOT}/requests/I1/actions").mock( + return_value=httpx.Response(200, json={}) + ) + task = respx.post(f"{ROOT}/requests/I1/tasks").mock( + return_value=httpx.Response(200, json={}) + ) + with EasyvistaClient(config) as client: + client.create_action( + "I1", + PostAction( + action_type_id=94, + group_id=3, + extra_payload={"STATUS_ID_ON_CREATE": "12"}, + ), + ) + client.create_task( + "I1", + PostTask( + action_type_id=94, + group_id=3, + extra_payload={"STATUS_ID_ON_CREATE": "12"}, + ), + ) + assert action.call_count == 1 + assert task.call_count == 1 diff --git a/easyvista_python_client/_version.py b/easyvista_python_client/_version.py index 0907569..aaff85a 100644 --- a/easyvista_python_client/_version.py +++ b/easyvista_python_client/_version.py @@ -5,4 +5,4 @@ live only in ``__init__``. """ -__version__ = "0.4.3" +__version__ = "0.5.0" diff --git a/easyvista_python_client/resources/requests.py b/easyvista_python_client/resources/requests.py index 7440c09..1adfa27 100644 --- a/easyvista_python_client/resources/requests.py +++ b/easyvista_python_client/resources/requests.py @@ -140,3 +140,71 @@ def parse(data: Any) -> Request: ) return spec, parse + + +def _build_state_request( + wrapper: str, + rfc_number: str, + *, + comment: str | None, + done_by_id: int | None, + context: dict[str, Any] | None, +) -> tuple[RequestSpec, Callable[[Any], Request]]: + body: dict[str, Any] = {} + if comment is not None: + body["comment"] = comment + if done_by_id is not None: + body["done_by_id"] = done_by_id + spec = RequestSpec("PUT", f"requests/{rfc_number}", json={wrapper: body}) + + 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_suspend_ticket( + rfc_number: str, + *, + comment: str | None = None, + done_by_id: int | None = None, + context: dict[str, Any] | None = None, +) -> tuple[RequestSpec, Callable[[Any], Request]]: + """Build the ``{"suspended": {...}}`` PUT spec -- the vendor's suspend request. + + https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md + (tier 1): ``comment`` and ``done_by_id`` are the page's two optional + parameters, and both are left out of the body when ``None``. + """ + return _build_state_request( + "suspended", + rfc_number, + comment=comment, + done_by_id=done_by_id, + context=context, + ) + + +def build_restart_ticket( + rfc_number: str, + *, + comment: str | None = None, + done_by_id: int | None = None, + context: dict[str, Any] | None = None, +) -> tuple[RequestSpec, Callable[[Any], Request]]: + """Build the ``{"restarted": {...}}`` PUT spec -- the vendor's restart request. + + https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md + (tier 1): ``comment`` and ``done_by_id`` are the page's two optional + parameters, and both are left out of the body when ``None``. + """ + return _build_state_request( + "restarted", + rfc_number, + comment=comment, + done_by_id=done_by_id, + context=context, + ) diff --git a/easyvista_python_client/resources/tests/test_requests.py b/easyvista_python_client/resources/tests/test_requests.py index a38bd3d..3b7300f 100644 --- a/easyvista_python_client/resources/tests/test_requests.py +++ b/easyvista_python_client/resources/tests/test_requests.py @@ -189,3 +189,15 @@ def test_build_close_ticket_unwraps_a_capital_r_requests_envelope(): """Red before the case-insensitive match.""" _, parser = r.build_close_ticket("I1") assert parser({"Requests": [{"RFC_NUMBER": "I1"}]}).rfc_number == "I1" + + +def test_build_suspend_and_restart_ticket_bodies(): + for build, wrapper in ( + (r.build_suspend_ticket, "suspended"), + (r.build_restart_ticket, "restarted"), + ): + spec, _ = build("I1") + assert (spec.method, spec.path) == ("PUT", "requests/I1") + assert spec.json == {wrapper: {}} + spec, _ = build("I1", comment="c", done_by_id=3) + assert spec.json == {wrapper: {"comment": "c", "done_by_id": 3}} diff --git a/easyvista_python_client/testing/test_method_invocation.py b/easyvista_python_client/testing/test_method_invocation.py index 00768c3..b58e1ad 100644 --- a/easyvista_python_client/testing/test_method_invocation.py +++ b/easyvista_python_client/testing/test_method_invocation.py @@ -81,6 +81,8 @@ # it because `send` returns the raw JSON body unchanged. "send": (("GET", "requests"), {}), "close_ticket": (("I1",), {"allow_workflow_effect": WorkflowEffect.INTERRUPTS}), + "suspend_ticket": (("I1",), {"allow_workflow_effect": WorkflowEffect.UNKNOWN}), + "restart_ticket": (("I1",), {"allow_workflow_effect": WorkflowEffect.UNKNOWN}), "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 d5959d7..321e40b 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.4.3" + assert easyvista_python_client.__version__ == "0.5.0" def test_public_exports_available(): diff --git a/easyvista_python_client/workflow.py b/easyvista_python_client/workflow.py index b15f398..f040f2f 100644 --- a/easyvista_python_client/workflow.py +++ b/easyvista_python_client/workflow.py @@ -35,7 +35,8 @@ ``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, type, +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 @@ -114,11 +115,17 @@ class WorkflowEffect(enum.Enum): ) #: Columns on ``actions/{id}`` that end, re-type, re-parent or move an action. +#: ``status_id_on_create``: workflow state. Measured 2026-11-09 and 2026-11-10 +#: on one instance (tier 4, may not generalise): a write to it on an existing +#: action changed where the ticket's status went. Not in the create sets +#: below: on create the server overwrites it with the current status +#: (measured 2026-11-05). _ACTION_COLUMNS = frozenset( { "end_date_ut", "end_date", "status_id_on_terminate", + "status_id_on_create", "workflow_id", "stage_id", "process_step_id", diff --git a/pyproject.toml b/pyproject.toml index 17dbe48..c3e103b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,7 +44,7 @@ exclude = [ [project] name = "easyvista-python-client" -version = "0.4.3" +version = "0.5.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 f75b991..b077771 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.4.3" + version: "0.5.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 8094999..a379bd9 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.4.3" + version: "0.5.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 022b7e8..3ca68c5 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.4.3" + version: "0.5.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 5bb7ce5..67f1a5c 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.4.3" + version: "0.5.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 7b6d541..e664a12 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.4.3" + version: "0.5.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 a42c5fb..a2b970f 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.4.3" + version: "0.5.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 b2d1ac6..c3e9a39 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.4.3" + version: "0.5.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 cc6141c..5099a8a 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.4.3" + version: "0.5.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, @@ -388,11 +388,17 @@ UI's transfer is a wizard), so the effect is measured, not specified. Measured 2026-10-02 on one instance (Service Manager 2025.3; two tickets, so it may not generalise): the group was stored (`GROUP_ID` 57 to 50 on the open workflow step of both tickets); the step stayed open and the ticket's status did not move; the -open actions were unchanged and no new action rows appeared. **The ticket's own -`OWNING_GROUP_ID` does not follow the action's group** (it stayed 57 on the first -ticket, the only one read for it), so reassigning a step is not reassigning the -ticket. Reassigning to a person (`done_by_id`) was **not measured**, and whether -the UI wizard's notifications fire is not observable from the API. +open actions were unchanged and no new action rows appeared. The ticket's own +`OWNING_GROUP_ID` was read on one ticket only and had not moved; that reading was +taken too soon. Measured 2026-11-04 to 2026-11-10 on one instance (several tickets, +may not generalise): **the ticket's `OWNING_GROUP_ID` follows the step's new group** +after a delay of a few seconds to about two minutes (consistent with a server-side +job; inferred, not observed; `LAST_UPDATE` moves with it); the status does not move, +the step is not started and no action row is added. Also measured 2026-11-04 on one +ticket: after `done_by_id` was written on the step, the ticket's `OWNER_ID` followed +about 1 min 45 s later. The person's effect on the step was not measured beyond that +one `OWNER_ID` observation, and whether the UI wizard's notifications fire is not +observable from the API. `reassign_action` is not refused by the workflow guard, because the group and the person are data the workflow reads, not workflow state. diff --git a/skills/easyvista-ticket-workflow/SKILL.md b/skills/easyvista-ticket-workflow/SKILL.md index aa3e09f..a496ce7 100644 --- a/skills/easyvista-ticket-workflow/SKILL.md +++ b/skills/easyvista-ticket-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 requests resource." metadata: package: easyvista-python-client - version: "0.4.3" + version: "0.5.0" --- > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`, @@ -199,6 +199,40 @@ a `TypeError`), and a value that does not include `WorkflowEffect.INTERRUPTS` is refused before any request is sent (see the first Gotcha). `WorkflowEffect` and `EasyvistaWorkflowEffectRefused` are both importable from the package root. +### Suspend and restart + +`suspend_ticket` and `restart_ticket` are the vendor's suspend and restart requests +(tier 1: `rest-api-suspend-an-incident-request.md`, +`rest-api-reopen-an-incident-request.md`). Each takes an optional `comment` and an +optional `done_by_id`, and no status. They are not status setters. Both require +`allow_workflow_effect` and are refused before any request 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.suspend_ticket( + "YOUR_RFC_NUMBER", + allow_workflow_effect=WorkflowEffect.UNKNOWN, + comment="Waiting for the requester", + ) + client.restart_ticket( + "YOUR_RFC_NUMBER", + allow_workflow_effect=WorkflowEffect.UNKNOWN, + comment="Requester answered", + ) + # Re-read: the answer carries an HREF only. + print(client.get_ticket("YOUR_RFC_NUMBER").status_id) +``` + +Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not generalise): a +suspend moves the ticket to the instance's suspended status and adds one +already-ended suspension action carrying the comment, with the workflow step left +open; a restart adds one end-of-suspension action and, in the tested case, returns +the ticket to the status it was suspended from; a restart on a ticket that is not suspended is refused with "The request is +not suspended. Operation aborted." + ```python from easyvista_python_client import EasyvistaClient, PostRequest