Data models

Service metadata

Service metadata is used to describe the interface of a processing service so it can be executed by Steep.

PropertyTypeDescription
id
(required)		stringA unique service identifier
name
(required)		stringA human-readable name
description
(required)		stringA human-readable description
path
(required)		stringRelative path to the service executable in the service artefact (or a Docker image if runtime equals docker)
runtime
(required)		stringThe runtime environment
parameters
(required)		arrayA list of service parameters
runtimeArgs
(optional)		arrayAn optional list of arguments to pass to the runtime
requiredCapabilities
(optional)		arrayA set of strings specifying capabilities a host system must provide to be able to execute this service. See also setups.
retries
(optional)		objectAn optional retry policy specifying how often the execution of this service should be retried in case of an error. Can be overridden in an executable action.
maxInactivity
(optional)		duration or objectAn optional duration or timeout policy that defines how long the execution of this service can take without producing any output (i.e. without writing anything to the standard output and error streams) before it is automatically cancelled or aborted. Can be overridden in an executable action and can be combined with maxRuntime and deadline (see below). Note that a service cancelled due to inactivity is still subject to any configured retry policy, which means its execution may be retried even if one attempt timed out. If you want to cancel a long-running service immediately even if there is a retry policy configured, use a deadline.
maxRuntime
(optional)		duration or objectAn optional duration or timeout policy that defines how long the execution of this service can take before it is automatically cancelled or aborted, even if the service regularly writes to the standard output and error streams. Can be overridden in an executable action and can be combined with maxInactivity (see above) and deadline (see below). Note that a service cancelled due to a too long runtime is still subject to any configured retry policy, which means its execution may be retried even if one attempt timed out. If you want to cancel a long-running service immediately even if there is a retry policy configured, use a deadline.
deadline
(optional)		duration or objectAn optional duration or timeout policy that defines how long the execution of this service can take at all (including all retries and their associated delays) until it is cancelled or aborted. Can be overridden in an executable action and can be combined with maxInactivity and maxRuntime (see above).
Example
​
id: cp
name: cp
description: Copies files
path: cp
runtime: other
parameters:
  - id: no_overwrite
    name: No overwrite
    description: Do not overwrite existing file
    type: input
    cardinality: 1..1
    label: '-n'
    dataType: boolean
    default: false
  - id: input_file
    name: Input file name
    description: Input file name
    type: input
    cardinality: 1..1
    dataType: file
  - id: output_file
    name: Output file name
    description: Output file name
    type: output
    cardinality: 1..1
    dataType: file

Runtime environments

Steep provides a set of default runtime environments that define how processing services are executed. More environments can be added through runtime environment plugins.

NameDescription
dockerThe service will be executed through Docker. The service metadata attribute path specifies the Docker image to run. The attribute runtimeArgs specifies parameters that should be forwarded to the docker run command.
otherThe service will be executed like a normal executable program (binary or shell script)

Service parameters

This data model describes the parameters that can be passed to a processing service.

PropertyTypeDescription
id
(required)		stringA unique parameter identifier
name
(required)		stringA human-readable name
description
(required)		stringA human-readable description
type
(required)		stringThe type of this parameter. Valid values: input, output
cardinality
(required)		stringA string in the form lower..upper specifying how many times the parameter must appear at least (lower limit) and how many times it can appear at most (upper limit). The character n can be used for the upper limit to specify an arbitrary number. The lower limit must not be greater that the upper limit. Examples cardinalities are listed below.
dataType
(optional)		stringThe type of the parameter value. Steep treats parameters differently depending on the data type (see description below).
default
(optional)		stringAn optional default value for this parameter that will be used if the lower limit of cardinality is 1 but no parameter value is given in the workflow.
fileSuffix
(optional)		stringAn optional suffix that should be appended to the generated filename of an output parameter. This property is typically used for file extensions (including the dot), e.g. ".xml" or ".json".
label
(optional)		stringAn optional string that will be used as a label for the parameter in the service call. Examples are -i, --input, --resolution, etc.
Example cardinalities:
  • "0..1" means the parameter is optional (it can appear 0 times or 1 time)
  • "1..1" means the parameter is mandatory (it must appear 1 time)
  • "1..n" means it must appear at least once or many times (no upper limit)
Data type:

Steep treats parameters differently depending on the type and dataType:

  • If type is "output" and dataType is "directory", Steep will create a new directory for the service’s output and recursively search it for result files after the service has been executed.

  • If type is "input" and dataType is "directory", Steep will find the common parent directory of the files from the parameter’s value and pass it to the service. For example, if the parameter’s value is an array with the elements ["/tmp/a.txt", "/tmp/b.txt", "/tmp/subdir/c.txt"], Steep will pass "/tmp/" to the service.

  • If type is "input", dataType is not "directory", but the parameter’s value is an array, Steep will duplicate the parameter as many times as there are items in the array (given that the cardinality has no upper limit).

  • If type is "input", dataType is "boolean", and the parameter has a label, Steep will pass the label to the service if the parameter’s value is true and ignore the parameter if the value is false.

  • Otherwise, this property can be an arbitrary string. New data types with special handling can be added through output adapter plugins.

Example
​
id: no_overwrite
name: No overwrite
description: Do not overwrite existing file
type: input
cardinality: 1..1
label: '-n'
dataType: boolean
default: false

Runtime arguments

Runtime arguments are similar to service parameters, except they are passed to the runtime that executes the service (e.g. Docker) instead of the service itself.

PropertyTypeDescription
id
(required)		stringA unique argument identifier
name
(required)		stringA human-readable name
description
(required)		stringA human-readable description
dataType
(optional)		stringThe type of the parameter value. Typically "string" or "boolean". The same rules apply as for service parameters.
label
(optional)		stringAn optional string that will be used as a label for the parameter. Examples are -v, --volume, --entrypoint, etc.
value
(optional)		stringAn optional value for this parameter.
Example
​
id: volume
name: Volume mount
description: Mount data directory
label: '-v'
value: /data:/data
Submissions
Macros