Use Data Hub from workflows

The six Data Hub activities, what they need and a first workflow that writes and reads records.

Beta

Data Hub is in Beta. It is off by default; an administrator turns it on per tenant.

Studio workflows use six activities in the Orchestrator activities pack, VeloPhex.Orchestrator.Activities, from version 0.7.1-rc.11. They are under the toolbox category Data Hub. Every new project already has the pack, so updating it is enough. See Manage packages.

Each activity below links to its reference page. The pack itself is described in Orchestrator activities.

The activities#

Activity What it does
Create Entity Record Creates a record. Set Idempotency Key when a retried job must not create a second one.
Create or Update Entity Record Creates a record, or updates the one whose Key Field has the same value. The key field must be unique (dh_key_field_not_unique).
Get Entity Record Reads one record by id.
Query Entity Records Reads the records that match Match and Filter, sorted by Sort.
Update Entity Record Changes the fields you send.
Delete Entity Record Deletes a record, if the entity allows automations to delete records.

Each activity names the Entity by its API name.

Outputs#

  • Record is a flat dictionary of the field values plus the system keys (id, revision, createdAt and the others).
  • Get, Create and Create or Update also give Revision. Create or Update gives Created.
  • Query gives Records, Data Table (typed columns in schema order), Count (the records returned) and Next Cursor (empty after the last page).

A literal Filter, Sort or Fields value is checked when the workflow compiles.

Filter and sort#

Match is a dictionary of equalities. Filter is the JSON filter from the web app's Copy filter as JSON. When you set both, they are combined with AND. Sort is one string, such as amount desc, invoiceNumber. See Records, import and export.

A first workflow#

You need the Invoice entity from the overview, Studio signed in to the Orchestrator with a workspace set, and the pack at 0.7.1-rc.11 or later.

  1. Create a project from Blank Automation.
  2. Add Create or Update Entity Record. Set Entity to Invoice, Key Field to invoiceNumber, and Values:
C#Visual BasicC#Copy
new Dictionary<string, object?> { ["invoiceNumber"] = "INV-1001", ["amount"] = 1250.00m, ["status"] = "open" }
TextCopy
New Dictionary(Of String, Object) From {{"invoiceNumber", "INV-1001"}, {"amount", 1250.00D}, {"status", "open"}}

Bind its Created output to a bool variable. 3. Add Query Entity Records. Set Entity to Invoice, Match to new Dictionary<string, object?> { ["status"] = "open" } (Visual Basic: New Dictionary(Of String, Object) From {{"status", "open"}}), Sort to amount desc and turn on Fetch All. Bind Count. 4. Press F5. This is a design-time run: it needs no publish and no Robot, and it acts as you. 5. In the web app, open Data Hub ▸ Entities ▸ Invoice ▸ Records. INV-1001 is there.

A design-time run needs jobs.create and processes.view in the workspace, and design-time runs turned on under Settings ▸ Security. See Run and debug workflows.

Errors#

The activities fault with the same dh_* code the API returns, so a Try Catch can branch on it. See API.

If the Orchestrator does not offer Data Hub, the activities fault with data_hub_unavailable.

Who the activities act as#

A job on a Robot acts with the Robot's run permissions. A design-time run acts as the user who started it.

The activities

Outputs

Filter and sort

A first workflow

Errors

Who the activities act as