What API do I use to create/update bulk tasks?

Purpose:

This API is used to create or update tasks in bulk or individually within the Joyn FSM system. It supports metadata validation, template resolution, and schema enforcement before persisting records.

Highlights:

Create, update tasks to Joyn FSM in bulk or individually

API EndPoint

v1/api/task/bulk

Method:

POST

Request Format

Accepts a list of task JSON objects (array)
JSON must be sent in plain format
Maximum size of file should be less than 6 MB

Getting Started

To use the /api/task/bulk API for creating or updating tasks, the following setup and configurations are recommended:

Authentication
- The client must generate and provide a valid x-api-key or token to authenticate the API request.
Mandatory Field Requirements
- Ensure each task object includes all required fields like xid, asset, taskType and field.
- If global attributes are required, they must be provided in the correct format. Note that the global attributes' data will not be validated during processing.
Schema Validation
- All records are validated against internal schema definitions.
- Records missing required fields or having incorrect data types will be rejected.
Reference Entity Validation
- Referenced IDs (e.g., asset.id, taskType.id, field.id, etc.) must already exist in the system.
- The system supports validation against existing records and ensures consistent task creation.
Idempotency
- Use unique xid for each task to allow reprocessing without duplication.
- Updating a task with an existing xid will override its data.
Bulk Limit
- Recommended batch size: ≤ 200 tasks per request for optimal performance.

JSON structure

JSON

[
  {
    "field": {
      "xid": "string"
    },
    "asset": {
      "xid": "string",
      "type": "string"
    },
    "taskType": {
      "xid": "string"
    },
    "assigneeIds": {
      "userName": "string"
    },
    "linkedTasks": {
      "id": "string"
    },
    "score": 0,
    "increment": 0,
    "dueDate": "string",
    "description": "string",
    "workOrderNumber": "string",
    "source": "string",
    "parts": [
      {
        "picklist": {},
        "picklistOptionId": "string",
        "quantity": 0
      }
    ],
    "formSchema": {},
    "onlyAllowManualScoreUpdate": true,
    "xid": "",
    "id": "",
    "isDeleted": false,
    "approvalStatus": "approved",
    "approverIds": [
      "string"
    ],
    "requestorIds": [
      "string"
    ],
    "template": [
      {
        "field": {
          "xid": "string"
        },
        "asset": {
          "xid": "string",
          "type": "string"
        },
        "taskType": {
          "name": "string"
        },
        "data": {},
        "xid": "string",
        "isHardAssignee": false,
        "eventSource": "",
        "dependsOn": {
          "xid": "string"
        },
        "sameAssigneeAs": {
          "xid": "string"
        }
      }
    ],
    "approvedBy": "string",
    "approvedOn": "string",
    "status": "string",
    "priority": "string",
    "attachments": [
      {
        "bucket": "string",
        "key": "string",
        "region": "string"
      }
    ],
    "completedOn": "string",
    "parentTaskId": "string",
    "delayMinutes": 0,
    "duration": 0,
    "resolvedBy": "string",
    "resolvedOn": "string",
    "startTime": "string",
    "workflowStepId": "string",
    "workflowVersion": "string",
    "correlationId": "string"
  }
]

Mandatory Fields

#	Field	Guidance
1	xid	Unique identifier of the task. Required for updates
2	TaskType	`{ id: "..." }` or `{ xid: "..." }`, references task type
3	asset	`{ id: "..." }` or `{ xid: "..." }`, the asset associated with the task `"type":` is required
4	field	`{ id: "..." }`

Optional Fields

#	Field	Guidance
1	description	description of the tasks
2	assigneeIds	`{ id: "..." }` array of users
3	template	array of templates

Request Body

JSON

[
    {
        "field": {
            "id": "b0d4e7cb-581b-46a2-aecd-69577a539ee0"
        },
        "tenantId": "dadd20ab-afcb-4e31-bfca-ea181ad93023",
        
        
        "assigneeIds": {
            "id": "47e13db9-4e47-4c49-b7f9-5679a2c916ab"
        },
        "description": "TEST WES FROM API ",
        "xid": "28-04-2025-08:32AM",
        "globalAttributes": {
            "DetectionType": {
                "name": "Fixed Sensor - SOOFIE"
            },
            "DeviceName": "Device 1",
            "EmissionRate(MCFD)": "10 abc",
            "OccuredDateTime": "30th oct 2023 15:30",
            "ProbableSourceLocation": "abc"
        },
        "template": [
            {
                "field": {
                    "id": "b0d4e7cb-581b-46a2-aecd-69577a539ee0"
                },
                "tenantId": "dadd20ab-afcb-4e31-bfca-ea181ad93023",
                "asset": {
                    "id": "1cbc020f-314a-4086-8713-5c44c82f703f",
                    "type": "stop"
                },
                "taskType": {
                    "id": "fbbca00d-3426-460a-ac88-2aa277fb61d8"
                },
                "description": "TEST WES FROM API  ",
                "xid": "28-05-2025-08:10AM-01"
            }
        ]
    }
]

Example Response Format

JSON

{
    "success": true,
    "message": "Processed 1 items, Failed to process 0 items",
    "output": {
        "processedItems": [
            {
                "message": "Item got updated",
                "record": {
                    "__trace": "Task created from API",
                    "statusAudit": {
                        "openOn": "2025-04-30T07:30:04.816Z",
                        "undefinedOn": "2025-04-30T07:36:50.882Z",
                        "openFor": 6
                    },
                    "status": "open",
                    "tenantId": "dadd20ab-afcb-4e31-bfca-ea181ad93023",
                    "isDeleted": true,
                    "workflowVersion": "v1",
                    "createdBy": "sreerag.thodeti@yopmail.com",
                    "assigneeIds": [
                        {
                            "assigneeId": "47e13db9-4e47-4c49-b7f9-5679a2c916ab",
                            "isDeleted": false,
                            "vendorId": "ffec0370-6005-4cfa-9d67-7ce1ccf7148d"
                        }
                    ],
                    "originalPriority": "High",
                    "globalAttributes": {
                        "EmissionRate(MCFD)": "10 abc",
                        "DetectionType": {
                            "name": "Fixed Sensor - SOOFIE"
                        },
                        "ProbableSourceLocation": "abc",
                        "assigneevendorcontract": "2088865",
                        "Foreman": "Williams, Colt",
                        "usercontact": "+1 (682) 298-6552(mobile) :: 972-969-1788(work)",
                        "Rollupglobalattribute": 0,
                        "DeviceName": "Device 1",
                        "OccuredDateTime": "30th oct 2023 15:30",
                        "assigneecheckvendor": "4325560476"
                    },
                    "isPlanned": false,
                    "referenceStartTime": "2025-04-30T07:30:04.814Z",
                    "assetId": "1cbc020f-314a-4086-8713-5c44c82f703f",
                    "data": {
                        "s_deeplink_fdg": {
                            "reading_view_id": null
                        },
                        "s_timespent": 3600,
                        "s_desc": "TEST WES FROM API ",
                        "s_workordernumber": " ",
                        "s_name": "Emission Site Inspection"
                    },
                    "sendNotification": true,
                    "taskNumber": "PAT-EMDS1595",
                    "isRecurring": false,
                    "id": "d3d8691e-0607-44ee-a0bf-afdd8ae15ce5",
                    "duration": 60,
                    "watcherIds": [],
                    "fieldId": "b0d4e7cb-581b-46a2-aecd-69577a539ee0",
                    "timeToNextPriority": 1,
                    "priority": "High",
                    "isParent": true,
                    "attachments": [],
                    "taskTypeId": "74d4a562-7aae-4164-b90c-2af228c8e473",
                    "xid": "28-04-2025-08:32AM",
                    "startTime": "2025-04-30T07:30:04.814Z",
                    "endTime": "2025-04-30T08:30:04.815Z",
                    "onlyAllowManualScoreUpdate": false,
                    "createdOn": "2025-04-30T07:30:04.814Z",
                    "modifiedOn": "2025-04-30T07:36:50.882Z",
                    "formData": {},
                    "priorityScore": null,
                    "eventSource": "API",
                    "linkedTaskIds": [],
                    "description": "TEST WES FROM API ",
                    "modifiedBy": "sreerag.thodeti@yopmail.com",
                    "template": [
                        {
                            "tenantId": "dadd20ab-afcb-4e31-bfca-ea181ad93023",
                            "description": "TEST WES FROM API template 28 vaishnavi",
                            "xid": "28-05-2025-08:10AM-01",
                            "globalAttributes": {
                                "C_COSTCENTER_TASK": "1050507274",
                                "Foreman": "Williams, Colt",
                                "FOREMAN_TASK_PRACT": "Emission Inspection - Thermographer",
                                "ForemanArea": "BIG LAKE",
                                
                            },
                            "workflowStepId": "2c79f1fe-716f-41bc-8ac0-d92abb7f1032",
                            "fieldId": "b0d4e7cb-581b-46a2-aecd-69577a539ee0",
                            "assetId": "1cbc020f-314a-4086-8713-5c44c82f703f",
                            "taskTypeId": "fbbca00d-3426-460a-ac88-2aa277fb61d8"
                        }
                    ]
                }
            }
        ],
        "unProcessedItems": []
    }
}

Error Handling

Our API uses standard HTTP status codes to indicate the success or failure of a request.

**Common Error Codes:** -

Code	Description
400 Bad Request	The request was invalid.
401 Unauthorized	Authentication failed.
404 Not Found	The requested resource was not found.
500 Internal Server Error	An error occurred on the server.

Error Response:
{"success":false,"message":"Some error message"}

Sample Validation Errors in API Failure

Error Message	Potential Issue
ValidationError : asset with id '...' not found in data base	Provided asset ID does not exist in the system.
SchemaError : "asset.type" is required	Required attribute `type` inside `asset` is missing.
SchemaError : "value" must contain at least one of [id, xid]	Provided field expects at least one of `id` or `xid`, but both are missing.
ValidationError : field object not present in the record to create	A required field like `field`, `taskType`, or `asset` is missing in the task payload.

Checks / Validations

#	Validation	Description
1	Schema validation	Ensures required fields are present and match types
2	Entity resolution	Validates presence of related entities like asset, taskType, assignee
3	Duplicate check	Checks against existing DB using `xid`, `asset`, and `taskType`
4	Single active task validation	For taskTypes with `singleActiveTask = true`, enforces no overlap
5	Template schema validationtype of value provided	If `template` is present, ensures each item matches expect

Current Limitations

#	Limitation
1	In a single API payload only one kind of entity should be present.
2	Tasks with unresolved or invalid references (e.g., missing asset/taskType/asset) will fail.
3	Partial updates to templates are not supported—template must be passed fully.
4	Duplicate `xid` values across payloads will result in validation failure.

Setup Requirements

#	Requirement
1	`x-api-key` and authorization headers must be present.
2	Tenant ID must be inferred from context or included in headers if required by implementation.
3	For `singleActiveTask = true`, the system will enforce that only one such task can exist concurrently.
4	Task types, assets, and users must exist in the system before creating tasks that reference them.
5	Ensure that global attribute definitions are configured for the task type if using dynamic metadata.