Using PI Graph writebacks in Annotation Builder
This feature is currently available as a Private Preview only
During a Private Preview, only customers who have agreed to our Private Preview usage agreements can access this feature. Additionally, the features documented here are subject to change and / or cancellation, so they may not be available to all users in future.
For more information about our Private Preview releases, including the level of Support offered with them, see: Feature release types.
The Native PI Graph writeback feature allows you to write AI-generated outputs from the Annotation Builder, such as extracted entities, categorizations, and risk scores, directly back into your Object-Centric Process Mining (OCPM) data models. By natively integrating these outputs as first-class attributes within the Process Intelligence Graph (PI Graph), your AI-enriched data becomes instantly reusable across downstream applications, Studio assets, AI Agents, and Action Flows, bypassing the 200,000-row limit associated with standard Augmented Attributes.
The writeback process relies on a fully automated data pipeline and deployment mechanism to ensure your AI annotations are securely persisted and immediately available by executing the following steps:
Data Ingestion: During an Annotation Builder execution, the Large Language Model (LLM) outputs are batched and pushed into the Data Pool using an API. The system automatically provisions dedicated raw tables for this data (e.g.,
ai_annotations_<source_table>_<output>).Schema Update: The system dynamically updates the target entity's
SQL_FACTORYand OBJECT definitions via APIs in order to map the newly ingested data columns.Targeted Versioning & Deployment: The system creates a new package version of your data model and automatically deploys it to the Development environment.
Data Reload: An OCPM data job is automatically triggered by an API to reload the data model, making the new attributes immediately queryable.
To configure and execute native PI Graph writebacks, you must meet the following requirements:
An Object-Centric Process Mining data model. (Event-log-based models are not supported.)
Data Integration permissions to read from and write to the underlying Data Pool.
Edit and Deployment permissions for the target Data Model and Objects & Events package.
To prepare your Annotation Builder to write outputs directly into your OCPM data model:
Navigate to Studio and open your Annotation Builder asset.
In the setup wizard, select your target OCPM Entity from the drop-down menu.
Define your AI extraction or classification logic.
Map the expected LLM outputs to your desired attribute names. The system will run a validation check to ensure your proposed attribute names do not conflict with existing PI Graph attributes.
Save and execute the model.
Be aware of the following system behaviors regarding automated deployments and data architecture:
Bundling of Draft Changes (Warning): When Annotation Builder automatically creates and deploys a new version of the data model to include your AI attributes, it will bundle all pending draft changes currently existing in the Objects & Events UI for that model. The system currently cannot isolate or filter only the AI-specific changes.
Best Practice: To avoid accidentally deploying incomplete data model changes, ensure that all manual draft changes in the Objects & Events UI are either reverted or safely completed before triggering an Annotation Builder execution.
Development Environment Only: The automated deployment of the package version is executed solely in your Development (DEV) environment. Production data models remain untouched until you manually promote the package version.
Automated Data Reload: During the deployment of the package to DEV, the system automatically runs the associated OCPM data job. This ensures the underlying data model is reloaded from the raw tables, syncing the data with the new schema.
Namespace Architecture: Currently, the system leverages APIs which operate within the
customnamespace, rather than an isolated application namespace. Therefore, these AI-generated attributes will share the same namespace as your user-managed content.
When using PI Graph writebacks in Annotation Builder, you may encounter the following issues:
Missing Attributes: If the execution completes successfully but the new attributes do not appear in your Studio views, verify in Data Integration that the automatically triggered OCPM Data Job finished without errors.
Validation Errors: If an attribute name matches an existing field on the OCPM entity, the validation step will block the configuration. You must rename the Annotation Builder output to proceed.