Update a Process Instance

Details

URI /processinstances/<process_instance_id>
Where <process_instance_id> is the process instance ID.
Method PUT
Parameters

userIdentifier=<user_id>
    Required; the user ID you want to use as credentials for this API call. See Get userIdentifier for the steps required to get the userIdentifier value.

view=<view_type>&scope=view
    Optional; used to update process instance based on pre-defined views. Possible values for view_type are propertyinfo and processinstancestate. With processinstancestate, the process instance state, return code and status can be changed.

<property_>action<_>=merge
   Optional; use the merge option with the action meta tag query parameter to update only a portion of the process instance. The following the use cases are allowed:

  • With view=propertyinfo, specifying property_action_=merge will merge the properties specified in the request body with the existing process instance properties.
  • With view=processinstancestate, specifying action=merge will merge the state information specified in the request body with the existing process instance state.
Request Body ProcessInstance VO
Response Body Updated ProcessInstance VO
Returns 200 - Ok
401 - Not authorized
404 - Not found
500 - Server exception

Process instance state (processInstanceState) values:

  • INITIALIZED
  • PENDING
  • READY
  • ACTIVE
  • COMPLETED
  • ERROR
  • CANCELED

Process instance return code (processReturnCode) values:

  • SUCCESS
  • FAILURE
  • RUNNING
  • TIMEOUT

The request body sent in the API will be strictly validated for the following:

 

  • Process Instance Id sent has to exist in CSA, otherwise the call will fail with appropriate error message.
  • Process Instance state will be validated using the rule that the state cannot be changed to a transitional state while it is already in a terminal state. The terminal states are ‘COMPLETED, ERROR, CANCELED’ . So if the process instance state is already in any of the above states, this call will fail if it attempts to set the state to a different value than what it is currently. In addition, a process instance which is already in Active state cannot be reset back to Ready state using this call.

Examples

The following was sent to update propertyinfo of a process instance:

https://<host>:<port>/csa/rest/processinstances/90d9652b362d4ecd01362d4fb7be0f71?userIdentifier=90d9652b362d4ecd01362d4ef51e00a5&view=propertyinfo&scope=view&property_action_=merge

The following XML was sent in the request to update a property:

<ProcessInstance>>
   <id>90d9652b362d4ecd01362d4fb7be0f71</id>
   <property>
     <name>Property Name</name>
     <valueType>
       <name>STRING</name>
     </valueType>
     <values>
       <value>Hello World!</value>
     </values>
   </property>
 </ProcessInstance>

The following was sent to update the process instance state:

https://<host>:<port>/csa/rest/processinstances/90d9652b362d4ecd01362d4fb7be0f71?userIdentifier=90d96588360da0c701360da0f1d5f483&scope=view&view=processinstancestate&action=merge

<ProcessInstance>>
   <id>90d9652b3752ad4f013752ae38cb0065</id>
   <processInstanceState>
     <name>COMPLETED</name>
   </processInstanceState>
 </ProcessInstance>

The following was sent to update the process instance return code:

https://<host>:<port>/csa/rest/processinstances/90d9652b3752ad4f013752ae38cb0065?userIdentifier=90d96588360da0c701360da0f1d5f483&scope=view&view=processinstancestate&action=merge

<ProcessInstance>>
   <id>90d9652b3752ad4f013752ae38cb0065</id>
   <processReturnCode>
     <name>SUCCESS</name>
   </processReturnCode>
 </ProcessInstance>

The following was sent to update the process instance state, status and return code:

https://<host>:<port>/csa/rest/processinstances/90d9652b3752ad4f013752ae38cb0065?userIdentifier=90d96588360da0c701360da0f1d5f483&scope=view&view=processinstancestate&action=merge

<ProcessInstance>>
   <id90d9652b3752ad4f013752ae38cb0065</id>
   <processInstanceState>
     <name>COMPLETED</name>
   </processInstanceState>
   <processReturnCode>
     <name>SUCCESS</name>
   </processReturnCode>
   <status>The Process Instance has successfully completed.</status>
 </ProcessInstance>