ProjectProvisioningRuntimeCapability exposes ProjectProvisioningApi under platform.project.provisioning. It is for plugins that own a one-to-one mapping between a business project and an Xpert Chat Project.
ensure() creates or reconciles the project with the caller-supplied ID, handling its name, lifecycle and content initialization. Initial creation connects the entry Assistant and its recursive external Assistant dependencies. Existing projects retain current membership: removed Assistants are not restored, and later template dependencies are not automatically added.
See Plugin apps and projects for the product experience. Task mapping and synchronization use a separate capability, described in the SDK project task integration guide.
Contract
The result contains
projectId, xpertIds and operation: 'created' | 'updated'. xpertIds is the saved Assistant connection set. workspaceId is echoed only when supplied by a legacy caller and does not determine project ownership.
Example
This logic runs in authenticated, authorized host request context. The business object has saved its target platform project ID. Replace the example project type with an entity-bound type actually registered by the plugin.IProjectTypeProvider that validates the saved business-object/project association in the current scope and supplies the app entry.
Idempotency and ownership
- Generate or reserve
projectIdonce when the business project is created, then reuse it for every retry and reconciliation. - Do not generate a new ID after a timeout. Call
ensure()again with the same ID. - Obtain tenant, organization and user identity from trusted host context. The entry Assistant must match the project organization, and reconciliation of an existing project requires its owner.
- Derive classification from the app declaration and saved association, never the display name. Provisioning cannot arbitrarily reclassify an existing project.
- Manage project connections explicitly. Provisioning retries must not overwrite existing membership settings.
- Synchronize
status: 'archived'when the business project is archived; do not silently create a replacement active project. - Treat
operationas reconciliation evidence. Product logic should depend on the effective result, not assume every successful call inserted a new record.
First conversation creation and cleanup
Apps may implement optionalIProjectTypeProvider.createForConversation() to save the business object and project association in a host-owned transaction. The host creates the platform project and conversation binding. Do not call ensure() again, start Agents or perform external I/O inside the hook. Complete application configuration confirmation when required. The optional SDK confirmConversation() confirms a pending conversation’s first project without moving an existing binding.
The SDK also declares optional purge(), restricted to an owner physically removing an archived, plugin-bound project and its file workspace. This is not a routine archive or synchronization step. Confirm host support and follow the app’s deletion workflow.
See the Project integration guide for project access, business tasks and views.