Introduction to the Genesys Cloud Skill Expression Groups

Greetings everyone! The end of the year is fast approaching and before we know it, 2023 will be upon us. This month I want to introduce a new feature in Genesys Cloud called Skill Expression Groups. Traditionally, Genesys Cloud has only allowed you to define queue membership statically. Before the Skill Expression Group feature, queue membership was done by either assigning an agent directly to the queue or assigning the agent to a group that was assigned to the queue. Both of these mechanisms required constant administration from a Genesys Cloud Administrator if queue membership changed on a regular basis.

Skill Expression Groups allow a Genesys Cloud administrator to define group membership for a queue based on a set of "and/or/not" conditional statements. The conditional statements all focus on what skills/languages and levels an agent possesses. As new agents are added to the platform or an existing agent's skills change, they will be automatically be added or removed from a group. Skill Expression Groups offer the ability to build powerful and deep rules for determining what agents in your organization belong to a queue.

This blog post is not going to show you how to configure the Skill Expression Group via the Genesys Cloud UI. Instead, this article is going to focus on:

1. The Skill Expression Group APIs and their corresponding API commands
2. Understanding how divisions work with Skill Expression Groups
3. Using CX as Code to configure a Skill Expression Group

All of the Skill Expression Group APIs can be found under the Routing and Conversation Handling section of the Genesys Cloud Developer Center. The Skill Expression Group feature has 8 APIs broken into five categories:

1. Retrieving all Skill Expression Groups
2. Creating a Skill Expression Group
3. Updating and deleting a Skill Expression Group
4. Reading what agents are part of a Skill Expression Group
5. Divisions and Skill Expression Groups

There is a single API for returning all of the Skill Expression Groups currently defined in your organization. This API is shown below:

Remember this API is paginated so if you have more than 25 skill groups defined, you will need to call to account for pagination in your code. The GET /api/v2/routing/skillsgroup API does pagination a little bit differently from the previous APIs in that the API does not allow you to directly access the next page of data by incrementing the page number. Instead, you need to use the URI presented in the nextUri attribute to retrieve the next page of data. The nextUri contains an after token which is passed as a query parameter in the API uri.

You can also use the Genesys Cloud CLI to retrieve all of the skill groups by using the following Genesys Cloud CLI:

gc routing skillgroups list -a

This will return a list of all of the returned Skill Expression Groups. We return all of the Skill Expression Groups (not just a page) because we are using the -a option. However, if you take a close look at the results, you will see that the conditions (e.g. the rules) associated with the Skill Expression Group are not returned by the API or the CLI. In order to see the conditions for a Skill Expression Group you must retrieve a specific Skill Expression Group by its id. To retrieve a single skill group you can use the following API:

The corresponding Genesys Cloud CLI command is shown below:

gc routing skillgroups get {id}

If you are using CX as Code you can also retrieve the id of a Skill Expression Group by using the CX as Code data source genesyscloudroutingskill_group. An example of this data source in action is shown below:

data "genesyscloud_routing_skill_group" "skill_group" {
  name = "MyDynamicGroup"
}

To create a Skill Expression Group you can use the following API:

Let's use the API above to define a Skill Expression Group where we want to capture all agents with Series 6 skills greater than 2 and who have a language skill of Spanish greater than 3. To create this skill group using the Genesys Cloud API shown above you need to define a POST body that looks like this:

{
  "name": "Series6andSpanish",
  "description": "Capture all agents with a series 6>2 and a language skill of spanish>3",
  "skillConditions": [
    {
      "routingSkillConditions": [
        {
          "routingSkill": "Series 6",
          "comparator": "GreaterThan",
          "proficiency": 2
        }
      ],
      "languageSkillConditions": [],
      "operation": "And"
    },
    {
      "routingSkillConditions": [],
      "languageSkillConditions": [
        {
          "languageSkill": "Spanish",
          "comparator": "GreaterThan",
          "proficiency": 3
        }
      ],
      "operation": "And"
    }
  ]
}

Notice in the above body, there is a difference between routingSkillConditions and languageSkillConditions. The routingSkillConditions capture skill expressions and languageSkillConditions capture language expressions. In addition, notice the operation keyword where you can define AND, OR, and NOT conditions.

If you want to define a Skill Expression Group using CX as Code, you would use genesyscloudskill_group resource. Below is an example of creating our series 6 and Spanish Skill Expression Group:

resource "genesyscloud_routing_skill_group" "skillgroup" {
  name        = "Series6andSpanish"
  description = "Capture all agents with a series 6>2 and a language skill of spanish>3"
  skill_conditions = jsonencode(
    [
      {
        "routingSkillConditions": [
          {
            "routingSkill": "Series 6",
            "comparator": "GreaterThan",
            "proficiency": 2
          }
        ],
        "languageSkillConditions": [],
        "operation": "And"
      },
      {
        "routingSkillConditions": [],
        "languageSkillConditions": [
          {
            "languageSkill": "Spanish",
            "comparator": "GreaterThan",
            "proficiency": 3
          }
        ],
        "operation": "And"
      }
  ])
}

The Skill Expression Group API does not have a PUT endpoint for updating the Skill Expression Group. Instead, it has a PATCH endpoint. Remember, that a PATCH endpoint allows you to submit only the attributes that have changed instead of the entire JSON body for the record. The PATCH endpoint can be seen here:

To update a Skill Expression Group using the CLI the command you would use would be:

gc routing skillgroups update {skillGroupId} --file "FILE CONTAINING THE JSON BODY"

To delete a Skill Expression Group you can use the DELETE endpoint:

To use the CLI you would issue the following command:

gc routing skillgroups delete {skillGroupId}

Once you have defined the Skill Expression Group, you can see what agents are part of the Skill Expression Group by issuing the following API call:

The corresponding CLI command is:

gc routing skillgroups members list {skillGroupId} -a

Genesys Cloud divisions are often one of the most misunderstood capabilities within the platform. Most people think divisions are mechanisms for segmenting your Genesys Cloud organization so that you can cleanly delineate and group various Genesys Cloud assets into groups that can only be accessed by members of that division. A Genesys Cloud division is really a filtering mechanism. When a division is applied to a Genesys Cloud asset (e.g. a Queue, Flow, etc..), it means that a resource is only "visible" to members of that division. However, it should be not thought of as an access control mechanism. It is used in coordination with the Genesys Cloud roles permissions.

Here are a few additional things to keep in mind about Genesys Cloud divisions:

1. Every Genesys Cloud organization has a default division That division is called the Home division.
2. Every "division-aware" asset in Genesys Cloud will be assigned to the division of the user creating it.
3. An asset in Genesys Cloud can be assigned to one and only one division at a time.
4. A role can be assigned to multiple divisions and any user assigned that role can see assets in any division defined in the role. However, a user that is assigned that role can still only be assigned to one division.

One of the most common questions I am asked about Skill Expression Groups is: How can I make agents from multiple divisions visible to that Skill Expression Group? For example, I might want to have agents who have a series 7 stockbroker license from multiple divisions available to take customer calls. Skill Expression Groups allow you to do this via the UI, the Skill Expression Group APIs, and CX as Code. To add or remove divisions that are visible to the Skill Expression Group, you can use the following API:

If you want to manage Skill Expression Group visibility using CX as Code you can set the member_division_ids attribute on the genesys_cloud_skill_groups resource. This optional attribute accepts a list of division_ids that will be made visible to Skill Expression Group.

To see the divisions made visible to the Skill Expression Group you can use the following API:

That's it! The new Genesys Cloud Skill Expression Group capability is a welcome edition because it shifts managing Genesys Cloud groups statically to dynamically. However, it does add a layer of complexity if you want to manage the Skill Expression Group pragmatically via the API or declaratively via CX as Code. Remember, trying to write the conditional rules by hand is painful. Use the UI to model the rule and then capture the rule's JSON using the CLI or API. Also, remember that Skill Expression Groups can pull members across multiple divisions

1. Skill Expression Group - Resource Center
2. Skill Expression Group API Code. This is part of the routing API, so filter on the keyword skillgroup if you want to just see these APIs.
3. Skill Expression Group Terraform Resource
4. Genesys Cloud Resource Center
5. Genesys Cloud Developer Center
6. CX as Code

Article Author

John Carnell
Director, Developer Engagement, R&D Genesys Cloud