Notifications

Slack Notifications

To send Slack notifications, you’ll need to have your own Slack app. If you don’t have one, you may follow steps 1 and 2 to create it. Otherwise, please proceed to Step 3.

Note: This module also requires an optional dependency. See Installation for details.

Step 1: Set up a Slack environment to receive messages

  1. Create a Slack app

  2. Specify the app Name, such as my_slack_app

  3. Choose a Development Slack Workspace you want to receive messages upon

  4. Click Create App

  5. Go to Building Apps for Slack -> Add features and functionality -> Permissions

  6. In Scopes, click Add an OAuth Scope and add chat:write to Bot Token Scopes

  7. Click Install App to Workspace

  8. Click Allow

  9. Copy Bot User OAuth Access Token as your slack_api_token

Step 2: Add the Slack app to a Slack channel

Make sure you add the Slack app to a public Slack channel via Details -> More -> Add apps on the channel UI. You may locate Details using a circled exclamation mark on its left side.

Step 3: Use Cases

  • You can customize and send any Slack messages by calling notifications.slack.send_message().

  • If you have already created a slack client (NOT your Slack app!), you can directly pass it via the argument slack_client, otherwise you may create one using WebClient(token=slack_api_token)

  • notifications.slack.monitor_job() monitors a single job/operation kicked off by either the UI (using a job ID), or the Tamr-Client (using a Tamr operation). Notifications will stop if 1) the job is resolved, or 2) the timeout is reached. To reduce redundancy, a Slack message will be generated ONLY when the job is established, or the job state gets updated. For example, when a job switches from RUNNING to SUCCEEDED, a slack message including [host_ip, job_id, job_description, job state: SUCCEEDED] will be posted to the public Slack channel which your Slack app joins at STEP 3.

  • You may further customize/limit what job states (e.g., SUCCEEDED, FAILED, CANCELLED, PENDING, RUNNING) you would like to be notified using the argument notify_states.

"""Example script for generating Slack notifications based on Tamr jobs"""
import tamr_toolbox as tbox
from slack import WebClient

from tamr_toolbox.models.operation_state import OperationState

# Make Tamr Client
tamr = tbox.utils.client.create(username="user", password="pw", host="localhost")

# Make Slack Client with your own slack api token, a Bot User token that starts with "xoxb-"
slack_api_token = "xoxb-12345-12345-A1b2C3d4E5"
slack_client = WebClient(token=slack_api_token)

# Send any texts to a Slack channel
tbox.notifications.slack.send_message(
    slack_client=slack_client, channel="#test_tbox_messaging", message="This is a test message.",
)

# Use case 1: Track the status updates for a specific job using its job id
tbox.notifications.slack.monitor_job(
    tamr=tamr, slack_client=slack_client, channel="#test_tbox_messaging", operation="my_job_id",
)

# Use case 2: Track the status updates for a job kicked off by the tamr-unify-client
project = tamr.projects.by_name("Project_1")
op = project.unified_dataset().refresh(asynchronous=True)
tbox.notifications.slack.monitor_job(
    tamr=tamr,
    slack_client=slack_client,
    channel="#test_tbox_messaging",
    operation=op,
    notify_states=[OperationState.SUCCEEDED, OperationState.FAILED, OperationState.CANCELED],
)

Email Notifications

"""Example script for generating Email notifications based on Tamr jobs"""
import tamr_toolbox as tbox
from tamr_toolbox.models.operation_state import OperationState

# Make Tamr Client
tamr = tbox.utils.client.create(username="user", password="pw", host="localhost")

# Make Email configuration object that include smtp server information
# and sender/recipient email addresses
config = {
    "sender_address": "sender@gmail.com",
    "sender_password": "sender_email_password",
    "recipient_addresses": ["recipient@gmail.com"],
    "smtp_server": "smtp.gmail.com",
    "smtp_port": 587,
}


# Send any email message
tbox.notifications.emails.send_email(
    message="This is a test message.",
    subject_line="Subject",
    sender_address=config["sender_address"],
    sender_password=config["sender_password"],
    recipient_addresses=config["recipient_addresses"],
    smtp_server=config["smtp_server"],
    smtp_port=config["smtp_port"],
)

# Use case 1: Track the status updates for a specific job using its job id
tbox.notifications.emails.monitor_job(
    tamr=tamr,
    sender_address=config["sender_address"],
    sender_password=config["sender_password"],
    recipient_addresses=config["recipient_addresses"],
    smtp_server=config["smtp_server"],
    smtp_port=config["smtp_port"],
    operation="my_job_id",
)

# Use case 2: Track the status updates for a job kicked off by the tamr-unify-client
project = tamr.projects.by_name("Project_1")
op = project.unified_dataset().refresh(asynchronous=True)
tbox.notifications.emails.monitor_job(
    tamr=tamr,
    sender_address=config["sender_address"],
    sender_password=config["sender_password"],
    recipient_addresses=config["recipient_addresses"],
    smtp_server=config["smtp_server"],
    smtp_port=config["smtp_port"],
    operation=op,
    notify_states=[OperationState.SUCCEEDED, OperationState.FAILED, OperationState.CANCELED],
)