Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Service Task Catalog
Choose an activity by contract and capability
A service-task catalog describes what a workflow can author. The implementation catalog and current capability/readiness describe how that activity can execute in this deployment. An external provider/connection has its own admission and credentials. Treat these as three checks, not one “the card exists” test.
For Leave requests, possible needs include checking a policy rule, creating a notification or converting an approved letter. Start with the actual current activity catalog, inspect the exact implementation and typed configuration/input/output schema, then map declared case variables through the supported designer controls. A marketplace blueprint may be useful design metadata while its provider is unavailable.
Activity selection worksheet
| Question | Record from the actual source/catalog |
|---|---|
| What is selected? | Exact activity type/version and implementation identity |
| What must be configured? | Required config fields, allowed values, defaults and expression dialect |
| What comes from the case? | Typed inputs/cardinality and authored mappings |
| What may come back? | Declared outputs, open-output behavior and business bindings |
| How does it execute? | Synchronous handler or durable async work/run and actual worker/lease contract |
| What authorizes it? | Current workspace/object/run-as/provider/disclosure policy |
| Is it ready here? | Capability/readiness and admitted connection, not a catalog count |
The detailed XML/Java reference below remains useful for extension developers. A short JSON schema sketch in a descriptor is not automatically a full standard JSON Schema or a complete runtime response. Inspect typed field definitions and their actual consumers before using a fragment as executable configuration. Existing source fixtures/examples qualify only their stated boundary; no provider, document renderer or workflow runtime was invoked for this guide.
Worked examples
Example FLOW-SC-01 — Choose actual DMS conversion instead of a similarly named blueprint
Scenario and inputs. Nadia wants a PDF of a permitted synthetic approval letter. The current catalog contains a specific service.dms.convert.docx-to-pdf activity and other broadly named document/PDF options. The source document, published workflow and conversion engine each retain their own preparation and rights.
Procedure. Find the exact activity/type and inspect its configured implementation, required documentId and optional resultVariable. Check the current capability/readiness and document engine status separately. In the owned state flow, choose the admitted conversion activity, map the allowed source using the supported governed field syntax, and declare where its result may enter the case file. Review the authored requester/run-as and resource checks before publication.
Expected result. The workflow is configured for the actual DMS conversion contract, whose result creates a new sibling PDF and preserves its source. It is not assumed equivalent to every generic catalog item with “PDF” in its name.
Failure and recovery. If the implementation or engine is unavailable, do not replace its result with a sample documentId or claim toolbox presence proves readiness. Have the authorized owner qualify the dependency; keep private renderer/source evidence and human holds separate from ordinary configuration.
Sources. ActivityCatalogController.java:53; DmsConvertDocxToPdfServiceTaskExecutor.java:38.
Example FLOW-SC-02 — Read a typed field before mapping a case value
Scenario and inputs. A consultant maps requestedDays into an admitted activity. The case declaration is Number; a record column may separately be INTEGER. A source descriptor can contain a legacy type sketch or typed field children with requiredness/cardinality/defaults. This exercise reads the existing descriptor; it does not invent a new field that the implementation cannot consume.
Procedure. Open the selected activity’s current configuration/input/output contract. For each required field, identify its actual name, supported type, SINGLE/MANY cardinality, permitted defaults and expression mode. Map the declared business value through the real designer input. Review the output field and openOutputs marker before choosing a result binding. Where a record/list structure is declared, preserve that structure rather than flattening it into a display string.
Expected result. The mapping matches the actual contract the validator and executor use. The reader can explain why five requested days is a numeric input and why a list/object requires its own declared shape. A metadata sketch is not misrepresented as a complete portable schema.
Failure and recovery. Correct a scalar/list mismatch, missing required field or undeclared result at authoring time. Do not suppress validation, assume a UI label is the wire key or add undocumented JSON properties to make a copied example appear accepted.
Sources. ServiceTaskField.java:1; XmlServiceTaskDefinitionLoader.java:225.
Example FLOW-SC-03 — Bind business results without exposing executor telemetry as case data
Scenario and inputs. The leave workflow uses an admitted calculation/rule activity before manager review. The author has declared the business target that will receive the result and knows the selected implementation’s actual output. The executor may also record metadata/logging fields, which are not necessarily case-file outputs.
Procedure. Choose the actual activity and inspect its supported rule/implementation references. Map inputs from declared case values and select an explicit legal business output binding. Compare the definition’s output contract with the runtime projection: envelope fields are retained in the run output, but only explicitly authored envelope bindings should enter business variables. Save and verify the state flow before publication.
Expected result. The workflow receives the intended business result under its declared name. Durable run telemetry can remain available for authorized inspection without silently creating arbitrary case variables. The selected rule/version or implementation remains a concrete dependency.
Failure and recovery. If a result targets an engine-owned reserved name, choose a declared business field instead. A valid output name does not waive field type, workspace, rule or disclosure admission. Do not copy a generic operationId from another activity’s sketch into every result contract or use it as universal acceptance proof.
Sources. DefaultServiceTaskExecutionService.java:64.
Example FLOW-SC-04 — Recognize a blueprint whose provider is not ready
Scenario and inputs. A marketplace card suggests a third-party spreadsheet, report or AI operation for the leave application. The descriptor exists in source, but this deployment may not have its provider implementation, connection, credentials or policy admission. The tutorial uses synthetic content and never spends a provider attempt to disguise that gap.
Procedure. Inspect the actual blueprint and its implementation reference. Read the current capability/readiness and the connection/provider prerequisites. Identify whether it is a synchronous supported executor, a durable external work contract or an extension that the operator must supply. Choose a currently admitted alternative only after checking that alternative’s own input/output, authorization and failure semantics; similar names are insufficient.
Expected result. The reader can separate “authorable declaration,” “installed/admitted implementation” and “working external dependency.” A missing provider remains a concrete prerequisite rather than becoming an apparently successful sample response.
Failure and recovery. Do not fabricate output rows/documents or reuse another connection’s credentials. If the extension is unavailable, ask the responsible owner for that exact admission/configuration and continue independent authoring that does not require it. Catalog coverage counts and old evidence do not qualify the missing provider or authorize a held runtime proof.
Sources. ActivityCatalogController.java:65; ServiceTaskImplementationController.java:41.
Detailed reference
The service task catalog lets the platform expose many workflow service tasks without hardcoding every service into the workflow engine.
Service tasks are defined as XML files under:
conf/service-tasks/
At startup, the platform loads every *.xml file in that folder. Each <serviceTask> becomes an activity handler and is exposed through the normal activity catalog API:
GET /api/activity-catalog
The seed distribution currently uses multiple catalog packs:
conf/service-tasks/platform-service-tasks.xml
conf/service-tasks/platform-enterprise-service-tasks.xml
conf/service-tasks/platform-service-task-expansion.xml
conf/service-tasks/platform-service-task-marketplace.xml
This layout is intentional. The base catalog holds core workflow services, the enterprise pack adds broad business-system coverage, and the expansion pack adds additional document, spreadsheet, calculation, integration, AI, agent, RPA, data, audit, security, notification, and workflow utility tasks. The marketplace pack adds installable service blueprints for document generation, PDF conversion, Google Sheets, Excel, AI, agents, integrations, notifications, reports, and Fabric data operations. Custom installations should add their own XML files instead of editing platform files.
Architecture
flowchart TD
A["conf/service-tasks/*.xml"] --> B["XmlServiceTaskDefinitionLoader"]
B --> C["ServiceTaskCatalogService"]
C --> D["XmlDefinedServiceTaskHandler"]
D --> E["ActivityHandlerRegistry"]
F["BPMN serviceTask"] --> E
E --> G["RegistryBackedServiceTaskExecutor"]
G --> H["ServiceTaskExecutorRegistry"]
H --> I["Standard executor"]
H --> J["ConnectorRestServiceTaskExecutor"]
H --> K["ConnectorJdbcServiceTaskExecutor"]
H --> T["ConnectorEventStreamServiceTaskExecutor"]
H --> O["AiGatewayServiceTaskExecutor"]
H --> P["Custom Java executor"]
H --> S["ServiceTaskExecutorSupport"]
J --> L["ConnectorExecutionService"]
L --> M["REST ConnectorExecutor"]
K --> Q["JDBC ConnectorExecutor"]
T --> U["EventStreamConnectorExecutor"]
U --> V["MessageOutboxService"]
O --> R["AiGatewayService"]
I --> N["Engine work item or sync output"]
P --> N
S --> P
M --> N
Q --> N
V --> N
R --> N
Definition Format
<serviceTask type="service.document.generate" version="1">
<name>Generate Document</name>
<description>Generate a document from a template and workflow variables.</description>
<category>document</category>
<executionMode>ASYNC_AUTOMATED</executionMode>
<source>REMOTE_EXTENSION</source>
<workItemType>EXTERNAL_SERVICE</workItemType>
<implementation>standard-work-item</implementation>
<timeoutSeconds>300</timeoutSeconds>
<retryPolicyId>io-default</retryPolicyId>
<maxAttempts>3</maxAttempts>
<retryBackoffSeconds>30</retryBackoffSeconds>
<authRequirement>authenticated</authRequirement>
<loggingCategory>service.document</loggingCategory>
<auditEnabled>true</auditEnabled>
<tags>document,template,generation</tags>
<metadata>{"extensionPack":"documents"}</metadata>
<configurationSchema>{"templateId":"string","outputFormat":"docx"}</configurationSchema>
<inputSchema>{"variables":"object"}</inputSchema>
<outputSchema>{"documentId":"string","url":"string"}</outputSchema>
</serviceTask>
Operational fields are optional. If they are omitted, the loader uses safe defaults: no timeout, one attempt, no retry backoff, authenticated access, category-based logging, audit enabled, and no tags.
| Field | Purpose |
|---|---|
timeoutSeconds |
Maximum time a worker or executor should spend on the task. 0 means no catalog-level timeout. |
retryPolicyId |
Named retry policy that a worker, message controller, or future scheduler can resolve. |
maxAttempts |
Maximum attempts allowed by the catalog definition. |
retryBackoffSeconds |
Default wait between attempts. |
authRequirement |
Human-readable execution requirement such as authenticated, permission:AI_USE, or connector:google-sheets. |
loggingCategory |
Service-specific logger/category, useful for per-service log files and retention rules. |
auditEnabled |
Whether execution should be written to the audit trail. |
tags |
Comma-separated search and marketplace tags. |
metadata |
Optional JSON object for extension hints such as connector defaults, marketplace pack, provider, or runtime policy. |
Typed contract fields
Each schema element may carry its contract as typed <field> children instead of the legacy
key→type sketch text. This is the second revision of the catalog grammar — a property of the
element vocabulary, not of the catalog version attribute: typed fields are accepted under any
catalog version, and a schema element itself carries no attributes (any attribute on one is
refused at load):
<configurationSchema>
<field name="documentId" type="string" required="required" picker="document"
description="The governed document. Choose it by name, or write an expression. Publishing checks a name. The case checks an expression."/>
<field name="resultVariable" type="text" required="optional" default="document"
description="Case-file variable the document binds to."/>
</configurationSchema>
-
type: a sketch type (string|number|boolean|object|array) or a business type (text|date|datetime|user|record|list|any|integer), mapped onto the sketch vocabulary for legacy consumers (text/date/datetime/user/record→string,list→array,integer→number,any→value).integeris stricter than its sketch mapping: the design-time validator refuses a fractional value (2.5 parses as a number but is not a version anybody can pin to), and the derived JSON Schema keeps the JSON-Schema nameinteger. -
required:required|optional|designer(designer-decides). Default:optional. -
picker: a typed asset the designer can offer a picker for —user|group|role|form|screen| data-action|connector|agent|record-type|document|fabric-query|dataset|process|rule|enumeration. -
enum: an enumeration id from the enumeration catalog — validated at load; an id the catalog does not declare is refused, naming the task and field. Only string-family fields (sketch typestring:string/text/user/record/date/datetime) may declare one — an enum on a number or object would be an unsatisfiable contract and is refused at load. -
default,description,tooltip,hidden,multiple,expressionable: designer-facing metadata.expressionable="true"offers a fixed phrase or an=expression. A dataset, document, or process picker is expressionable from the picker itself. -
title: the inspector label. Optional — when omitted, a label is derived from the field name (camelCase/dashes split into words, sentence case). A whitespace-only title is refused: a blank label is worse than a derived one.
The governed process nodes (service.fabric.query, service.dms.attach,
service.dms.convert.docx-to-pdf, service.escalation.start (see the note on child cases
below), service.record.create,
service.record.create-many, service.record.update, service.record.update-many,
service.record.delete, service.record.delete-many) ship
their configuration contracts as typed fields; the process-node palette derives each node's
inspector JSON Schema from them (ServiceTaskConfigSchema.fromFields), so the catalog is the one
source of truth for what a governed node accepts. Create/update/archive nodes wrap the model's
make-live CRUD rules. Change Record (service.dataaction.patch) remains in the catalog so an
already-published diagram can dispatch, with an empty configuration schema, and fails closed.
Use Update record.
Rules that keep one source of truth:
- A schema element carries fields or sketch text, never both — mixing is refused at load
with
SERVICE_TASK_DEFINITION_INVALID. - Unknown types, requirements, or pickers are refused at load, naming the task and field.
- Field names are machine identifiers (
[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)*) — a name that would corrupt the derived sketch or a key-based lookup is refused. - A field name may appear once per schema element; duplicates are refused.
- Fields are direct children of the schema element and leaves (attributes only) — nested or element-carrying fields are refused rather than silently dropped.
- Each schema element may be declared once per task.
- The task element itself is a closed grammar: unknown elements, duplicated leaves, and elements nested inside leaf values are all refused at load rather than shadowing a declared value.
- The catalog root is closed too: it must be
serviceTaskCatalog, its only accepted attribute is an optionalversion(a positive integer when present), and tasks must be direct children — a task nested in a wrapper element would otherwise be silently activated. hidden/multipleaccept onlytrue/false; adefaultis checked against the field's type for the checked types (numbers parse, booleans are true/false, objects/arrays/lists are JSON of that shape); business-type defaults (date/datetime/user/record/text) are designer-facing text, deliberately unchecked until the picker validation slice.- When fields are present, the legacy sketch is derived from the required fields only: the runtime contract validator treats every listed key as mandatory, so an optional field must never appear in the sketch. Note this means a value supplied for an optional field is not type-checked at runtime today — the typed layer is a design-time contract until D2 wires it.
- The design-time checks (catalog pinning, config field validation, the timer-delay refusal) run
on the designer save path (
DesignerFlowMapper, behindPOST /api/process-definitions/drafts/ from-modelandPUT .../drafts/{id}/model). A draft created from imported or hand-authored BPMN XML (POST .../drafts/from-bpmn, or a rawbpmnXmlcreate/update) bypasses them until the publish-time gates of the re-bind slice exist — treat that path as trusted input. - Entries without fields parse exactly as before; the typed layer is additive.
Output sketches and the openOutputs marker
The legacy outputSchema sketch is the catalog's only output declaration for sketch-only
entries, and the publish-time binding validator reads its keys as the declared output set: an
output binding naming a field outside the set is refused, because the runtime skips it and the
target is never written. That makes sketch accuracy a contract, not documentation — the shipped
sketches list every constant key the executor emits (for example the connector-rest envelope
connectorId/operationId/externalReference/metadata next to response), and no key the
executor never emits.
Executors whose emitted names are genuinely dynamic cannot declare a closed set and instead
carry the metadata marker "openOutputs": true:
<serviceTask type="service.data.query" version="1">…<implementation>connector-jdbc</implementation>
<metadata>{"openOutputs":true}</metadata>…</serviceTask>
The shipped families that carry it: connector-jdbc tasks (the executor merges the connector
result map top-level with putAll, so column names spill next to the declared keys),
connector-event-stream tasks (the same spill), service.rule.evaluate (decision-table row
outputs spill top-level so gateway conditions can route on them),
service.calculation.formula.evaluate (the configured outputField is a config-driven output
name), and async standard-work-item entries (the outputs arrive with the external work-item
completion, so no platform executor can declare them). The marker switches the publish gate's
unknown-output-field and output-collision checks OFF for the generation, and with them the
overridden-default refusal — under a spill the displaced resultVariable default may still be
emitted, so "never emits the displaced default" is unprovable; deterministic checks that do not
depend on the emitted set — the resultVariable reserved-name and length guards — still apply.
Use it sparingly: it is for spill-style and externally-completed emitters, never a way to
excuse an inaccurate sketch. Sketch accuracy is regression-gated by
CatalogExecutorEmissionCensusTest (platform-services-runtime): it routes every catalog entry
through the real registry order and fails when a shipped sketch and its executor's constant
emitted keys disagree in either direction.
Studio contract generation
The typed fields also feed the Studio process designer offline: CatalogContractGenerator
(platform-services-runtime, activity.service) emits
studio/frontend/src/features/process/generated/catalogContracts.ts — a TypeScript
CATALOG_CONTRACTS map keyed by activity type (latest generation per type), carrying each node's
configSchema (the same ServiceTaskConfigSchema.fromFields derivation the process-node palette
serves) plus its full field list. The designer's property inspector prefers this checked-in
contract for governed platform nodes and falls back to the palette API's schema for plugin nodes.
The file is generated — do not hand-edit it. Regenerate after changing conf/service-tasks
or conf/enumerations with:
mvn -pl platform-services-runtime process-classes -Pregen-studio-contracts
The generator is deliberately behind the regen-studio-contracts profile, NOT bound to the
default build: a generator that ran on every build would refresh the checked-in file just before
CatalogContractGeneratorFreshnessTest reads it, making the freshness gate vacuous and letting CI
self-heal a stale commit. Freshness is test-enforced: the test fails when the checked-in file
drifts from the catalog, and regeneration is the explicit act above.
Enumeration catalog
The enumerations a field's enum attribute references live in conf/enumerations/*.xml, loaded
by XmlEnumerationCatalogLoader into EnumerationDefinition(id, version, name, values) records:
<enumerationCatalog version="1">
<enumeration id="task-priority" version="1">
<name>Task Priority</name>
<description>Priority levels offered for human and service tasks.</description>
<value>low</value>
<value>normal</value>
<value>high</value>
<value>urgent</value>
</enumeration>
</enumerationCatalog>
The grammar is as closed as the service-task catalog's — anything outside it is refused at load
with ENUMERATION_CATALOG_INVALID (a duplicate id+version across files with
ENUMERATION_DEFINITION_DUPLICATE; an unreadable catalog with ENUMERATION_CATALOG_LOAD_FAILED):
- The root must be
enumerationCatalog; its only accepted attribute is an optionalversion(a positive integer when present). Enumerations are direct children — a wrapper element is refused. - An
enumerationcarries a requiredid(machine identifier — the field-name grammar, dotted segments allowed) and an optional positive-integerversion(default1). No other attributes. - Child elements are
name(required, non-blank, once),description(optional, once — editor-facing documentation, grammar-checked but not carried on the record yet), andvalue(one or more, non-blank, distinct — a duplicate allowed value is refused). Children are text leaves: no attributes, no nested elements. - DOCTYPE is refused, as in every platform catalog.
- One generation (id + version) may be declared once across the whole catalog. The same id at different versions coexists — generations let a value list evolve without rewriting every field that references the id.
- A missing
conf/enumerations/directory loads as an empty catalog, not an error.
Reference validation: every <field> with a non-blank enum attribute must resolve against this
catalog (same id, any version) at catalog load; an unresolvable reference is refused with
SERVICE_TASK_DEFINITION_INVALID, naming the task, the field, and the missing id. The catalog is
platform-wide — even a task catalog loaded from another directory resolves enum references against
conf/enumerations/.
Marketplace Service Blueprints
platform-service-task-marketplace.xml is the seed marketplace catalog. It is
not a separate runtime. It is a large set of XML-defined service-task
blueprints that all use the same platform service-task execution contract.
Every marketplace service task is tagged with marketplace and declares three
metadata fields:
| Metadata | Purpose |
|---|---|
marketplaceFamily |
Functional family such as document, pdf, spreadsheet, data, ai, agent, integration, notification, or report. |
implementationTemplate |
The implementation style to use now, such as standard-work-item, standard-sync, or ai-gateway. |
extensionPoint |
The future plug-in surface that can provide a concrete implementation, such as document-generator, pdf-converter, google-sheets-worker, agent-runtime, or report-generator. |
Example:
<serviceTask type="service.document.generate.offer.letter" version="1">
<name>Generate Offer Letter</name>
<category>document</category>
<executionMode>ASYNC_AUTOMATED</executionMode>
<implementation>standard-work-item</implementation>
<metadata>{
"marketplaceFamily":"document",
"implementationTemplate":"standard-work-item",
"extensionPoint":"document-generator"
}</metadata>
<configurationSchema>{"templateId":"string","locale":"string","outputFormat":"string"}</configurationSchema>
<inputSchema>{"candidate":"object","offer":"object","approvals":"array"}</inputSchema>
<outputSchema>{"documentId":"string","version":"number","artifact":"object"}</outputSchema>
</serviceTask>
This means a service can be useful before a specialized Java executor exists:
standard-work-item creates a durable run for an external worker. Later, a
developer can add a Java executor or worker implementation for the declared
extensionPoint without changing the BPMN model or service-task type.
The marketplace currently seeds more than 50 additional service blueprints, including:
- document generation for offer letters, invoices, contracts, policies, statements, meeting minutes, and board packs
- PDF conversion from Word, Excel, PowerPoint, email, thumbnails, signatures, and metadata extraction
- Excel and Google Sheets creation, cleaning, splitting, merging, validation, synchronization, and export/import operations
- AI tasks for workflow drafts, form drafts, presentations, document classification, entity extraction, redaction, risk scoring, and next action recommendations
- agent tasks for browser operators, API operators, remediation, test generation, and data stewardship
- integration tasks for n8n, Make.com, Zapier, IFTTT, GraphQL, and OpenAPI operations
- report generation and distribution tasks for Excel, PDF, and PowerPoint
The platform also exposes a marketplace-oriented API so designers, AI copilots, and future marketplace screens do not need to parse XML directly:
GET /api/activity-catalog/service-tasks/marketplace
GET /api/activity-catalog/service-tasks/marketplace/{family}
The report groups marketplace service tasks by:
marketplaceFamilyimplementationTemplateextensionPoint
Example response shape:
{
"serviceTaskCount": 67,
"familyCount": 10,
"byFamily": {
"document": 10,
"ai": 8
},
"byImplementationTemplate": {
"standard-work-item": 55,
"ai-gateway": 8
},
"byExtensionPoint": {
"document-generator": 7,
"agent-runtime": 5
},
"families": [
{
"family": "document",
"serviceTaskCount": 10,
"extensionPoints": ["document-generator", "document-converter"],
"serviceTasks": [
{
"type": "service.document.generate.offer.letter",
"implementationTemplate": "standard-work-item",
"extensionPoint": "document-generator"
}
]
}
]
}
The API requires ACTIVITY_CATALOG_VIEW, the same permission used by the
normal activity catalog endpoints.
Extension Point Catalog
Marketplace entries also define an extensionPoint. This is the stable
developer-facing target for implementation work. For example, a document engine
does not need to inspect every service task manually; it can ask the platform
for the document-generator extension point and see all service tasks,
schemas, auth requirements, and preferred implementation templates that belong
to that point.
GET /api/activity-catalog/service-tasks/extension-points
GET /api/activity-catalog/service-tasks/extension-points/{extensionPoint}
The seed marketplace currently exposes extension points such as:
document-generatordocument-converterpdf-converterspreadsheet-transformergoogle-sheets-workerai-provideragent-runtimen8n-connectormake-connectorgraphql-connectoropenapi-connectorreport-generatornotification-provider
Each extension point reports:
- service task count
- related marketplace families and categories
- implementation templates such as
standard-work-item,standard-sync, orai-gateway - service task types and JSON contracts
- auth requirements
- metadata such as the preferred implementation template
This gives extension developers a clean workflow:
- Find an extension point, for example
document-generator. - Inspect its service task contracts.
- Generate or write an extension pack using those contracts.
- Register the Java executor through Spring, ServiceLoader, or a future plugin
bootstrap, or implement an external worker for
standard-work-itemtasks. - Run the service-task governance report before deploying.
Marketplace Provider Runtime
Marketplace blueprints can now be executed through a provider SPI keyed by
metadata.extensionPoint. This is lighter than creating a new implementation id
for every marketplace task. A provider can implement a family capability such
as document-generator, pdf-converter, google-sheets-worker,
data-transformer, n8n-connector, notification-provider, or
agent-runtime, and the platform can route all matching marketplace service
tasks to that provider.
The runtime classes are:
ServiceTaskExtensionProvider
ServiceTaskExtensionProviderRegistry
MarketplaceServiceTaskExecutor
Built-in starter providers currently cover:
- document, PDF, spreadsheet, Google Sheets, and report marketplace tasks
- data, integration, connector, and notification marketplace tasks
- agent runtime and lineage capture marketplace tasks
These starter providers return deterministic platform metadata such as
documentId, pdfId, spreadsheetId, datasetId, connectorInvocationId,
notificationId, agentRunId, or lineageEventId. They are intentionally
safe local implementations for early workflow design, testing, demos, and
extension authoring. Production connectors can replace them with provider SDKs,
remote workers, or custom implementation ids when real external execution is
needed.
To add a Java marketplace provider:
public class AcmePdfProvider extends MarketplaceServiceTaskExtensionSupport {
public AcmePdfProvider() {
super(List.of("pdf-converter", "pdf-renderer"));
}
@Override
public ActivityExecutionResult execute(ServiceTaskDefinition definition, ActivityExecutionRequest request) {
Map<String, Object> output = Map.of(
"pdfId", "...",
"artifact", Map.of("kind", "pdf"));
return completed(definition, request, output);
}
}
Then register it with Java ServiceLoader:
META-INF/services/com.inflowai.platform.activity.service.ServiceTaskExtensionProvider
The file contains the provider class name:
com.example.inflow.extension.AcmePdfProvider
Provider registration is fail-fast. Two providers cannot claim the same
extension point in the same runtime. Startup fails with
SERVICE_TASK_EXTENSION_PROVIDER_COLLISION instead of silently choosing one.
Durable runtime note: asynchronous or agentic marketplace tasks using
standard-work-item are persisted as service-task runs when a local
MarketplaceServiceTaskExecutor supports their extensionPoint. The built-in
service-task worker does not claim every standard-work-item run. Instead, it
claims only the concrete service-task types backed by registered marketplace
providers. This lets service.document.generate.offer.letter be processed by a
document provider while a different standard-work-item task remains available
for an external worker.
For large production deployments, teams can still create dedicated implementation ids and worker pools when they need provider-specific leases, resource limits, SDK isolation, or separate deployment scaling. The extension-point provider runtime is the lightweight path for marketplace packs that share the platform worker pool.
Connector Defaults In Metadata
Connector-backed service tasks can declare their default connector target in
XML. This keeps the task catalog extensible: adding a new connector-backed
service should not require changing the Java executor when the generic
connector-rest implementation can run it.
<serviceTask type="service.google.sheets.read" version="1">
<name>Read Google Sheets</name>
<category>spreadsheet</category>
<executionMode>SYNC_AUTOMATED</executionMode>
<source>REMOTE_EXTENSION</source>
<workItemType>EXTERNAL_SERVICE</workItemType>
<implementation>connector-rest</implementation>
<metadata>{"defaultConnectorId":"google-sheets","defaultOperationId":"read-range"}</metadata>
<configurationSchema>{"spreadsheetId":"string","range":"string"}</configurationSchema>
<inputSchema>{"parameters":"object"}</inputSchema>
<outputSchema>{"response":"object"}</outputSchema>
</serviceTask>
At execution time, ConnectorRestServiceTaskExecutor resolves the target in
this order:
- Explicit workflow configuration:
connectorIdplusoperationoroperationId. - XML metadata:
defaultConnectorIdplusdefaultOperationId. - Legacy built-in defaults for older seed tasks.
This pattern is the preferred way to add services such as document generation, PDF conversion, Google Sheets, Excel, SaaS actions, automation platform calls, AI provider calls, and custom API operations.
Child cases started by a step
service.process.start and service.escalation.start start another case from a step. The
child is accountable to the person who started the case the step runs in (transitively, the root
of the case tree), never to whoever completed the previous task or to the timer that fired the
step: process.initiator, initiator-based assignment and governed INITIATOR steps in the child
see the root's initiator. A child of a root that has no accountable initiator (a timer, message or
API-key start) inherits none, so INITIATOR and SERVICE_ACCOUNT governed steps in it fail
closed. The child also records which step of which case started it (process_instance_origins),
which the identity and access capability steps use to check that a child never runs as anybody but
the root's initiator.
BPMN Usage
A BPMN service task selects the catalog item using activityType:
{
"activityType": "service.document.generate",
"activityVersion": 1,
"templateId": "contract-template",
"outputFormat": "docx"
}
If no activityVersion is provided, version 1 is used.
Standard Implementations
standard-work-item
Creates a waiting engine work item. This is the right default for service tasks that will later be completed by a worker, connector, callback, or external runtime.
It also creates a persistent service task run through
ServiceTaskRunRepository, including retry, timeout, auth, logging, and audit
policy copied from the XML definition. See
docs/manuals/service-task-execution.md.
standard-sync
Completes immediately and returns a small standard output map. This is useful for light utility tasks such as cache invalidation or JSON transformation placeholders.
connector-rest
Executes immediately through ConnectorExecutionService and the REST connector
executor. This is used for service tasks that can be mapped to a configured REST
connector operation.
The generic REST service task uses explicit configuration:
{
"activityType": "service.connector.rest.call",
"connectorId": "n8n",
"operation": "trigger-workflow",
"workflowId": "onboard-customer",
"payload": {
"customerNumber": "C-100"
}
}
connector-jdbc
Executes approved database reads through ConnectorExecutionService and the
JDBC connector executor. Workflow configuration provides a queryId, optional
connectorId, optional parameters, and optional maxRows.
Example:
{
"activityType": "service.data.query",
"connectorId": "postgresql",
"queryId": "identity.active-users",
"parameters": {
"active": true
},
"maxRows": 50
}
The SQL itself is not stored in the BPMN model. It is centrally approved in
conf/queries/*.xml.
connector-event-stream
Publishes workflow events and queue messages through ConnectorExecutionService
and the event-stream connector executor. The executor writes to the durable
message outbox, so Kafka, Redpanda, RabbitMQ, and compatible brokers can be
published by scalable workers instead of blocking BPMN execution on broker IO.
Example:
{
"activityType": "service.integration.kafka.publish",
"topic": "inflow.integration.commands",
"messageKey": "customer-100",
"messageName": "CustomerSynced",
"payload": {
"customerId": "C-100"
},
"headers": {
"correlationId": "corr-1"
}
}
RabbitMQ-style paths use the XML connector operation path
{exchange}/{routingKey}:
{
"activityType": "service.integration.rabbitmq.publish",
"exchange": "workflow",
"routingKey": "task.created",
"payload": {
"taskId": "T-1"
},
"options": {
"channel": "jms"
}
}
The seed catalog includes service.integration.kafka.publish,
service.integration.rabbitmq.publish, service.integration.event.publish,
and service.queue.publish. New broker-backed tasks should prefer XML
metadata with defaultConnectorId and defaultOperationId.
cache-invalidation
Invalidates approved-query cache entries through the platform cache service. The
seed task is service.data.cache.invalidate. Approved-query cache keys embed
the connector's workspace scope (workspace:<id>, from the connector's
workspaceId metadata or the current workspace context) after the connector
id, so cached rows never cross workspace boundaries.
Examples:
{
"activityType": "service.data.cache.invalidate",
"scope": "key",
"cacheKey": "jdbc-approved-query:postgresql:workspace:00000000-0000-0000-0000-000000000001:identity.active-users:maxRows=50:parameters={active=true}"
}
{
"activityType": "service.data.cache.invalidate",
"scope": "prefix",
"cacheKeyPrefix": "jdbc-approved-query:postgresql"
}
{
"activityType": "service.data.cache.invalidate",
"scope": "all"
}
Output includes removedEntries, so workflows can audit whether the
invalidation actually removed cached data.
dataset-materialization
Builds a materialization run artifact for a Fabric dataset. The seed task is
service.data.materialize.dataset.
Example:
{
"activityType": "service.data.materialize.dataset",
"datasetId": "customer-360",
"idempotencyKey": "customer-360-nightly",
"forceRefresh": true,
"parameters": {
"customerNumber": "C-100"
}
}
Datasets without executable steps run in PLAN_ONLY. The task resolves the
dataset through Fabric, returns connector links and the governed plan, and
produces a stable datasetRunId.
Datasets with queryModel.materializationSteps execute through
ConnectorExecutionService. This keeps materialization database-agnostic:
database work goes through approved JDBC queries, API work goes through REST or
SaaS connectors, and future file/event executors can use the same step model.
Each connector result is saved in the materialization run plan under
materializationResults. For datasets marked as materialized, successful
connector output is also persisted through MaterializedDatasetRecordRepository.
The JDBC adapter stores those rows in ai_fabric_materialized_records, so later
tasks and reports can read a materialized dataset by run id or by the latest
dataset records instead of rerunning the connector fan-out. The task metadata
includes materializedRecordCount when durable records are written.
ai-gateway
Executes AI service tasks through AiGatewayService. The executor converts the
service-task configuration and workflow variables into an AiGatewayRequest,
then returns the selected model/provider, AI text, structured output, usage, and
audit id as workflow variables.
Example:
{
"activityType": "service.ai.summarize",
"modelId": "my-openai-chat",
"prompt": "Summarize this customer conversation for a case worker.",
"input": {
"content": "Customer asked for renewal pricing and escalation."
},
"constraints": {
"maxOutputTokens": 250
}
}
Output includes:
{
"serviceTaskStatus": "COMPLETED",
"serviceTaskType": "service.ai.summarize",
"aiText": "The customer requested renewal pricing...",
"aiStructuredOutput": {},
"modelId": "my-openai-chat",
"providerId": "openai",
"usage": {},
"auditId": "..."
}
Default purposes and capabilities are inferred from the task type. For example,
service.ai.agent.run requests chat, tool calling, and agentic reasoning,
while extraction/classification/email generation request structured output.
Configuration may override this with purpose, modelId or
preferredModelId, prompt, requiredCapabilities, input, and
constraints.
The executor also provides default mappings for common tasks:
service.n8n.webhook.trigger->n8n.trigger-workflowservice.make.webhook.trigger->make.run-scenarioservice.google.sheets.read->google-sheets.read-rangeservice.google.sheets.write->google-sheets.append-rangeservice.google.sheets.append->google-sheets.append-rangeservice.excel.read->microsoft-excel.read-rangeservice.slack.message->slack.send-messageservice.teams.message->microsoft-teams.send-channel-message
Output includes:
{
"serviceTaskStatus": "COMPLETED",
"connectorId": "n8n",
"operationId": "trigger-workflow",
"externalReference": "run-100",
"response": {}
}
Java Implementation Template
Every XML definition names an implementation. At runtime,
RegistryBackedServiceTaskExecutor asks ServiceTaskExecutorRegistry for a Java
executor that supports that implementation.
Starter templates are available in:
docs/templates/service-task-extension-pack.xml
docs/templates/service-task-implementation-manifest.xml
docs/templates/ExampleServiceTaskExecutor.java.txt
You can also generate a starter pack:
.\scripts\service-task-extension-create.ps1 `
-PackName salesforce-account `
-ServiceType service.salesforce.account.get `
-ImplementationId salesforce-account-get `
-DisplayName "Get Salesforce Account" `
-Category crm `
-JavaBacked `
-ServiceLoaderRegistration
The same authoring flow is also available through the authenticated service layer as a preview API:
POST /api/service-task-implementations/extension-pack/preview
This endpoint does not write files. It returns generated service-task XML,
implementation manifest XML, optional Java executor source, suggested target
paths, optional ServiceLoader entry, and next steps. This is the preferred
entry point for Studio, an AI assistant, marketplace clients, or a CLI
because users can review the generated pack before saving it.
Example request:
{
"packName": "salesforce-account",
"serviceType": "service.salesforce.account.get",
"implementationId": "salesforce-account-get",
"displayName": "Get Salesforce Account",
"description": "Fetch a Salesforce account through an approved connector.",
"category": "crm",
"javaBacked": true,
"serviceLoaderRegistration": true,
"authRequirement": "connector:salesforce",
"configurationSchemaJson": "{\"connectorId\":\"string\",\"operation\":\"string\"}",
"inputSchemaJson": "{\"accountId\":\"string\"}",
"outputSchemaJson": "{\"serviceTaskStatus\":\"string\",\"account\":\"object\"}"
}
Example response fields:
{
"packName": "salesforce-account",
"serviceTaskPath": "conf/service-tasks/salesforce-account.xml",
"implementationPath": "conf/service-task-implementations/salesforce-account-implementations.xml",
"javaExecutorPath": "platform-monolith/src/main/java/com/inflowai/platform/extension/SalesforceAccountGetExecutor.java",
"serviceLoaderPath": "src/main/resources/META-INF/services/com.inflowai.platform.activity.service.ServiceTaskExecutor",
"serviceTaskXml": "...",
"implementationXml": "...",
"javaExecutorSource": "...",
"serviceLoaderEntry": "com.inflowai.platform.extension.SalesforceAccountGetExecutor",
"nextSteps": []
}
The preview service validates naming rules and verifies that all three schema
fields contain a strict JSON object (no trailing content, no duplicate keys).
Generated XML is parseable by the same
XmlServiceTaskDefinitionLoader and
XmlServiceTaskImplementationCatalogLoader used at startup.
The generator creates:
conf/service-tasks/<pack>.xmlconf/service-task-implementations/<pack>-implementations.xml- an optional Java executor skeleton under
platform-monolith/src/main/java
For Java-backed packs, the generated executor skeleton must still be registered
through Spring configuration, plugin bootstrap, or Java ServiceLoader before
the catalog health report can show the task as executable. Passing
-ServiceLoaderRegistration creates or appends the provider file under
src/main/resources/META-INF/services/ for the generated executor class.
Implementation manifests live under:
conf/service-task-implementations/
Each manifest is XML and describes a Java implementation id, template class, owner, supported execution modes, configuration schema, and marketplace tags. The default manifest is:
conf/service-task-implementations/platform-service-task-implementations.xml
Example:
<serviceTaskImplementationCatalog version="1">
<implementation id="example-operation">
<name>Example Operation Executor</name>
<description>Executes service.example.operation through a Java extension.</description>
<kind>java-extension</kind>
<templateClass>com.example.inflow.extension.ExampleServiceTaskExecutor</templateClass>
<executionOwner>example-team</executionOwner>
<syncSupported>true</syncSupported>
<asyncSupported>true</asyncSupported>
<configurationSchema>{"connectorId":"string"}</configurationSchema>
<tags>example,java,extension-template</tags>
</implementation>
</serviceTaskImplementationCatalog>
The manifest does not load arbitrary classes by itself. Java executors are
registered through Spring configuration, plugin bootstrap, or Java
ServiceLoader. The manifest is the machine-readable contract that lets
designers, validators, documentation generators, and marketplaces understand
which implementation ids exist and how they are meant to be used.
The implementation catalog is available through the authenticated API:
GET /api/service-task-implementations
GET /api/service-task-implementations/{implementationId}
GET /api/service-task-implementations/report
The report endpoint is the extension-pack health check. It returns:
serviceTaskCount: number of loaded XML service tasks.implementationManifestCount: number of loaded implementation manifests.usage: service-task counts by implementation id, plus whether that id has a manifest and an executor.missingImplementationManifests: implementation ids used by service tasks but not documented inconf/service-task-implementations.unusedImplementationManifests: manifests that are not directly referenced by any XMLimplementation. This can be normal for typed Java families such as document/office, calculation/rules, and platform utility executors when they deliberately take over broader XML task families ahead of the generic fallback executor.unsupportedServiceTasks: service task type/version keys that no registered executor can run.governanceIssues: warnings and errors found by catalog governance rules.productionReady:trueonly when there are no missing manifests, no unsupported tasks, and no governance errors.
For production deployments, missingImplementationManifests and
unsupportedServiceTasks should be empty before releasing an extension pack,
and productionReady should be true. Governance warnings are allowed during
early design, but production packs should work them down before release.
Governance errors include missing implementation manifests, missing executors, invalid JSON schemas, execution-mode mismatches between XML and the implementation manifest, and broken connector bindings for connector-backed tasks.
Connector binding governance uses the live connector catalog when the service
is wired with ConnectorRegistryService:
CONNECTOR_REFERENCE_MISSING: a service task references a connector id that does not exist inconf/connectors.CONNECTOR_OPERATION_MISSING: service-task metadata references adefaultOperationIdthat is not defined on the selected connector.
For connector-rest, connector-jdbc, and connector-event-stream tasks,
missing connector references are errors because the worker cannot execute the
task safely. For future placeholder tasks that use standard-work-item,
missing connector references are warnings so architects can model future
extension points before the connector pack exists.
Governance warnings also include missing timeout, missing retry policy, missing retry backoff for multi-attempt tasks, generic authentication, generic logging category, disabled audit, and missing tags.
Extension-readiness warnings also protect the long-term marketplace and plugin model:
MARKETPLACE_FAMILY_MISSING: a marketplace task should declaremetadata.marketplaceFamily.IMPLEMENTATION_TEMPLATE_MISSING: a marketplace task should declaremetadata.implementationTemplate.EXTENSION_POINT_MISSING: a marketplace task, or a remotestandard-work-itemtask, should declaremetadata.extensionPoint.
These are warnings instead of hard startup failures. That lets architects model future services before every worker, connector, or provider exists. Production extension packs should still treat them as release blockers because the extension point is what allows Java providers, remote workers, marketplace screens, and AI design tools to bind to the same service contract.
Recommended metadata for a new extension task:
<metadata>{
"marketplaceFamily": "document",
"implementationTemplate": "standard-work-item",
"extensionPoint": "document-generator",
"enforceRuntimeContracts": true
}</metadata>
Use these fields consistently:
| Metadata | Required when | Purpose |
|---|---|---|
marketplaceFamily |
Marketplace tasks | Groups tasks for designers, catalogs, install screens, and AI recommendations. |
implementationTemplate |
Marketplace tasks | Records the intended runtime style, such as standard-work-item, standard-sync, connector-rest, or ai-gateway. |
extensionPoint |
Marketplace and remote worker tasks | Names the stable hook a Java provider, remote worker, or future plugin implements. |
enforceRuntimeContracts |
Runtime-enforced services | Turns schemas from documentation into execution gates for configuration, input, output, and requester authorization. |
The clean extension path is:
- Define the service in XML under
conf/service-tasks. - Add implementation metadata under
metadata. - Reuse an existing implementation id when possible.
- Add a manifest under
conf/service-task-implementationsonly when using a new implementation id. - Implement a
ServiceTaskExecutororServiceTaskExtensionProvideronly when XML and generic connector executors are not enough. - Run
GET /api/service-task-implementations/reportor the test suite before release.
Capability API
The raw activity catalog is intentionally detailed. Designers, AI assistants, marketplaces, and extension screens often need a higher-level answer: what service families are available, how they execute, and which implementation types back them.
The platform exposes that grouped view through:
GET /api/activity-catalog/service-tasks/capabilities
GET /api/activity-catalog/service-tasks/capabilities/{category}
The endpoint requires ACTIVITY_CATALOG_VIEW. It groups XML service tasks by
category and returns capability flags, service types, implementation ids,
execution counts, auth requirements, logging categories, tags, and extension
readiness.
Example:
{
"category": "ai",
"serviceTaskCount": 14,
"syncCount": 12,
"asyncCount": 1,
"agenticCount": 1,
"serviceTypes": [
"service.ai.extract",
"service.ai.review.contract"
],
"implementations": [
"ai-gateway",
"standard-work-item"
],
"aiCapable": true,
"agentCapable": true,
"extensionReady": false,
"metadata": {
"hasAiGatewayTasks": true,
"hasConnectorBackedTasks": false,
"hasStandardWorkItemTasks": true,
"extensionReadyTaskCount": 8
}
}
Capability flags are derived from the category, service type, task name, and
tags using token matching. For example, email and wait do not imply the
ai capability just because those words contain adjacent letters. Capability
flags are a discovery aid, not an authorization decision. Runtime access still
comes from authRequirement, connector credentials, identity services, and
normal service-layer permission checks.
extensionReady is intentionally strict at the category level. It is true
only when every service task in that category has meaningful schemas, explicit
timeout and retry metadata, a non-generic auth requirement, a stable
service.* logging category, and tags. The metadata.extensionReadyTaskCount
field shows how many tasks in the category already meet that stronger
marketplace-readiness bar.
Common capability flags include:
documentCapablepdfCapablespreadsheetCapableintegrationCapableaiCapableagentCapabledataCapableworkflowCapablenotificationCapablesecurityCapableautomationCapableobservabilityCapable
AI workflow design should use this endpoint before recommending a service task.
For example, when the user asks to add a document-generation step, the designer
can look at the document capability group, then choose a concrete service
type such as service.document.generate, service.document.generate.batch, or
service.document.assemble.packet.
For a Java-backed service task, start from:
docs/templates/StandardJavaServiceTaskExecutor.java.txt
The standard template extends ServiceTaskExecutorSupport, which gives custom
executors helper methods for completed output, waiting work items, sync-mode
detection, and typed configuration reads. A typical Java executor looks like
this:
public class SalesforceAccountGetExecutor extends ServiceTaskExecutorSupport {
public SalesforceAccountGetExecutor() {
super("salesforce-account-get");
}
@Override
public ActivityExecutionResult execute(ServiceTaskDefinition definition, ActivityExecutionRequest request) {
Object payload = request.configuration().get("payload");
if (isSync(definition)) {
Map<String, Object> output = new LinkedHashMap<>();
output.put("implementation", implementation());
output.put("correlationId", request.configuration().getOrDefault("correlationId", ""));
output.put("idempotencyKey", request.idempotencyKey());
output.put("result", payload == null ? Map.of() : payload);
return completed(definition, output);
}
return waiting(definition, request);
}
}
Then register it through Spring configuration:
new DefaultServiceTaskExecutorRegistry(List.of(
new ConnectorRestServiceTaskExecutor(connectorExecutionService),
new AiGatewayServiceTaskExecutor(aiGatewayService),
new StandardServiceTaskExecutor(),
new SalesforceAccountGetExecutor()
));
Or package it in an extension jar with a service provider file:
META-INF/services/com.inflowai.platform.activity.service.ServiceTaskExecutor
The file contains the executor class name:
com.example.inflow.extension.SalesforceAccountGetExecutor
At startup, the platform appends ServiceLoader executors to the built-in
registry before the standard fallback executor. This lets extension jars add
Java-backed service tasks without editing platform configuration.
Generated Java-backed service task output should include:
serviceTaskStatusserviceTaskTypeimplementationcorrelationIdidempotencyKeyresult
Keep these fields in the XML outputSchema even when a custom executor adds
extra provider-specific outputs. They give workflow logs, retries, and support
tools a stable envelope across all Java-backed services.
The catalog can validate executor bindings at startup. If XML references an
implementation that no executor supports, startup fails with
SERVICE_TASK_EXECUTOR_NOT_FOUND.
Catalog Summary API
Designers and operators can inspect the loaded service-task catalog through the authenticated summary endpoint:
GET /api/activity-catalog/service-tasks/summary
A static generated report is also available at:
docs/generated/service-task-catalog-summary.md
Regenerate it after catalog changes with:
.\scripts\service-task-catalog-summary.ps1
The endpoint requires ACTIVITY_CATALOG_VIEW and returns:
serviceTaskCount: total loaded XML service task definitions.byCategory: counts for families such asdocument,pdf,spreadsheet,ai,agent,integration,data, andworkflow.byImplementation: counts by runtime implementation id such asstandard-work-item,standard-sync,connector-rest,connector-jdbc,connector-event-stream,ai-gateway,document-office,calculation-rules, and extension ids.byExecutionMode: counts bySYNC_AUTOMATED,ASYNC_AUTOMATED,AGENTIC, and other execution modes.bySource: counts by extension source.byWorkItemType: counts by workflow work item type.metadataQuality: operational metadata signals.
metadataQuality is intentionally diagnostic, not a hard startup gate. It
shows how many tasks rely on default timeout, retry, authentication, logging,
or audit behavior, plus the task ids missing explicit operational metadata.
This lets platform owners gradually harden seed packs and custom packs without
blocking early prototyping.
Example shape:
{
"serviceTaskCount": 174,
"byCategory": {
"document": 13,
"pdf": 14,
"spreadsheet": 28
},
"byImplementation": {
"standard-work-item": 88,
"standard-sync": 32,
"connector-event-stream": 4,
"connector-rest": 29
},
"metadataQuality": {
"tasksWithoutTimeout": 51,
"tasksWithoutRetryPolicy": 51,
"tasksMissingOperationalMetadata": [
"service.document.generate:1"
]
}
}
Catalog Quality Rules
The catalog is designed to grow into hundreds or thousands of services, so extension packs must be deterministic:
type + versionmust be unique across all XML files loaded fromconf/service-tasks.configurationSchema,inputSchema, andoutputSchemamust be valid JSON.implementationmust be eitherstandard-work-item,standard-sync, or a registered Java executor id.- XML-only tasks should use
standard-work-itemwhen real execution will happen in a worker, connector, callback, or remote service. - REST-backed tasks should use
connector-restwhen they can safely execute synchronously through a configured connector operation. - Database read tasks should use
connector-jdbcand approved query IDs instead of raw SQL. - Broker-backed tasks should use
connector-event-streamso publishing goes through the durable outbox and connector execution history. - Cache maintenance tasks should use
cache-invalidationwhen clearing approved-query cache entries. - Dataset refresh tasks should use
dataset-materializationso query planning stays centralized in Fabric. - AI tasks should use
ai-gatewayso provider routing, redaction, usage, and audit behavior stay centralized. - Java-backed tasks should keep provider SDK details inside the executor and expose stable workflow-facing input/output schemas.
Duplicate service definitions fail startup with
SERVICE_TASK_DEFINITION_DUPLICATE. Missing Java executors fail startup with
SERVICE_TASK_EXECUTOR_NOT_FOUND.
Runtime Contract Enforcement
configurationSchema, inputSchema, and outputSchema are always validated as
valid JSON when the catalog loads. By default they are treated as extension
metadata so older seed tasks and provider placeholders remain backward
compatible.
For a new service task that must enforce contracts at runtime, add this metadata:
<metadata>{"enforceRuntimeContracts":true}</metadata>
The runtime then checks:
configurationSchemaagainst the node configuration map.inputSchemaagainst the workflow variable map.outputSchemaagainst the executor output map.authRequirementagainst the execution request requester.
The supported schema vocabulary is intentionally small and portable:
string, number, boolean, object, and array. Fields listed in the
schema are required when runtime contracts are enforced.
Example:
<serviceTask type="service.document.generate.offer" version="1">
<implementation>document-office</implementation>
<authRequirement>authenticated</authRequirement>
<metadata>{"enforceRuntimeContracts":true}</metadata>
<configurationSchema>{"templateId":"string"}</configurationSchema>
<inputSchema>{"customerId":"string"}</inputSchema>
<outputSchema>{"documentId":"string"}</outputSchema>
</serviceTask>
If a local worker returns output that does not match the enforced
outputSchema, the worker fails the service-task run. When attempts are
exhausted the run moves to DEAD_LETTER.
Seed Catalog
The seed catalog includes hundreds of service-task definitions. Automated tests protect both the catalog floor and the spread across core families so extension work does not accidentally narrow the platform. The family coverage includes document, PDF, spreadsheet, AI, agent, integration, Fabric, data, connector, workflow, notification, security, automation/RPA, cache, messaging, observability, reports, rules, storage, CRM, payment, e-signature, OCR, media, calendar, governance, and audit tasks.
It includes:
- document generation, merging, text extraction, watermarking, and signatures
- batch document generation, comparison, redaction, HTML rendering, and packaging
- PDF conversion, splitting, merging, OCR, stamping, compression, encryption, and decryption
- Excel and Google Sheets read/write, formatting, charting, protection, pivot, CSV, and PDF export operations
- report generation, scheduling, and dashboard export
- Fabric query, write, cache, and materialization tasks
- data warehouse sync, data quality, enrichment, and deduplication tasks
- REST, GraphQL, SOAP, n8n, Make.com, and webhook connector tasks
- Google Drive, Google Calendar, Microsoft Graph, Salesforce, HubSpot, Zoho, ServiceNow, Jira, Stripe, PayPal, DocuSign, and Adobe Sign connector tasks
- email, SMS, push, Slack, and Teams notifications
- WhatsApp and voice-call notifications
- file upload/download/archive and virus scan
- OCR, image resize, thumbnail, retention, audit, search, queue, cache, monitoring, rules, and RPA tasks
- AI extraction, summarization, classification, translation, email drafting, document generation, contract review, SQL generation, content moderation, and agent execution
- workflow start, signal, escalation, wait, and JSON transform utilities
The expansion pack adds additional task families for:
- document packet assembly, certificate generation, PDF form filling, PDF table extraction, and PDF redaction
- Google Sheets copy/protection/pivot/validation and Excel create/format/pivot/chart/validation operations
- formula, score, pricing, tax, SLA due-date, and currency calculations
- Kafka, queue, FTP, SFTP, HTTP polling, and batch API integration tasks
- invoice review, language detection, RAG search, embeddings, and report-summary AI tasks
- agent planning, agent tool calls, agent memory read/write, and human handoff
- browser/desktop RPA, screen scraping, data lookup/match/dedupe/enrichment/quality/cache warming
- audit writing, permission checks, fraud scoring, calendar events, WhatsApp messages, workflow timers, and decision tables
Extension Practice
To add a new service:
- Add a new XML file under
conf/service-tasks. - Use a stable namespaced type such as
service.salesforce.account.get. - Keep schemas small and explicit.
- Choose an existing implementation id such as
connector-rest,connector-jdbc,connector-event-stream,ai-gateway, orstandard-work-item, or create a custom Java implementation id. - For a custom Java implementation id, add a matching manifest under
conf/service-task-implementations. - Add a Java executor only when XML configuration is not enough.
- Register that executor with platform configuration, plugin bootstrap, or a
ServiceLoaderprovider file. - Keep generated Java output aligned with the XML
outputSchema. - Add
{"enforceRuntimeContracts":true}when the XML schemas should be hard runtime gates instead of descriptive contracts.
Custom executors can implement ServiceTaskExecutor directly or extend
AbstractImplementationServiceTaskExecutor for advanced cases, but
ServiceTaskExecutorSupport is the preferred starting point because it keeps
completed and waiting behavior consistent. This gives the platform two levels
of extension:
- XML-only service definitions for common connector/work-item tasks.
- Java-backed executors for services that need SDKs, streaming, provider-specific authentication, or custom retry behavior.
For most custom Java executors, extend ServiceTaskExecutorSupport. It already
provides:
completed(definition, output)for standard workflow output.waiting(definition, request)for external worker or callback tasks.isSync(definition)for sync-vs-waiting behavior.- typed helpers such as
stringConfig(...)andintConfig(...).
This keeps custom extensions consistent with the platform's standard execution shape while still allowing provider-specific code inside the executor.