SOAP API Workflow Service
Last Updated: 22 May 2017
The SOAP setup
The SOAP API Workflow Service asset manages the Workflow functions of the SOAP Server including approving an asset in workflow and starting workflow.
To add a SOAP API Workflow Service, go to Web Services -> SOAP API Workflow Service. For the API to work, it must be created under a SOAP Server within the Web Services folder, as shown in the figure to the right. The API will then be available to enable on the Details screen of the SOAP Server, as shown in the figure below.
The SOAP API Permission And Role Service available on the SOAP Server
You can configure the settings of the SOAP API Metadata Service on its associated asset screens. The majority of these screens are the same or similar to those for a Standard Page and are described in the Asset Screens manual. In this chapter we will describe the Details screen, which is different for a SOAP API Search Service.
Bookmarks to the headings on this page:
Details Screen
The Details screen allows you to configure the interface functions for the SOAP API Permission and Role Service. For more information about the Status, Future Status, Thumbnail and Details sections,refer to the Details Screen chapter in the Asset Screens manual.
Interface Settings
This section allows you to control which functions the SOAP API Workflow Service will be able to provide when enabled on a SOAP Server. The Interface Settings section of the Details screen is shown in the figure below.
The Interface Settings section of the Details screen
In the Function List, select Enabled for the functions you want to make available on the API. For a full explanation of these functions, see the Operations section below.
Operations
The operations that are managed by the SOAP API Workflow Service are as follows:
See the sections below for more information on each of the operations available on this API.
StartWorkflow
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type | |
|---|---|---|---|---|
| StartWorkflowSoapInput StartWorkflow | AssetID [string] | 1 | 1 | simple |
| StartWorkflowSoapOutput StartWorkflowResponse | StartWorkflowResult [boolean] | 0 | 1 | simple |
TheStartWorkflow operation will begin workflow for a specified asset by changing its status, for example: from Under Construction to Pending Approval. The parameters available for this operation are as follows:
- AssetID: the asset ID of the asset to begin workflow on. This parameter is mandatory.
Example Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:StartWorkflow>
<AssetID>100</AssetID>
</ns1:StartWorkflow>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:StartWorkflowResponse>
<StartWorkflowResult>true</StartWorkflowResult>
</ns1:StartWorkflowResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SafeEditAsset
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type | |
|---|---|---|---|---|
| SafeEditAssetSoapInput SafeEditAsset | AssetID [string] | 1 | 1 | simple |
| SafeEditAssetSoapOutput SafeEditAssetResponse | SafeEditAssetResult [boolean] | 0 | 1 | simple |
The SafeEditAsset operation will change a specified asset's status from Live to Safe Edit. The parameters available for this operation are as follows:
- AssetID: the asset ID of the asset whose status will be changed to Safe Edit. Please note that this asset must have Live status for this operation to work. This parameter is mandatory.
Example Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SafeEditAsset>
<AssetID>100</AssetID>
</ns1:SafeEditAsset>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SafeEditAssetResponse>
<SafeEditAssetResult>true</SafeEditAssetResult>
</ns1:SafeEditAssetResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
CancelWorkflow
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type | |
|---|---|---|---|---|
| CancelWorkflowSoapInput CancelWorkflow | AssetID [string] | 1 | 1 | simple |
| CancelWorkflowSoapOutput CancelWorkflowResponse | CancelWorkflowResult [boolean] | 0 | 1 | simple |
The CancelWorkflow operation will cancel any workflow currently running for a specified asset. The parameters available for this operation are as follows:
- AssetID: the asset ID of the asset to cancel workflow on. This parameter is mandatory.
Example Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:CancelWorkflow>
<AssetID>100</AssetID>
</ns1:CancelWorkflow>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:CancelWorkflowResponse>
<CancelWorkflowResult>true</CancelWorkflowResult>
</ns1:CancelWorkflowResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
CompleteWorkflow
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type | |
|---|---|---|---|---|
| CompleteWorkflowSoapInput CompleteWorkflow | AssetID [string] | 1 | 1 | simple |
| CompleteWorkflowSoapOutput CompleteWorkflowResponse | CompleteWorkflowResult [boolean] | 0 | 1 | simple |
The CompleteWorkflow operation will complete any workflow currently running for a specified asset, making the asset Live if it is already in Approved, Live Approved or Editing Approved status. The parameters available for this operation are as follows:
- AssetID: the asset ID of the asset to complete Workflow on. This parameter is mandatory.
Example Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:CompleteWorkflow>
<AssetID>100</AssetID>
</ns1:CompleteWorkflow>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:CompleteWorkflowResponse>
<CompleteWorkflowResult>true</CompleteWorkflowResult>
</ns1:CompleteWorkflowResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SetWorkflowSchema
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type | |
|---|---|---|---|---|
| SetWorkflowSchemaSoapInput SetWorkflowSchema | AssetID [string] SchemaID [string] Grant [Grant] AutoCascadeToNewChildren [boolean] Cascade [boolean] | 1 1 1 0 0 | 1 1 1 1 1 | simple simple simple simple simple |
| SetWorkflowSchemaSoapOutput SetWorkflowSchemaResponse | SetWorkflowSchemaResult [boolean] | 0 | 1 | simple |
The SetWorkflowSchema operation will apply, deny or revoke (delete the schema from the specified asset) a Workflow Schema on a specified asset. The parameters available for this operation are as follows:
- AssetID: the asset ID of the asset where the Workflow Schema is set. This parameter is mandatory.
- SchemaID: the asset ID of the Workflow Schema. This parameter is mandatory.
- Grant: the grant that will determine how the Workflow Schema is implemented, for example Apply. This parameter is mandatory.
- AutoCascadeToNewChildren: indicates whether the Workflow Schema will be cascaded to all future child assets. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is TRUE.
- Cascade: indicates whether the Workflow Schema will be cascaded to all current child assets. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is TRUE.
Example Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SetWorkflowSchema>
<AssetID>100</AssetID>
<SchemaID>150</SchemaID>
<Grant>Apply</Grant>
<AutoCascadeToNewChildren>FALSE</AutoCascadeToNewChildren>
<Cascade>TRUE</Cascade>
</ns1:SetWorkflowSchema>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SetWorkflowSchemaResponse>
<SetWorkflowSchemaResult>true</SetWorkflowSchemaResult>
</ns1:SetWorkflowSchemaResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
ApproveAssetInWorkflow
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type | |
|---|---|---|---|---|
| ApproveAssetInWorkflowSoapInput ApproveAssetInWorkflow | AssetID [string] WorkflowMessage [string] | 1 0 | 1 1 | simple simple |
| ApproveAssetInWorkflowSoapOutput ApproveAssetInWorkflowResponse | ApproveAssetInWorkflowResult [string] | 0 | 1 | simple |
The ApproveAssetInWorkflow operation will approve any workflow currently running for a specified asset, progressing the asset to the next workflow step. Please note that you must have user permission to approve the workflow step for this operation to work. The parameters available for this operation are as follows:
- AssetID: the asset ID of the asset where workflow will be approved. This parameter is mandatory.
- WorkflowMessage: the approval message for the approved workflow.
Example Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:ApproveAssetInWorkflow>
<AssetID>100</AssetID>
<WorkflowMessage>Approval Message</WorkflowMessage>
</ns1:ApproveAssetInWorkflow>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:ApproveAssetInWorkflowResponse>
<ApproveAssetInWorkflowResult>1</ApproveAssetInWorkflowResult>
</ns1:ApproveAssetInWorkflowResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>