Feature/281 business key support

[klajmajk]

Adds business key support

[gemini-code-assist]

Summary of Changes

Hello @klajmajk, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request implements the highly anticipated businessKey feature, providing a robust mechanism to link process instances with external business identifiers. This enhancement significantly improves the ability to manage and query process instances by a meaningful business context, streamlining operations and integration with other systems. The changes are comprehensive, touching all layers from the data model and persistence to the API and internal service logic, ensuring a complete and well-tested solution.

Highlights

• Business Key Support: Introduced a businessKey attribute for process instances, allowing for correlation of process instances to external business entities. This enables more efficient identification and retrieval of specific process instances.
• API and Data Model Updates: The businessKey has been integrated into the process instance data model across internal/cluster/proto/zen_cluster.proto, internal/sql/models.go, and pkg/bpmn/runtime/types.go. The OpenAPI specification (openapi/api.yaml) and generated REST API types (internal/rest/public/zz_generated.go, pkg/zenclient/zz_generated.go) have been updated to support businessKey for creating and querying process instances.
• Persistence and Query Enhancements: A new business_key column has been added to the process_instance table via a database migration (internal/sql/migrations/001_schema.up.sql). The persistence layer (internal/cluster/partition/partition_persistence.go, internal/sql/process_instance.sql.go) and query methods (internal/sql/querier.go) have been updated to store, retrieve, and filter process instances by businessKey.
• Internal Logic and Context Propagation: Logic has been added to internal/appcontext/context.go for propagating the businessKey through the application context. Core cluster node and server components (internal/cluster/node.go, internal/cluster/server/server.go) now handle the businessKey during process instance creation and retrieval.
• Documentation and Testing: New documentation has been added to docs/reference/bpmn-engine.md explaining the businessKey feature. Comprehensive end-to-end tests (test/e2e/process_instance_test.go) have been introduced to validate the functionality of creating and querying process instances with a businessKey.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a 'business key' feature to the BPMN engine, allowing process instances to be correlated with external business entities. The changes involve updating the database schema to include a business_key column in the process_instance table, modifying internal data structures (bpmnruntime.ProcessInstance, sql.ProcessInstance, proto.ProcessInstance) to store and retrieve this key, and extending the API to support creating process instances with a business key and querying instances by it. Specifically, new appcontext functions (WithBusinessKey, BusinessKeyFromContext) were added, CreateInstance and GetProcessInstances methods in node.go and server.go were updated, and the OpenAPI specification was extended to reflect these new API capabilities. Review comments highlighted an incorrect CASE statement for string filtering in SQL queries, suggesting a NULL check instead of != 0, and pointed out commented-out test code for temporary directory cleanup and a businessKey assertion that should be re-enabled after API fixes. Additionally, a suggestion was made to use url.QueryEscape for businessKey in test URLs to handle special characters robustly.

[gemini-code-assist]

The CASE statement for filtering by business_key is incorrect. The condition WHEN @business_key <> 0 will not work as intended for string values in SQLite, as non-numeric strings are coerced to 0 during comparison. This will cause filtering by a non-numeric business_key to fail.

A more robust way to handle optional string filters is to check for NULL.

    CASE WHEN @business_key IS NOT NULL THEN
        process_instance.business_key = @business_key
    ELSE
        1
    END

[gemini-code-assist]

The cleanup of the temporary directory is commented out. This was likely for debugging, but it should be re-enabled to ensure tests do not leave artifacts on the filesystem.

Suggested change

	// os.RemoveAll(tempDir)
	os.RemoveAll(tempDir)

[gemini-code-assist]

This assertion is commented out, likely because the CreateProcessInstance endpoint doesn't return the businessKey. Once the API response is fixed, this assertion should be re-enabled to ensure the businessKey is correctly returned upon creation.

Suggested change

	// assert.NotEmpty(t, instance.BusinessKey)
	assert.NotEmpty(t, instance.BusinessKey)

[gemini-code-assist]

The businessKey is being inserted directly into the URL string. This could lead to issues if the key contains special characters that need to be URL-encoded. Using url.QueryEscape would make this test helper more robust.

You'll also need to import the net/url package.

Suggested change

	WithPath(fmt.Sprintf("/v1/process-instances?businessKey=%s", key)).
	WithPath(fmt.Sprintf("/v1/process-instances?businessKey=%s", url.QueryEscape(key))).