How do I convert a heritage human service with heritage coaches to a client-side human service step by step?

Question

We have dozens of heritage human services (server-side flow with heritage coaches from the BPM 7.5 / 8.0 era). BAW marks them deprecated and CP4BA does not run them. What is a repeatable procedure to convert one, and which parts convert automatically?

Answer 1

A repeatable procedure that teams use for the conversion (about half a day per simple service, more for complex coaches):

1. Inventory the service: list its coaches (heritage vs coach-view based), server scripts, nested services, integration steps, and the variables it exposes. The validation report and the twx (question on twx structure) give this quickly.
2. Use the converter where it applies: the Convert to client-side human service action exists for heritage human services whose coaches already use coach views (8.5+ style coaches); it copies the flow, turns server scripts into client-side scripts where they only touch tw.local, and moves everything else into generated service flows. Heritage coaches (7.5-style, Coach Designer) are not converted - they appear as placeholders.
3. Rebuild heritage coaches as coaches: one CSHS coach per heritage coach; map controls (Text → Text, Select → Single Select, Checkbox → Checkbox, Table → Table, Button → Button with boundary event, custom HTML blocks → custom coach views or Output Text with HTML). Bind to the same variables so the flow logic stays.
4. Move server logic to service flows: every server script that used tw.system, Java, SQL, REST becomes a service flow called between coaches (Stay on page when the user must remain on the coach); pure data shuffling becomes a client-side script.
5. Replace server-side validation with the CSHS validation script (tw.system.coachValidation still works there) or control-level validation (question on validation frameworks).
6. Re-wire exposure: the BPD activity's implementation points to the new CSHS; dashboards / startable services exposed to the same teams; URLs of startable heritage services change (new service id) - update links.
7. Test with the same data as the old service (playback on a test server, side by side), then retire the heritage service (keep it until instances that hold its open tasks are finished - open tasks keep running the old implementation).

// heritage server script (ran on the server between coaches)          // CSHS equivalent
var u = tw.system.org.findUserByName(tw.system.user.name);              // -> service flow "Get user info" (server) called before the coach
tw.local.email = u.attributes.get("Email Address");                     //    output mapped to tw.local.email
if (tw.local.amount > 10000) tw.local.route = "MANAGER";                // -> client-side script (no server needed)

Pitfalls: heritage coaches used tw.local in Custom HTML with server-side templating (<#= tw.local.x #>) - these become bindings; this.context semantics differ; server-side log.info has no browser equivalent (use console.log or a logging service); and the CSHS runs as the user in the browser, so anything that relied on server-side privileges must stay in a service flow.

References

• BAW documentation - converting heritage human services to client-side human services
• BPM UI Toolkit