NextGen APIs
NextGen APIs
Breadcrumbs

POST /integration/work-orders/permits/r1/permits

Http Verb

POST

Url

integration/work-orders/permits/r1/permits

Permissions required

Core Additional Parameters: Edit (fsm.core.additionalparameter.edit)

WO Configuration: View (fsm.core.workorder.configuration.view) or WO Configuration: Edit (fsm.core.workorder.configuration.edit)

Permits View Permission: fsm.core.wopermit.view

Permits View/Edit Permission: fsm.core.wopermit.view fsm.core.wopermit.edit

Last Modified Version

r1

Tech Tags


Available Async

No

BPMN Diagram (TBD)


Business Logic

This Integration API creates or updates the complete permit picture for a Work Order and, optionally, for its Operations.

One of code or externalCode must be present. If code is provided it has the precedence among the other fields.

System verifies Permission Required and starts the elaboration that is organized in steps.

STEP 1 - External System Validation

System takes Input fields and checks their existence in internal configuration.

API Verb: GET

Resource: External Systems

Input: externalSystemCode, active=true

Output: externalSystemId

If System can obtain the Output fields → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

STEP 2 - Work Order Existence

System takes Input fields and checks their existence in internal configuration.

API Verb: GET

Resource: Work Orders

Input: {workOrder.code} OR {externalSystemId, workOrder.externalCode}

Output: workOrderId, woOperationsAssignment, addressId

If System can obtain the Output fields → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

STEP 3 - Work Order Operation Existence

The following steps are executed for each WO Operations in Input.

System validates each workOrderOperations presents in Input.

API Verb: GET

Resource: Work Order Operations

Input: workOrderId, workOrderOperationCode

Output: workOrderOperationId

If System can obtain the target operation for every item in workOrderOperations → continue to next step.

If System can't obtain one target operation → responds with error. Elaboration is stopped.

Error Type:

STEP 4 - Permit Type Validation

System validates the Permit Type of each required permit received at Work Order level and Operation level.

API Verb: GET

Resource: Permit Types

Input: code

Output: permitTypeId

If System can obtain the Permit Type for every required permit item → continue to next step.

If System can't obtain the Permit Type → responds with error. Elaboration is stopped.

Error Type:

  • Others - see link in Resource

STEP 5 - Required Permit Validation

System searches an existing required permit using the business key composed by Work Order, optional Operation, Permit Type, Permit Code and Blocker flag.

API Verb: GET

Resource: Required Permits

Input: workOrderId, workOrderOperationId

Output: list of [id, deleted]

If System can obtain an existing required permit matching the business key and deleted = false or null (not present) → continue with update path in next step Required Permit on Update.

If System can't obtain an existing required permit matching the business key and deleted = false or null (not present) → continue with creation path in step Required Permit on Creation.

If System can obtain an existing required permit matching the business key and deleted = true → continue with de delete required permit path in step Required Permit on Deletion.

Error Type:

  • Others - see link in Resource

STEP 6 - Required Permit Management

STEP 6a - Required Permit on Update

System updates required permit record.

API Verb: PATCH

Resource: Required Permits

Input: code, description, institute, blocker

Output: Response State

If System can obtain the required permit identifier from creation or update → continue to next step.

If System can't create or update the required permit → responds with error. Elaboration is stopped.

Error Type:

  • Others - see link in Resource

STEP 6b - Required Permit on Creation

System creates required permit record.

API Verb: POST

Resource: Required Permits

Input: code, description, typeId, workorderId, workOrderOperationId, institute, blocker

Output: permitRequiredId, Response State

If System can obtain the required permit identifier from creation or update → continue to next step.

If System can't create or update the required permit → responds with error. Elaboration is stopped.

Error Type:

  • Others - see link in Resource

STEP 6c - Required Permit on Deletion

System deactives the required permit when it is no longer valid in the source system.

API Verb: DELETE

Resource: Required Permits

Input: permitRequiredId

Output: Response State

If System can obtain the required permit identifier from delete → deleted the required permit on Wo Header

If System can't delete the required permit → responds with error.

Error Type:

  • Others - see link in Resource

STEP 7 - Obtained Permit Validation

For each obtained permit of the current required permit, system searches an existing obtainment record through the related required permit and the practiceCode.

API Verb: GET

Resource: Obtained Permits

Input: list of [permitRequiredId]

Output: list of [id, requestDate, obtainedDate, deleted]

If System can obtain an existing obtained permit matching the related required permit and requestDate, obtainedDate, practiceCode, and deleted = false o or null → continue with update path in next step Obtained Permit Update.

If System can't obtain an existing obtained permit → continue with creation path in next step Obtained Permit Creation.

If System can obtain an existing obtained permit matching the related required permit and requestDate, obtainedDate,practiceCode, and deleted = true → continue with step Obtained Permit Deletion.

Error Type:

  • Others - see link in Resource

STEP 8 - Obtained Permit Management

STEP 8a - Obtained Permit Creation

System creates the obtained permit record.

API Verb: POST

Resource: /required/{permitRequiredId}/obtained

Input: permitRequiredId, practiceCode, notes, requestDate, obtainedDate, dueDate

Output: permitObtainedId, Response State

If Response State is SUCCESS → elaboration is stopped. See Response payload fields.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 8b - Obtained Permit Update

System updates the obtained permit record.

API Verb: PATCH

Resource: /required/{permitRequiredId}/obtained/{permitObtainedId}

Input: permitRequiredId, permitObtainedId, practiceCode, notes, requestDate, obtainedDate, dueDate, deleted flag handling

Output: Response State

If Response State is SUCCESS → elaboration is stopped. See Response payload fields.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 8c - Obtained Permit Deletion

The field deleted is used to logically deactivate the required permit when it is no longer valid in the source system.

API Verb: DELETE

Resource: /obtained/{permitObtainedId}

Input: permitObtainedId

Output: Response State

If Response State is SUCCESS → elaboration is stopped. See Response payload fields.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource


Query String Parameters

Start with a ? and includes parameters listed one after the another separated by &.

Not applicable.

Header Parameters

Parameters included in the request headers. Generally, request headers are used to keep authorization parameters.

Default.

Request Body Parameters

Request body parameters are used when clients send data to the API. They are shipped in a JSON Object only in POST, PUT, or PATCH requests.

 



Field

Description

Mandatory

Constraint




externalSystemCode

External system code

Y

Not Blank




workOrderCode

Internal Work Order code

N

Null or Not Blank




workOrderExternalCode

Work Order code in the external system

N

Null or Not Blank

requiredPermits

(minOccurs=0,

maxOccurs=N)



typeCode

Permit type business code

N




code

Permit code

N

Null or Not Blank



description

Permit description

N




institute

Institute requiring the permit

N




isBlocker

Flag indicating whether the permit blocks dispatching if not obtained

N




deleted

Flag indicating that the required permit must be deactivated

N


obtainedPermits

(minOccurs=0,

maxOccurs=N)


practiceCode

Business key of the obtained permit record

N

Null or Not Blank


practiceNotes

Notes for the obtained permit

N



permitRequestDate

Permit request date

N



permitObtainedDate

Permit obtained date

N



permitDueDate

Permit due date

N



deleted

Flag indicating that the obtained permit must be deactivated

N


workOrderOperations

(minOccurs=0,

maxOccurs=N)



workOrderOperationCode

Work Order Operation Code

N

Null or Not Blank

requiredPermits

(minOccurs=0,

maxOccurs=N)


typeCode

Permit type business code

N 

Null or Not Blank


code

Permit code

N



description

Permit description

N



institute

Institute requiring the permit

N



isBlocker

Flag indicating whether the permit blocks dispatching if not obtained

N



deleted

Flag indicating that the required permit must be deactivated

N


obtainedPermits

(minOccurs=0,

maxOccurs=N)

practiceCode

Business key of the obtained permit record

N

Null or Not Blank

practiceNotes

Notes for the obtained permit

N


permitRequestDate

Permit request date

N


permitObtainedDate

Permit obtained date

N


permitDueDate

Permit due date

N


deleted

Flag indicating that the obtained permit must be deactivated

N


The objects in input could have also the extension object that allows to add additional, customized data to this API. More info here How to use APIs: Custom data via Extension.

Request example

JSON
{
  "workOrderExternalCode": "400012345",
  "externalSystemCode": "SAP_S4HANA",
  "extension": {
    "sourceBatchId": "PERMIT_SYNC_20260625_01"
  },
  "requiredPermits": [
    {
      "typeCode": "HOT_WORK",
      "code": "HWP-2026-00451",
      "description": "Hot work permit for transformer maintenance",
      "institute": "Public Works",
      "isBlocker": true,
      "deleted": false,
      "obtainedPermits": [
        {
          "practiceCode": "PRC-88421",
          "practiceNotes": "Approved by safety officer",
          "permitRequestDate": "2026-06-20T08:15:00Z",
          "permitObtainedDate": "2026-06-21T09:30:00Z",
          "permitDueDate": "2026-06-30T23:59:59Z",
          "deleted": false
        }
      ]
    },
    {
      "typeCode": "TRAFFIC_CTRL",
      "code": "TCP-2026-00119",
      "description": "Traffic control authorization",
      "institute": "City of Oakland",
      "isBlocker": false,
      "deleted": true
    }
  ],
  "workOrderOperations": [
    {
      "workOrderOperationCode": "OP-0010",
      "requiredPermits": [
        {
          "typeCode": "SWITCHING",
          "code": "SWP-2026-01773",
          "description": "Switching authorization for operation 0010",
          "institute": "Grid Control",
          "isBlocker": true,
          "deleted": false,
          "obtainedPermits": [
            {
              "practiceCode": "SW-OK-991",
              "practiceNotes": "Control room confirmation",
              "permitRequestDate": "2026-06-20T07:45:00Z",
              "permitObtainedDate": "2026-06-20T07:50:00Z",
              "permitDueDate": null,
              "deleted": false
            }
          ]
        }
      ]
    }
  ]
}

Response documentation

Response payload fields

Compliant with RFC Standard https://www.rfc-editor.org/rfc/rfc9457.html

Extension fields:

Field

Description

Note

code

Extension member of a Problem Details Object that contains the error code

Only for ERROR

Response example

JSON
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "External system string does not exist",
  "instance": "/integration/work-orders/r1/work-orders",
  "code": "IA001_001"
}


Response error codes