Summary of Simple Object Access Protocol (SOAP) Operations - EcoSys - Customization & Programming - Hexagon PPM

EcoSys Web Service API Usage Documentation

Language
English
Product
EcoSys
Search by Category
Customization & Programming
EcoSys Version
9.0

The following tables provide a high-level summary of the typical operations, messages, and types involved in an EcoSys published API for SOAP. This is a simplified view, intended to provide an overview. Refer to the generated WSDL for the full interface specification. In these examples, the API names are "SampleObject" and "SampleEvent".

Object Read SOAP Operations and Messages

ReadSampleObject

▶ in

◇ SampleObjectReadRequest

SampleObjectOptions

SampleObjectParameters


← credentials & logging options, if desired
← runtime parameters, if any

◀ out

◇ SampleObjectReadResponse

Meta

SampleObject [0..*]

Performance


← meta data, if requested
← list of resulting objects defined by the API
← performance data, if requested

Object Write (Create/Update/Delete) SOAP Operations and Messages

UpdateSampleObject

▶ in

◇ SampleObjectUpdateRequest

SampleObjectOptions

SampleObjectParameters

SampleObject [1..*]


← credentials & logging options, if desired
← runtime parameters, if any
← list of objects to update

◀ out

◇ SampleObjectUpdateResponse

Meta

ObjectResult [1..*]

ResultMessage [0..*]

Performance


← meta data, if requested
← list of per-record result status (success/fail)
← list of warning/error code and message(s)
← performance data, if requested

CreateSampleObject

▶ in

◇ SampleObjectCreateRequest

SampleObjectOptions

SampleObjectParameters

SampleObject [1..*]


← credentials & logging options, if desired
← runtime parameters, if any
← list of objects to create

◀ out

◇ SampleObjectCreateResponse

Meta

ObjectResult [1..*]

ResultMessage [0..*]

Performance


← meta data, if requested
← list of per-record result status (success/fail)
← list of warning/error code and message(s)
← performance data, if requested

CreateOrUpdateSampleObject

▶ in

◇ SampleObjectCreateOrUpdateRequest

SampleObjectOptions

SampleObjectParameters

SampleObject [1..*]


← credentials & logging options, if desired
← runtime parameters, if any
← list of objects to create or update, if found

◀ out

◇ SampleObjectCreateOrUpdateResponse

Meta

ObjectResult [1..*]

ResultMessage [0..*]

Performance


← meta data, if requested
← list of per-record result status (success/fail)
← list of warning/error code and message(s)
← performance data, if requested

DeleteSampleObject

▶ in

◇ SampleObjectDeleteRequest

SampleObjectOptions

SampleObjectParameters

SampleObjectKey [1..*]


← credentials & logging options, if desired
← runtime parameters, if any
← list of key values of objects to delete

◀ out

◇ SampleObjectDeleteResponse

Meta

ObjectResult [1..*]

ResultMessage [0..*]

Performance


← meta data, if requested
← list of per-record result status (success/fail)
← list of warning/error code and message(s)
← performance data, if requested

Event Trigger SOAP Operations and Messages

TriggerSampleEvent

▶ in

◇ SampleEventTriggerRequest

SampleEventOptions

SampleEventParameters


← credentials & logging options, if desired
← runtime parameters, if any

◀ out

◇ SampleEventTriggerResponse

Performance


← performance data, if requested, otherwise empty mesg

Request Options

The <...Options> element within any SOAP request contains optional elements, but is typically included to at least provide the username and password credentials for the call.

Request Parameters

The <...Parameters> element within any SOAP request contains the values of the runtime parameters to be used for defined runtime parameters. Refer to the specific API's definition page for the list of defined runtime parameters, if any, and their respective types and values.

The <...Parameters> element is optional for any SOAP request, unless one or more required runtime parameters are defined for the given API.

SOAP Faults

Each SOAP call may optionally return a SOAP fault element. The element names are, for example, <SampleObjectFault> or <SampleEventFault>.

In practice, SOAP faults are not part of normal business processes since the success/failure status of individual records are returned in response objects' <ObjectResult> structures and do not generate fault messages.

SOAP faults typically only occur when a very low-level error is encountered, such as: authentication failures, API definition validation failures, or system exceptions (not business rule-related).

SOAP faults have the following components:

Element Name

Type & Values

Description

Fault

string

A short name or phrase identifying the fault reason

Description

string

A descriptive text providing more information or detail on the cause of the fault

Stack Trace

(optional)

The Java stack trace of the original cause of fault, if available.