Zotero Slack Connector

Pings a Slack channel with Zotero updates.

This Slack bot sends two kinds of messages:

• Recent papers: a list of the most recent papers added to a Zotero group
• Papers added since last message: a list of the papers added to a Zotero group since the Slack bot's last message in this channel

Originally created to update a Learning Engineering Virtual Institute Slack channel. Read more.

Usage

You can run the Zotero Slack Connector from the command line, assuming the presence of a .env file with the appropriate environment variables (see below).

uv run python -m zsc

Deployment

The connector can be deployed to either Google Cloud or Azure.

Quick Start - Azure

1. Create Azure resources (Container Registry, Key Vault)
2. Upload secrets: uv run python src/zsc/azure.py
3. Build and push Docker image to Azure Container Registry
4. Deploy using Azure Container Apps with scheduled jobs or Container Instances + Logic Apps

See AZURE_DEPLOYMENT.md for full instructions.

Quick Start - Google Cloud

The Docker image is built and pushed to the image repository on commits to main, thanks to a Cloud Build trigger.

Updating the Cloud Run function/job is currently manual.

• Create a Cloud Run job/function, pointing to the Docker image and any required secrets.
• Create a Cloud Scheduler cron trigger to invoke the function. I'm using 0 */6 * * * to execute every 6 hours.

Development

Install deps with uv sync.

To run tests:

uv run pytest

To play around with notebooks:

uv run jupyter lab

To add dependencies:

uv add numpy
# or, for dev dependencies
uv add --group dev pytest

Secrets

Create a .env file with appropriate values.

Here are the basic settings you'll want to include:

# Required configuration
ZOTERO_API_KEY="AAAAAAAAAAAAAAAAAAAAAAAA"
ZOTERO_GROUP_ID="1234567"
SLACK_BOT_TOKEN="xoxb-0000000000000-0000000000000-AAAAAAAAAAAAAAAAAAAAAAAA"
SLACK_CHANNEL_IDS="CAAAAAAAAAA"

# Optional configuration
ZOTERO_GROUP_LINK_TEXT="the <your-group> Zotero group"

# Google Cloud-specific configuration (choose one)
# The ID of your Google Cloud project (required for uploading secrets)
GCLOUD_PROJECT_ID="some-project-000000"

# Azure-specific configuration (choose one)
# The name of your Azure Key Vault (required for uploading secrets)
AZURE_KEY_VAULT_NAME="your-keyvault"

The ZOTERO_API_KEY can be generated per the instructions here, and it is required if pulling from a non-public group. The ZOTERO_GROUP_ID can be easily found in the group's URL; just visit the group in a browser and copy the group identifier from the URL path.

SLACK_BOT_TOKEN should be generated by creating and installing an app in your Slack workspace. Add the bot to the channel you want to provide updates in, and you can determine the Slack channel IDs by running uv run python src/zsc/slack.py

Uploading Secrets to Azure Key Vault

If you provide an AZURE_KEY_VAULT_NAME, you can upload secrets to Azure Key Vault from the command line:

# First, ensure you're logged in to Azure
az login

# Upload secrets from .env file
uv run python src/zsc/azure.py

This will create new secrets but will not update existing secret values that have changed in your .env file. To update secrets, you can either:

• Delete the secret and re-run the script: az keyvault secret delete --vault-name <vault-name> --name <secret-name>
• Manually update using the CLI: az keyvault secret set --vault-name <vault-name> --name <secret-name> --value <new-value>
• Use the Azure Portal web UI

Uploading Secrets to Google Cloud

If you provide a GCLOUD_PROJECT_ID, you can upload the remaining secrets to Google Cloud Secret Manager from the command line:

uv run src/zsc/gcp.py

This will not update secret values that have changed in your .env file. To update secrets, manually update the expected secret using the CLI or the web UI.

Other configuration

A few other behavioral settings are configurable via the environment variables (such as the ZOTERO_GROUP_LINK_TEXT, which customizes the text used in the resulting report). Look at the code to see what is configurable.

Docker

Build Docker image:

docker build -t zotero-slack-connector .

Execute locally:

docker run --env-file .env zotero-slack-connector