Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 42 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions docs/user_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 10 additions & 4 deletions docs/vendor-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
115 changes: 107 additions & 8 deletions easyvista_python_client/_async/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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`
Expand Down
147 changes: 147 additions & 0 deletions easyvista_python_client/_async/tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading
Loading