Build and run Python plans

Start with an approved environment in the selected workspace and application. Follow environment approval and registration if one is missing. Read metadata.authoring.context to discover the application's dimensions, members, hierarchy versions and semantic descriptions.

Save, Test, Activate and Run

1. Save. Submit python.program.save through execute_v2_python_program_registry, with readable Python source, immutable version, entry point, parameter schema, approved environment and current revision pins. Syntax errors return structured diagnostics immediately. A successful save returns a validation build/task ID for automatic semantic checking. Supply representative validationParameters when the source requires parameters.
2. Repair. Poll read_v2_python_program_build. A sealed Validation establishes valid compiled code. Failed validation returns source-bound diagnostics with locations, stable codes and repair hints. Correct and save another immutable source version. Validation does not activate code or change business data.
3. Test. Send python.program.test through execute_v2_python_program_build, with the exact program/version, builder parameters and current metadata, policy and schema pins. For typed definitions, supply actual rule or member-list bindings separately as definitionParameters; read their declarations from the exact sealed source Validation descriptor instead of treating sample values as defaults. No execution delegation is needed for this design-authorized work. Poll the returned build ID, then read the Impact section with read_v2_python_program_build_artifact. Follow all pages and verify their digests before treating the result as complete.
4. Inspect. Compare full-coordinate before/after values, deltas, selected/changed/created/cleared counts and per-unit results. Later units see earlier proposed values. Supported effects are numeric batch, ordered numeric sequence, scoped numeric transform, text batch, supporting-detail replacement, composite batch and bounded expression calculations over private intermediate state. Calculation results are identified by result key and generation separately from raw facts. Typed application rules use these same units; member-list and calculated-member Tests inspect their evaluations. Unsupported effects or expression dependencies fail explicitly; a partial result is not a successful Test. A current Test covers at most 10,000 cells, 500 units and 100,000 statement visits, with a 16 MiB result and a 20-second impact budget. Results expire after 24 hours; submit a fresh Test to obtain new evidence.
5. Activate. Submit python.program.publish for the exact validated version through the registry tool, with validationBuildId identifying the specific sealed Validation or completed ImpactTest you inspected. That field is required for typed definitions. Activation grants that version permission to run; it does not execute the rule or make Test mandatory. A later change in business data means the earlier impact describes its original baseline.
6. Run. Use python.program.build with current pins and an existing execution delegation to build the active version with the intended parameters. Then submit python.program.run with that sealed Plan build ID. The fixed worker rechecks authority and the active version. Validation and ImpactTest build IDs are not runnable.
7. Inspect or cancel a Python workflow using its workflow ID. A separate build cancellation tool takes a build ID. Inspect checkpoints and committed units after cancellation. Earlier committed effects remain.

For facts.expression.calculate, the private Test supports bounded SourceAmount, exact amount/ratio literals, arithmetic, comparison and conditional expressions. Published-result inputs (PublishedAmount, PublishedRatio, PublishedUnitAmount), raw value/text lookups and unit-valued result generations are unsupported and fail explicitly. Do not treat a supported active Run as proof that its effect is covered by private Test.

Retain each request key while reconciling retries and lost responses. A new test or intended repeated run uses a new key. An ordinary Run evaluates current inputs; it is not a promise to apply a historical Test's exact differences.

Python prompt templates · Python tools · Authoring and execution architecture