SOAP API Reference › Web Services Methods › controlProcess

controlProcess

Use this method to create a request to control a process.

Example

<tns:controlProcess xmlns:tns="http://www.ca.com/itpam"> 
  <tns:ProcessID>ProcessID__</tns:ProcessID> 
  <tns:action>action__</tns:action> 
  <tns:auth> 
<!--xsd:Choice Type--> 
<tns:token>token__</tns:token> 
<tns:user>user__</tns:user> 
<tns:password>password__</tns:password> 
  </tns:auth> 
</tns:controlProcess> 

SOAP Request

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<SOAP-ENV:Header/>

<SOAP-ENV:Body>

<tns:controlProcess xmlns:tns="http://www.ca.com/itpam">
<tns:ProcessID>47</tns:ProcessID>
<tns:action>suspend</tns:action>
<tns:auth>
<!--xsd:Choice Type-->
<tns:token>token__</tns:token>
<tns:user>Joe</tns:user>
<tns:password>thisismypassword</tns:password>
<tns:auth>
</tns:controlProcess></SOAP-ENV:Body></SOAP-ENV:Envelope>

SOAP Response

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<controlProcessResponse xmlns="http://www.ca.com/itpam">
<actionStatus>The suspend action for Process ID "47" was queued.</actionStatus>
</controlProcessResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Actions

Suspend

You can suspend a single process instance through a web services method.

If you cannot suspend a process instance (for example, it already completed or aborted), an error message returns containing details about the request.

Here is an example of a fault when you try to suspend a completed process:

<Fault xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>The process with Process ID "208" is in completed state and therefore cannot be suspended.</faultstring>
</Fault>

Resume

You can resume a single process instance that was previously suspended through a web services method.

If you cannot resume a process instance, an error message returns containing details about the request. For example, a process instance cannot resume because it was already completed, aborted, or not currently suspended.

Here is an example of a fault when you try to resume a completed process:

<Fault xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>The process with Process ID "208" is in completed state and therefore cannot be resumed.</faultstring>
</Fault>

Abort

You can abort a single process instance through a web services method.

If you cannot abort a process instance (for example, it already completed or aborted), an error message returns containing details about the request.

Here is an example of a fault when you try to abort a completed process:

<Fault xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>The process with Process ID "486" is in completed  state and therefore cannot be Aborted.</faultstring>
</Fault>

Example 1

<tns:controlProcess xmlns:tns="http://www.ca.com/itpam">
        <tns:ProcessID>ProcessID </tns:ProcessID>
        <tns:action>action</tns:action>
          <tns:auth>
	   <!--xsd:Choice Type-->
	   <tns:token>token__</tns:token>
           <tns:user>Joe</tns:user>
           <tns:password>thisismypassword</tns:password>
          <tns:auth></tns:controlProcess>

"ProcessedID" is the ROID of the process instance that you must control (suspend/ resume/abort). The "ROID" of a running process is in the response when executing a process through web services.

Example 2

<tns:ExecuteC2OFlowResponse xmlns:tns="http://www.ca.com/itpam">
        <tns:ExecuteC2OFlowResult>
        <tns:ROID>567</tns:ROID>
        ...
        ...
        </tns:ExecuteC2OFlowResult>
</tns:ExecuteC2OFlowResponse>

The value for action is to suspend, resume, or abort. Only an authorized user can perform this action; otherwise, a fault is returned.

Example 3

<SOAP-ENV:Fault xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
        <faultcode>SOAP-ENV:Server</faultcode>
        <faultstring>Invalid user/password or token.</faultstring>
</SOAP-ENV:Fault>

A fault returns if you try to perform an operation that you cannot perform on a process in its current state. For example, trying to suspend a process that already completed.

Example 4

<SOAP-ENV:Fault xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
        <faultcode>SOAP-ENV:Server</faultcode>
        <faultstring>Process with Process Id "576" is in completed state therefore cannot be suspended.</faultstring>
</SOAP-ENV:Fault>