Atomic “All-or-None” GraphQL mutation for multi-step Concept create/update (timeouts + partial writes)

[filiperochalopes]

Summary

Creating or updating a Concept in OCL via the current workflow requires multiple sequential requests (e.g., create concept → add names → add descriptions → add mappings). When any one request fails (often due to timeouts or slow processing), the Concept ends up partially written on the OCL side (missing pieces). This is increasingly common and forces manual repair/retry logic client-side.

We need a single GraphQL mutation that can validate and apply a batch of concept actions atomically (all succeed or none persist), while returning the final, real-time Concept representation.

Problem

Current behavior

• The client performs multiple REST calls (or multiple GraphQL calls) for a single logical operation:
  • Create concept
  • Add/update Names
  • Add/update Descriptions
  • Add/update Mappings
  • (and potentially other “concept extras”)
• Each action hits a different endpoint.
• Failures occur mid-flight:
  • Timeouts / slow processing
  • 5xx (some already addressed by PRs)
  • 4xx from validations (client side issues; expected - I solved most of it, though)
• Result: partial state on OCL (concept created, but incomplete), which is hard to recover from reliably and leads to inconsistent UI/UX.

Why bulk import is not a fit

• Bulk import queues work and is not real-time.
• The client needs to immediately display the final resolved Concept after the action completes (no background queue).

Expected behavior

• The client sends one request describing all intended actions.
• Server performs:
  1. Validation of all actions (including permissions, schema validation, domain rules)
  2. If validation passes, apply all actions in a single atomic transaction
  3. Return the final Concept (or a structured error report if validation fails)
• If any action fails, no partial writes remain.

Proposed solution

Add a GraphQL mutation that accepts a list of concept operations to be executed atomically.

Mutation name

conceptBulkActions

Signature (proposal)

NOTE: naming/types can be aligned with existing GraphQL conventions in OCL.

type Mutation {
  conceptBulkActions(id: Int, input: [ConceptBulkActionInput!]!): ConceptBulkActionsPayload!
}

• If id is provided → treat as update for that concept.
• If id is not provided → treat as create, and return the created concept id/URI.

Input type

input ConceptBulkActionInput {
  uri: String!          # e.g. "/orgs/CIEL/sources/CIEL/HEAD/concepts/..."
  method: HttpMethod!   # POST | PUT | PATCH | DELETE
  body: JSON            # request payload
}

Where uri would include paths such as:

• /orgs/CIEL/sources/CIEL/HEAD/concepts/ (create concept)
• /orgs/CIEL/sources/CIEL/HEAD/concepts/{concept_id}/names/
• /orgs/CIEL/sources/CIEL/HEAD/concepts/{concept_id}/descriptions/
• /orgs/CIEL/sources/CIEL/HEAD/concepts/{concept_id}/mappings/
• etc.

Payload type

type ConceptBulkActionsPayload {
  ok: Boolean!
  conceptId: Int
  conceptUri: String
  concept: Concept
  errors: [ConceptBulkActionError!]
  results: [ConceptBulkActionResult!]
}

• errors should be present when ok=false, and contain per-action details.
• results may optionally contain per-action status/metadata when ok=true.

Example supporting types:

type ConceptBulkActionError {
  index: Int!           # index of the input action that failed
  uri: String!
  method: HttpMethod!
  statusCode: Int
  message: String!
  details: JSON
}

type ConceptBulkActionResult {
  index: Int!
  uri: String!
  method: HttpMethod!
  statusCode: Int!
  response: JSON
}

Execution model

Validation-first + atomic apply

Implementation should ensure “all-or-none” semantics:

1. Parse & validate all actions (schema + domain validation + permissions)
2. Resolve target concept:
   • If id is null → create concept object in memory (or staged)
   • If id provided → fetch and lock the concept for update
3. Execute actions within a single DB transaction:
   • If any action fails → rollback transaction
4. Return:
   • ok=true + final Concept
   • or ok=false + per-action error details (no DB changes persisted)

Real-time response requirement

Mutation must return the final resolved concept (including names/descriptions/mappings added by the action list) so the client can immediately display it.

Example request (create)

mutation CreateConceptAtomic($input: [ConceptBulkActionInput!]!) {
  conceptBulkActions(input: $input) {
    ok
    conceptId
    conceptUri
    concept { id displayName ... }
    errors { index message statusCode uri }
  }
}

Variables:

{
  "input": [
    {
      "uri": "/orgs/CIEL/sources/CIEL/HEAD/concepts/",
      "method": "POST",
      "body": { "concept_class": "Diagnosis", "datatype": "N/A", "names": [] }
    },
    {
      "uri": "/orgs/CIEL/sources/CIEL/HEAD/concepts/{newConceptId}/names/",
      "method": "POST",
      "body": { "name": "Example", "locale": "en", "name_type": "Fully Specified" }
    },
    {
      "uri": "/orgs/CIEL/sources/CIEL/HEAD/concepts/{newConceptId}/mappings/",
      "method": "POST",
      "body": { "map_type": "SAME-AS", "to_concept_url": "..." }
    }
  ]
}

The server can support a placeholder mechanism for {newConceptId} during execution (e.g., a token like $created.id), or apply actions after the initial create step while still remaining inside the same transaction.

Example request (update)

mutation UpdateConceptAtomic($id: Int!, $input: [ConceptBulkActionInput!]!) {
  conceptBulkActions(id: $id, input: $input) {
    ok
    conceptId
    concept { id displayName ... }
    errors { index message statusCode uri }
  }
}

Acceptance criteria

• ✅ One mutation performs create/update + related sub-resource mutations in one request.
• ✅ No partial writes: if any sub-action fails, DB state remains unchanged.
• ✅ Returns the final, real-time Concept representation upon success.
• ✅ Provides structured per-action errors upon failure (including index + endpoint).
• ✅ Works for both create (no id) and update (id provided).
• ✅ Eliminates client-side “repair” logic for partial writes caused by timeouts.

Notes / open questions

• How should placeholders be handled for create-then-append actions (e.g., referencing created concept id within the same input list)?
• Should the mutation accept higher-level structured input (names/descriptions/mappings arrays) instead of generic uri/method/body? (Generic is simpler to map from existing client behavior; structured is safer/cleaner long-term.)
• Do we want to expose a generic “execute internal REST endpoints” mechanism, or implement a dedicated concept-specific atomic mutation only?

Proposed next steps

1. Confirm whether maintainers prefer:
   • A generic uri/method/body executor, or
   • A concept-specific structured input model
2. Implement server-side transaction + validation strategy
3. Add tests for:
   • Timeout simulation / mid-flight failure
   • 4xx validation failure
   • 5xx internal failure
   • Successful create and update flows
4. Open PR with GraphQL schema + resolver + tests

Request for feedback

Would maintainers accept a PR implementing this mutation (conceptBulkActions) to provide atomic “all-or-none” semantics for concept create/update workflows and eliminate partial writes caused by timeouts/slow processing?

[filiperochalopes]

That's how I do it now on my CIEL Lab API

Create concept

{
    "query": "\n  mutation OclApiRequest($requests: [OclApiRequestInput!]!) {\n    oclApiRequest(requests: $requests) {\n      success\n      statusCode\n      message\n      data\n    }\n  }\n",
    "variables": {
        "requests": [
            {
                "method": "create_concept",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "payload": {
                        "concept_class": "Diagnosis",
                        "datatype": "N/A",
                        "external_id": "2ffb272c-63ea-458e-8160-1ffb27ee522f",
                        "names": [
                            {
                                "name": "Metabolic syndrome",
                                "locale": "en",
                                "locale_preferred": true,
                                "name_type": "FULLY_SPECIFIED",
                                "external_id": "09c122dc-cae2-4f98-9ad4-1cb3b1b448bb"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

Update the just created concept

{
    "query": "\n  mutation OclApiRequest($requests: [OclApiRequestInput!]!) {\n    oclApiRequest(requests: $requests) {\n      success\n      statusCode\n      message\n      data\n    }\n  }\n",
    "variables": {
        "requests": [
            {
                "method": "update_concept",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "concept_id": "118543",
                    "payload": {
                        "concept_class": "Diagnosis",
                        "datatype": "N/A",
                        "names": [
                            {
                                "name": "Metabolic syndrome",
                                "locale": "en",
                                "locale_preferred": true,
                                "name_type": "FULLY_SPECIFIED"
                            }
                        ]
                    }
                }
            },
            {
                "method": "add_concept_name",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "concept_id": "118543",
                    "payload": {
                        "name": "Sindrome metabólica",
                        "locale": "pt",
                        "locale_preferred": false,
                        "external_id": "fd70ad7b-42f4-4d37-8571-754c850b4409"
                    }
                }
            },
            {
                "method": "add_concept_description",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "concept_id": "118543",
                    "payload": {
                        "description": "DEF: Fator de risco associado para problemas cardiovasculares REF: https://www.heart.org/ DESC: Pensamos em critérios como PREVENT",
                        "locale": "pt",
                        "external_id": "ce07fc12-abfd-48d8-b98a-8ea5226f0bd5",
                        "locale_preferred": false
                    }
                }
            },
            {
                "method": "create_mapping",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "payload": {
                        "map_type": "SAME-AS",
                        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
                        "to_concept_code": "237602007",
                        "external_id": "e645e492-bbb7-4e47-ba4f-02559a79ef85",
                        "to_source_url": "/orgs/CIEL/sources/SNOMED-CT/"
                    }
                }
            },
            {
                "method": "update_concept_extra",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "concept_id": "118543",
                    "field_name": "is_set",
                    "value": true
                }
            },
            {
                "method": "update_concept_extra",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "concept_id": "118543",
                    "field_name": "Definition(ce07fc12-abfd-48d8-b98a-8ea5226f0bd5)",
                    "value": "Fator de risco associado para problemas cardiovasculares"
                }
            },
            {
                "method": "update_concept_extra",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "concept_id": "118543",
                    "field_name": "Description(ce07fc12-abfd-48d8-b98a-8ea5226f0bd5)",
                    "value": "Pensamos em critérios como PREVENT"
                }
            },
            {
                "method": "update_concept_extra",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "concept_id": "118543",
                    "field_name": "Reference(ce07fc12-abfd-48d8-b98a-8ea5226f0bd5)",
                    "value": "https://www.heart.org/"
                }
            },
            {
                "method": "create_mapping",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "payload": {
                        "map_type": "CONCEPT-SET",
                        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
                        "to_concept_code": "115115",
                        "sort_weight": 0,
                        "external_id": "29c77913-4d23-4dba-9729-a8b188bf50f9",
                        "to_source_url": "/orgs/CIEL/sources/CIEL/"
                    }
                }
            },
            {
                "method": "create_mapping",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "payload": {
                        "map_type": "CONCEPT-SET",
                        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
                        "to_concept_code": "117399",
                        "sort_weight": 1,
                        "external_id": "57a13dfb-474b-4153-a482-cab334072fe6",
                        "to_source_url": "/orgs/CIEL/sources/CIEL/"
                    }
                }
            },
            {
                "method": "create_mapping",
                "payload": {
                    "org": "CIEL",
                    "source": "CIEL",
                    "payload": {
                        "map_type": "CONCEPT-SET",
                        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
                        "to_concept_code": "159644",
                        "sort_weight": 2,
                        "external_id": "eef197b4-3257-4656-8e04-d09abc8209d8",
                        "to_source_url": "/orgs/CIEL/sources/CIEL/"
                    }
                }
            }
        ]
    }
}

That's what it means on OCL API

# Create the base concept

curl -X POST "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/" \
    -H "Authorization: Token <OCL_API_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
      "concept_class": "Diagnosis",
      "datatype": "N/A",
      "external_id": "2ffb272c-63ea-458e-8160-1ffb27ee522f",
      "names": [
        {
          "name": "Metabolic syndrome",
          "locale": "en",
          "locale_preferred": true,
          "name_type": "FULLY_SPECIFIED",
          "external_id": "09c122dc-cae2-4f98-9ad4-1cb3b1b448bb"
        }
      ]
    }'

# Update the base concept

    curl -X PUT "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/" \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "concept_class": "Diagnosis",
        "datatype": "N/A",
        "names": [
          {
            "name": "Metabolic syndrome",
            "locale": "en",
            "locale_preferred": true,
            "name_type": "FULLY_SPECIFIED"
          }
        ]
      }'
  - Add the Portuguese name:

    curl -X POST "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/names/" \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Sindrome metabólica",
        "locale": "pt",
        "locale_preferred": false,
        "external_id": "fd70ad7b-42f4-4d37-8571-754c850b4409"
      }'
 
# Add the Portuguese description:

    curl -X POST "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/
  descriptions/" \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "description": "DEF: Fator de risco associado para problemas cardiovasculares REF:
  https://www.heart.org/ DESC: Pensamos em critérios como PREVENT",
        "locale": "pt",
        "external_id": "ce07fc12-abfd-48d8-b98a-8ea5226f0bd5",
        "locale_preferred": false
      }'

# Add the SNOMED mapping:

    curl -X POST "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/mappings/"
  \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "map_type": "SAME-AS",
        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
        "to_concept_code": "237602007",
        "external_id": "e645e492-bbb7-4e47-ba4f-02559a79ef85",
        "to_source_url": "/orgs/CIEL/sources/SNOMED-CT/"
      }'

# Add the first concept-set mapping (115115):

    curl -X POST "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/mappings/"
  \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "map_type": "CONCEPT-SET",
        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
        "to_concept_code": "115115",
        "sort_weight": 0,
        "external_id": "29c77913-4d23-4dba-9729-a8b188bf50f9",
        "to_source_url": "/orgs/CIEL/sources/CIEL/"
      }'
  - Add the second concept-set mapping (117399):

    curl -X POST "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/mappings/"
  \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "map_type": "CONCEPT-SET",
        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
        "to_concept_code": "117399",
        "sort_weight": 1,
        "external_id": "57a13dfb-474b-4153-a482-cab334072fe6",
        "to_source_url": "/orgs/CIEL/sources/CIEL/"
      }'

# Add the third concept-set mapping (159644):

    curl -X POST "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/mappings/"
  \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "map_type": "CONCEPT-SET",
        "from_concept_url": "/orgs/CIEL/sources/CIEL/concepts/118543/",
        "to_concept_code": "159644",
        "sort_weight": 2,
        "external_id": "eef197b4-3257-4656-8e04-d09abc8209d8",
        "to_source_url": "/orgs/CIEL/sources/CIEL/"
      }'

# Patch the is_set extra flag:

    curl -X PATCH "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/extra/" \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "is_set": true
      }'

# Patch the definition extra:

    curl -X PATCH "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/extra/" \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "Definition(ce07fc12-abfd-48d8-b98a-8ea5226f0bd5)": "Fator de risco associado para
  problemas cardiovasculares"
      }'

# Patch the description extra:

    curl -X PATCH "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/extra/" \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "Description(ce07fc12-abfd-48d8-b98a-8ea5226f0bd5)": "Pensamos em critérios como PREVENT"
      }'

# Patch the reference extra:

    curl -X PATCH "https://api.openconceptlab.org/orgs/CIEL/sources/CIEL/concepts/118543/extra/" \
      -H "Authorization: Token <OCL_API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "Reference(ce07fc12-abfd-48d8-b98a-8ea5226f0bd5)": "https://www.heart.org/"
      }'