Share via

Job Router Operations - Upsert Job

  • Reference
Service:
Communication
API Version:
2023-11-01

Creates or updates a router job.

PATCH {endpoint}/routing/jobs/{jobId}?api-version=2023-11-01

URI Parameters

Name In Required Type Description
endpoint
 path True

string

Uri of your Communication resource
jobId
 path True

string

Id of a job.
api-version
 query True

string

The API version to use for this operation.

Request Header

Media Types: "application/merge-patch+json"

Name Required Type Description
If-Match

string

The request should only proceed if an entity matches this string.
If-Unmodified-Since

string

date-time-rfc7231

The request should only proceed if the entity was not modified after this time.

Request Body

Media Types: "application/merge-patch+json"

Name Type Description
channelId

string

The channel identifier. eg. voice, chat, etc.
channelReference

string

Reference to an external parent context, eg. call ID.
classificationPolicyId

string

Id of a classification policy used for classifying this job.
dispositionCode

string

Reason code for cancelled or closed jobs.
labels

A set of key/value pairs that are identifying attributes used by the rules engines to make decisions. Values must be primitive values - number, string, boolean.
matchingMode JobMatchingModeCreateOrUpdate:

If provided, will determine how job matching will be carried out. Default mode: QueueAndMatchMode.
notes

RouterJobNote[]

Notes attached to a job, sorted by timestamp.
priority

integer

Priority of this job. Value must be between -100 to 100.
queueId

string

Id of a queue that this job is queued to.
requestedWorkerSelectors

RouterWorkerSelector[]

A collection of manually specified worker selectors, which a worker must satisfy in order to process this job.
tags

A set of non-identifying attributes attached to this job. Values must be primitive values - number, string, boolean.

Responses

Name Type Description
200 OK

RouterJob

The request has succeeded.

Headers

  • ETag: string
  • Last-Modified: string
201 Created

RouterJob

The request has succeeded and a new resource has been created as a result.

Headers

  • ETag: string
  • Last-Modified: string
Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Examples

Creates a new job
Creates a new scheduled router job
Updates a router job

Creates a new job

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/jobs/JobId?api-version=2023-11-01

{
  "channelId": "CustomChatChannel",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "queueId": "MainQueue",
  "priority": 5,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true
    }
  ],
  "labels": {},
  "matchingMode": {
    "kind": "queueAndMatch"
  }
}

Sample response

Status code:
200 
{
  "id": "JobId",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "status": "queued",
  "enqueuedAt": "2021-09-30T23:59:04.5311999+00:00",
  "channelId": "CustomChatChannel",
  "classificationPolicyId": null,
  "queueId": "MainQueue",
  "priority": 5,
  "dispositionCode": null,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true,
      "expiresAfterSeconds": null
    }
  ],
  "attachedWorkerSelectors": [],
  "labels": {},
  "assignments": {},
  "notes": [],
  "matchingMode": {
    "kind": "queueAndMatch"
  },
  "etag": "etag"
}
Status code:
201 
{
  "id": "JobId",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "status": "queued",
  "enqueuedAt": "2021-09-30T23:59:04.5311999+00:00",
  "channelId": "CustomChatChannel",
  "classificationPolicyId": null,
  "queueId": "MainQueue",
  "priority": 5,
  "dispositionCode": null,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true,
      "expiresAfterSeconds": null
    }
  ],
  "attachedWorkerSelectors": [],
  "labels": {},
  "assignments": {},
  "notes": [],
  "matchingMode": {
    "kind": "queueAndMatch"
  },
  "etag": "etag"
}

Creates a new scheduled router job

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/jobs/JobId?api-version=2023-11-01

{
  "channelId": "CustomChatChannel",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "queueId": "MainQueue",
  "priority": 5,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true
    }
  ],
  "labels": {},
  "matchingMode": {
    "kind": "scheduleAndSuspend",
    "scheduleAt": "2023-05-26T23:22:12.0774222+00:00"
  }
}

Sample response

Status code:
200 
{
  "id": "JobId",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "status": "queued",
  "enqueuedAt": "2021-09-30T23:59:04.5311999+00:00",
  "channelId": "CustomChatChannel",
  "classificationPolicyId": null,
  "queueId": "MainQueue",
  "priority": 5,
  "dispositionCode": null,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true,
      "expiresAfterSeconds": null
    }
  ],
  "attachedWorkerSelectors": [],
  "labels": {},
  "assignments": {},
  "notes": [],
  "matchingMode": {
    "kind": "scheduleAndSuspend",
    "scheduleAt": "2023-05-26T23:22:12.0774222+00:00"
  },
  "scheduledAt": null,
  "etag": "etag"
}
Status code:
201 
{
  "id": "JobId",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "status": "queued",
  "enqueuedAt": "2021-09-30T23:59:04.5311999+00:00",
  "channelId": "CustomChatChannel",
  "classificationPolicyId": null,
  "queueId": "MainQueue",
  "priority": 5,
  "dispositionCode": null,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true,
      "expiresAfterSeconds": null
    }
  ],
  "attachedWorkerSelectors": [],
  "labels": {},
  "assignments": {},
  "notes": [],
  "matchingMode": {
    "kind": "scheduleAndSuspend",
    "scheduleAt": "2023-05-26T23:22:12.0774222+00:00"
  },
  "scheduledAt": null,
  "etag": "etag"
}

Updates a router job

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/jobs/8780b28c-7079-4de1-9143-4d369289e958?api-version=2023-11-01

{
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af"
}

Sample response

Status code:
200 
{
  "id": "383541b3-5637-4af6-8aac-3391da8a578a",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "status": "queued",
  "enqueuedAt": "2021-09-30T23:59:04.5311999+00:00",
  "channelId": "CustomVoiceChannel",
  "classificationPolicyId": null,
  "queueId": "MainQueue",
  "priority": 5,
  "dispositionCode": null,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true,
      "expiresAfterSeconds": null
    }
  ],
  "attachedWorkerSelectors": [],
  "labels": {},
  "assignments": {},
  "notes": [],
  "matchingMode": {
    "kind": "queueAndMatch"
  },
  "etag": "etag"
}
Status code:
201 
{
  "id": "383541b3-5637-4af6-8aac-3391da8a578a",
  "channelReference": "1d5896f3-8b54-40be-82d3-910323f5e2af",
  "status": "queued",
  "enqueuedAt": "2021-09-30T23:59:04.5311999+00:00",
  "channelId": "CustomVoiceChannel",
  "classificationPolicyId": null,
  "queueId": "MainQueue",
  "priority": 5,
  "dispositionCode": null,
  "requestedWorkerSelectors": [
    {
      "key": "Sales",
      "labelOperator": "equal",
      "value": true,
      "expiresAfterSeconds": null
    }
  ],
  "attachedWorkerSelectors": [],
  "labels": {},
  "assignments": {},
  "notes": [],
  "matchingMode": {
    "kind": "queueAndMatch"
  },
  "etag": "etag"
}

Definitions

Name Description
Azure.Core.Foundations.Error

The error object.
Azure.Core.Foundations.ErrorResponse

A response containing error details.
Azure.Core.Foundations.InnerError

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
JobMatchingModeKind

Discriminators for supported matching mode types.
LabelOperator

Describes supported operations on label values.
QueueAndMatchMode

Describes a matching mode where matching worker to a job is automatically started after job is queued successfully.
QueueAndMatchModeCreateOrUpdate

Describes a matching mode where matching worker to a job is automatically started after job is queued successfully.
RouterJob

A unit of work to be routed
RouterJobAssignment

Assignment details of a job to a worker.
RouterJobCreateOrUpdate

A unit of work to be routed
RouterJobNote

A note attached to a job.
RouterJobStatus

Describes the various status of a job.
RouterWorkerSelector

Describes a condition that must be met against a set of labels for worker selection.
RouterWorkerSelectorStatus

Describes the status of a worker selector.
ScheduleAndSuspendMode

Describes a matching mode used for scheduling jobs to be queued at a future time. At the specified time, matching worker to a job will not start automatically.
ScheduleAndSuspendModeCreateOrUpdate

Describes a matching mode used for scheduling jobs to be queued at a future time. At the specified time, matching worker to a job will not start automatically.
SuspendMode

Describes a matching mode where matching worker to a job is suspended.
SuspendModeCreateOrUpdate

Describes a matching mode where matching worker to a job is suspended.

Azure.Core.Foundations.Error

The error object.

Name Type Description
code

string

One of a server-defined set of error codes.
details

Azure.Core.Foundations.Error[]

An array of details about specific errors that led to this reported error.
innererror

Azure.Core.Foundations.InnerError

An object containing more specific information than the current object about the error.
message

string

A human-readable representation of the error.
target

string

The target of the error.

Azure.Core.Foundations.ErrorResponse

A response containing error details.

Name Type Description
error

Azure.Core.Foundations.Error

The error object.

Azure.Core.Foundations.InnerError

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
code

string

One of a server-defined set of error codes.
innererror

Azure.Core.Foundations.InnerError

Inner error.

JobMatchingModeKind

Discriminators for supported matching mode types.

Name Type Description
queueAndMatch

string

Discriminator value for QueueAndMatchMode.
scheduleAndSuspend

string

Discriminator value for ScheduleAndSuspendMode.
suspend

string

Discriminator value for SuspendMode.

LabelOperator

Describes supported operations on label values.

Name Type Description
equal

string

Equal.
greaterThan

string

Greater than.
greaterThanOrEqual

string

Greater than or equal.
lessThan

string

Less than.
lessThanOrEqual

string

Less than or equal.
notEqual

string

Not Equal.

QueueAndMatchMode

Describes a matching mode where matching worker to a job is automatically started after job is queued successfully.

Name Type Description
kind string:

queueAndMatch

The type discriminator describing a sub-type of JobMatchingMode.

QueueAndMatchModeCreateOrUpdate

Describes a matching mode where matching worker to a job is automatically started after job is queued successfully.

Name Type Description
kind string:

queueAndMatch

The type discriminator describing a sub-type of JobMatchingMode.

RouterJob

A unit of work to be routed

Name Type Description
assignments

<string,  RouterJobAssignment>

A collection of the assignments of the job. Key is AssignmentId.
attachedWorkerSelectors

RouterWorkerSelector[]

A collection of worker selectors attached by a classification policy, which a worker must satisfy in order to process this job.
channelId

string

The channel identifier. eg. voice, chat, etc.
channelReference

string

Reference to an external parent context, eg. call ID.
classificationPolicyId

string

Id of a classification policy used for classifying this job.
dispositionCode

string

Reason code for cancelled or closed jobs.
enqueuedAt

string

Timestamp a job was queued in UTC.
etag

string

The entity tag for this resource.
id

string

Id of a job.
labels

A set of key/value pairs that are identifying attributes used by the rules engines to make decisions. Values must be primitive values - number, string, boolean.
matchingMode JobMatchingMode:

If provided, will determine how job matching will be carried out. Default mode: QueueAndMatchMode.
notes

RouterJobNote[]

Notes attached to a job, sorted by timestamp.
priority

integer

Priority of this job. Value must be between -100 to 100.
queueId

string

Id of a queue that this job is queued to.
requestedWorkerSelectors

RouterWorkerSelector[]

A collection of manually specified worker selectors, which a worker must satisfy in order to process this job.
scheduledAt

string

If set, job will be scheduled to be enqueued at a given time.
status

RouterJobStatus

The status of the job.
tags

A set of non-identifying attributes attached to this job. Values must be primitive values - number, string, boolean.

RouterJobAssignment

Assignment details of a job to a worker.

Name Type Description
assignedAt

string

Timestamp when the job was assigned to a worker in UTC.
assignmentId

string

Id of a job assignment.
closedAt

string

Timestamp when the job was marked as closed after being completed in UTC.
completedAt

string

Timestamp when the job was marked as completed after being assigned in UTC.
workerId

string

Id of the Worker assigned to the job.

RouterJobCreateOrUpdate

A unit of work to be routed

Name Type Description
channelId

string

The channel identifier. eg. voice, chat, etc.
channelReference

string

Reference to an external parent context, eg. call ID.
classificationPolicyId

string

Id of a classification policy used for classifying this job.
dispositionCode

string

Reason code for cancelled or closed jobs.
labels

A set of key/value pairs that are identifying attributes used by the rules engines to make decisions. Values must be primitive values - number, string, boolean.
matchingMode JobMatchingModeCreateOrUpdate:

If provided, will determine how job matching will be carried out. Default mode: QueueAndMatchMode.
notes

RouterJobNote[]

Notes attached to a job, sorted by timestamp.
priority

integer

Priority of this job. Value must be between -100 to 100.
queueId

string

Id of a queue that this job is queued to.
requestedWorkerSelectors

RouterWorkerSelector[]

A collection of manually specified worker selectors, which a worker must satisfy in order to process this job.
tags

A set of non-identifying attributes attached to this job. Values must be primitive values - number, string, boolean.

RouterJobNote

A note attached to a job.

Name Type Description
addedAt

string

The time at which the note was added in UTC. If not provided, will default to the current time.
message

string

The message contained in the note.

RouterJobStatus

Describes the various status of a job.

Name Type Description
assigned

string

Job has been assigned to a worker.
cancelled

string

Job has been cancelled.
classificationFailed

string

Classification process failed for the job.
closed

string

Job has been closed by a worker.
completed

string

Job has been completed by a worker.
created

string

Job has been created.
pendingClassification

string

Job is waiting to be classified.
pendingSchedule

string

Job has been created but not been scheduled yet.
queued

string

Job has been queued.
scheduleFailed

string

Job scheduling failed.
scheduled

string

Job has been scheduled successfully.
waitingForActivation

string

Job is in a suspended state and waiting for an update.

RouterWorkerSelector

Describes a condition that must be met against a set of labels for worker selection.

Name Type Description
expedite

boolean

Pushes a job to the front of the queue as long as this selector is active.
expiresAfterSeconds

number

Describes how long this label selector is valid in seconds.
expiresAt

string

The time at which this worker selector expires in UTC.
key

string

The label key to query against.
labelOperator

LabelOperator

Describes how the value of the label is compared to the value defined on the worker selector.
status

RouterWorkerSelectorStatus

Status of the worker selector.
value

The value to compare against the actual label value with the given operator. Values must be primitive values - number, string, boolean.

RouterWorkerSelectorStatus

Describes the status of a worker selector.

Name Type Description
active

string

Worker selector is valid.
expired

string

Worker selector is not valid.

ScheduleAndSuspendMode

Describes a matching mode used for scheduling jobs to be queued at a future time. At the specified time, matching worker to a job will not start automatically.

Name Type Description
kind string:

scheduleAndSuspend

The type discriminator describing a sub-type of JobMatchingMode.
scheduleAt

string

Requested schedule time.

ScheduleAndSuspendModeCreateOrUpdate

Describes a matching mode used for scheduling jobs to be queued at a future time. At the specified time, matching worker to a job will not start automatically.

Name Type Description
kind string:

scheduleAndSuspend

The type discriminator describing a sub-type of JobMatchingMode.
scheduleAt

string

Requested schedule time.

SuspendMode

Describes a matching mode where matching worker to a job is suspended.

Name Type Description
kind string:

suspend

The type discriminator describing a sub-type of JobMatchingMode.

SuspendModeCreateOrUpdate

Describes a matching mode where matching worker to a job is suspended.

Name Type Description
kind string:

suspend

The type discriminator describing a sub-type of JobMatchingMode.