State.md

 [[_TOC_]]
 
+# Overview
 For any instance, states and a corresponding a workflow may be defined. Using them it's possible to define who can do which action (transition) which which instance in which state.
 
 E.g. a contract is entered by an employee, then has to be approved by a supervisor (and cannot be changed any longer at that point by the employee).
@@ -8,4 +9,31 @@ To move an instance from one state to the other, a transition must be used. If a
 
 A visualization of a workflow might look like this:
 
-![core__project.svg](uploads/7718457dad2492faf0aa3d31d08198c1/core__project.svg)
+![core__project.svg](uploads/7718457dad2492faf0aa3d31d08198c1/core__project.svg)
\ No newline at end of file
+
+# instance_state
+
+A entity will have an attribute "instance_state" and it's value is the id of the state the instance is in.
+
+To get a full list of all states for an entity, query the system.state table with the id of the entity (can be found in the universe):
+
+POST /data/system/state/query
+
+```
+{
+  "conds" : {"entity" : 156}
+}
+```
+
+You may join instance_state on your base entity to get it's details or filter by it's name etc:
+```
+{
+   "attrs" : {"prefetch":"instance_state"}
+}
+```
+```
+{
+   "conds" : {"instance_state.name" : {"-ilike":"a%"}},
+   "attrs" : {"join":"instance_state"}
+}
+```
\ No newline at end of file