proto/gateway.proto in zeebe-client-0.17.0 vs proto/gateway.proto in zeebe-client-0.18.0

@@ -96,12 +96,29 @@
   // process instance; it must be a JSON object, as variables will be mapped in a
   // key-value fashion. e.g. { "a": 1, "b": 2 } will create two variables, named "a" and
   // "b" respectively, with their associated values. [{ "a": 1, "b": 2 }] would not be a
   // valid argument, as the root of the JSON document is an array and not an object.
   string variables = 4;
+  // List of start instructions. If empty (default) the process instance
+  // will start at the start event. If non-empty the process instance will apply start
+  // instructions after it has been created
+  repeated ProcessInstanceCreationStartInstruction startInstructions = 5;
 }
 
+message ProcessInstanceCreationStartInstruction {
+
+  // future extensions might include
+  // - different types of start instructions
+  // - ability to set local variables for different flow scopes
+
+  // for now, however, the start instruction is implicitly a
+  // "startBeforeElement" instruction
+
+  // element ID
+  string elementId = 1;
+}
+
 message CreateProcessInstanceResponse {
   // the key of the process definition which was used to create the process instance
   int64 processDefinitionKey = 1;
   // the BPMN process ID of the process definition which was used to create the process
   // instance
@@ -252,11 +269,11 @@
   int32 retries = 2;
   // an optional message describing why the job failed
   // this is particularly useful if a job runs out of retries and an incident is raised,
   // as it this message can help explain why an incident was raised
   string errorMessage = 3;
-  // the backoff timeout for the next retry
+  // the backoff timeout (in ms) for the next retry
   int64 retryBackOff = 4;
 }
 
 message FailJobResponse {
 }
@@ -384,10 +401,52 @@
 message SetVariablesResponse {
   // the unique key of the set variables command
   int64 key = 1;
 }
 
+message ModifyProcessInstanceRequest {
+  // the key of the process instance that should be modified
+  int64 processInstanceKey = 1;
+  // instructions describing which elements should be activated in which scopes,
+  // and which variables should be created
+  repeated ActivateInstruction activateInstructions = 2;
+  // instructions describing which elements should be terminated
+  repeated TerminateInstruction terminateInstructions = 3;
+
+  message ActivateInstruction {
+    // the id of the element that should be activated
+    string elementId = 1;
+    // the key of the ancestor scope the element instance should be created in;
+    // set to -1 to create the new element instance within an existing element
+    // instance of the flow scope
+    int64 ancestorElementInstanceKey = 2;
+    // instructions describing which variables should be created
+    repeated VariableInstruction variableInstructions = 3;
+  }
+
+  message VariableInstruction {
+    // JSON document that will instantiate the variables for the root variable scope of the
+    // process instance; it must be a JSON object, as variables will be mapped in a
+    // key-value fashion. e.g. { "a": 1, "b": 2 } will create two variables, named "a" and
+    // "b" respectively, with their associated values. [{ "a": 1, "b": 2 }] would not be a
+    // valid argument, as the root of the JSON document is an array and not an object.
+    string variables = 1;
+    // the id of the element in which scope the variables should be created;
+    // leave empty to create the variables in the global scope of the process instance
+    string scopeId = 2;
+  }
+
+  message TerminateInstruction {
+    // the id of the element that should be terminated
+    int64 elementInstanceKey = 1;
+  }
+}
+
+message ModifyProcessInstanceResponse {
+
+}
+
 service Gateway {
   /*
     Iterates through all known partitions round-robin and activates up to the requested
     maximum and streams them back to the client as they are activated.
 
@@ -570,7 +629,26 @@
 
       INVALID_ARGUMENT:
         - retries is not greater than 0
    */
   rpc UpdateJobRetries (UpdateJobRetriesRequest) returns (UpdateJobRetriesResponse) {
+  }
+
+  /*
+    Modifies the process instance. This is done by activating and/or terminating specific elements of the instance.
+
+    Errors:
+      NOT_FOUND:
+        - no process instance exists with the given key
+
+      FAILED_PRECONDITION:
+        - trying to activate element inside of a multi-instance
+
+      INVALID_ARGUMENT:
+        - activating or terminating unknown element
+        - ancestor of element for activation doesn't exist
+        - scope of variable is unknown
+   */
+  rpc ModifyProcessInstance (ModifyProcessInstanceRequest) returns (ModifyProcessInstanceResponse) {
+
   }
 }