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 (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
}
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 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"
}
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)
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"
}
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
}
]
}
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"
}
]
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
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 public
,private
,mpim
, andim
, represent the conversations you want to collect. Respectively public and private channels, multiparty, and private conversations- Set
use_custodian_collection
totrue
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
andto_date
parameters are optional and set the date and time boundaries of the data collected - 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.
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.