Developer Documentation / Tutorials / Datasources / Create user-based Slack Enterprise Datasource

Create user-based Slack Enterprise Datasource

💡 10 min read

Learn how to create a Slack user-based collection in Onna using the API

From March 2018, Slack Enterprise Grid (opens new window) includes an Audit logs API (opens new window) that allows you to audit data from specific user accounts, which is more efficient and effective for legal hold purposes and data preservation.

Onna integrates with Slack Enterprise Grid, allowing you to create Datasources that collect data for specific users leveraging Slack's Audit logs API. This Datasource type is called Slack Enterprise in Onna.

For more information on user-based collections in Slack, check our Online Help article (opens new window).

# Requirements

You must be a Slack admin to collect data from it. When you are an Onna admin, you can add Slack admin credentials to Onna, where they are stored and encrypted. You can then share Slack admin permissions with other Onna admins so that they can collect data from Slack.

An active Enterprise Grid plan (opens new window) in your Slack account, which also gives you access to Slack's Audit logs API (opens new window)
Enabled Slack's Discovery API (opens new window), which allows you to connect Onna to Slack Enterprise Grid
Enabled message and file retention (opens new window) in your Slack account from the date of the data you want to collect
An admin (opens new window) role in Onna
Access to Slack's admin credentials (opens new window) in Onna. Some API calls require that you are a Slack admin
An existing Workspace where to create the Datasource
A valid auth token to include in all your API calls

# Get the ID of your Onna Workspace

You can create your Datasource in an existing or newly-created Workspace. Make a GET request to @data to see a list of the available Workspaces for your account and note the URL listed as the @id value of the Workspace where you want to create the Datasource.

Ensure you have permissions to edit the Workspace

You must have Manage permissions for a Workspace (opens new window) to create Datasources in it. In the response payload, they correspond to "guillotina.ModifyContent": true, "guillotina.DeleteContent": true, and "guillotina.AddContent": true.

A successful response will contain the list of your Workspaces and their metadata.

{
    "updates": {
          "@type": "Workspace",
          "@name": "WORKSPACE_ID",
          "@uid": "125g2996823e47a49dedad7ba0173fda",
          "local_shared": true,
          "creation_date": "2021-03-10T10:08:35.269877+00:00",
          "modification_date": "2021-03-10T10:08:35.269877+00:00",
          "creators": [
              "demo@onna.com"
          ],
          "@behaviors": [
              "onna.canonical.behaviors.following.IFollowing",
              "guillotina.behaviors.dublincore.IDublinCore"
          ],
          "group_app_type": "web",
          "description": null,
          "template": false,
          "legal_hold": null,
          "last_preserved": null,
          "title": "Demo Workspace",
          "@users-permissions": {
              "guillotina.ModifyContent": true,
              "guillotina.DeleteContent": true,
              "guillotina.AddContent": true,
              "guillotina.SeePermissions": true,
              "guillotina.ChangePermissions": true,
              "onna.SendToSpyder": true
          },
          "@path": "/workspaces/WORKSPACE_ID",
          "@timestamp": "2021-03-10T10:08:35.782491",
          "@cursor": "2021-03-10 10:08:35.782491//125g2996823e47a49dedad7ba0173fda",
          "@assigned-roles": {
              "guillotina.Reader": [
                  "WORKSPACE_ID"
              ],
              "guillotina.Owner": [
                  "admin@acmecorp.com"
              ]
          },
          "@id": "https://enterprise.onna.com/api/ACMECORP/ACMECORP/workspaces/WORKSPACE_ID"
      },
    "total": 1,
    "deleted": [],
    "cursor": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

# Get the UID of the admin credentials

With the UID of the admin credentials you'll be authorized to collect data by the connected app. In Onna, those credentials are stored in containers called Wallets. You can find the credentials by sending a GET request the @data endpoint for Wallets.

A successful response will contain the list of your Wallet credentials.

Choose the right credentials

If you have several Slack credentials and don't know which one to choose, look at the team parameter, which matches the name of your Slack instance.

{
    "updates":
      {
          "@type": "WalletEntry",
          "@name": "fak3246cf67145f4ked3mo618f69d3m0",
          "@uid": "fak3246cf67145f4ked3mo618f69d3m0",
          "local_shared": true,
          "creation_date": "2020-04-23T22:10:44.195386+00:00",
          "modification_date": "2021-03-10T10:01:12.209785+00:00",
          "creators": [
              "admin@acmecorp.com"
          ],
          "@behaviors": [
              "guillotina.behaviors.dublincore.IDublinCore"
          ],
          "metadata": {
              "team_id": "T8HRFAKE5",
              "team": "acmecorp-slack-team"
          },
          "credential_type_name": "SlackEDatasource",
          "config_type": null,
          "title": "Slack Enterprise",
          "credentials_status": "200",
          "original_account": "admin@acmecorp.com",
          "@users-permissions": {
              "guillotina.ModifyContent": false,
              "guillotina.DeleteContent": false,
              "guillotina.AddContent": true,
              "guillotina.SeePermissions": false,
              "guillotina.ChangePermissions": false,
              "onna.SendToSpyder": false
          },
          "@path": "/wallet/fak3246cf67145f4ked3mo618f69d3m0",
          "@timestamp": "2021-03-10T10:01:12.226128",
          "@cursor": "2021-03-10 10:01:12.226128//fak3246cf67145f4ked3mo618f69d3m0",
          "@id": "https://enterprise.onna.com/api/ACMECORP/ACMECORP/wallet/fak3246cf67145f4ked3mo618f69d3m0"
      },
    "total": 1,
    "deleted": [],
    "cursor": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# Create Datasource

Now you must create the Datasource in your Workspace. Later, you will patch it with the settings of the data you want to collect from Slack. This method prevents the Datasource from being shown to users until you have configured all the settings.

Confirm that you have permission to create Slack Enterprise Datasources

To ensure you can create a Slack Enterprise Datasource in Onna, you can make a GET request to the @datasourceTypes endpoint. If you do, SlackEDatasource will be listed in the enabled_edatasources part of the response payload.

Make a POST request to your Workspace and include the Datasource settings in the payload.

A successful response will contain some basic Datasource information.

{
    "@id": "https://enterprise.onna.com/api/ACMECORP/ACMECORP/workspaces/WORKSPACE_ID/DEMO_DATASOURCE",
    "@name": "DEMO_DATASOURCE",
    "@type": "SlackEDatasource",
    "@uid": "ffak3246cf67145f4ked3mo618f69d3m0"
}

1
2
3
4
5
6

In the payload:

@type indicates the app you are creating the Datasource for
sync_status with a value of created will prevent the Datasource from being processed and from being shown to users
Replace the value of wallet_credentials with the UID of your Wallet credentials
Set the data_types values to resources
title is the name of the Datasource that will be displayed on the UI
The value of id is used for the URI of your Datasource. Ensure it follows URI standards (opens new window)

If you don't remember the name of your Datasource

Make a GET request to https://enterprise.onna.com/api/ACMECORP/ACMECORP/workspaces/WORKSPACE_ID/@data?types=_datasources_ to retrieve a list of the existing ones.

# Get Slack information

When creating a Slack Enterprise Datasource, you must set it to retrieve information about specific teams or users. To do that, you need the team ID and the user ID.

You can get that information from the @api/teams and @api/users/info endpoints that become available at your Datasource's location after you create it.

# Get Slack user ID

With the email address of the user you want to collect data for, you can retrieve their ID. You will need it later to configure the Datasource.

Make a POST request to the @api/user/info endpoint at your Datasource's location and include the email address in the request payload. This will launch an asynchronous job that you can then query to get the results.

A successful response will contain the job ID that you can use to retrieve the results afterwards.

{
    "status": "scheduled",
    "job_id": "1sf4k31sf4k31sf4k31sf4k31sf4k31s"
}

1
2
3
4

Now, make a GET request to the same endpoint, but append the value of the job_id. For example:

A successful response will give you the user information linked to the email you provided, including the Slack user ID.

{
    "status": "finished",
    "job_id": "1sf4k31sf4k31sf4k31sf4k31sf4k31s",
    "result": [
        {
            "id": "F4K3IDF4K3",
            "name": "acmeuser",
            "profile": {
                "real_name": "Acme User",
                "display_name": "Best Employee",
                "email": "acmeuser@acmecorp.com"
            },
            "teams": null,
            "is_bot": false,
            "deleted": false
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Get Slack team ID

Make a POST request the @api/teams endpoint at your Datasource's location to retrieve the available Slack Enterprise teams.

A successful response will contain the list of the available Workspaces for the Datasource with their name and ID.

[
    {
        "id": "FAK3TEAM0",
        "name": "acmecorp-slack-team",
        "description": "Acmecorp's Slack Team"
    }
]

1
2
3
4
5
6
7

# Configure Datasource

Now that you know the information of users and teams you want to collect data from, you can finish the configuration of your Datasource.

Make a PATCH request to the Datasource and add to the payload the settings for the data you want to collect. For example:

In this payload:

Set sync_status to pending to make the Datasource show up in the UI
Set type_sync to arch to ensure data is kept in Onna even if the user deletes it in Slack Enterprise
public, private,mpim, and im, represent the conversations you want to collect. Respectively public and private channels, multiparty, and private conversations
Set use_custodian_collection to true to set the Datasource as a user-based collection and retain all data from a specific user
Replace FAK3D3M0ID0 with the ID of the user you want to collect data from
The from_date and to_date parameters are optional and set the date and time boundaries of the data collected
Under selected, replace the id value FAK3D3M0ID0 with the ID of the user you want to collect data from

A successful response will have a 204 No Content status.

# Sync Datasource

Now that your Datasource is configured, you can start syncing data.

Make a GET request and force the sync.

A successful response will have a 200 OK status.

As data is synced, it will start populating your Datasource in the Onna UI.

create-slack-ds-sync-completed

← Datasource sync types and statuses Create a Preservation →