Core concepts

The objects you work with in VeloPhex and how they relate to each other.

This page explains the objects you meet in every part of VeloPhex. The Glossary has short definitions of every term.

Tenant#

A tenant is the organization boundary in an Orchestrator. Users, roles, machines, Robots, packages and credential stores belong to one tenant. Every tenant has its own package feed, its own encryption key for secrets and its own settings. A platform administrator creates tenants from Platform admin (/admin).

Workspace#

A workspace is the unit of access inside a tenant. Processes, jobs, queues, triggers and assets live in a workspace, and roles can be granted per workspace. Use workspaces to separate teams, business units or environments (for example Finance and HR, or Test and Production).

A machine is assigned the workspaces whose jobs it may run. A Robot never picks up work from a workspace its machine is not assigned to.

Project#

A project is what you build in Studio or with the Python SDK. Its root holds project.json, which declares:

  • the project's identity (name, version, description),
  • its outputType (process for something you run, library for reusable workflows that other projects install and use as activities, tests for test projects),
  • its runtime (velophex-workflow or python),
  • its entry points, each with a JSON Schema for inputs and outputs,
  • its activity package dependencies, and the published automations it invokes (automationDependencies).

Workflow projects lock their package closure in project.lock.json. Python projects lock their environment in uv.lock.

Package#

A package is a published version of a project: a .nupkg file that contains the project content and a manifest (velophex/package-manifest.json) listing the SHA-512 of every file. A package can carry a detached signature. Package versions follow SemVer and cannot be overwritten: to change an automation, publish a new version.

Activity packages are a different kind of package: they ship the activities a workflow uses. See Activities overview.

Process#

A process is a package configured to run in a workspace. It uses a package version (a pinned one, or always the latest) and an entry point, and it holds a retry policy and an optional time limit. A library package cannot become a process. In the Orchestrator you find processes under Automations > Processes. The API calls them automations.

Entry point#

An entry point is a workflow (or a Python function) that a job can start. Its input and output JSON Schemas come from the workflow's arguments or the function's type hints. The Orchestrator validates job inputs against the input schema and generates the start form from it.

Job and attempt#

A job is a request to run a process with specific inputs. An attempt is one execution of that job on one Robot. A job that fails with a technical error can be retried by its retry policy, which creates a new attempt. Each attempt holds a lease that the Robot renews while it runs. If the Robot stops renewing, the Orchestrator recovers the job.

Jobs have a status: Pending, Running, CancelRequested, Succeeded, Failed, Canceled or DeadLettered.

An attempt that ends after the automation may have started but before it reported a result (for example, the Robot lost its lease) fails as an unknown outcome (VXR-OUTCOME-UNKNOWN). It is never retried automatically, because the automation may already have changed other systems.

Business and application errors#

VeloPhex separates two kinds of failure:

  • A business error means the work cannot be done by the rules (an invoice is rejected). It is final and never retried.
  • An application error is technical (a timeout, an unavailable system). It can be retried.

The same distinction applies to jobs and to queue items.

Queue and queue item#

A queue holds units of work, called queue items, that Robots process one at a time. An item has a payload, an optional reference, a priority, an optional deadline and a status (New, InProgress, Successful, Failed, Abandoned, Retried, Deleted). A queue can define an SLA and a risk SLA in minutes and a maximum number of retries. See Queues and SLAs.

Trigger#

A trigger starts jobs automatically:

  • A time trigger fires on a cron schedule in a time zone you choose.
  • A queue trigger starts jobs when items are waiting in a queue, scaling the number of jobs with the backlog up to a limit.

Machine and Robot#

A machine is a Windows host enrolled in the tenant. It has its own identity: a key pair generated on the host, whose private key never leaves it. A machine defines how many jobs may run on it at once and which workspaces it serves. An administrator adds a machine and enrols it with a single-use machine key. A person signed in to the Assistant can also connect a machine as their own personal machine, which runs only the automations that person starts.

The Robot is the software on that machine that runs jobs. It reports which runtimes it has, and the Orchestrator offers it only jobs it can run.

Attended use means a person starts automations on their own desktop through the Assistant; the job runs as that person. Unattended use means the Orchestrator starts jobs on the machine with no one present; each job runs as a robot account, a Windows user assigned to the job's workspace.

Asset, credential and credential store#

  • An asset is a named value stored in a workspace: text, integer, Boolean, secret, or credential (user name and password).
  • A credential store is the vault that holds secret values. Every tenant has a built-in store named "Orchestrator".
  • A credential lease is how a Robot gets a secret: it redeems a one-time, purpose-bound lease seconds before the job starts. The password never travels inside the job claim and is never written to disk or logs.

Runtime#

A runtime is what executes a package: the VeloPhex workflow runtime or the Python runtime. A package has exactly one runtime, and a workflow can call automations of the other runtime.

Next steps#

Tenant

Workspace

Project

Package

Process

Entry point

Job and attempt

Business and application errors

Queue and queue item

Trigger

Machine and Robot

Asset, credential and credential store

Runtime

Next steps