5.8.3. Retrieve

The operation retrieve in case of a task will fetch task details which can contain information added by the third party, for instance status or planned time or date of execution.

The entityType valuation is always used in case of operation retrieve.

The data is selected by providing the {taskId} as a path parameter of the endpoint.

How to use variants

The retrieve operation is a webservice call without a body. For more information see the Retrieve operations section of the Design principles paragraph.

The output of the retrieve operation uses the taskStructure as described in the taskStructure section.

If a negative response is generated, that means the request is technically incorrect, it follows the general rules as described in the Error section of the HTTP status codes and error handling chapter.

Variants

The variant enables a differentiation in requirements to suit the specific situations (listed below), and for each variant, to which AFD structure it applies.

<default> – Obtain full details of a single task based on the unique reference

The variant default retrieves full details of a task based on a unique reference, using the taskStructure. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.

Endpoint definition

Method	Endpoint	Request	Query parameter(s)	Response	Remarks
GET	{ uri } /tasks/{taskId}/retrieve	taskStructure		taskStructure

Mandatory input and/or output (I/O) attributes

Entity	Attribute	I/O	Remarks
commonFunctional	dataCatalogVersion	O	Version of the data catalog on which the message is based.
commonFunctional	functionVariant	O	The function variant is used to determine the additional set of required and optional input and output data.
commonFunctional	afdDefinitionName	O	Name of the AFD-definition.
commonFunctional	afdDefinitionVersion	O	Version of the AFD-definition.
task	refkey	O	Unique reference key assigned to an entity.

Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.

status – Obtain status information of a task by a unique reference

The variant status retrieves all information about the status of a task by a unique reference, using the taskStructure. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.

Endpoint definition

Method	Endpoint	Request	Query parameter(s)	Response	Remarks
GET	{ uri } /tasks/{taskId}/status	taskStructure	N/A	taskStructure

Mandatory input and/or output (I/O) attributes

Entity	Attribute	I/O	Remarks
commonFunctional	dataCatalogVersion	O	Version of the data catalog on which the message is based.
commonFunctional	functionVariant	O	The function variant is used to determine the additional set of required and optional input and output data.
commonFunctional	afdDefinitionName	O	Name of the AFD-definition.
commonFunctional	afdDefinitionVersion	O	Version of the AFD-definition.
task	refkey	O	Unique reference key assigned to an entity.
task	statusType	O	Status code.

Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.