# Model Version Trigger

Launch executions or pipelines automatically when a model's latest approved version changes. Perfect for automating deployment workflows, validation checks, or downstream updates when models are approved.

## Use Case

Deploy models immediately after they're approved, without manual intervention. When someone approves a model version (or rejects the current one, making an older version the latest), your deployment workflow launches automatically.

**Perfect for:**

* Auto-deploying approved models to production
* Running validation checks on newly approved models
* Updating downstream systems when model versions change
* Uploading model files to external repositories

***

## How It Works

1. **Model approved:** User approves a model version in Valohai
2. **Notification fires:** "Model latest approved version changes" event triggers
3. **Pipeline launches:** Your deployment workflow starts automatically
4. **Parse payload:** First node extracts model version URI from notification
5. **Deploy model:** Second node receives URI and deploys the model

### What Counts as "Latest Approved Version Changes"?

This event fires when:

* **A new version is approved** (becomes the latest approved)
* **Current latest is rejected** (an older approved version becomes latest)

The notification always contains the **current** latest approved version — which is always approved and always the latest.

{% hint style="info" %}
**Concurrent runs:** If the latest approved version changes again during your workflow, the current run continues unaffected. A new notification fires, launching a new run with the updated version.
{% endhint %}

***

## Step 1: Create a Model (or Use Existing)

You need a model to trigger automation for. You can use an existing model or create a new one.

### Create New Model

1. Navigate to your project → **Models** tab
2. Click **+ Create Model**
3. Enter model name (e.g., "Rock Formations")
4. Note the **model slug** from the URI (e.g., `rock-formations` from `model://rock-formations`)

{% hint style="warning" %}
**Use the slug, not the name:** The slug is the immutable identifier. If you rename the model, the slug stays the same, so your automation won't break.
{% endhint %}

***

## Step 2: Create the Scripts

### Parse Notification Payload

This script extracts the model version URI from the notification payload.

Create `new_latest_version.py`:

```python
"""Parse latest model version from the payload.

The payload is a JSON file that Valohai sends to the step.
"""

import json
import valohai

# notification payload is provided in a Valohai input file
input_file = valohai.inputs("payload").path()

# get the json "payload" content from the input file
with open(input_file) as file:
    payload = json.load(file)

# retrieve the new model version URI from the payload
model_version_uri = payload["data"]["model_version"]["uri"]

# output the URI
print(f"The latest approved model version is: {model_version_uri}")
# output it as metadata for use in a pipeline input edge later
print(json.dumps({"model": model_version_uri}))
```

### Basic YAML Configuration

Add to `valohai.yaml`:

```yaml
- step:
    name: new_latest_version
    image: python:3.12
    command:
      - pip install valohai-utils
      - python ./new_latest_version.py {parameters}
    inputs:
      - name: payload
```

***

## Step 3: Create the Trigger

1. Go to Project Settings → Triggers
2. Click **Create Trigger**
3. Configure:

**Basic Settings:**

* **Title:** `New model version handler`
* **Trigger Type:** Notification

**Conditions:** Add **Payload Filter** to only trigger for your specific model:

* **Lookup Path:** `data.model.slug`
* **Operation:** Equals
* **Invariant:** `rock-formations` (use your model's slug)

{% hint style="info" %}
**Why filter by slug?** Without this filter, the trigger fires for **every** model in your project. The filter ensures it only runs for your specific model.
{% endhint %}

**Actions:**

* **Action Type:** Run Execution
* **Source Commit Reference:** `main`
* **Execution Step:** `new_latest_version`
* **Execution Title:** (optional)
* **Payload Input Name:** `payload`

4. Click **Save Trigger**

***

## Step 4: Set Up Notification Routing

1. Go to Project Settings → Notifications → Project Notifications
2. Click **Create new notification routing**
3. Configure:
   * **Event:** `model latest approved version changes`
   * **Filter events by users:** All users
   * **Channel:** Select `Launches trigger: New model version handler`
4. Save

***

## Step 5: Test the Trigger

### Upload and Approve a Model Version

1. Go to your model in the Models tab
2. Click **+ Create Version**
3. Upload a model file (any file works for testing)
4. After upload, click **Approve** on the version

### Check Execution Launched

1. Navigate to **Executions** tab
2. Look for automatically created execution
3. Open execution and check logs:

```
The latest approved model version is: model://rock-formations/1
```

Success! Your trigger is working.

***

## Advanced: Upload Model Files to External Service

Let's extend this to actually do something with the approved model, upload it to an external repository.

### Add Upload Script

Create `upload_latest_model.py`:

```python
import valohai
import requests

# Notice! This is a non-functioning sample URL; replace it with your own service endpoint.
# It should accept a single multipart form upload with the field name "model_file".
post_endpoint = "https://example.com/model_repository/"

for file_path in valohai.inputs("model").paths():
    print(f"Uploading {file_path}...")
    with open(file_path, "rb") as model_file:
        requests.post(
            post_endpoint,
            files={"model_file": model_file},
        ).raise_for_status()
```

{% hint style="warning" %}
**Replace the URL:** The example URL is a placeholder. Replace with your actual model repository endpoint.
{% endhint %}

***

### Update YAML for Pipeline

Replace your YAML with this pipeline configuration:

```yaml
- step:
    name: new_latest_version
    image: python:3.12
    command:
      - pip install valohai-utils
      - python ./new_latest_version.py {parameters}
    inputs:
      - name: payload
- step:
    name: upload_latest_model
    image: python:3.12
    command:
      - pip install valohai-utils requests
      - python ./upload_latest_model.py {parameters}
    parameters:
      - name: model_url
        type: string
    inputs:
      - name: model
        default: "{parameter:model_url}"
- pipeline:
    name: Automatically upload newest approved model version
    nodes:
      - name: new_latest_version
        step: new_latest_version
        type: execution
      - name: upload_latest_model
        step: upload_latest_model
        type: execution
    edges:
      - [new_latest_version.metadata.model, upload_latest_model.parameter.model_url]
```

### How the Pipeline Works

**Node 1: new\_latest\_version**

* Receives notification payload
* Extracts model version URI
* Outputs as metadata

**Edge: Connect metadata to parameter**

* Takes `new_latest_version.metadata.model`
* Passes to `upload_latest_model.parameter.model_url`

**Node 2: upload\_latest\_model**

* Receives model URI via parameter
* Downloads model files from Valohai
* Uploads each file to external repository

***

### Update the Trigger

1. Edit your existing trigger
2. Change **Actions:**
   * **Action Type:** Run Pipeline (was: Run Execution)
   * **Pipeline Name:** `Automatically upload newest approved model version`
   * **Pipeline Title:** `Model approved version uploader`
   * **Payload Input Name:** `new_latest_version.payload` (was: `payload`)

{% hint style="info" %}
**Payload input for pipelines:** Format is `<node-name>.<input-name>` to specify which pipeline node receives the notification.
{% endhint %}

3. Save trigger

***

## Step 6: Test End-to-End

1. Upload a new model version
2. Approve it
3. Check Pipelines tab for automatically launched pipeline
4. Verify both nodes execute:
   * First node extracts model URI
   * Second node uploads to external service
5. Check external service to confirm files uploaded

***

## Troubleshooting

### Trigger Not Firing

**Check model slug:**

* Verify payload filter uses correct slug
* Check model page for actual slug in URI

**Check notification routing:**

* Confirm event is "model latest approved version changes"
* Verify channel is correctly selected

**Check trigger status:**

* Ensure trigger is enabled
* Check trigger logs for errors

***

### Pipeline Fails at Upload Node

**Common issues:**

* External endpoint URL is incorrect
* Authentication missing or wrong
* Network connectivity issues
* Model files too large

**Debug steps:**

* Test external endpoint with `curl` or Postman first
* Add authentication headers if required
* Check execution logs for detailed error messages
* Verify model files downloaded successfully before upload attempt

***

### Wrong Model Version Triggered

**Possible causes:**

* Multiple models without payload filters
* Payload filter using name instead of slug
* Model was renamed (name changed but slug stayed same)

**Solutions:**

* Always filter by `data.model.slug`, not name
* Verify slug matches in model URI
* Check trigger logs to see which model fired it

***

### Multiple Triggers Firing

**This is expected if:**

* You have multiple triggers without payload filters
* Multiple models share the same slug (impossible, but check anyway)

**Solutions:**

* Add or fix payload filters
* Consider consolidating triggers if intentional

## Best Practices

### Use Model Slugs for Filtering

Always filter by `data.model.slug`, never by name:

* ✅ `data.model.slug` = `my-model` (stable, never changes)
* ❌ `data.model.name` = `My Model` (can be renamed)

### Validate Before Deploying

Don't blindly deploy approved models:

* Run sanity checks (model loads, correct format)
* Test on validation data
* Verify expected outputs
* Check model size and complexity

### Handle Deployment Failures

Build robust error handling:

* Log detailed error information
* Set up failure notifications
* Test failure scenarios

### Version Your Deployment Code

Your deployment pipeline is critical infrastructure:

* Keep deployment scripts in version control
* Test changes before deploying to production
* Document deployment procedures
* Use staging environments

***

## Next Steps

* **Process datasets automatically:** [Dataset Version Trigger Guide](/automation-overview/triggers/notification-triggers/dataset-version-trigger.md)
* **Schedule recurring jobs:** [Scheduled Triggers](/automation-overview/triggers/scheduled-triggers.md)
* **Integrate external tools:** [Webhook Triggers](/automation-overview/triggers/webhooks.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/automation-overview/triggers/notification-triggers/model-version-trigger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.