SOAP API Workflow Service

Last Updated: 22 May 2017

The SOAP API Workflow Service setup
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 Workflow Service available on the SOAP Server
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:

  1. Details Screen
  2. Operations

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 on the SOAP API Workflow Service
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 OccursMax OccursType
StartWorkflowSoapInput
StartWorkflow
AssetID [string]11simple
StartWorkflowSoapOutput
StartWorkflowResponse
StartWorkflowResult [boolean]01simple

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 OccursMax OccursType
SafeEditAssetSoapInput
SafeEditAsset
AssetID [string]11simple
SafeEditAssetSoapOutput
SafeEditAssetResponse
SafeEditAssetResult [boolean]01simple

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 OccursMax OccursType
CancelWorkflowSoapInput
CancelWorkflow
AssetID [string]11simple
CancelWorkflowSoapOutput
CancelWorkflowResponse
CancelWorkflowResult [boolean]01simple

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 OccursMax OccursType
CompleteWorkflowSoapInput
CompleteWorkflow
AssetID [string]11simple
CompleteWorkflowSoapOutput
CompleteWorkflowResponse
CompleteWorkflowResult [boolean]01simple

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 OccursMax OccursType
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]01simple

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 OccursMax OccursType
ApproveAssetInWorkflowSoapInput
ApproveAssetInWorkflow
AssetID [string]
WorkflowMessage [string]
1
0
1
1
simple
simple
ApproveAssetInWorkflowSoapOutput
ApproveAssetInWorkflowResponse
ApproveAssetInWorkflowResult [string]01simple

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>

Previous Chapter Next Chapter

The Latest

Let Us Know What You Think

Let us know if you spot any errors or if you have any ideas on how we can improve the Matrix Community Website.

Contact Squiz for Demo

Let us show you the true power of Squiz Matrix by giving you a personalised demonstration.