Teamwork Details via Core API

With the 24C update, this feature enables efficient retrieval of teamwork details within a specified timeframe through extended resource-related operations and a new, dedicated Core API operation. The primary objective is to provide a comprehensive view of teamwork compositions, including key information such as team leaders and members including mobile workers, vehicles, tools, and assigned skills.

The enhancement of existing resources-related API operations, provides the capability to identify resources as team holders or team participants. Additionally, a new Core API operation, 'Get a list of assistants' has been introduced. This API operation offers a detailed breakdown of team compositions for a specified period, including the aforementioned teamwork specifics.

The implementation of this feature simplifies the process of managing and monitoring teamwork, offering a convenient way to retrieve real-time data on the go. It caters to the needs of businesses that rely on dynamic team structures, especially those utilizing mobile workers, multiple resources, and skill sets.

Get list of resources that may be a team holder or participate in a team

The OFS REST API can obtain lists of resources using three Core API methods:

Get resources GET /rest/ofscCore/v1/resources
Get child resources GET /rest/ofscCore/v1/resources/{resourceId}/children
Get resource descendants GET /rest/ofscCore/v1/resources/{resourceId}/descendants

These three operations now accept additional query parameters:

New query parameters:

canBeTeamHolder(optional): boolean
canParticipateInTeam(optional): boolean

Usage example

GET /rest/ofscCore/v1/resources/OFS_GROUP/descendants?canBeTeamHolder=true

The above request will return all resources that are nested within the 'OFS_GROUP' node (e.g., Bucket or Organization Unit), specifically those with the 'Can be a team holder' parameter enabled.

Get a list of assistants

The new Core API operation returns the lists of assistants for a specified team holder and date range.

Get a list of assistants GET /rest/ofscCore/v1/resources/{resourceId}/assistants

List of assistants is date-specific and as such, needs to be requested for a particular date or date range. The operation searches all teamwork activities related to a specified team holder and returns the necessary information. Only teamwork activities with statuses 'pending', 'started', or 'en route' will be taken into account when compiling the list of assistants.

Path Parameters

resourceId: string

Query Parameters

dateFrom: string(date)
dateTo(optional): string(date)
resourceFields(optional): array
expand(optional): array

Response attributes

items: array

EXAMPLE

GET /rest/ofscCore/v1/resources/FR23-1121/assistants?dateFrom=2024-08-10&resourceFields=resourceType,name&expand=workSkills

"items": [

{

"date": "2024-08-10",

"assistants": [

{

"resourceDetails": {

"resourceId": "ext_id_1",

"resourceType": "FR",

"name": "Arndt, William",

"workSkills": {

"totalResults": 2,

"items": [

{

"workSkill": "sl_2",

"ratio": 100,

"active": true

{

"workSkill": "sl_7",

"ratio": 70,

"active": false

}

]

}

"teamWorkActivities": [

{

"activityId": 12229743,

"activityNumber": "A1223-2024",

"activityType": "TW",

"duration": 60,

"startTime": "2024-08-10 12:00:00"

{

"activityNumber": "A1223-2024",

"activityType": "TWREP",

"duration": 60

}

]

{

"resourceDetails": {

"resourceId": "ext_id_2",

"resourceType": "FR",

"workSkills": {

"totalResults": 502,

"links": [

{

"rel": "canonical",

"href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/resources/{resourceId}/workSkills?dateFrom=2024-08-10&dateTo=2024-08-10"

}

]

}

"teamWorkActivities": [

{

"activityId": 12229744,

"activityNumber": "A1224-2024",

"activityType": "TW",

"duration": 60,

"startTime": "2024-08-10 12:00:00"

{

"activityNumber": "A1223-2024",

"activityType": "TWREP",

"duration": 60

}

]

}

]

}

]

REST API Errors

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",

"title": "Bad Request",

"status": "400",

"detail": "The value '12024-01-26' is not a valid date in format 'YYYY-MM-DD'."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",

"title": "Bad Request",

"status": "400",

"detail": "Invalid request parameters: 'dateFrom' is greater than 'dateTo'. Values: '2024-01-26', '2024-01-20'."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",

"title": "Bad Request",

"status": "400",

"detail": "Invalid request parameters: 'dateFrom', 'dateTo'. Date interval contains more than 14 days."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10",

"title": "Bad Request",

"status": "409",

"detail": "The resourceId = 2 is not a teamholder."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10",

"title": "Bad Request",

"status": "400",

"detail": "Mandatory parameter is missing: 'dateFrom'."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",

"title": "Bad Request",

"status": "400",

"detail": "Invalid property value. Property: fields. Value: '{fieldName}'"

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10",

"title": "Conflict",

"status": "409",

"detail": "Too many assistances in one response (>100), try requesting smaller date range."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10",

"title": "Bad Request",

"status": "400",

"detail": "Action on past date is not allowed."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",

"title": "Bad Request",

"status": "400",

"detail": "The 'expand' value '{expand}' is not a valid value. The valid value is 'workSkills'."

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",

"title": "Bad Request",

"status": "400",

"detail": "Invalid query parameter value. Parameter: 'canParticipateInTeam'. Value: 'incorrect'. Valid values: 'true' or 'false'"

}

{

"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",

"title": "Bad Request",

"status": "400",

"detail": "Invalid query parameter value. Parameter: 'canBeTeamHolder'. Value: 'incorrect'. Valid values: 'true' or 'false'"

}

Business Benefit

Improved Efficiency: Quick retrieval of team details enables better oversight and efficient management of operations.
Informed Decision Making: Having a clear overview of team compositions allows for informed decisions about resource allocation and team assignments.
Real-Time Insights: Details about mobile workers, vehicles, and tools help optimize logistics and ensure up-to-date team compositions.

Steps to Enable

To use the API functions, the requesting application needs to be configured with appropriate permissions for Core API - Resource with at least read-only access.

Tips And Considerations

For the 'Get a list of assistants' operation:

To ensure optimal performance and response times, the operation has a limit of returning up to 100 assistants in a single response. In rare configurations with a large number of assistants, if this limit is exceeded, the API will respond with an error. To mitigate this, it is recommended to validate your use case and possibly reduce the number of dates requested.
The 'expand' parameter can be used to fetch the work skill list for each assistant. However, due to performance considerations, if an assistant has more than 500 active skills for a particular date, the API will provide a link structure instead, which can be followed for a detailed request of work skills for the specific resource and date.
Only teamwork activities with statuses 'pending', 'started', or 'en route' will be taken into account when compiling the list of assistants.