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 in your Slack account with access to Slack's Audit Logs API
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
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. Send 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": "demo-workspace-YLzLFe",
          "@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/demo-workspace-YLzLFe",
          "@timestamp": "2021-03-10T10:08:35.782491",
          "@cursor": "2021-03-10 10:08:35.782491//125g2996823e47a49dedad7ba0173fda",
          "@assigned-roles": {
              "guillotina.Reader": [
                  "demo-workspace-YLzLFe"
              ],
              "guillotina.Owner": [
                  "admin@acmecorp.com"
              ]
          },
          "@id": "https://enterprise.onna.com/api/ACMECORP/ACMECORP/workspaces/demo-workspace-YLzLFe"
      },
    "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 the Datasource

Confirm that you can create Slack Enterprise Datasources

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

Now you must create the Datasource that later you will patch with the settings of the data you want to collect from Slack. This method will prevent the Datasource from being shown to users until you have configured all the settings.

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/demo-workspace-YLzLFe/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)

# Get Slack information

If you are 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 @getTeams and @getEnterpriseUsers endpoints that become available after you create a Slack Enterprise Datasource.

If you don't remember the name of your Datasource

Send 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 team ID

Make a POST request the @getTeams endpoint at your Datasource 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"
    }
]

1
2
3
4
5
6

# Get Slack user ID

Make a GET request the @getEnterpriseUsers endpoint at your Datasource to retrieve the available Slack Enterprise users.

A successful response will contain the list of the existing users in Slack. Note their id value.

{
    "users": [
        {
            "id": "F4K3D3M0ID0",
            "name": "mscott",
            "real_name": "Michael Scott",
            "teams": [
                "FAK3TEAM0"
            ],
            "email": "michael@dundermifflin.com",
            "display_name": "REGIONAL MANAGER",
            "is_bot": false,
            "deleted": false
        },
        {
            "id": "F4K3D3M0ID2",
            "name": "pbeasley",
            "real_name": "Pam Beasley",
            "teams": [
                "FAK3TEAM0"
            ],
            "email": "pamela@dundermifflin.com",
            "display_name": "PAM",
            "is_bot": true,
            "deleted": false
        },
        {
            "id": "F4K3D3M0ID3",
            "name": "dschrute",
            "real_name": "Dwight Schrute",
            "teams": [
                "FAK3TEAM0"
            ],
            "email": "dwight@dundermifflin.com",
            "display_name": "ASSISTANT REGIONAL MANAGER",
            "is_bot": false,
            "deleted": false
        },
    ],
        "offset": "F4K3D3MOZ"
}

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

When lists have more than a 1000 users

You can use the value of the offset parameter to get more results. Send another request to @getEnterpriseUsers and append the offset value. For example, https://enterprise.onna.com/api/ACMECORP/ACMECORP/workspaces/demo-workspace-YLzLFe/demo-datasource/@getEnterpriseUsers?offset=F4K3D3MOZ.

# Configure Datasource

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

Send 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
Set use_custodian_collection to true to set the Datasource as a user-based collection and retain all data from a specific user
The value of sync_filters has the syntax user-FAK3D3M0ID0. 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 excluded, replace the Workspace ID FAK3TEAM0 with the ID of your Slack Team
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.

Send a GET request to the @sendToSpyder endpoint in your Datasource 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 →