Home/Field Guide/Platform foundations
CONCEPT 03
Choose an extension point
Decide between configuration, Objects, fragments, client extensions, public APIs, and OSGi.
Start with the behavior
Turn “we need a custom app” into requirements. What is the authoritative data model? Who updates it? Where does the UI run? Does the requirement need a synchronous portal transaction, or can an external system react asynchronously? Which hosting model must support the result? Different parts of an app can use different extension points.
| Requirement | Starting point | Verify |
|---|---|---|
| Reusable, editable page section | Fragment, style book, or display page template | Editor and locale behavior |
| Structured business records | Object, form fragments, workflow | Scope, relationships, permissions, and limits |
| Interactive app on a page | Custom-element client extension | Lifecycle, accessibility, and browser authentication |
| ERP or CRM integration | Public APIs plus an external service | OAuth scopes, retries, and data ownership |
| A supported in-process Java hook | OSGi module | Hosting, package exports, and upgrade exposure |
Worked architecture
A Partner Hub request needs structured fields, review, an interactive status view, and fulfillment in an ERP. An Object can own the record. A workflow can handle approval. A custom element can present requests. An external service can handle fulfillment using supported APIs and a stable correlation key. Keep permission checks at the API or service boundary and decide how ERP failures become visible to reviewers.
When Java belongs inside the portal
A module is a candidate when an explicitly supported SPI requires in-process execution, when domain persistence or transactions exceed Objects capabilities, or when you are maintaining existing Java extensions. Confirm the hook is published and stable enough for the upgrade policy. Capture an architecture decision with the chosen API or SPI, deployment model, owners, and a regression test.
A decision you can rehearse
Take an existing MVC portlet and list its responsibilities. If the custom persistence can become an Object and the interface uses CRUD and workflow, prototype that slice against the generated API. If a retained operation relies on an atomic server-side transaction, isolate it and test that transaction separately.