Proposal: API Contract for Close Experiment with Mandatory Fields

1. Problem Statement

The DataRiver Facade endpoint POST /experiments/{eid}/close allows closing an experiment without signing. However, closing fails due to two blockers:

Blocker 1: Mandatory template fields

The template used by AutoLab includes required fields that must be populated before an experiment can be closed:

• pRED Experiment Start & End Dates → Start Date
• pRED Experiment Start & End Dates → End Date
• pRED Experiment Purpose

The Facade supports closing but does not expose the property update endpoint (PUT /entities/{eid}/properties) needed to populate these fields first. The AutoLab AAB (signals_close_experiment) has no way to set them.

Blocker 2: Race condition with async metadata job

The signals-legal-metadata job (operated by ORCA/LEM) runs in the background every 15 seconds. It scans newly created experiments to check the Cost Center field — if empty, it populates it with the appropriate value. This creates a race condition: the experiment cannot be closed until this metadata update completes. If the close is attempted before the job runs, it fails because Cost Center is still empty.

Current vs required flow

Current:  AAB calls close → Signals rejects (mandatory fields missing) → failure

Required: Wait for metadata job → populate mandatory fields → close → success

2. User Story

As a scientist using AutoLab to run automated workflows, I want to close my Signals experiment automatically when my workflow completes, so that the experiment is properly finalised with all required metadata without me having to manually go into Signals to fill in fields and click close.

Acceptance Criteria

1. The integration can read the current experiment state (including which fields are mandatory and which are already populated)
2. The integration can populate any missing mandatory fields with values provided by the workflow (or sensible defaults)
3. The integration can close the experiment after all mandatory fields are satisfied
4. If a mandatory field cannot be populated (no value available), the integration returns a clear error indicating which fields are missing (which)
5. The experiment’s audit trail correctly attributes the field updates and close action to the authenticated user

3. Proposed Flow

Key Points

• The flow runs entirely at the AutoLab consumer (AAB), not through an xRED proxy
• Phase 1 uses the DataRiver Facade (GET /experiments/{eid}/details) to read the experiment including its fields and digest
• Phase 2 handles the race condition with the signals-legal-metadata job — polls until Cost Center is populated (the job runs every ~15 seconds)
• Phase 3 uses the LEM API Proxy (Route 2 in ADR-005) because the property update endpoint is not in the DataRiver Facade. Populates Start Date, End Date, and Experiment Purpose.
• Phase 4 uses the DataRiver Facade (POST /experiments/{eid}/close)
• The digest from Phase 1/2 is passed to Phase 3 to handle concurrent editing (see the Signals REST API digest mechanism) (see the Signals REST API digest mechanism)

4. API Contract (OpenAPI)

4.1 Existing endpoints used

DataRiver Facade (Route 1):

LEM API Proxy (Route 2) — not in facade, requires LEM approval:

4.2 Property update request format

The native Signals PUT /entities/{eid}/properties endpoint expects:

{
  "data": [
    {
      "attributes": {
        "name": "Description",
        "value": "Automated experiment from AutoLab workflow XYZ"
      }
    },
    {
      "attributes": {
        "name": "Group",
        "value": "Research Team A"
      }
    }
  ]
}

The digest is passed as a query parameter: ?digest=60367023

4.3 Close experiment request format

The DataRiver Facade POST /experiments/{eid}/close expects:

{
  "data": {
    "attributes": {
      "reason": "Workflow completed successfully"
    }
  }
}

The reason field can be an empty string.

4.4 Error responses

5. Mandatory Fields

The pRED templates have mandatory fields at two different lifecycle stages. Both must be satisfied for the auto-close flow to succeed.

Fields required at experiment creation

Per the template analysis (AAB-1919 ), the pRED templates require these fields when creating the experiment:

These are handled by the AAB’s signals_create_experiment action. If the experiment was created correctly, these should already be populated at close time.

Fields required before closing

These fields are not set at creation and must be populated before the experiment can be closed:

Fields populated by background job (race condition)

The Cost Center field is populated asynchronously by ORCA’s legal metadata injection job. The integration must either wait for the job to complete or check that the field is populated before attempting to close. If the close is attempted within the first ~15 seconds of experiment creation, it may fail.

Summary: what must be true before close

All of the following must be satisfied:

1. Creation fields (Description, Group, etc.) — should already be set if created via SDK
2. Start Date, End Date, Experiment Purpose — must be explicitly set by the integration
3. Cost Center — must wait for async job to populate it
4. Digest — must be current (no concurrent modifications since last read)

6. What Needs to Happen

7. Enablement through Facade

Instead of using the LEM API Proxy for property updates, propose to DataRiver that they add either:

Option A: A new endpoint PUT /experiments/{eid}/properties to the facade (wrapping the native endpoint).

Option B: An enhanced close endpoint that accepts field values in the request body and populates them before closing — a single atomic operation:

{
  "data": {
    "attributes": {
      "reason": "Workflow completed",
      "fields": {
        "Description": "Automated experiment",
        "Group": "Research Team A",
        "Limited Access": false,
        "Limited Access Reason": "",
        "Portfolio Projects": "Project XYZ"
      }
    }
  }
}

Option B would be ideal as it avoids the digest race condition between update and close.