diff --git a/models/automations/create-automations.mdx b/models/automations/create-automations.mdx index 87a74430d6..22bb7d8b48 100644 --- a/models/automations/create-automations.mdx +++ b/models/automations/create-automations.mdx @@ -23,6 +23,10 @@ Looking for companion tutorials for automations? - To create a Slack automation, you must have permission to post to the Slack instance and channel you select. ## Create an automation +You can create an automation using the W&B App or the Python SDK. Select a tab to continue. + + + Create an automation from the project or registry's **Automations** tab. At a high level, to create an automation, follow these steps: 1. If necessary, [create a W&B secret](/platform/secrets/) for each sensitive string required by the automation, such as an access token, password, or SSH key. Secrets are defined in your **Team Settings**. Secrets are most commonly used in webhook automations. @@ -43,12 +47,87 @@ For details, refer to: - [Create a Slack automation](/models/automations/create-automations/slack/) - [Create a webhook automation](/models/automations/create-automations/webhook/) + + +To create an automation using the Python SDK, define the [event and scope](/models/ref/python/automations#events-triggers), the [action](/models/ref/python/automations#actions) to take, and [filters](https://docs.wandb.ai/models/ref/python/automations#filters) (optional). Next, use [`api.create_automation`](/models/ref/python/public-api/api#method-api-create-automation) to create the automation. + +This example code creates an automation that sends a Slack notification whenever a metric called `custom-metric` exceeds `10`. `custom-metric` is expected to be logged during training using `wandb.Run.log({"custom-metric": value })`. + +```python +import wandb +from wandb.automations import OnRunMetric, RunEvent, SendNotification + +api = wandb.Api() + +project = api.project("", entity="") + +# Use the first Slack integration for the team +slack_hook = next(api.slack_integrations(entity="")) + +# Create a trigger event +event = OnRunMetric( + scope=project, + filter=RunEvent.metric("custom-metric") > 10, +) + +# Create an action that responds to the event +action = SendNotification.from_integration(slack_hook) + +# Create the automation +automation = api.create_automation( + event >> action, + name="my-automation", + description="Send a Slack message whenever 'custom-metric' exceeds 10.", +) +``` + +For more details about creating automations programmatically, see the [Automations SDK reference](/models/ref/python/automations) + + + ## View and manage automations +You can view and manage automations using the W&B App or the Python SDK. Select a tab to continue. + + + View and manage automations from a project or registry's **Automations** tab. - To view an automation's details, click its name. - To edit an automation, click its action `...` menu, then click **Edit automation**. - To delete an automation, click its action `...` menu, then click **Delete automation**. + + +### List automations +To list automations, use the [`Api.automations`](/models/ref/python/public-api/api#method-api-automations) method. Optionally, set the `entity` parameter to a team to return only automations from that team. For example: + +```python +import wandb + +api = wandb.Api() +automations = api.automations(entity="my-team") +``` +If you omit the entity, all automations are returned that you have permission to view, regardless of the team. + +### Update an automation +To edit an automation programmatically, use the [`Api.update_automation`](/models/ref/python/public-api/api#method-api-update-automation) method. Set the `name` parameter to the name of the automation to update. You can update any detail about the automation, including the name, description, action, event, or scope, or turn the automation on or off by changing the value of `enabled`. + +This example turns off an automation and edits its description: +```python +import wandb + +api = wandb.Api() + +automation = api.automation(name="my-automation") +automation.enabled = False +automation.description = "Kept for reference, but no longer used." + +updated_automation = api.update_automation(automation) +``` + +### Delete an automation +To delete an automation programmatically, use the [`Api.delete_automation`](/models/ref/python/public-api/api#method-api-delete-automation) method, which accepts either an `Automation` object or the automation ID passed as a string. + + ## Next steps - Learn more about [automation events and scopes](/models/automations/automation-events/) diff --git a/models/automations/create-automations/slack.mdx b/models/automations/create-automations/slack.mdx index aa67c0b103..52bec19962 100644 --- a/models/automations/create-automations/slack.mdx +++ b/models/automations/create-automations/slack.mdx @@ -14,7 +14,8 @@ At a high level, to create a Slack automation, you take these steps: 1. [Create the automation](#create-an-automation), which defines the [event](/models/automations/automation-events/) to watch for and the channel to notify. ## Add a Slack integration -A team admin can add a Slack integration to the team. + +To add a Slack integration to the team: 1. Log in to W&B and go to **Team Settings**. 1. In the **Slack channel integrations** section, click **Connect Slack** to add a new Slack instance. To add a channel for an existing Slack instance, click **New integration**. @@ -35,6 +36,10 @@ A team admin can view and manage the team's Slack instances and channels. ## Create an automation After you [add a Slack integration](#add-a-slack-integreation), select **Registry** or **Project**, then follow these steps to create an automation that notifies the Slack channel. + +To create an automation programmatically, use the [`api.create_automation`](/models/ref/python/public-api/api#method-api-create-automation) method. + + A Registry admin can create automations in that registry. @@ -80,6 +85,12 @@ A W&B admin can create automations in a project. ## View and manage automations + +To view, manage, or delete automations programmatically, use these Python SDK methods: +- [`Api.automations`](/models/ref/python/public-api/api#method-api-automations) +- [`Api.update_automation`](/models/ref/python/public-api/api#method-api-update-automation) +- [`Api.delete_automation`](/models/ref/python/public-api/api#method-api-delete-automation) + Manage the registry's automations from the registry's **Automations** tab. diff --git a/models/automations/create-automations/webhook.mdx b/models/automations/create-automations/webhook.mdx index 9d382bd8ac..3a8d989126 100644 --- a/models/automations/create-automations/webhook.mdx +++ b/models/automations/create-automations/webhook.mdx @@ -44,6 +44,10 @@ Now you can [create an automation](#create-a-webhook-automation) that uses the w ## Create an automation After you [configure a webhook](#create-a-webhook), select **Registry** or **Project**, then follow these steps to create an automation that triggers the webhook. + +To create an automation programmatically, use [`api.create_automation`](/models/ref/python/public-api/api#method-api-create-automation). + + A Registry admin can create automations in that registry. Registry automations are applied to all collections in the registry, including those added in the future. @@ -93,6 +97,13 @@ A W&B admin can create automations in a project. ## View and manage automations + + +To view, manage, or delete automations programmatically, use these Python SDK methods: +- [`Api.automations`](/models/ref/python/public-api/api#method-api-automations) +- [`Api.update_automation`](/models/ref/python/public-api/api#method-api-update-automation) +- [`Api.delete_automation`](/models/ref/python/public-api/api#method-api-delete-automation) + Manage a registry's automations from the registry's **Automations** tab.