Developer documentation

SOAP interface

Main entry point

The main entry point is:

class vmw.vco.client.Client

Implementation of a vCO webservice client. API Calls implemented:

• echo
• echoWorkflow
• answerWorkflowInput
• cancelWorkflow
• executeWorkflow
• find
• findForId
• findRelation
• hasChildrenInRelation
• getAllPlugins
• getAllWorkflows
• getWorkflowForId
• getWorkflowsWithName
• getWorkflowTokenForId
• getWorkflowTokenResult
• getWorkflowTokenStatus
• simpleExecuteWorkflow
• hasRights
• sendCustomEvent

__init__(self, url, username, password, async=False, **kw)

Build a client for target vCO server.

Parameters:

• url (string) – full URL for the target vCO SOAP service
• username (string) – user name
• password (string) – password for the user
• async (bool) – whether to use asynchronous bindings
• kw (dict) – keyword arguments passed to underlying Binding object

answerWorkflowInput(token, inputs={})

Provide answer for the user interaction the token is waiting on.

Parameters:

• token (vmw.vco.client.WorkflowToken) – workflow token to answer to
• inputs (dict) – input parameters to provide as an answer

cancelWorkflow(token)

Cancel specified workflow token.

Parameters:

• token (vmw.vco.client.WorkflowToken) – Token to cancel

echo(msg)

Test method. Echo back provided message.

Parameters:

• msg (string) – Message to echo.

echoWorkflow(wf)

Test method. Echo back provided workflow.

Parameters:

• wf (vmw.vco.client.Workflow) – Workflow to echo.

executeWorkflow(wf, inputs={})

Run a workflow with specified set of inputs.

Parameters:

• wf (vmw.vco.client.Workflow) – workflow to run
• inputs (dict) – inputs to run with

find(type, query='')

Find objects of a given type, that match a plug-in dependant query.

findForId(type, id)

Find specific object, from it’s type and unique id.

findRelation(type, id, relation)

Find children of specific object (defined by its type and unique id), according to specified relation.

getAllPlugins()

Retrieve all plugins installed in the server.

Return type:list of vmw.vco.client.Plugin

getAllWorkflows()

Retrieve all workflows installed in the server.

Return type:list of vmw.vco.client.Workflow

getWorkflowForId(id)

Retrieve workflow with specified id.

Parameters:

• id (string) – Workflow id

getWorkflowTokenForId(token_id)

Retrieve a workflow token from its id.

Parameters:

• token_id (string) – token id

getWorkflowTokenResult(token)

Get result for workflow token. Only applies when the workflow execution is completed.

Parameters:

• token (vmw.vco.client.WorkflowToken) – token to extract result from

getWorkflowTokenStatus(tokens)

Get status for specified list of workflow tokens. Returns a list of status in the same order.

getWorkflowsWithName(name)

Retrieve all workflows with specified name (might be in different categories).

Parameters:

• name (string) – Workflow name

hasChildrenInRelation(type, id, relation)

Check if specified object (defined by its type and unique id) has any children according to specified relation.

hasRights(task, right)

Check if current user has rights over the specified task.

sendCustomEvent(event, props)

Send a custom event with specified properties.

Parameters:

• event (string) – event to send
• props (dict) – properties of the event

simpleExecuteWorkflow(wf, encoded_input)

deprecated

Alternate way of executing a workflow. This will encode inputs in an unsafe way, please don’t use.

Parameters:

• wf (vmw.vco.client.Workflow) – workflow to run
• inputs (dict) – inputs to run with

Helper objects

A collection of helpers is also provided, that make use of the API more object-oriented:

class vmw.vco.client.Plugin

description

Plugin description

name

Plugin name

version

Plugin version

class vmw.vco.client.Workflow

attributes

Workflow attributes. list of vmw.vco.client.WorkflowAttribute

description

Workflow description

execute(inputs={})

Execute this workflow with provided input parameters.

Parameters:

• inputs (dict) – input parameters

id

Workflow id

inParameters

Workflow input parameters. list of vmw.vco.client.WorkflowAttribute

name

Workflow name

outParameters

Workflow output parameters. list of vmw.vco.client.WorkflowAttribute

class vmw.vco.client.WorkflowAttribute

name

Attribute name

type

Attribute type

class vmw.vco.client.WorkflowToken

globalState

WorkflowToken state

id

WorkflowToken id

title

WorkflowToken title

workflowId

Related Workflow id

class vmw.vco.client.FinderResult

id

FinderResult id

properties

FinderResult properties (dict)

uri

FinderResult uri

Using objects

A surprisingly challenging part in using vCO SOAP API is to provide workflows with proper input parameters. For that it’s necessary to generate valid representations of all types that can be used as input. For immediate values, it’s rather easy (and worst case, vmw.vco.client.TypedValue can be used to wrap anything).

class vmw.vco.client.TypedValue

__init__(self, type, value)

Build a typed value

Parameters:

• type – type of the value
• value – string representation of the value

For objects, it’s more complicated, as they can come from different places (workflow output, finder result, other component that’s specific to your application’s logic).

The rule in vmw.vco is that a valid input is something that implements the interface vmw.vco.interfaces.ITypedValue. This include of course vmw.vco.components.TypedValue, but also everything that has an adapter registered for that interface.

In particular, the adapters from vmw.vco.adapters are loaded by default.

class vmw.vco.adapters.BoolValue(original)

Adapter from bool to ITypedValue.

class vmw.vco.adapters.IntValue(original)

Adapter from int to ITypedValue.

class vmw.vco.adapters.StringValue(original)

Adapter from string to ITypedValue.

vmw.vco.adapters.adapter(ifrom, ito)

Decorator to help registering a new adapter.

Parameters:

• ifrom – interface or class to adapt
• ito – interface to expose

So, if you have some custom objects that could be transformed into an input value, just register an adapter for it, and pass it !