transition.batch · Umwelt docs

Reference/Commands/transition.batch

transition.batchcommandsince 0.1

Moves many records to one status at once: retracted, revoked, forgotten or abandoned.

Command lineTypeScript.NET

Request

umwelt call story.umw transition.batch '{
  "projectId": "ball",
  "attemptId": "forget",
  "position": { "tick": 7 },
  "recordIds": ["butler-unsure"],
  "status": "forgotten"
}'

Request

const result = await client.transitionBatch({
  projectId: 'ball',
  attemptId: 'forget',
  position: { tick: 7 },
  recordIds: ['butler-unsure'],
  status: 'forgotten',
});

Request

var result = engine.TransitionBatch(new TransitionBatchInput
{
    ProjectId = "ball",
    AttemptId = "forget",
    Position = new Position { Tick = 7 },
    RecordIds = new() { "butler-unsure" },
    Status = TransitionStatus.Forgotten,
});

Response

{
  "eventId": "01a1cbd8-63f5-7de2-a86a-15baf5c507c3",
  "recordIds": [],
  "transitionIds": ["01a1cbd8-63f5-7de2-a86a-15c47bf15f39"],
  "version": 11,
  "warnings": []
}

Payload

Field	Type	Description
`projectId`required	string	The project to write to.
`attemptId`required	string	Makes a retry safe: the same request with the same attempt id is applied once.
`position`required	Position	Where the generated event stands on the main axis: `{ "tick": n }`.
`recordIds`required	string[]	The records.
`status`required	"retracted" \| "revoked" \| "forgotten" \| "abandoned"	`retracted`, `revoked`, `forgotten` or `abandoned`. For `superseded`, use `holding.adjustBatch`.
`on`	object	Positions of the generated event on additional axes, such as `{ "reading": 12 }`.
`provenance`	Provenance	Who or what made the change: a person, a model, the system or an import.
`timelineId`	stringdefault "main"	The timeline to write to.
`expectedVersion`	integer	Fails the write with `VERSION_CONFLICT` unless the timeline’s head is still this version.

Result

Field	Type	Description
`eventId`always	string	The event written, with the id given or generated.
`recordIds`always	string[]	The records written, in order.
`transitionIds`always	string[]	The transitions written, in order.
`version`always	integer	The version this commit received. Reads at an earlier `asOfVersion` do not see it.
`warnings`	Warning[]	`UNKNOWN_PREDICATE` (open vocabulary) or `SECRET_BREACH`. Warnings never block a write.

Rules

Nothing is deleted. Each record becomes inactive from position on. Before it, the record is still active.

One commit. With one engine event of type umwelt:transition, kept out of full-text search.

The status is your account. The engine treats every status alike; the name says why it changed.

Errors

VALIDATION_FAILEDThe payload is malformed, the status is superseded, or the position precedes a record.

NOT_FOUNDThe project, a record or the timeline does not exist.

VERSION_CONFLICTexpectedVersion is no longer the head of the timeline.

CONFLICTThe attemptId was already used with a different request.

INVALID_STATEThe timeline is a draft that was promoted or discarded, and accepts no more writes.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also