Queries and mutations for managing States in the platform.

Queries

Query States

QUERYstates
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get State

QUERYstate
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:State

Mutations

Create State

MUTATIONcreateState
Arguments
draft​
Output:State

Update State

MUTATIONupdateState
Arguments
version​
Long​
actions​
Array of StateUpdateAction​
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:State

Delete State

MUTATIONdeleteState
Arguments
version​
Long​
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:State

Output types

State

id​
String​

Unique identifier of the State.

version​
Long​

Current version of the State.

key​
String​

User-defined unique identifier of the State.

type​

Indicates to which resource or object types the State is assigned to.

Can be LineItemState, OrderState, PaymentState, ProductState, QuoteRequestState, QuoteState, RecurringOrderState, ReviewState, or StagedQuoteState​
roles​
Array of StateRole​
Roles the State can fulfill for Reviews and Line Items.
Can be Return, or ReviewIncludedInStatistics​
name​
String​

Name of the State.

nameAllLocales​
Array of LocalizedString​

Name of the State.

description​
String​

Description of the State.

descriptionAllLocales​
Array of LocalizedString​

Description of the State.

builtIn​
Boolean​
true for States that are an integral part of the Project. Those States cannot be deleted and their key cannot be changed.
transitionsRef​
Array of Reference​
  • list of States of the same type that the current State can be transitioned to. For example, when the current State is the Initial State of StateType OrderState and this list contains the reference to the Shipped OrderState, the transition Initial -> Shipped is allowed.
  • if empty, no transitions are allowed from the current State, defining the current State as final for this workflow.
  • if not set, the validation is turned off and the current State can be transitioned to any other State of the same type as the current State.
transitions​
Array of State​
  • list of States of the same type that the current State can be transitioned to. For example, when the current State is the Initial State of StateType OrderState and this list contains the reference to the Shipped OrderState, the transition Initial -> Shipped is allowed.
  • if empty, no transitions are allowed from the current State, defining the current State as final for this workflow.
  • if not set, the validation is turned off and the current State can be transitioned to any other State of the same type as the current State.
initial​
Boolean​
true for an initial State, the first State in a workflow.
createdAt​

Date and time (UTC) the State was initially created.

lastModifiedAt​

Date and time (UTC) the State was last updated.

createdBy​

IDs and references that created the State.

lastModifiedBy​

IDs and references that last modified the State.

StateQueryResult

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of State​

StateType

LineItemState
OrderState
PaymentState
ProductState
QuoteRequestState
QuoteState
RecurringOrderState
ReviewState
StagedQuoteState

StateRole

Return
ReviewIncludedInStatistics

Input types

StateDraft

key​
String​

User-defined unique identifier for the State.

If set to an empty value, an InvalidOperation error is returned.
If the value is used by another State in the Project, a DuplicateField error is returned.
type​

Specify to which resource or object type the State is assigned to.

Can be LineItemState, OrderState, PaymentState, ProductState, QuoteRequestState, QuoteState, RecurringOrderState, ReviewState, or StagedQuoteState​
name​

Name of the State.

description​

Description of the State.

initial​
Boolean​
Set to false if the State is not the first step in a workflow.
roles​
Array of StateRole​
If suitable, assign predefined roles the State can fulfill in case the State's type is LineItemState or ReviewState.
Can be Return, or ReviewIncludedInStatistics​
transitions​
Array of ReferenceInput​
Define the list of States of the same type to which the current State can be transitioned to.
  • If, for example, the current State is the Initial State of StateType OrderState and you want to allow the transition Initial -> Shipped, then add the StateResourceIdentifier to the Shipped OrderState to this list.
  • Set to empty list for not allowing any transition from the current State and defining it as final State for a workflow.
  • Do not set this field at all to turn off validation and allowing transitions to any other State of the same type as the current State.

StateUpdateAction

addRoles​
changeInitial​
changeKey​
changeType​
removeRoles​
setDescription​
setName​
setRoles​
setTransitions​

Update actions

Add Roles

roles​
Array of StateRole​

Value to append to the array.

If the specified roles are already present, an InvalidOperation error is returned.
If a specified role is not applicable to the State's type, an InvalidOperation error is returned.
Can be Return, or ReviewIncludedInStatistics​

Change Initial

initial​
Boolean​

Whether to define the State as the initial State in a state machine and make it the first step in a workflow.

If the new value is the same as the current value, an InvalidOperation error is returned.

Change Key

key​
String​

New value to set.

If set to an empty value, an InvalidOperation error is returned.
If the value is used by another State in the Project, a DuplicateField error is returned.

Change Type

type​

Resource or object types the State shall be assigned to. Must not be empty.

If the new value is the same as the current value, an InvalidOperation error is returned.
Can be LineItemState, OrderState, PaymentState, ProductState, QuoteRequestState, QuoteState, RecurringOrderState, ReviewState, or StagedQuoteState​

Remove Roles

roles​
Array of StateRole​

Roles to remove from the State.

If none of the specified roles are already present, an InvalidOperation error is returned.
Can be Return, or ReviewIncludedInStatistics​

Set Description

description​
Value to set. If the new value is the same as the current value, an InvalidOperation error is returned.

Set to an empty object to remove any existing value.

Set Name

name​
Value to set. If the new value is the same as the current value, an InvalidOperation error is returned.

Set to an empty object to remove any existing value.

Set Roles

roles​
Array of StateRole​
Value to set. If the new value is the same as the current value, an InvalidOperation error is returned. If a specified role is not applicable to the State's type, an InvalidOperation error is returned.

Set to an empty array to remove any existing value.

Can be Return, or ReviewIncludedInStatistics​

Set Transitions

transitions​

Value to set. If omitted, any existing value is removed.

Possible transformations of the current State to other States of the same type (for example, Initial -> Shipped). When performing a transitionState update action and transitions is set, the currently referenced State must have a transition to the new State.
If transitions is an empty list, it means the current State is a final State and no further transitions are allowed. If transitions is not set, the validation is turned off.
When performing a transitionState update action, any other State of the same type can be transitioned to.
If the new value is the same as the current value, an InvalidOperation error is returned.