Example commands (*) that you can use to validate proxy behavior against the Slack Discovery APIs. Follow the steps and change the values to match your configuration when needed.

For AWS, change the role to assume with one with sufficient permissions to call the proxy (-r flag). Example:

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.enterprise.info -r arn:aws:iam::PROJECT_ID:role/ROLE_NAME

If any call appears to fail, repeat it using the -v flag.

(*) All commands assume that you are at the root path of the Psoxy project.

Read workspaces

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.enterprise.info

Read Users in Grid

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.users.list?include_deleted=true

Read Conversations in Workspace (any kind, public and private)

1. Get a workspace ID (accessor path in response .enterprise.teams[0].id):

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.enterprise.info?limit=1

1. Get conversation details of that workspace (replace workspace_id with the corresponding value):

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.list?team=[workspace_id]&limit=10

Read Messages in Workspace Channel

1. Get a channel ID (accessor path in response .channels[0].id):

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.list?team=[workspace_id]&limit=10

1. Get DM information (no workspace):

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.list?limit=10

1. Read messages for workspace channel:1

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.history?team=[workspace_id]&channel=[channel_id]&limit=10

1. Omit the workspace ID if channel is a DM

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.history?channel=[channel_id]&limit=10

Workspace Channel Info

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.info?team=[workspace_id]&channel=[channel_id]&limit=1

Omit the workspace ID if channel is a DM

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.info?channel=[channel_id]&limit=1

Recent Workspace Conversations

node tools/psoxy-test/cli-call.js -u [your_psoxy_url]/api/discovery.conversations.recent

Examples

• Example Rules

• Example Rules: bulk

• Example Rules: bulk hierarchical

• Example Data : original/discovery-conversations-history.json | sanitized/discovery-conversations-history.json

See more examples in the docs/sources/slack/example-api-responses folder of the Psoxy repository.

Steps to Connect

For enabling Slack Discovery with the Psoxy you must first set up an app on your Slack Enterprise instance.

1. Go to https://api.slack.com/apps and create an app.

   • Select "From scratch", choose a name (for example "Worklytics connector") and a development workspace

1. Take note of your App ID (listed in "App Credentials"), contact your Slack representative and ask them to enable discovery:read scope for that App ID. If they also enable discovery:write then delete it for safety, the app just needs read access.

The next step depends on your installation approach you might need to change slightly

Org wide install

Use this step if you want to install in the whole org, across multiple workspaces.

1. Add a bot scope (not really used, but Slack doesn't allow org-wide installations without a bot scope). The app won't use it at all. Just add for example the users:read scope, read-only.

1. Under "Settings > Manage Distribution > Enable Org-Wide App installation", click on "Opt into Org Level Apps", agree and continue. This allows to distribute the app internally on your organization, to be clear it has nothing to do with public distribution or Slack app directory.

1. Generate the following URL replacing the placeholder for YOUR_CLIENT_ID and save it for

   https://api.slack.com/api/oauth.v2.access?client_id=YOUR_CLIENT_ID

2. Go to "OAuth & Permissions" and add the previous URL as "Redirect URLs"

1. Go to "Settings > Install App", and choose "Install to Organization". A Slack admin should grant the app the permissions and the app will be installed.

1. Copy the "User OAuth Token" (also listed under "OAuth & Permissions") and store as PSOXY_SLACK_DISCOVERY_API_ACCESS_TOKEN in the psoxy's Secret Manager. Otherwise, share the token with the AWS/GCP administrator completing the implementation.

Workspace install

Use this steps if you intend to install in just one workspace within your org.

1. Go to "Settings > Install App", click on "Install into workspace"

2. Copy the "User OAuth Token" (also listed under "OAuth & Permissions") and store as PSOXY_SLACK_DISCOVERY_API_ACCESS_TOKEN in the psoxy's Secret Manager. Otherwise, share the token with the AWS/GCP administrator completing the implementation.

Bulk Data Flow

beta As an alternative to connecting Worklytics to the Slack Discovery API via the proxy, it is possible to use the bulk-mode of the proxy to sanitize an export of Slack Discovery data and ingest the resulting sanitized data to Worklytics. Example data of this is given in the example-bulk/ folder.

This data can be processing using custom multi-file type rules in the proxy, of which discovery-bulk.yaml is an example.

For clarity, example files are NOT compressed, so don't have .gz extension; but rules expect .gz.