<!-- Source: https://docs.squirro.com/en/latest/technical/communities/augmentation.html -->
# Communities Augmentation

Profile: Project Creator

This page describes the Communities data augmentation feature and its configuration.

This feature requires the facilitation of an external API that Squirro can call to append additional properties to a community object.

Project creators can configure the external API URL in the Squirro project settings.

Note: The external API can also be hosted within the Squirro environment using a Studio plugin.

## Overview

Out of the box, Squirro [Communities](index.md#communities) are created using a predefined set of attributes, including the following:

- Name
- Community type
- Label value (that the community is mapped to)
- Photo

However, there are situations where you may wish to add more properties to a community.

For example, in an enterprise search setting, you may wish to augment a community type _People_ with additional properties such as phone number, email, contact information, and social links.

The communities augmentation feature allows you to do this.

Tip: This feature can also be used to overwrite existing `name` and `photo` data for communities, based on the response from the external API. This is particularly useful if the preexisting name or photo data is missing or inaccurate.

## Configuration

To configure the Community Augmentation feature, follow the steps below:

1. Log in to your Squirro project.
2. Navigate to Setup → Settings.
3. Click Project Configuration from the left menu.
4. Locate `topic.community.augment-community-data` as shown in the screen clip below:

[![Communities Augmentation Settings](https://s3.amazonaws.com/download.squirro.net/docs/technical/communities/augmentation-settings.png)](https://s3.amazonaws.com/download.squirro.net/docs/technical/communities/augmentation-settings.png)

## Configuration Values

There are two parameters requiring configuration for the community data augmentation feature:

- `topic.community.augment-community-data`: Enables or disables the augmentation of community with external data. It is a boolean type with a default value of `False`.
- `topic.community.augment-community-data-url`: Contains the relative or absolute URL that hosts the external API from which the augmented data is fetched.

### Example GET Responses

A successful GET community response **without** any community augmentation looks like this:

```json
{
  "id": "Abdrgjsdj09831Oda",
  "name": "Jon Snow",
  "created_at": "2022-05-19T14:44:37",
  "photo": "www.xyz.com",
  "facet_value": "rishu@squirro.com",
  "modified_at": "2022-05-19T14:44:40"
}
```

A successful GET community response **with** community augmentation looks like this:

```json
{
  "id": "Abdrgjsdj09831Oda",
  "name": "Jon Snow",
  "created_at": "2022-05-19T14:44:37",
  "photo": "www.xyz.com",
  "facet_value": "jon.snow@example.com",
  "modified_at": "2022-05-19T14:44:40",
  "properties": {
    "id": 10,
    "username": "theUser",
    "name": "Jon Snow",
    "photo": "www.xyz.com",
    "title": "Lord Commander of the Night's Watch",
    "phone": "12345",
    "social": [
      {
        "url": "www.example.com",
        "name": "Microsoft teams"
      }
    ],
    "contact": {
      "profiles": [
        {
          "name": "Intranet"
          "url": "https://intranet.example.com/"
        }
      ],
      "office": "OF123.61",
      "location": "Stuttgart",
      "extension": "1234",
      "email": "jon.snow@example.com"
    },
    "roles": [
      {
        "role": "JST Teamlead",
        "expertise": ["Project Lifecycle"],
        "language": ["EN"]
      }
    ],
    "projects": [
      {
        "name": "XYZ",
        "url": "www.xyz.com"
      }
    ],
    "additional_info": "Jon Snow is a Business executive with... and organizational apps."
  }
}
```

## OpenAPI Specification

This external service can be implemented according to an OpenAPI specification. It can be visualized using [Swagger](https://editor.swagger.io/).

Download [`community-augmentation-api.yml`](../../_downloads/df0ca10edebbe6aa58fc3b7fe2045551/community-augmentation-api.yml).