Services
A service composes several steps into one call: read a row, check it, call an endpoint, branch on the answer, write, answer. It is built by drawing — no code — and used two ways: a screen calls it from a button, or it is exposed as an API endpoint that a job, the assistant or an outside system calls like any other.
Access: Liberty Next → Logic → Services, for superusers. A service is the shared action a screen calls with call_action; see Actions and lifecycle for the actions of a screen.
At a glance
The list
Each line gives the service, its number of steps and inputs, and the endpoints it already serves (POST /api/http/<connector>/<endpoint>). New service adds one. On a line: Run, Expose, Find usages, Find dependencies, Rename, Clone, Delete. A click opens its designer.
The flow
The designer opens on the Flow view; List gives the steps as a list.
The flow reads left to right: Start, which shows the inputs; one card per step; Answer, which shows what the service returns. A condition forks into its True and False lanes; a loop or a group frames its own steps. The layout follows the structure of the service: nothing is placed by hand. A long flow continues on the next row, and the zoom (− / % / +) is kept on the device.
- A click on a card edits that step in the side panel: its target, its input mapping.
- The + on a link adds a step at that place.
- With nothing picked, the panel edits The service: Label, Description, Inputs (Add input).
| Step | Does |
|---|---|
| Query | Runs a query of a connector. |
| Endpoint | Calls an API endpoint. When the endpoint says where its rows are, the next steps read them by column name: <step>.first_row.<COLUMN>, <step>.rows. |
| Function | Calls a function of an application's plugin. |
| Service | Calls another service. |
| Condition | Forks on a test. |
| For each | Repeats its steps for each row. |
| Message, Notification | Tells the user, or sends a notification. |
| Answer | Says what the service returns. |
A step reads the service's inputs as INPUT.<name> and the result of an earlier step by that step's name.
Run
Run tries the service as it is saved: one field per input (its default as a placeholder), then the result — Done in N ms, the Answer it would give as an endpoint, and the Steps that ran.
A step that writes, writes. Run a service that changes data on a test environment, or with inputs made for it.
Expose as an endpoint
Expose creates an API endpoint served by the service. A screen, an action, a job, the assistant or an outside caller then calls it like any endpoint.
| Field | Meaning |
|---|---|
| On the connector | An API connector of the installation, or the Studio's own — studio, created on first use. |
| Endpoint name | The service's identifier by default. |
| It changes data | Tick it when a step writes: the assistant then asks before calling it. |
The service's inputs become the endpoint's parameters. The dialog answers with the address and the permission: Exposed: POST … — permission api:<connector>:<endpoint>.
The service runs with the endpoint's permission: who may call the endpoint runs all its steps, which are not checked again one by one — a composed service is granted as a whole. The caller's row-level data scope still applies to every query. What the service returns is the answer; its messages come with it; a step that fails is the endpoint's error.
Where a service is used
Find usages lists the screens that call the service and the endpoints it serves; renaming it follows them. In the Studio, a selected service lights the screens that call it. A service is carried in a package with the screens and endpoints that need it.
Tips & best practices
- Give each step a name that says what it holds (
customer,open_orders): the next steps read it by that name. - Put the checks first and the writes last: a condition that stops early leaves nothing half done.
- Expose a service when the same sequence is needed by a screen and by a job or an outside system: one definition, one permission.
- Cover an exposed service with a test case.
Related
- Overview and Studio · API endpoints · Tests
- Actions and lifecycle — the actions of a screen.