|
| 1 | +# Azure Communication Job Router client library for Java |
| 2 | + |
| 3 | +Azure Communication Job Router contains the APIs used in job router applications for Azure Communication Services. |
| 4 | + |
| 5 | +[Source code][source] | [Package (Maven)][package] | [API reference documentation][api_documentation] |
| 6 | +| [Product documentation][product_docs] |
| 7 | + |
| 8 | +## Getting started |
| 9 | + |
| 10 | +### Prerequisites |
| 11 | + |
| 12 | +- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). |
| 13 | +- [Java Development Kit (JDK)](https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable) version 8 or above. |
| 14 | +- [Apache Maven](https://maven.apache.org/download.cgi). |
| 15 | +- A deployed Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up. |
| 16 | +### Include the package |
| 17 | +#### Include the BOM file |
| 18 | + |
| 19 | +Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. |
| 20 | +To learn more about the BOM, see the [AZURE SDK BOM README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/boms/azure-sdk-bom/README.md). |
| 21 | + |
| 22 | +```xml |
| 23 | +<dependencyManagement> |
| 24 | + <dependencies> |
| 25 | + <dependency> |
| 26 | + <groupId>com.azure</groupId> |
| 27 | + <artifactId>azure-sdk-bom</artifactId> |
| 28 | + <version>{bom_version_to_target}</version> |
| 29 | + <type>pom</type> |
| 30 | + <scope>import</scope> |
| 31 | + </dependency> |
| 32 | + </dependencies> |
| 33 | +</dependencyManagement> |
| 34 | +``` |
| 35 | +and then include the direct dependency in the dependencies section without the version tag. |
| 36 | + |
| 37 | +```xml |
| 38 | +<dependencies> |
| 39 | + <dependency> |
| 40 | + <groupId>com.azure</groupId> |
| 41 | + <artifactId>azure-communication-jobrouter</artifactId> |
| 42 | + </dependency> |
| 43 | +</dependencies> |
| 44 | +``` |
| 45 | + |
| 46 | +#### Include direct dependency |
| 47 | +If you want to take dependency on a particular version of the library that is not present in the BOM, |
| 48 | +add the direct dependency to your project as follows. |
| 49 | + |
| 50 | +[//]: # ({x-version-update-start;com.azure:azure-communication-jobrouter;current}) |
| 51 | +```xml |
| 52 | +<dependency> |
| 53 | + <groupId>com.azure</groupId> |
| 54 | + <artifactId>azure-communication-jobrouter</artifactId> |
| 55 | + <version>1.0.0-beta.1</version> |
| 56 | +</dependency> |
| 57 | +``` |
| 58 | + |
| 59 | +## Key concepts |
| 60 | + |
| 61 | +### Job |
| 62 | + |
| 63 | +A Job is a unit of work (demand), which must be routed to an available Worker (supply). A real-world example is an incoming call or chat in the context of a call center. |
| 64 | + |
| 65 | +### Worker |
| 66 | + |
| 67 | +A Worker is the supply available to handle a Job. When you use the SDK to register a Worker to receive jobs, you can specify: |
| 68 | + |
| 69 | +- One or more queues to listen on. |
| 70 | +- The number of concurrent jobs per Channel that the Worker can handle. |
| 71 | +- A set of Labels that can be used to group and select workers. |
| 72 | + |
| 73 | +A real-world example is an agent in a call center. |
| 74 | + |
| 75 | +### Queue |
| 76 | + |
| 77 | +A Queue is an ordered list of jobs, that are waiting to be served to a worker. Workers register with a queue to receive work from it. |
| 78 | + |
| 79 | +A real-world example is a call queue in a call center. |
| 80 | + |
| 81 | +### Channel |
| 82 | + |
| 83 | +A Channel is a grouping of jobs by some type. When a worker registers to receive work, they must also specify for which channels they can handle work, and how much of each can they handle concurrently. Channels are just a string discriminator and aren't explicitly created. |
| 84 | + |
| 85 | +Real-world examples are `voice calls` or `chats` in a call center. |
| 86 | + |
| 87 | +### Offer |
| 88 | + |
| 89 | +An Offer is extended by Job Router to a worker to handle a particular job when it determines a match. You can either accept or decline the offer with the JobRouter SDK. If you ignore the offer, it expires according to the time to live configured on the Distribution Policy. |
| 90 | + |
| 91 | +A real-world example is the ringing of an agent in a call center. |
| 92 | + |
| 93 | + |
| 94 | +### Distribution Policy |
| 95 | + |
| 96 | +A Distribution Policy is a configuration set that controls how jobs in a queue are distributed to workers registered with that queue. This configuration includes: |
| 97 | + |
| 98 | +- How long an Offer is valid before it expires. |
| 99 | +- The distribution mode, which define the order in which workers are picked when there are multiple available. |
| 100 | +- How many concurrent offers can there be for a given job. |
| 101 | + |
| 102 | +### Labels |
| 103 | + |
| 104 | +You can attach labels to workers, jobs, and queues. Labels are key value pairs that can be of `string`, `number`, or `boolean` data types. |
| 105 | + |
| 106 | +A real-world example is the skill level of a particular worker or the team or geographic location. |
| 107 | + |
| 108 | +### Worker selectors |
| 109 | + |
| 110 | +Worker selectors can be attached to a job in order to target a subset of workers on the queue. |
| 111 | + |
| 112 | +A real-world example is a condition on an incoming call that the agent must have a minimum level of knowledge of a particular product. |
| 113 | + |
| 114 | +### Classification policy |
| 115 | + |
| 116 | +A classification policy can be used to programmatically select a queue, determine job priority, or attach worker label selectors to a job. |
| 117 | + |
| 118 | +### Queue selectors |
| 119 | + |
| 120 | +Queue selectors can be attached to a classification policy in order to target a queue which fulfills certain conditions. |
| 121 | +This queue is used enqueueing an incoming job. |
| 122 | + |
| 123 | +A real-world example is a condition on an incoming call that the call has to get queued to a queue which supports `chat`. |
| 124 | + |
| 125 | + |
| 126 | +### Exception policy |
| 127 | + |
| 128 | +An exception policy controls the behavior of a Job based on a trigger and executes a desired action. The exception policy is attached to a Queue so it can control the behavior of Jobs in the Queue. |
| 129 | + |
| 130 | + |
| 131 | +## Examples |
| 132 | + |
| 133 | +### Client Initialization |
| 134 | +To initialize the JobRouter Client, the connection string can be used to instantiate. |
| 135 | +Alternatively, you can also use Active Directory authentication using DefaultAzureCredential. |
| 136 | + |
| 137 | +```java |
| 138 | +RouterClient routerClient = new RouterClientBuilder() |
| 139 | + .connectionString(connectionString); |
| 140 | + .buildClient(); |
| 141 | +``` |
| 142 | + |
| 143 | +Using `RouterClient` created from builder, create Job Router entities as described below. |
| 144 | + |
| 145 | +### Create a Distribution Policy |
| 146 | + |
| 147 | +```java |
| 148 | +CreateDistributionPolicyOptions createDistributionPolicyOptions = new CreateDistributionPolicyOptions( |
| 149 | + "distribution-policy-id", |
| 150 | + 10.0, |
| 151 | + new LongestIdleMode() |
| 152 | + .setMinConcurrentOffers(1) |
| 153 | + .setMaxConcurrentOffers(10) |
| 154 | +); |
| 155 | +DistributionPolicy distributionPolicy = routerClient.createDistributionPolicy(createDistributionPolicyOptions); |
| 156 | +``` |
| 157 | + |
| 158 | +### Create a Queue |
| 159 | + |
| 160 | +```java |
| 161 | +CreateQueueOptions createQueueOptions = new CreateQueueOptions("queue-id", distributionPolicy.getId()); |
| 162 | +JobQueue jobQueue = routerClient.createQueue(createQueueOptions); |
| 163 | +``` |
| 164 | + |
| 165 | +### Create a Job |
| 166 | + |
| 167 | +```java |
| 168 | +CreateJobOptions createJobOptions = new CreateJobOptions("job-id", "chat-channel", queueId) |
| 169 | + .setPriority(1) |
| 170 | + .setChannelReference("12345") |
| 171 | + .setRequestedWorkerSelectors( |
| 172 | + new ArrayList<>() {{ |
| 173 | + new WorkerSelector() |
| 174 | + .setKey("Some-skill") |
| 175 | + .setLabelOperator(LabelOperator.GREATER_THAN) |
| 176 | + .setValue(10); |
| 177 | + }} |
| 178 | + ); |
| 179 | +RouterJob routerJob = routerClient.createJob(createJobOptions); |
| 180 | +``` |
| 181 | + |
| 182 | +### Create a Worker |
| 183 | + |
| 184 | +```java |
| 185 | +Map<String, LabelValue> labels = new HashMap<String, LabelValue>() { |
| 186 | + { |
| 187 | + put("Label", new LabelValue("Value")); |
| 188 | + } |
| 189 | +}; |
| 190 | + |
| 191 | +Map<String, Object> tags = new HashMap<String, Object>() { |
| 192 | + { |
| 193 | + put("Tag", "Value"); |
| 194 | + } |
| 195 | +}; |
| 196 | + |
| 197 | +Map<String, ChannelConfiguration> channelConfigurations = new HashMap<String, ChannelConfiguration>() { |
| 198 | + { |
| 199 | + put("channel1", new ChannelConfiguration().setCapacityCostPerJob(1)); |
| 200 | + } |
| 201 | +}; |
| 202 | + |
| 203 | +Map<String, QueueAssignment> queueAssignments = new HashMap<String, QueueAssignment>() { |
| 204 | + { |
| 205 | + put(jobQueue.getId(), new Object()); |
| 206 | + } |
| 207 | +}; |
| 208 | + |
| 209 | +CreateWorkerOptions createWorkerOptions = new CreateWorkerOptions(workerId, 10) |
| 210 | + .setLabels(labels) |
| 211 | + .setTags(tags) |
| 212 | + .setAvailableForOffers(false) |
| 213 | + .setChannelConfigurations(channelConfigurations) |
| 214 | + .setQueueAssignments(queueAssignments); |
| 215 | + |
| 216 | +RouterWorker routerWorker = routerClient.createWorker(createWorkerOptions); |
| 217 | +``` |
| 218 | + |
| 219 | +## Troubleshooting |
| 220 | + |
| 221 | +Running into issues? This section should contain details as to what to do there. |
| 222 | + |
| 223 | +## Next steps |
| 224 | +- [Read more about Router in Azure Communication Services][router_concepts] |
| 225 | + |
| 226 | +### More sample code |
| 227 | +Please take a look at the [samples](https://github.com/cparisineti/azure-sdk-for-java/tree/feature/jobrouter-initial-commit/sdk/communication/azure-communication-jobrouter/src/samples/) directory for detailed examples of how to use this library. |
| 228 | + |
| 229 | + |
| 230 | +## Contributing |
| 231 | + |
| 232 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution. |
| 233 | + |
| 234 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. |
| 235 | + |
| 236 | +This project has adopted the [Microsoft Open Source Code of Conduct ][coc]. For more information see the [Code of Conduct FAQ ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments. |
0 commit comments