AzureCommunicationRoutingService REST client library for JavaScript

Article
11/21/2023

Azure Communication Routing Service

Please rely heavily on our REST client docs to use this library

Key links:

Getting started

Currently supported environments

LTS versions of Node.js

Prerequisites

You must have an Azure subscription to use this package.

Have an ACS Resource

Create an ACS resource in the Azure Portal or use an existing resource.

Install the `@azure-rest/communication-job-router` package

Install the AzureCommunicationRoutingService REST client REST client library for JavaScript with npm:

npm install @azure-rest/communication-job-router

Create and authenticate a `AzureCommunicationRoutingServiceClient`

To use an Azure Active Directory (AAD) token credential, provide an instance of the desired credential type obtained from the @azure/identity library.

To authenticate with AAD, you must first npm install @azure/identity

After setup, you can choose which type of credential from @azure/identity to use. As an example, DefaultAzureCredential can be used to authenticate the client.

Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Tutorial: Route jobs to workers using the Azure Communication Services (ACS) Job Router Rest SDK

In this tutorial, you will learn:

How to create a queue.
How to create workers and assign them to a queue.
How to route jobs to workers.
How to subscribe to and handle Job Router events.
How to complete and close jobs.

Start a NodeJS Express server

In a shell (cmd, PowerShell, Bash, etc.), create a folder called RouterQuickStart and inside this folder execute npx express-generator. This will generate a simple Express project that will listen on port 3000.

Example

mkdir RouterQuickStart
cd RouterQuickStart
npx express-generator
npm install
DEBUG=routerquickstart:* npm start

Install the Azure ACS Job Router SDK

In the RouterQuickStart folder, install the ACS Job Router SDK by executing npm install @azure-rest/communication-job-router --save.

Routing Jobs

Construct AzureCommunicationRoutingServiceClient

First we need to construct an AzureCommunicationRoutingServiceClient.

const JobRouterClient = require("@azure-rest/communication-job-router").default;

const connectionString = "endpoint=https://<YOUR_ACS>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>";
const routerClient = JobRouterClient(connectionString);

Create a Distribution Policy

This policy determines which workers will receive job offers as jobs are distributed off their queues.

const distributionPolicy = await routerClient.path("/routing/distributionPolicies/{id}", "distributionPolicy-1").patch({
  contentType: "application/merge-patch+json",
  body: {
    name: "distribution-policy-123",
    offerExpiresAfterSeconds: 30,
    mode: {
      kind: "longestIdle",
      minConcurrentOffers: 1,
      maxConcurrentOffers: 3,
    },
  }
});

Create a Queue

This queue offers jobs to workers according to our previously created distribution policy.

const salesQueueId = "queue-123";
await routerClient.path("/routing/queues/{id}", salesQueueId).patch({
  contentType: "application/merge-patch+json",
  body: {
    distributionPolicyId: distributionPolicy.body.id,
    name: "Main",
    labels: {},
  }
});

Create Workers

These workers are assigned to our previously created "Sales" queue and have some labels.

setting availableForOffers to true means these workers are ready to accept job offers.
refer to our labels documentation to better understand labels and label selectors.

  // Create worker "Alice".
const workerAliceId = "773accfb-476e-42f9-a202-b211b41a4ea4";
const workerAliceResponse = await routerClient.path("/routing/workers/{workerId}", workerAliceId).patch({
  contentType: "application/merge-patch+json",
  body: {
    capacity: 120,
    queues: [salesQueueId],
    labels: {
      Xbox: 5,
      german: 4,
      name: "Alice"
    },
    channels: [
      {
        channelId: "CustomChatChannel",
        capacityCostPerJob: 10,
      },
      {
        channelId: "CustomVoiceChannel",
        capacityCostPerJob: 100,
      },
    ],
  }
});

// Create worker "Bob".
const workerBobId = "21837c88-6967-4078-86b9-1207821a8392";
const workerBobResponse = await routerClient.path("/routing/workers/{workerId}", workerBobId).patch({
  contentType: "application/merge-patch+json",
  body: {
    capacity: 100,
    queues: [salesQueueId],
    labels: {
      Xbox: 5,
      english: 3,
      name: "Alice"
    },
    channels: [
      {
        channelId: "CustomChatChannel",
        capacityCostPerJob: 10,
      },
      {
        channelId: "CustomVoiceChannel",
        capacityCostPerJob: 100,
      },
    ],
  }
});

Job Lifecycle

Refer to our job lifecycle documentation to better understand the lifecycle of a job.

Create a Job

This job is enqueued on our previously created "Sales" queue.

const jobId = "router-job-123";
const result = await routerClient.path("/routing/jobs/{id}", jobId).patch({
  contentType: "application/merge-patch+json",
  body: {
    channelReference: "66e4362e-aad5-4d71-bb51-448672ebf492",
    channelId: "voice",
    priority: 2,
    queueId: "salesQueueId",
    labels: {},
  }
});

(Optional) Create Job With a Classification Policy

Create a Classification Policy

This policy classifies jobs upon creation.

Refer to our rules documentation to better understand prioritization rules.

const classificationPolicyId = "classification-policy-123";
const result = await routerClient.path("/routing/classificationPolicies/{id}", classificationPolicyId).patch({
  contentType: "application/merge-patch+json",
  body: {
    name: "Default Classification Policy",
    fallbackQueueId: salesQueueId,
    queueSelectorAttachments: [
      {
        kind: "static",
        queueSelector: { key: "department", labelOperator: "equal", value: "xbox" }
      },
    ],
    workerSelectorAttachments: [{
      kind: "static",
      workerSelector: { key: "english", labelOperator: "greaterThan", value: 5 }
    }],
    prioritizationRule: {
      kind: "expression",
      language: "powerFx",
      expression: "If(job.department = \"xbox\", 2, 1)"
    }
  }
});

Create and classify job

This job will be classified with our previously created classification policy. It also has a label.

const result = await routerClient.path("/routing/jobs/{id}", jobId).patch({
  contentType: "application/merge-patch+json",
  body: {
    channelReference: "66e4362e-aad5-4d71-bb51-448672ebf492",
    channelId: "voice",
    classificationPolicyId: classificationPolicy.id,
    labels: {
      department: "xbox"
    },
  }
});
``

## Events

Job Router events are delivered via Azure Event Grid. Refer to our [Azure Event Grid documentation](/azure/event-grid/overview) to better understand Azure Event Grid.

In the previous example:

- The job gets enqueued to the “Sales" queue.
- A worker is selected to handle the job, a job offer is issued to that worker, and a `RouterWorkerOfferIssued` event is sent via Azure Event Grid.

Example `RouterWorkerOfferIssued` JSON shape:

```json
{
  "id": "1027db4a-17fe-4a7f-ae67-276c3120a29f",
  "topic": "/subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}",
  "subject": "worker/{worker-id}/job/{job-id}",
  "data": {
    "workerId": "w100",
    "jobId": "7f1df17b-570b-4ae5-9cf5-fe6ff64cc712",
    "channelReference": "test-abc",
    "channelId": "FooVoiceChannelId",
    "queueId": "625fec06-ab81-4e60-b780-f364ed96ade1",
    "offerId": "525fec06-ab81-4e60-b780-f364ed96ade1",
    "offerTimeUtc": "2023-08-17T02:43:30.3847144Z",
    "expiryTimeUtc": "2023-08-17T02:44:30.3847674Z",
    "jobPriority": 5,
    "jobLabels": {
      "Locale": "en-us",
      "Segment": "Enterprise",
      "Token": "FooToken"
    },
    "jobTags": {
      "Locale": "en-us",
      "Segment": "Enterprise",
      "Token": "FooToken"
    }
  },
  "eventType": "Microsoft.Communication.RouterWorkerOfferIssued",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "eventTime": "2023-08-17T00:55:25.1736293Z"
}

Subscribing to Events

One way to subscribe to ACS Job Router events is through the Azure Portal.

Navigate to your ACS resource in the Azure Portal and open the “Events” blade.
Add an event subscription for the “RouterWorkerOfferIssued” event.
Select an appropriate means to receive the event (e.g. Webhook, Azure Functions, Service Bus).

Refer to our "subscribe to Job Router events" documentation to better understand subscribing to Job Router events.

The route in your NodeJS application that receives events may look something like this:

app.post('/event', (req, res) => {
    req.body.forEach(eventGridEvent => {
        // Deserialize the event data into the appropriate type
        if (eventGridEvent.eventType === "Microsoft.EventGrid.SubscriptionValidationEvent") {
            res.send({ validationResponse: eventGridEvent.data.validationCode });
        } else if (eventGridEvent.eventType === "Microsoft.Azure.CommunicationServices.RouterWorkerOfferIssued") {
           // RouterWorkerOfferIssued handling logic;
        } else if ...
    });
    ...
});

Accept or Decline the Job Offer

Once you receive a RouterWorkerOfferIssued event you can accept or decline the job offer.

workerid - The id of the worker accepting the job offer.
offerId - The id of the offer being accepted or declined.

const acceptResponse = await routerClient.path("/routing/workers/{workerId}/offers/{offerId}:accept", workerId, offerId).post();
// or
const declineResponse = await routerClient.path("/routing/workers/{workerId}/offers/{offerId}:decline", workerId, offerId).post();

Complete the Job

The assignmentId received from the previous step's response is required to complete the job.

const completeJob = await routerClient.path("/routing/jobs/{id}/assignments/{assignmentId}:complete", jobId, acceptResponse.body.assignmentId).post({
  body: {
    note: `Job has been completed by ${workerId} at ${new Date()}`
  }
});

Close the Job

Once the worker has completed the wrap-up phase of the job the jobRouterClient can close the job and attach a disposition code to it for future reference.

const closeJob = await routerClient.path("/routing/jobs/{id}/assignments/{assignmentId}:close", jobId, acceptResponse.body.assignmentId).post({
  body: {
    note: `Job has been closed by ${workerId} at ${new Date()}`
  }
});

Troubleshooting

Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.

Share via

AzureCommunicationRoutingService REST client library for JavaScript

Getting started

Currently supported environments

Prerequisites

Have an ACS Resource

Install the `@azure-rest/communication-job-router` package

Create and authenticate a `AzureCommunicationRoutingServiceClient`

Tutorial: Route jobs to workers using the Azure Communication Services (ACS) Job Router Rest SDK

Start a NodeJS Express server

Example

Install the Azure ACS Job Router SDK

Routing Jobs

Construct AzureCommunicationRoutingServiceClient

Create a Distribution Policy

Create a Queue

Create Workers

Job Lifecycle

Create a Job

(Optional) Create Job With a Classification Policy

Create a Classification Policy

Create and classify job

Subscribing to Events

Accept or Decline the Job Offer

Complete the Job

Close the Job

Troubleshooting

Logging

Additional resources

Share via

AzureCommunicationRoutingService REST client library for JavaScript

Getting started

Currently supported environments

Prerequisites

Have an ACS Resource

Install the @azure-rest/communication-job-router package

Create and authenticate a AzureCommunicationRoutingServiceClient

Tutorial: Route jobs to workers using the Azure Communication Services (ACS) Job Router Rest SDK

Start a NodeJS Express server

Example

Install the Azure ACS Job Router SDK

Routing Jobs

Construct AzureCommunicationRoutingServiceClient

Create a Distribution Policy

Create a Queue

Create Workers

Job Lifecycle

Create a Job

(Optional) Create Job With a Classification Policy

Create a Classification Policy

Create and classify job

Subscribing to Events

Accept or Decline the Job Offer

Complete the Job

Close the Job

Troubleshooting

Logging

Additional resources

Install the `@azure-rest/communication-job-router` package

Create and authenticate a `AzureCommunicationRoutingServiceClient`