NextGen APIs

POST /work-orders/execution/r1/interventions/{interventionId}/outcomes

Http Verb

POST

Url

/work-orders/execution/r1/interventions/{interventionId}/outcomes

Permissions required

FROM W32026 (FSM 24.0) WO Accounting: Edit (fsm.core.workorder.accounting.edit)

Personally Identifiable Information (PII)

No

Sensitive Information

No

Last Modified Version

r1 - 2025 W2 (FSM 20.0)

Released since

2024 W3 (FSM 18.0)

Deprecated since


Removed since


Tech Tags


Business Logic

This API inserts an outcome for the intervention with the given interventionId. To retrieve the interventionId, call the API at GET /work-orders/execution/r1/interventions.

This API manages intervention outcomes for interventions that are not CLOSED.

This API updates information related to:

Preconditions

Compared to the historical functionality provided by the user interface, the API currently omits the following management functions:

  • Management of booking operations → outcomes for booking operations are not supported. If the intervention refers to a booking operation, the API returns error WORKORDERS_ORCHESTRATOR_029

  • Management of pre-distributed work orders

  • Management of external systems

  • Alignment of materials by intervention group

  • Deletion of procedure instances

  • Management of permits

Process

We will refer to interventionFromInputId as the intervention record whose intervention.id equals interventionId in this API's path parameter.

Examples:

    • interventionFromInputId.workOrderOperationId is the workOrderOperationId field of the intervention record where intervention.id = interventionId passed as this API's path parameter.

    • interventionFromInputId.outcome.startDate is the startDate of the interventionOutcome linked to the intervention with id = interventionId provided as the API path parameter.

Steps

  1. Retrieve related intervention records:

    • Fetch all related intervention records with interventions.workOrderOperationId = interventionFromInputId.workOrderOperationId

    • Check whether at least one accounted intervention already exists by filtering the list:

      • interventions.startDate > startDate

      • interventions.outcome.reasonId is not null

      • interventions.status is 'CANCELLED' or 'CLOSED'

    • If at least one record is found, return error ALREADY_ACCOUNTED_INTERVENTION.

  2. Check booking operation
    If the work order operation related to interventionFromInputId.workOrderOperationId is a booking operation, return error WORKORDERS_ORCHESTRATOR_029

  3. Set dates:

    • Start Date:

      • If startDate is not null, set interventionFromInputId.outcome.startDate = startDate.

      • Otherwise, get interventionFromInputId.startDate.

        • If interventionFromInputId.startDate <= Date.now, set interventionFromInputId.outcome.startDate = interventionFromInputId.startDate.

      • Check for other related interventions not yet accounted for, filtering by:

        • interventions.startDate < interventionFromInputId.startDate

        • interventions.outcome.reasonId is null

      • If a record is found on previous point, overwrite interventionFromInputId.outcome.startDate with the startDate of the found intervention record.

    • End Date:

      • If endDate is not null, set interventionFromInputId.outcome.endDate = {endDate}.

      • Otherwise, if interventionFromInputId.endDate <= Date.now, set interventionFromInputId.outcome.endDate = interventionFromInputId.endDate.

    • Additional validations

      • If interventionFromInputId.outcome.startDate >interventionFromInputId.outcome.endDate return ERROR.

      • If interventionFromInputId.outcome.endDate > now return ERROR.

      • if interventionFromInputId.outcome.arrivalOnSiteDate is not null, if yes return ERROR. If not:

        • Check if interventionFromInputId.outcome.takeInChargeDate < interventionFromInputId.outcome.arrivalOnSiteDate. If yes return E

      • if interventionFromInputId.outcome.arrivalOnSiteDate is not null, if yes return ERROR. If not:

        • Check if interventionFromInputId.outcome.arrivalOnSiteDate > interventionFromInputId.outcome.endDate. If yes, return ERROR.

      • if reasonId.mandatoryEncodedNote = true:

  4. Save outcome and update Work Order Operation and Work Order:

    • Validate Status:

      • We are managing intervention outcomes related to interventions in status not CLOSED.

      • If interventionFromInputId.status is not 'CLOSED' and interventionFromInputId.workOrderOperationId.status is 'CLOSED' or 'CANCELLED', return error INVALID_WO_OPERATION_STATUS.

    • Validate Measures (FSM 20.0):

    • Save outcome:

    • Update Work Order Operation:

      • Retrieve and update the workOrderOperation related to interventionFromInputId.workOrderOperationId:

        • Status ID: Update interventionFromInputId.workOrderOperationId.statusId based on interventionFromInputId.outcome.reasonId.outcomeTypeId.

        • Current Duration: Update interventionFromInputId.workOrderOperationId.currentDuration

        • Progress Percentage: Calculate and update interventionFromInputId.workOrderOperationId.progressPercentage.

        • Outcome Count: Update interventionFromInputId.workOrderOperationId.outcomeCount by counting all related intervention records where intervention.outcome.reasonId is null.

        • Last Outcome Intervention ID: Set interventionFromInputId.workOrderOperationId.lastOutcomeInterventionId = interventionFromInputId

        • Last Outcome Reason ID: Set interventionFromInputId.workOrderOperationId.lastOutcomeReasonId = interventionFromInputId.outcome.reasonId.

        • Last Outcome Date: Set interventionFromInputId.workOrderOperationId.lastOutcomeDate = interventionFromInputId.endDate.

        • Last Outcome Origin ID: Set interventionFromInputId.workOrderOperationId.lastOutcomeOriginId = interventionFromInputId.originId.

        • Last Outcome User ID: Set interventionFromInputId.workOrderOperationId.lastOutcomeUserId to the user ID of the caller.

    • Update Work Order:

      • Retrieve and update the work order related to the most recent work order operation (which sould be interventionFromInputId.workOrderOperationId).
        If no operation has an outcome, the last outcome data of the work order is cleared.

        • Last Outcome Reason ID: Set interventionFromInputId.workOrderOperationId.workOrderId.lastOutcomeReasonId = interventionFromInputId.workOrderOperationId.lastOutcomeReasonId.

        • Last Outcome Date: Set interventionFromInputId.workOrderOperationId.workOrderId.lastOutcomeDate =interventionFromInputId.workOrderOperationId.lastOutcomeDate.

        • Last Outcome Origin ID: Set interventionFromInputId.workOrderOperationId.workOrderId.lastOutcomeOriginId=interventionFromInputId.workOrderOperationId.lastOutcomeOriginId.

        • Last Outcome User ID: Set interventionFromInputId.workOrderOperationId.workOrderId.lastOutcomeUserId =interventionFromInputId.workOrderOperationId.lastOutcomeUserId.

      • Recalculates the work order status



Path Parameters

Field

Note

interventionId

 

Header Parameters

Default.

Request Body Parameters

Field

Validations

Note

takeInChargeDate

Mandatory → it can be specified in the body or by previously calling the taking-charge API POST /work-orders/execution/r1/interventions/{interventionId}/taking-charge


arrivalDate

Mandatory → it can be specified in the body or by previously calling the arrival-on-site API


startDate

Mandatory → it can be specified in the body or by previously calling the running API TODO


endDate

Mandatory


reasonId

Mandatory

Referenced resource id existance check


encodedNoteId

Referenced resource id existance check


validationDate



validationStatusId

Referenced resource id existance check


notes

Max length: 4000


originId

Mandatory

Referenced resource id existance check


Response documentation

Response payload fields

Field

Note

Example value

payload

 

 

Response error codes

NOT_FOUND, BASE_0001, BASE_0003, BASE_0012, WORKORDERS_ORCHESTRATOR_001, WORKORDERS_ORCHESTRATOR_002, WORKORDERS_ORCHESTRATOR_005