Create user-based Slack Enterprise Datasource
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
}
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
}
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"
}
2
3
4
5
6
In the payload:
@type
indicates the app you are creating the Datasource forsync_status
with a value ofcreated
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 toresources
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"
}
]
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"
}
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
topending
to make the Datasource show up in the UI - Set
type_sync
toarch
to ensure data is kept in Onna even if the user deletes it in Slack Enterprise - Set
use_custodian_collection
totrue
to set the Datasource as a user-based collection and retain all data from a specific user - The value of
sync_filters
has the syntaxuser-FAK3D3M0ID0
. ReplaceFAK3D3M0ID0
with the ID of the user you want to collect data from - The
from_date
andto_date
parameters are optional and set the date and time boundaries of the data collected - Under
excluded
, replace the Workspace IDFAK3TEAM0
with the ID of your Slack Team - Under
selected
, replace theid
valueFAK3D3M0ID0
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.