Jobs: scheduling and lifecycle
Set a typed job assignee
/a/Job_setUserIdAndType
Assign a job to a tenant user or outsource and perform the corresponding handover workflow.
When to use this endpoint
Use the typed inline picker and timeline assignment workflow. This changes persisted assignment; it is not a user lookup.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Legacy edit-restriction bit 128 is enforced; client administrators retain the existing admin exception.
The primary job selection is tenant-scoped. There is no automatic schedule-conflict or assignee-ownership check. Cross-tenant follow-ups use persisted outsourcing context.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Positive active job ID. |
user_id | Integer string | Yes | Nonnegative ID. 0 means unassigned only for type 0. Positive type-0 users must be active in this tenant; type-1 IDs must be actively linked outsource companies. |
user_type | Integer string | No | Defaults to 0 tenant user; 1 outsource company. Unsupported values and type 1 with ID 0 are rejected. |
email_removed | Integer flag | No | Exactly 1 calls the removal-email helper after saving, using the PREVIOUS assignee and typed old/new snapshot. Default 0. An unchanged assignment returns before this step. |
Example request
$result = FM_api('Job_setUserIdAndType', [
'id' => '1042', 'user_id' => '27', 'user_type' => '0',
'email_removed' => '1',
]);Example response
{"ok":1}An unchanged ID/type pair returns {"ok":1,"warning":"no update necessary"}. Failed/uncertain optional removal mail retains ok and adds an Assignment saved warning; inspect mail history before retrying.
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"missing or invalid parameter: user_id"} | Missing/negative assignee. |
{"error":"no such job exists"} | Missing/deleted job. |
{"error":"Failed to update job assignment"} | Primary assignment write returned false. |
{"error":"tenant job does not exist"} | An old outsourced copy could not be cancelled; the local assignment may already be saved. |
{"error":"Invalid job assignee"} | Invalid type/ID or missing/inactive tenant user. |
{"error":"you are not linked to that outsource client"} | No active outgoing link for the type-1 target. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Enforces the legacy edit restriction with client-admin exception and validates supported typed targets before mutation.
- Before a changed assignment, status 4 is passed to Job_statusChange as a reopen-to-0 request; that result is ignored. Records previousUser and typed assignment snapshots.
- An old type-1 assignment with complete outsourced metadata cancels its remote copy through Workflow_updateTenantJobStatus and removes the local outsourced metadata. A new type-1 assignment attempts Outsourcing_sendJob; that return value is ignored.
- Changing between tenant users withdraws the new user's removal marker and logs the old user's removal when numeric IDs differ. Assigning a tenant user queues assigned/reassigned cron; it does not directly call Job_emailAbout.
- email_removed targets old assignment context. The standalone Jobs_emailRemoved route instead reads the CURRENT job assignee.
Side effects
- Writes assignment/history and sync edit metadata; changes mobile-removal markers, queues assignment snapshots, and recalculates job costs.
- May cancel/create cross-tenant jobs. Optional removal mail uses job_on_remove notification settings and returns a saved warning on uncertainty.
See it in Fieldmotion
CRM1
Click the User column in Jobs or drag between timeline rows. jobUserShow.js sends email_removed=1 and displays a returned warning; the timeline does not request removal mail.
CRM2
Drag a job between users/outsources in Jobs Timeline or Assets Timeline. After a date move, the caller issues this as a separate request; the two requests are not one transaction.
Related endpoints
Job_setUserIdsets a tenant-user assignee.Jobs_setUseruses the legacy bulk assignment workflow.Jobs_emailRemoveduses current context for standalone removal mail.