NextGen APIs
NextGen APIs
Breadcrumbs

GET /integration/workforce/r1/timesheets/resources-interventions

Http Verb

GET

Url

/integration/workforce/r1/timesheets/resources-interventions

Permissions required

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

Organizational Structure Entities: View (fsm.core.structure.view)

Resource Configuration: View (fsm.core.resource.configuration.view)

WorkOrder: View (fsm.core.workorder.view)

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

Outcome Configuration (fsm.core.workorder.accounting.configuration.edit)

Last Modified Version

r1

Tech Tags


Available Async

No

BPMN Diagram

diagram (40).svg

Business Logic

This Integration API return a list of resource interventions in .

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

Pagination is managed for the Resource entity.

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 - Operation Center Validation and Retrieve

System takes Input fields and checks their existence.

API Verb: GET

Resource: Operation Centers

Input: operationCenterCode, active=true, _language

Output: operationCenterId, operationCenterDescription

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 - Resource Retrieve

System takes Input fields and checks their existence.

This section is used only if input fields identificationNumber and/or secondaryIdentificationNumber are present.

API Verb: GET

Resource: Resources

Input: identificationNumber, secondaryIdentificationNumber, operationCenterId, _page, _order

Output: resourceId, name, surname, email, mobilePhone, identificationNumber, secondaryIdentificationNumber, operationCenterId, workCenterId, extension

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:

  • Others - see link in Resource

STEP 4 - Intervention Status Transcode

System takes Input fields and gets the resource.

This step is skipped if input field are absent.

API Verb: GET

Resource: Intervention Status

Input: list of [code]

Output: list of [id, code, description]

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:

  • Others - see link in Resource

STEP 5 - Resources Interventions Retrieve

System takes Input fields and checks their existence.

If Step Resource Retrieve has been performed, then also Input ‘resourceIds’ is populated.

System takes Input fields and checks their existence.

API Verb: GET

Resource: Interventions Resources

Input: dateRange.from=calendarDate.from, dateRange.to=calendarDate.to, teamLeader, interventionRangeType (default='ACTUAL'), statusId (default=2), resourceIds, _page, operationCenterId

Output: list of interventionId

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

If System can’t obtain the Output fields → Return an empty array and the elaboration is stopped.

Error Type:

  • Others - see link in Resource

STEP 6 - Intervention Retrieve

System takes Input fields and checks their existence.

API Verb: GET

Resource: Interventions

Input: list of interventionId

Output: list of [interventionId, foremanId, statusId, workOrderOperationId,startDate(=expectedStartDate), endDate(=expectedEndDate)]

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 7 - Intervention Outcome Retrieve

System takes Input fields and checks their existence.

API Verb: GET

Resource: Interventions Outcomes

Input: list of interventionId

Output: list of [interventionOutcome, outcomeReasonId, encodedNoteId]

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 8 - Outcome Reasons Retrieve

System takes Input fields and checks their existence. System calls this API to enrich Intervention Outcomes.

This step is skipped if input fields are absent.

API Verb: GET

Resource: Outcome Reasons

Input: list of outcomeReasonsId

Output: list of [code, description]

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 9 - Encoded Note Retrieve

System takes Input fields and checks their existence. System calls this API to enrich Intervention Outcomes.

This step is skipped if input fields are absent.

API Verb: GET

Resource: Encoded Notes

Input: list of encodedNoteId

Output: list of [code, description]

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 10 - Resource Accounted Hours Retrieve

System takes Input fields and checks their existence.

System calls this API to obtain resourceAccountedHours and the list of resourceId and workOrderOperationId.

API Verb: GET

Resource: Resources Accounted Hours

Input: list of interventionId

Output: list of [workShiftId, spentTime, takeInChargeDate, arrivalDate, outcomeStartDate, outcomeEndDate, workingHourTypeId, note, resourceId]

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:

  • Others - see link in Resource

STEP 11 - Resource Retrieve

System takes Input fields and checks their existence.

System calls this API to enrich both resourceAccountedHours with the list of resources and the main list of resources.

API Verb: GET

Resource: Resources

Input: list if resourceId

Output: list of [name, surname, email, mobilePhone, identificationNumber, secondaryIdentificationNumber, operationCenterId, workCenterId]

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 12 - Work Center Retrieve

System takes Input fields and checks their existence. System calls this API to enrich the main list of resources.

API Verb: GET

Resource: Work Centers

Input: list of workCenterId

Output: list of [code, description]

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 13 - Work Order Operations Retrieve

System takes Input fields and checks their existence.

API Verb: GET

Resource: Operations

Input: list of workOrderOperationId

Output: list of [code, description, typeId, activityId, workOrderId]

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 14 - Work Order Retrieve

System takes Input fields and checks their existence.

System extracts unique work order ids from work order operations list.

API Verb: GET

Resource: Work Orders

Input: list of workOrderId

Output: list of [operationCenterId, externalCode, description, typeId, 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 15 - Work Order Operation Types Retrieve

System takes Input fields and checks their existence. System extracts unique work order operation type ids from work order operation list.

System calls this API to enrich workOrderOperations.

API Verb: GET

Resource: Operation Types

Input: list of operationTypeId

Output: list of [code, description]

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 16 - Activity Retrieve

System takes Input fields and checks their existence. System extract unique activityIds from work order operation list.

System calls this API to enrich workOrderOperations.

API Verb: GET

Resource: Activities

Input: list of activityId

Output: list of [code, description]

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 17 - Work Order Types Retrieve

System takes Input fields and checks their existence. System extract unique work order type ids from work order list.

System calls this API to enrich workOrders.

API Verb: GET

Resource: Types

Input: list of typeId

Output: list of [code, description]

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 18 - Addresses Retrieve

System takes Input fields and checks their existence. System extracts address ids from work orders list.

System calls this API to enrich workOrders.

API Verb: GET

Resource: Addresses

Input: list of addressesId

Output: list of [description, countryCode, districtCode, municipality, municipalityCode, locality, postalCode, street, streetNumber, streetNumberExtension, floor, lot, staircase, apartment, directions, yCoordinate, xCoordinate, toponym, targetId]

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 19 - Service Types Retrieve

System takes Input fields and checks their existence. System extracts unique service type ids from work order list.

System calls this API to enrich workOrderTypes.

API Verb: GET

Resource: Service Types

Input: list of serviceTypeId

Output: list of [code, description]

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 20 - Request Types Retrieve

System takes Input fields and checks their existence. System extract unique request type ids from work order list.

System calls this API to enrich workOrderTypes and then workOrders.

API Verb: GET

Resource: Request Types

Input: list of requestTypeId

Output: list of [code, description]

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 21 - Work Order Operation Center Retrieve

System takes Input fields and checks their existence.

API Verb: GET

Resource: Operation Centers

Input: list of [workOrder.operationCenterId]

Output: list of [operationCenterCode, operationCenterDescription]

If System can obtain the Output fields → elaboration is stopped. See Response payload fields

If System can’t obtain the Output fields → elaboration is stopped. See Response payload fields

Error Type:


Path Parameters

Not present.

Query String Parameters

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

Field

Description

Mandatory

Constraint

1

_page

Object for pagination

N

Null or Not Blank

2

_order

Specify a collection of strings representing the desired fields and direction of resources. Inner objects, such as workShifts and unavailabilities will not be ordered.

N

Null or Not Blank

3

_language

Language option for the response. It supports the following values: - ALL: Request the server to return every possible translation of the response data. - USER

N

Null or Not Blank

4

_exclude

Allows to specify a subset of data that need to be excluded from the response

N

Null or Not Blank

5

_fields

Allows to specify a subset of data that need to be returned

N

Null or Not Blank

6

externalSystem

External system code

Y

Not Blank

7

operationCenterCode

Operation center code

Y

Not Blank

8

interventionStatusCode

List of intervention status code

(Default CLOSED)

N

Null or Not Blank

9

calendarDate

Interval of date (from-to) of resource calendar for filtering

Y

Not Blank

10

identificationNumber

Identification Number of resource

N

Null or Not Blank

11

secondaryIdentificationNumber

Alternative Identification Number of resource

N

Null or Not Blank

12

teamLeader

Flag that allows to retrive only interventions in which the resource has been team leader

N

Not Blank

13

interventionRangeType

Allows to define the conditions a

(default='ACTUAL')pplied by calendarDate filter.

(default='AC

(default='ACTUAL')TUAL')

N

Null or Not Blank

14

extension

Used to filter for extension

N

Null or Not Blank

Header Parameters

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

Default.

Request Example 

{baseUrl}/integration/timeesheets/r1/resources-interventions?externalSystemCode=SAP&identificationNumber=MI0030&calendarDate=from,2024-04-17T00:00:00.000Z,to,2024-04-20T00:00:00.000Z&operationCenterCode=OC61&teamLeader=true

Response documentation

Response payload fields





Field

Field Type

Description






resourceId


Id of resources






name


First name of the resource






surname


Surname of the resource






email


E-mail address of the resource






mobilePhone


Phone number of the resource






identificationNumber


Identification Number of the resource






secondaryIdentificationNumber


Secondary Identification Number of the resource






operationCenter

operationCenterObject

Operation Center of the resource






workCenter

workCenterObject

Work Center of the resource


workOrders




id


Work Order Id





externalCode


External Code





description


Work Order Description





operationCenter

operationCenterObject

Operation Center of the work order





address

addressObject

Work Order Address





type

workOrderTypeObject

Work Order Type


workOrders

operations



id


Work Order Operation Id





code


Work Order Operation Code





description


Work Order Operation Description





type

workOrderOperationTypeObject

Work Order Operation Type





activity

activityObject

Operation Activity


workOrders

operations

interventions


id


Intervention Id





takeInChargeDate


Intervention Take In Charge Date





arrivalDate


InterventOutcome ion Arrival Date





startDate


Inte Outcomervention Outcome Start Date





endDate


Intervention Outcome End Date





validationDate


Intervention Validation Date





notes


Intervention Note





status

interventionStatusObject

Intervention Status





reason

outcomeReasonObject

Intervention outcome Reaste






expectedStartDate


Intervention Expected Start Date





expectedEndDate


Intervention Expected End Date





encodedNote

encodedNoteObject

Intervention Encoded Note







expectedStartDate


Intervention Expected Start Date






expectedEndDate


Intervention Expected End Date


workOrders

operations

interventions

resources

resourceId


Id of resources





name


Resource Name





surname


Resource Surname





identificationNumber


Resource Identification Number





secondaryIdentificationNumber


Resource Secondary Identification Number





foreman


Describes if resource is team leader





workShiftId


Work Shift Id





spentTime


Time Spent on Intervention





takeInChargeDate


Take in Charge Date





arrivalDate


Arrival Date





outcomeStartDate


Outcome Start Date





outcomeEndDate


Outcome End Date





workingHourTypeId


Working Hour Type





note


Note


operationCenterObject

Field

Description

1

code

Code

2

description

Description

workCenterObject

Field

Description

1

code

Code

2

description

Description

addressObject

Field

Description

1

description

Description

2

countryCode

Country Code

3

districtCode

District Code

4

municipality

Municipality

5

municipalityCode

Municipality Code

6

locality

Locality

7

postalCode

Postal Code

8

street

Street

9

streetNumber

Street Number

10

streetNumberExtension

Street Number Extension

11

floor

Floor

12

lot

Lot

13

staircase

Stair Case

14

apartament

Apartment

15

direction

Direction

16

yCoordinate

Y Coordinate

17

xCoordinate

X Coordinate

18

toponym

Toponym

workOrderTypeObject

Field

Description

1

code

Code

2

description

Description (with language supports)

3

requestType

requestTypeObject

4

serviceType

serviceTypeObject

requestTypeObject

Field

Description

1

code

Code

2

description

Description (with language supports)

serviceTypeObject

Field

Description

1

code

Code

2

description

Description (with language supports)

workOrderOperationTypeObject

Field

Description

1

code

Code

2

description

Description (with language supports)

activityObject

Field

Description

1

code

Code

2

description

Description

outcomeReasonObject

Field

Description

1

code

Code

2

description

Description (with language supports)

encodedNoteObject

Field

Description

1

code

Code

2

description

Description (with language supports)

interventionStatusObject

Field

Description

1

code

Code

2

description

Description



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

Response example 

{
    "extension": {},
    "content": [
        {
            "extension": {},
            "resourceId": 3681,
            "name": "John",
            "surname": "Doe",
            "email": "john.doe@example.com",
            "mobilePhone": "+123456789",
            "identificationNumber": "JD3681",
            "identificationNumber2": "JD3681",
            "operationCenter": {
                "extension": {},
                "code": "ED-CMT",
                "description": [
                    {
                        "lang": "en",
                        "value": "ELEC Metro"
                    }
                ]
            },
            "workCenter": {
                "extension": {},
                "code": "WCN61",
                "description": [
                    {
                        "lang": "en",
                        "value": "Metro workCenter"
                    }
                ]
            },
            "workOrders": [
                {
                    "extension": {},
                    "id": 50220,
                    "operationCenter": {
                        "extension": {},
                        "code": "ED-CMT",
                        "description": [
                            {
                                "lang": "en",
                                "value": "ELEC Metro"
                            }
                        ]
                    },
                    "type": {
                        "extension": {},
                        "code": "CMP_CPD-SDIP-L91",
                        "description": [
                            {
                                "lang": "en",
                                "value": "CMP_CPD-SDIP-L91-SDGE Internally Planned"
                            }
                        ],
                        "requestType": {
                            "extension": {},
                            "code": "GD11",
                            "description": [
                                {
                                    "lang": "en",
                                    "value": "GD11 - SDG Inspection - Field"
                                }
                            ]
                        },
                        "serviceType": {
                            "extension": {},
                            "code": 612,
                            "description": [
                                {
                                    "lang": "en",
                                    "value": "Pipeline"
                                }
                            ]
                        }
                    },
                    "externalCode": "510000932037-0010",
                    "description": "Unplanned Outage",
                    "address": {
                        "extension": {},
                        "description": "MORENA BLVD & TAYLOR ST",
                        "countryCode": "US",
                        "municipality": "SAN DIEGO",
                        "postalCode": 92038,
                        "street": "MORENA BLVD & TAYLOR ST",
                        "streetNumber": 14,
                        "yCoordinate": 32.758306,
                        "xCoordinate": -117.197321
                    },
                    "operations": [
                        {
                            "extension": {},
                            "id": 5164,
                            "code": "CMP_CPD-SDIP-L91",
                            "description": "L91 Internally Planned",
                            "type": {
                                "extension": {},
                                "code": "DEFUALT",
                                "description": [
                                    {
                                        "lang": "en",
                                        "value": "Default Operation"
                                    }
                                ]
                            },
                            "activity": {
                                "extension": {},
                                "code": "VALVE",
                                "description": [
                                    {
                                        "lang": "en",
                                        "value": "Pipeline Valve Inspection"
                                    }
                                ]
                            },
                            "interventions": [
                                {
                                    "extension": {},
                                    "id": 1521,
                                    "takeInChargeDate": "2024-10-11T15:00:00Z",
                                    "arrivalDate": "2024-10-11T15:30:00Z",
                                    "startDate": "2024-10-11T16:00:00Z",
                                    "endDAte": "2024-10-11T17:30:00Z",
                                    "validationDate": "2024-10-11T18:30:00Z",
                                    "notes": "No problem detected",
                                    "status": {
                                        "extension": {},
                                        "code": "CLOSED",
                                        "description": "Closed"
                                    },
                                    "reason": {
                                        "extension": {},
                                        "code": "COMPLETED",
                                        "description": [
                                            {
                                                "lang": "en",
                                                "value": "Completed"
                                            }
                                        ]
                                    },
                                    "resources": [
                                        {
                                            "extension": {},
                                            "resourceId": 3681,
                                            "name": "Jon",
                                            "surname": "Snow",
                                            "identificationNumber": "JD3681",
                                            "identificationNumber2": "JD3681",
                                            "foreman": false,
                                            "workShiftId": 14,
                                            "spentTime": 90,
                                            "takeInChargeDate": "2024-10-11T15:00:00Z",
                                            "arrivalDate": "2024-10-11T15:30:00Z",
                                            "outcomeStartDate": "2024-10-11T16:00:00Z",
                                            "outcomeEndDAte": "2024-10-11T17:30:00Z",
                                            "workingHourTypeId": 1,
                                            "note": "No issue"
                                        },
                                        {
                                            "extension": {},
                                            "resourceId": 300,
                                            "name": "Arya",
                                            "surname": "Stark",
                                            "identificationNumber": "JD3000'",
                                            "identificationNumber2": "JD3000",
                                            "foreman": true,
                                            "workShiftId": 1443,
                                            "spentTime": 90,
                                            "takeInChargeDate": "2024-10-11T15:00:00Z",
                                            "arrivalDate": "2024-10-11T15:30:00Z",
                                            "outcomeStartDate": "2024-10-11T16:00:00Z",
                                            "outcomeEndDAte": "2024-10-11T17:30:00Z",
                                            "workingHourTypeId": 1,
                                            "note": "Nothing to report"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "_page": {
        "num": 0,
        "hasMore": false
    }
}

Error example

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

Response error codes