Skip to content

Add erp5_form_read and erp5_form_write dev tools for ERP5 Forms

Cédric Le Ninivin requested to merge feature/form-write-tool into master

This description follows ASD-STE100 Simplified Technical English.

Summary

This MR adds two dev tools: erp5_form_read and erp5_form_write. erp5_form_read reads an ERP5 Form from one skin folder as Formulator XML. erp5_form_write creates a new ERP5 Form with its settings, fields, values and TALES. The tools are registered in dev mode only (erp5-mcp-portalmanager). A new dev guide manage_skin_forms gives the procedure.

Why

  • Agents could not create a Formulator form through the MCP.
  • The agent-side route (Zope cookie, then an HTTP PUT) was blocked.
  • objectIds has no docstring. Zope does not publish it (404). The location check uses absolute_url.

What the tools do

erp5_form_read:

  1. Find the form with <folder>/<id>/absolute_url.
  2. Read the XML with manage_FTPget.
  3. Return sha256, groups, fields and unresolved method values. Return the XML inline or save it with save_to_path.

erp5_form_write (create=true only):

  1. Build the XML on a local copy of a new form. Run all guards. Send no HTTP before this step passes.
  2. Check the location with absolute_url.
  3. Send the addERP5Form POST.
  4. Read the new empty form with manage_FTPget. Add the settings and fields.
  5. Check the location again. Send one PUT of the form XML.
  6. Read the form back and compare it with the intended XML.

dry_run=true does steps 1 and 2 only. It sends no POST and no PUT.

Guards

  • The tool refuses an existing form. Update is not supported.
  • The tool refuses a form id that resolves to an object in another folder or the portal root (shadow). allow_shadow=true permits it.
  • The tool refuses a core skin folder. allow_core_folder=true permits it.
  • The tool sends no PUT unless the form is in the folder just before the PUT. A PUT on a missing id creates another document.
  • The create POST holds submit. Without submit, addERP5Form does not create the form.
  • A method value must be a plain identifier. manage_FTPget gives a repr text for a method value.
  • A list value must be a Python literal list (ast.literal_eval). A list of lists is written as a list of tuples.
  • The tool removes <messages> on a ProxyField. Formulator XMLToForm drops the delegated_list when <messages> is present.
  • The tool refuses <groups> without <group>, a DOCTYPE, an ENTITY and a bt5 <ZopeData> root.
  • The tool refuses a form XML above ERP5_FORM_MAX_BYTES (default 2 MB) before any HTTP request.
  • Settings use an allow-list. unicode_mode must be false. row_length must be an integer.
  • The tool removes <edit_order>. XMLToForm stores its text [] as a string.
  • The read-back compare reports a mismatch for values, TALES, delegated_list, group, type and settings.
  • Method values are reported as unverifiable, not as a mismatch. The read-back gives a repr text for them.
  • Each error after the POST has created=true.
  • When save_to_path fails after the PUT, the tool gives the XML inline with save_error.

Tests

All HTTP is mocked. The suite has 494 tests (473 before this MR). The new form tests are in test_erp5_mcp.py.

Guard or behaviour Test
POST holds submit test_create_cls_263
absent, here, shadow (read) test_404_is_absent, test_read_here_returns_xml_inline, test_acquired_form_is_not_read
absent, here, shadow (write) test_create_cls_263, test_existing_form_refused, test_acquired_id_is_shadow_and_refused, test_shadow_allowed_with_flag
No PUT unless "here" before the PUT test_no_put_when_form_not_here_before_put, test_create_checks_location_three_times
Method plain identifier, measured repr test_measured_method_repr_refused_and_unresolved, test_measured_repr_as_method_value_refused_without_http
Method values unverifiable test_measured_repr_in_readback_is_unverifiable
<messages> strip on ProxyField test_messages_stripped_on_proxy_field_only
List literal_eval, tuples kept test_list_value_literal_eval, test_list_of_lists_kept_as_tuples
<groups> without <group> test_groups_without_group_refused
DOCTYPE, ENTITY, ZopeData test_zopedata_and_doctype_refused, test_entity_or_doctype_alone_refused, test_read_refuses_zopedata
Size limit before HTTP test_too_large_form_sends_no_post
Settings allow-list, unicode_mode test_settings_allow_list, test_setting_refused
<edit_order> removal test_cls_263_builds_expected_xml
Mismatch on values, TALES, settings test_tool_value_and_tales_mismatch, test_compare_tales_mismatch, test_lost_setting_is_a_mismatch
created=true after the POST test_created_true_on_every_error_after_post (5 cases), test_ftpget_failure_after_post_says_created
dry_run sends nothing test_dry_run_sends_nothing
save_to_path failure after PUT test_bad_save_path_after_put_answers_inline
Dev-only registration test_form_tools_registered_in_dev_mode_only
CLS-263 GadgetField case test_create_cls_263, test_cls_263_builds_expected_xml

Eight guards were removed one at a time to prove the tests. Each removal made its test fail. The code was then restored. The guards were: POST submit, the location check before the PUT, the shadow refusal, the method plain-identifier rule, the unverifiable rule, the <messages> strip, created=true on a PUT failure and the dev-only registration.

Live smoke

The smoke test ran on dev on 2026-10-07.

  1. erp5_form_read on ArtificialTaskModule_viewPurchasePackingListReviewList gave unresolved=["listbox.list_method"].
  2. The measured method text was <Products.Formulator.MethodField.Method object at 0x7f201821f450 oid 0xeeb0d in <Connection at 7f2032936350>>.
  3. erp5_form_write created ArtificialTask_viewPurchasePackingListReviewClassic (GadgetField, 3 TALES).
  4. The result was status=created, verified=true, mismatches=[], unverifiable=[].
  5. erp5_form_read after the create gave the same sha256.
  6. The live test ran 28 tests. The result was OK.
  7. On that instance, objectIds gave 404 for each skin folder. The absolute_url check replaces it.

Limits and follow-ups

  • The tools only create a form. There is no update mode yet.
  • There is no expected_sha256 check. An update mode must add it.
  • erp5_skin_list uses objectIds and has the same 404. A separate MR must fix it.
  • Upstream Formulator XMLToForm.py:106 reuses the name entry in the <message> loop. This drops the delegated_list. The tool removes <messages> on a ProxyField as a workaround. An upstream fix is necessary.
  • The tool does not change a Business Template. Export the form to the bt5 after the check.
Edited by Cédric Le Ninivin

Merge request reports