All of them execute a service on the server; they differ in who triggers them, what data they see, and how errors come back.
| Mechanism | Triggered by | Data | Use for |
|---|
| Service flow in the CSHS flow (coach → boundary event → service step) | leaving the coach (button) | full access to tw.local, mapped in/out | work that happens between screens: validation before submit, saving, decisions |
| Stay on page service (same, the boundary event's "stay on page" option) | a button / boundary event while the coach stays | tw.local mapped in/out; the coach is refreshed with the outputs | lookups that update the page (get customer details after entering an id) when no custom JS is wanted |
| Service Call control (UI Toolkit) | JavaScript: ${Svc}.execute(input), or auto-run on load | only the input object you pass; result in the control's result binding / event | data-driven UI logic: typeahead, paging, cascading selects, background refresh |
| Ajax service on a control (Single Select / Table options, "service" data source) | the control itself | the control's input mapping; returns option lists | option lists and lookups tied to one control |
// Service Call control "GetCustomer" bound to the service flow "Get customer" (input id String; output customer Customer)
// button "Lookup" - On click:
${GetCustomer}.execute({ id: ${CustomerId}.getData() });
// GetCustomer > On result (result):
${Customer}.setData(result.customer); ${Status}.setText("");
// GetCustomer > On error (error):
${Status}.setText("Lookup failed: " + (error && error.errorMessage ? error.errorMessage : "unknown"));
// Stay on page (no JS): Lookup button -> boundary event (stay on page) -> [Get customer] (tw.local.customerId in, tw.local.customer out) -> back to the coachGuidance: keep business steps in the CSHS flow (they are visible in the diagram and tested with the flow); use Stay on page for simple lookups without scripting; use the Service Call control for interactive, event-driven UI logic (it can be called many times, with partial data, without touching tw.local); use control Ajax services only for option lists. Whatever is chosen, services called from coaches must be exposed to the coach's users (the service flow must be in the same app / toolkit and marked callable from the client - the designer enforces this) and must be fast: they hold the browser request open, so keep them under a second and paginate large results (question on large lists). Heritage human services had the same choices with heritage Ajax services; in CP4BA only the CSHS forms exist.
References