Skip to content

SlackDiscussionReporter

This content has moved!

We have moved our samples to a separate, dedicated site: https://solutions.atlan.com.

This document is no longer being maintained.

Extracts counts of the number of Slack conversations tracked against each asset, producing an Excel workbook consisting of 1 worksheet with the following columns:

Column name Usage
Qualified name Unique name of the asset.
Type Type of the asset.
Name Human-readable name of the asset.
Slack Number of discussions through Slack linked to this asset.
Link Link to the asset in Atlan.

Configuration

You can configure the following options for this reporter as environment variables:

ATLAN_BASE_URL

URL for your Atlan tenant (for example: https://tenant.atlan.com).

ATLAN_API_KEY

API token to use when accessing Atlan.

BATCH_SIZE

Defines how many records the API calls attempt to retrieve on each request. (Defaults to 50 if not specified.)

FILE_PREFIX

Defines what the Excel file's name will start with. (Defaults to slack-discussion-report if not specified.)

REGION

Defines the AWS region of the S3 bucket where you want to write the Excel file output.

BUCKET

Defines the S3 bucket where you want the reporter to store the Excel file output. (Note that there is no default value for this, so this must be sent for the utility to run via a Lambda function and produce consumable output — if blank (default) the reporter produces a local Excel file.)

Lambda configuration

To use this reporter as an AWS Lambda function, you can configure the same variables as above, but send them in a JSON structure:

Lambda configuration
{
  "BATCH_SIZE": "50",
  "FILE_PREFIX": "slack-discussion-report",
  "REGION": "ap-south-1",
  "BUCKET": ""
}

Logging

By default, only messages at INFO and above will be logged (to the console). You can change this level by copying the main/resources/log4j2.xml from the source repo and modifying it to give:

  • more detail (DEBUG will log every API request and response, including their full payloads)
  • less detail (WARN will only print warnings and errors, ERROR only errors).

Running the reporters locally

You can run the reporters locally on any machine with network access to your Atlan tenant.

When run in this mode, the reporter will read the input Excel file locally on the machine running the reporter. If you want to change any of the settings, you can simply prepend the command with the environment variables.

You can run the SlackDiscussionReporter by downloading the pre-compiled jar files for both:

  • Java SDK
  • Samples

With this approach you only need a JRE installed, as you will be using pre-compiled code.

Requires at least Java 11, though 17+ is recommended

You must have a Java 11 (or higher) JRE installed to use the samples. If possible, we recommend using Java 17 (or higher) for significantly improved performance.

Run SlackDiscussionReporter from pre-compiled jar files
1
2
3
4
5
6
export ATLAN_BASE_URL=https://tenant.atlan.com  # (1)
export ATLAN_API_KEY=eyNnCJd2T9Y8fEsbdx...
export FILE_PREFIX=slack
java \
    -cp atlan-java-...-jar-with-dependencies.jar:atlan-java-samples-...-jar-with-dependencies.jar \
    com.atlan.samples.reporters.SlackDiscussionReporter  # (2)

  1. Export environment variables for the configuration you want to use. At a minimum:

    • ATLAN_BASE_URL giving the URL of your Atlan tenant
    • ATLAN_API_KEY giving the value of an API token with access to that tenant to load the assets

    Overriding the configuration

    Note that you can specify any optional overrides as environment variables before running the reporter in the same way. For example, you could use export FILE_PREFIX=slack to change the prefix of the file the reporter will produce.

    (Optional) If you want to override the logging settings, also add -Dlog4j.configurationFile=./log4j2.xml just before the canonical classname, pointing to your modified version of the log4j2.xml file.

  2. Within the directory containing the downloaded jar files, run the java command providing at least two arguments:

    1. The two jar files, separated by a :.
    2. The canonical classname of the SlackDiscussionReporter.

    Replace the ... with proper version numbers

    Don't forget to replace the ... in the -cp argument's values with proper version numbers, or running this will not work.

Run SlackDiscussionReporter from pre-compiled jar files
1
2
3
4
5
$env:ATLAN_BASE_URL="https://tenant.atlan.com"  # (1)
$env:ATLAN_API_KEY="eyNnCJd2T9Y8fEsbdx..."
$env:FILE_PREFIX="slack"
$env:CLASSPATH="atlan-java-...-jar-with-dependencies.jar;atlan-java-samples-...-jar-with-dependencies.jar"  # (2)
java com.atlan.samples.reporters.SlackDiscussionReporter  # (3)

  1. Export environment variables for the configuration you want to use. At a minimum:

    • ATLAN_BASE_URL giving the URL of your Atlan tenant
    • ATLAN_API_KEY giving the value of an API token with access to that tenant to load the assets

    Overriding the configuration

    Note that you can specify any optional overrides as environment variables before running the reporter in the same way. For example, you could use $env:FILE_PREFIX="slack" to change the prefix of the file the reporter will produce.

    (Optional) If you want to override the logging settings, also add -Dlog4j.configurationFile=./log4j2.xml just before the canonical classname, pointing to your modified version of the log4j2.xml file.

    Note that on windows you must surround the value of the variable in double-quotes!

  2. In our experience, it seems that the java -cp command does not always work on Windows. Therefore, ensure you set the $env:CLASSPATH environment variable to include the names of the downloaded jar files, separated by a ;.

    Replace the ... with proper version numbers

    Don't forget to replace the ... in the -cp argument's values with proper version numbers, or running this will not work.

  3. Within the directory containing the downloaded jar files, run the java command providing the canonical classname of the SlackDiscussionReporter.

Run SlackDiscussionReporter from pre-compiled jar files
1
2
3
4
5
6
export ATLAN_BASE_URL=https://tenant.atlan.com  # (1)
export ATLAN_API_KEY=eyNnCJd2T9Y8fEsbdx...
export FILE_PREFIX=slack
java \
    -cp atlan-java-...-jar-with-dependencies.jar:atlan-java-samples-...-jar-with-dependencies.jar \
    com.atlan.samples.reporters.SlackDiscussionReporter  # (2)

  1. Export environment variables for the configuration you want to use. At a minimum:

    • ATLAN_BASE_URL giving the URL of your Atlan tenant
    • ATLAN_API_KEY giving the value of an API token with access to that tenant to load the assets

    Overriding the configuration

    Note that you can specify any optional overrides as environment variables before running the reporter in the same way. For example, you could use export FILE_PREFIX=slack to change the prefix of the file the reporter will produce.

    (Optional) If you want to override the logging settings, also add -Dlog4j.configurationFile=./log4j2.xml just before the canonical classname, pointing to your modified version of the log4j2.xml file.

  2. Within the directory containing the downloaded jar files, run the java command providing at least two arguments:

    1. The two jar files, separated by a :.
    2. The canonical classname of the SlackDiscussionReporter.

    Replace the ... with proper version numbers

    Don't forget to replace the ... in the -cp argument's values with proper version numbers, or running this will not work.

You can also run the SlackDiscussionReporter from a clone of the samples repository:

Repo

If you want to change the sample code provided to include additional logic, this is your best option. You have full control over all of the code this way and can make any changes you like before running it.

Additional requirements

You will need a JDK installed to run this way, not only the JRE, as the code must be compiled locally before it can be executed. The computer on which you run the code must also have network access to be able to configure Gradle itself and download the necessary dependencies of the code from Maven Central.

Run SlackDiscussionReporter from a clone of the GitHub repo
export FILE_PREFIX=slack
./gradlew SlackDiscussionReporter # (1)!

  1. Within the root directory of your local clone of the repo, run the Gradle task for the SlackDiscussionReporter.

    Overriding the configuration

    Note that you can specify any optional overrides as environment variables before running the loader. You can either do this in the same line where you run the command, or by exporting them first for example using export FILE_PREFIX=slack.

Example output
18:04:33.705 [main] INFO  com.atlan.samples.reporters.SlackDiscussionReporter - Creating Excel file (streaming)...
18:04:37.244 [main] INFO  com.atlan.samples.reporters.SlackDiscussionReporter - Investigating 7 linked resources in https://tenant.atlan.com in batches of: 50
18:04:37.660 [ForkJoinPool.commonPool-worker-2] INFO  com.atlan.samples.reporters.SlackDiscussionReporter -  ... processed 0/7 (0%)
18:04:37.660 [main] INFO  com.atlan.samples.reporters.SlackDiscussionReporter - Writing report to file: slack-discussion-report-20230906-170435-471.xlsx
More details
  • If there are many links in assets, you will see multiple lines (one per batch) about the extraction of the asset links (Slack discussions).
  • The final line will always tell you the name of the Excel file that it produced.