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
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 13 additions & 5 deletions docs/user_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion docs/vendor-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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}/<sub>`, `<sub>` 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 |
Expand Down
58 changes: 53 additions & 5 deletions easyvista_python_client/_async/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
77 changes: 77 additions & 0 deletions easyvista_python_client/_async/tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 ----------------


Expand Down
58 changes: 53 additions & 5 deletions easyvista_python_client/_sync/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
77 changes: 77 additions & 0 deletions easyvista_python_client/_sync/tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 ----------------


Expand Down
2 changes: 1 addition & 1 deletion easyvista_python_client/_version.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
live only in ``__init__``.
"""

__version__ = "0.5.0"
__version__ = "0.6.0"
Loading
Loading