diff --git a/site/guide/_sidebar.yaml b/site/guide/_sidebar.yaml index f83571cac..6017e6961 100644 --- a/site/guide/_sidebar.yaml +++ b/site/guide/_sidebar.yaml @@ -49,7 +49,15 @@ website: - guide/integrations/link-external-models.qmd - guide/mcp/connect-ai-assistants-via-mcp.qmd - guide/integrations/configure-analytics-exports.qmd - - guide/integrations/integrations-examples.qmd + - file: guide/integrations/integrations-examples.qmd + contents: + - guide/integrations/integrations-examples/create-jira-ticket.qmd + - guide/integrations/integrations-examples/create-servicenow-incident.qmd + - guide/integrations/integrations-examples/synchronize-aws-bedrock.qmd + - guide/integrations/integrations-examples/synchronize-aws-sagemaker.qmd + - guide/integrations/integrations-examples/synchronize-with-databricks.qmd + - guide/integrations/integrations-examples/synchronize-gitlab.qmd + - guide/integrations/integrations-examples/use-webhooks-with-workflows.qmd - text: "---" - section: "Workflows" contents: diff --git a/site/guide/integrations/configure-connections.qmd b/site/guide/integrations/configure-connections.qmd index 944a7fb98..831f96e5a 100644 --- a/site/guide/integrations/configure-connections.qmd +++ b/site/guide/integrations/configure-connections.qmd @@ -121,6 +121,21 @@ Required configuration details: **[personal access token]{.smallcaps}** : Select a secret containing your GitLab Personal Access Token with `api` or `read_api` scope. +### Databricks + +A unified analytics platform for data engineering, data science, and machine learning, including Unity Catalog for centralized metadata management. + +Required configuration details: + +**[databricks host]{.smallcaps}** +: The URL of your Databricks workspace, such as `https://yourcompany.cloud.databricks.com`. + +**[client id]{.smallcaps}** +: The ID of your SQL Warehouse (found in Databricks SQL Warehouses settings). + +**[client secret]{.smallcaps}** +: The secret that stores your Databricks personal access token (PAT). + ### Custom A user-defined connection to a third-party system that implements the {{< var vm.product >}} reference API.[^4] diff --git a/site/guide/integrations/integrations-examples.qmd b/site/guide/integrations/integrations-examples.qmd index 9ee496a77..91c9a5c15 100644 --- a/site/guide/integrations/integrations-examples.qmd +++ b/site/guide/integrations/integrations-examples.qmd @@ -4,461 +4,17 @@ # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial title: "Integrations examples" date: last-modified +listing: + - id: examples-listing + type: grid + grid-columns: 2 + max-description-length: 250 + sort: true + fields: [title, description] + contents: "integrations-examples/*.qmd" --- Adapt these usage examples for your own workflows or connections to interact with external systems. -- [Create a Jira ticket](#create-a-jira-ticket) -- [Create a ServiceNow incident](#create-a-servicenow-incident) -- [Start workflows via webhook](#start-workflows-via-webhook) -- [Add webhook step triggers](#add-webhook-step-triggers) -- [Synchronize models with AWS SageMaker](#synchronize-models-with-aws-sagemaker) -- [Synchronize models with AWS Bedrock](#synchronize-models-with-aws-bedrock) -- [Synchronize models with GitLab](#synchronize-models-with-gitlab) - -::: {.attn} - -## Prerequisites - -- [x] {{< var link.login >}} -- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure workflows.[^1] -- [x] You understand how to configure workflows and add steps to workflows.[^2] -- [x] Secrets are configured for any external systems that require authentication: integration secrets for connections, webhook secrets for HTTP Request step headers.[^3] -- [x] Connections are configured for any external systems you plan to integrate with.[^4] -- [x] You have admin access to the external systems you plan to integrate with. - -::: - -## Workflow examples - -These examples use HTTP requests or webhooks to integrate with external systems: - -- An _HTTP request_ step sends data from {{< var vm.product >}} to another service. A workflow can notify a partner tool when a model reaches a certain state or request an update in an external system. This pattern is useful when {{< var vm.product >}} owns the event and needs to push it outward. - -- A _webhook_ step does the opposite. Another system sends a POST request to start a {{< var vm.product >}} workflow or to continue a workflow that is paused while waiting for a webhook to continue. This lets external tools trigger actions inside {{< var vm.product >}} when an event occurs on their side. - -### Create a Jira ticket - -To create a Jira ticket when model validation requires attention: - -::: {.column-margin} -![Create a Jira issue](integrations-examples-http-request-open-jira-ticket.png){width=80% fig-alt="Screenshot of the HTTP request step configured to create a Jira ticket, showing the required fields described in step 4." .screenshot} -::: - -1. In the left sidebar, click **{{< fa gear >}} Settings**. - -2. Under {{< fa shield >}} Governance, select **Workflows**. - -3. Select the **Model Workflows** tab. - -4. Click on a workflow to modify or click **{{< fa plus >}} Add Model Workflow**[^5] to create a new workflow. - -5. From the **Workflow Steps** modal, drag and drop an **HTTP Request** step[^6] onto the canvas, then connect it to your workflow. - -6. Double-click the step to open the **Configure HTTP Request** modal. - -7. Configure the required fields, replacing the placeholder values with your own: - - - **[url]{.smallcaps}** — `https://yourcompany.atlassian.net/rest/api/3/issue` - - **[method]{.smallcaps}** — POST - - **[headers]{.smallcaps}** — Add: - - `Content-Type`: `application/json` - - `Authorization`: `Bearer {{Jira Personal Access Token}}` - - ::: {.callout-tip title="Use webhook secrets for credentials"} - Instead of entering credentials in plaintext, use a webhook secret: `Bearer {{secret:jira_pat}}`. See [Manage secrets](manage-secrets.qmd#webhook-secrets). - ::: - - - **[body type]{.smallcaps}** — JSON - - **[body]{.smallcaps}** — Use the following JSON payload: - - ```json - { - "fields": { - "project": { - "key": "MODEL" - }, - "summary": "Model validation failed: {{Model Name}}", - "description": "The model [{{Model Name}}|{{Model URL}}] failed validation. Review artifacts in ValidMind.", - "issuetype": { - "name": "Bug" - } - } - } - ``` - -8. Click **Update Step** to save your configuration. - -The HTTP request to create the Jira ticket is sent when the workflow executes the step. - -### Create a ServiceNow incident - -To create a ServiceNow incident when a data drift issue is detected during ongoing monitoring: - -1. In the left sidebar, click **{{< fa gear >}} Settings**. - - -2. Under {{< fa shield >}} Governance, select **Workflows**. - -3. Select the **Model Workflows** tab. - -4. Click on a workflow to modify or click **{{< fa plus >}} Add Model Workflow**[^5] to create a new workflow. - -5. From the **Workflow Steps** modal, drag and drop an **HTTP Request** step[^7] onto the canvas, then connect it to your workflow. - -6. Double-click the step to open the **Configure HTTP Request** modal. - -7. Configure the required fields, replacing the placeholder values with your own: - - - **[url]{.smallcaps}** — `https://yourinstance.service-now.com/api/now/table/incident` - - **[method]{.smallcaps}** — POST - - **[headers]{.smallcaps}** — Add: - - `Content-Type`: `application/json` - - `Authorization`: `Basic {{ServiceNow Credentials}}` - - ::: {.callout-tip title="Use webhook secrets for credentials"} - Instead of entering credentials in plaintext, use a webhook secret: `Basic {{secret:servicenow_creds}}`. See [Manage secrets](manage-secrets.qmd#webhook-secrets). - ::: - - - **[body type]{.smallcaps}** — JSON - - **[body]{.smallcaps}** — Use the following JSON payload: - - ```json - { - "short_description": "Data drift issue detected: {{Model Name}}", - "description": "A potential issue has been identified for model {{Model Name}} (link: [{{Model URL}}]({{Model URL}})). Please review the ongoing monitoring documentation in ValidMind.", - "urgency": "2", - "category": "Model Risk" - } - ``` - -::: {.column-margin} -![Create a ServiceNow incident](integrations-examples-http-request-open-servicenow-incident.png){width=80% fig-alt="Screenshot of the HTTP request step configured to create a ServiceNow incident, showing the required fields described in step 4." .screenshot} -::: - -The HTTP request to create the ServiceNow incident is sent when the workflow executes the step. - -### Start workflows via webhook - -To start a {{< var vm.product >}} workflow from an external system: - -::: {.panel-tabset} - -#### a. Configure workflow in {{< var vm.product >}} - -1. Add a new workflow, selecting the **Via Webhook** workflow start option.[^8] - -2. From the **Workflow Steps** modal, drag and drop a **Webhook** step[^9] onto the canvas, then connect it to your workflow. - -3. Double-click the step to open the **Webhook Step Trigger** modal. - -4. Copy or select the webhook details: - - - **URL** — Click **{{< fa regular copy >}} Copy** for the unique POST webhook URL to use when configuring your external system. - - **[select target model for payload]{.smallcaps}** — Select the model that is associated with the webhook payload from the dropdown. - - **Payload** — Click **{{< fa regular copy >}} Copy** for the JSON payload that external systems must send in their POST request, where the value for `target_cuid` is shown after you select a target: - - ```json - { - "action": "run_workflow", - "target": "", - "entity_name": "InventoryModel" - } - ``` - - - For the required authentication headers, click **{{< fa regular copy >}} Copy** for each of the following key-value pairs and paste them into your external system: - - `x-api-key`: `{{API Key}}` - - `x-api-secret`: `{{API Secret}}` - - **[wait for webhook trigger when reached]{.smallcaps}** — When enabled, the workflow pauses execution when it reaches this step and waits for the external system to send the POST request. - -5. Click **Save**. - -#### b. Start workflow from external system - -Send a POST request to the webhook URL with a JSON payload that includes the `run_workflow` action for the target model CUID: - -```bash -curl -X POST https://api.prod.vm.validmind.ai/vm/api/v1/webhooks/xxxxxxxxxxxxxxxxxxxxxxxxx/xxxx -H 'Content-Type`: `application/json' -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -H 'x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' --data '{ - "action": "run_workflow", - "target": "", - "entity_name": "InventoryModel" -}' -``` +:::{#examples-listing} ::: - -### Add webhook step triggers - -To trigger a waiting {{< var vm.product >}} workflow step to continue from an external system: - -::: {.panel-tabset} - -#### a. Configure workflow in {{< var vm.product >}} - -1. Open the workflow you want to configure, or add a new workflow.[^10] - -2. From the **Workflow Steps** modal, drag and drop a **Webhook** step[^11] onto the canvas, then connect the step to your workflow. - -3. Double-click the step to open the **Webhook Step Trigger** modal. - -4. Copy or select the webhook details: - - - **URL** — Click **{{< fa regular copy >}} Copy** for the unique POST webhook URL to use when configuring your external system. - - **[select target model for payload]{.smallcaps}** — Select the model that is associated with the webhook payload from the dropdown. - - **Payload** — Click **{{< fa regular copy >}} Copy** for the JSON payload that external systems must send in their POST request, where the value for `target_cuid` is shown after you select a target: - - ```json - { - "action": "run_step", - "target": "", - "entity_name": "InventoryModel" - } - ``` - - - For the required authentication headers, click **{{< fa regular copy >}} Copy** for each of the following key-value pairs and paste them into your external system: - - `x-api-key`: `{{API Key}}` - - `x-api-secret`: `{{API Secret}}` - -5. Click **Update Step** to save your configuration. - -When the workflow reaches this step, it pauses and waits for the external system. - -#### b. Trigger workflow to continue from external system - -Send a POST request to the webhook URL with a JSON payload containing the `run_step` action for the model CUID: - -```bash -curl -X POST https://api.prod.vm.validmind.ai/vm/api/v1/webhooks/xxxxxxxxxxxxxxxxxxxxxxxxx/xxxx -H 'Content-Type`: `application/json' -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -H 'x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' --data '{ - "action": "run_step", - "target": "", - "entity_name": "InventoryModel" -}' -``` - -::: - -## Connection examples - -### Synchronize models with AWS SageMaker - -::: {.column-margin} -![Connect with AWS SageMaker](integrations-examples-aws-sagemaker.png){width=80% fig-alt="Screenshot of the AWS Sagemaker connection configured to synchronize models, showing the required fields described in step 5." .screenshot} -::: - -To synchronize models registered in the {{< var vm.product >}} model inventory with AWS SageMaker models, you need to first configure the connection and then link the models: - -#### Configure the connection - -::: {.column-margin} -![A linked AWS SageMaker model](integrations-examples-aws-sagemaker-linked-model.png){width=60% fig-alt="Screenshot of the model linked to AWS SageMaker, showing the required fields described in step 4." .screenshot} -::: - -1. In the left sidebar, click **{{< fa gear >}} Settings**. - -2. Under {{< fa puzzle-piece >}} Integrations, select **Connections**. - -3. Click **{{< fa plus >}} Add Connection**. - -4. In the modal that opens, select **AWS Sagemaker**. - -5. Complete: - - - **[integration name]{.smallcaps}** — How other admins can identify the connection. - - **[description]{.smallcaps}** (optional) — The intended usage or additional details. - - **[aws region]{.smallcaps}** - The primary region where your SageMaker model registry lives, for example `us-west-2`. - - **[aws access key id]{.smallcaps}** — The secret generated by AWS IAM with permissions to read the model registry. - - **[aws secret access key]{.smallcaps}** — The secret generated by AWS IAM with permissions to read the model registry. - - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. - -6. Click **Save Integration**. - -7. Test the connection: - - a. Hover over the AWS SageMaker connection you just created. - b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. - - If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. - - -#### Link the models - -1. In the left sidebar, click **{{< fa cubes >}} Inventory**. - -2. Select a model by clicking on it or find your model by applying a filter or searching for it.[^12] - -3. Scroll down until you locate the **Amazon Sagemaker** connection box in the right sidebar. - -4. Hover over the Amazon SageMaker box. - -5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. - -6. In the modal that opens, click the [select model]{.smallcaps} dropdown to pick the AWS SageMaker model to link. - -7. Optional: Click **Test Connection** to ensure the connection is working as expected. - - If the test is successful, the message **{{< fa check-circle >}} Connection Test Successful** displays. - -8. Click **Link Model**. - -### Synchronize models with AWS Bedrock - -The AWS Bedrock integration lets you link {{< var vm.product >}} models to foundation models and generative AI agents in Amazon Bedrock, supporting governance across your AI/ML ecosystem. - -AWS Bedrock exposes two primary integration surfaces: - -- **Foundation model layer** — Access to AWS-hosted and custom foundation models through the Bedrock model catalog (Discover and Tune views). - -- **Application layer** — Bedrock primitives such as agents, flows, and knowledge bases that represent built generative AI applications and workflows. - -#### Configure the connection - -1. In the left sidebar, click **{{< fa gear >}} Settings**. - -2. Under {{< fa puzzle-piece >}} Integrations, select **Connections**. - -3. Click **{{< fa plus >}} Add Connection**. - -4. In the modal that opens, select **AWS Bedrock**. - -5. Complete: - - - **[integration name]{.smallcaps}** — How other admins can identify the connection. - - **[description]{.smallcaps}** (optional) — The intended usage or additional details. - - **[aws region]{.smallcaps}** — The primary region where your Bedrock resources are deployed, for example `us-east-1`. - - **[aws access key id]{.smallcaps}** — The secret generated by AWS IAM with permissions to access Bedrock. - - **[aws secret access key]{.smallcaps}** — The secret generated by AWS IAM with permissions to access Bedrock. - - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. - -6. Click **Save Integration**. - -7. Test the connection: - - a. Hover over the AWS Bedrock connection you just created. - b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. - - If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. - -#### Link models from Bedrock - -Once the connection is configured, you can link {{< var vm.product >}} models to your Bedrock resources: - -::: {.callout title="Model dependencies"} -Bedrock agents, flows, and runtimes typically call foundation models (LLMs) under the hood. When you link these application-layer resources to {{< var vm.product >}}, consider also registering their underlying foundation models and creating dependency relationships between them. - -This builds a complete dependency graph showing how your AI applications relate to underlying models. Benefits include: - -- **Impact analysis** — See which applications are affected if a foundation model is deprecated or has compliance issues. -- **Full audit trails** — Documentation and risk assessments capture the entire model stack, not just the top-level application. -- **Governance visibility** — Track model versions and changes across your AI ecosystem. -::: - -1. In the left sidebar, click **{{< fa cubes >}} Inventory**. - -2. Select a model by clicking on it or find your model by applying a filter or searching for it.[^13] - -3. Scroll down until you locate the **Amazon Bedrock** connection box in the right sidebar. - -4. Hover over the Amazon Bedrock box. - -5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. - -6. In the modal that opens, use the tabs to filter by resource type: - - - **All** — View all available Bedrock resources. - - **Foundation Models** — AWS-hosted and custom foundation models from the Bedrock catalog. - - **Agents** — Generative AI agents you've built in Bedrock. - - **Flows** — Prompt flows and orchestration workflows. - - **AgentCore Runtimes** — Agent runtime environments. - -7. Click **[select model]{.smallcaps}** to choose the specific Bedrock resource to link. - -8. Optional: Click **Test Connection** to ensure the connection is working as expected. - - If the test is successful, the message **{{< fa check-circle >}} Connection Test Successful** displays. - -9. Click **Link Model**. - -### Synchronize models with GitLab - -Synchronize GitLab model registry with ValidMind model inventory for comprehensive model tracking. - -#### Configure the connection - -::: {.column-margin} -![Configure GitLab connection](integrations-examples-gitlab.png){width=80% fig-alt="Screenshot of the Configure GitLab dialog showing fields for integration name, description, project ID, GitLab instance URL, personal access token, and initial status." .screenshot} -::: - -1. In the left sidebar, click **{{< fa gear >}} Settings**. - -2. Under {{< fa puzzle-piece >}} Integrations, select **Connections**. - -3. Click **{{< fa plus >}} Add Connection**. - -4. In the modal that opens, select **GitLab**. - -5. Complete: - - - **[integration name]{.smallcaps}** — How other admins can identify the connection. - - **[description]{.smallcaps}** (optional) — The intended usage or additional details. - - **[project id]{.smallcaps}** — The GitLab project ID or path containing ML models (required). - - **[gitlab instance url]{.smallcaps}** (optional) — Leave empty to use GitLab.com, or enter your self-hosted GitLab URL. - - **[personal access token]{.smallcaps}** — Select a secret containing your GitLab Personal Access Token with `api` or `read_api` scope. - - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. - -6. Click **Save Integration**. - -7. Test the connection: - - a. Hover over the GitLab connection you just created. - b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. - - If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. - -#### Link the models - -1. In the left sidebar, click **{{< fa cubes >}} Inventory**. - -2. Select a model by clicking on it or find your model by applying a filter or searching for it.[^14] - -3. Scroll down until you locate the **GitLab** connection box in the right sidebar. - -4. Hover over the GitLab box. - -5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. - -6. In the modal that opens, click the [select model]{.smallcaps} dropdown to pick the GitLab model to link. - -7. Optional: Click **Test Connection** to ensure the connection is working as expected. - - If the test is successful, the message **{{< fa check-circle >}} Connection Test Successful** displays. - -8. Click **Link Model**. - - - -[^1]: [Manage permissions](/guide/configuration/manage-permissions.qmd) - -[^2]: [Introduction to workflows](/guide/workflows/introduction-to-workflows.qmd) - -[^3]: [Manage secrets](manage-secrets.qmd) - -[^4]: [Configure connections](configure-connections.qmd) - -[^5]: [Add new workflows](/guide/workflows/configure-workflows.qmd#add-new-workflows) - -[^6]: [Workflow step types](/guide/workflows/workflow-step-types.qmd#http-request) - -[^7]: [Workflow step types](/guide/workflows/workflow-step-types.qmd#http-request) - -[^8]: [Add new workflows](/guide/workflows/configure-workflows.qmd#add-new-workflows) - -[^9]: [Workflow step types](/guide/workflows/workflow-step-types.qmd#webhook) - -[^10]: [Add new workflows](/guide/workflows/configure-workflows.qmd#add-new-workflows) - -[^11]: [Workflow step types](/guide/workflows/workflow-step-types.qmd#webhook) - -[^12]: [Working with the inventory](/guide/inventory/working-with-the-inventory.qmd#search-filter-and-sort-records) - -[^13]: [Working with the inventory](/guide/inventory/working-with-the-inventory.qmd#search-filter-and-sort-records) - -[^14]: [Working with the inventory](/guide/inventory/working-with-the-inventory.qmd#search-filter-and-sort-records) \ No newline at end of file diff --git a/site/guide/integrations/integrations-examples/configure-databricks.png b/site/guide/integrations/integrations-examples/configure-databricks.png new file mode 100644 index 000000000..d524781af Binary files /dev/null and b/site/guide/integrations/integrations-examples/configure-databricks.png differ diff --git a/site/guide/integrations/integrations-examples/create-jira-ticket.qmd b/site/guide/integrations/integrations-examples/create-jira-ticket.qmd new file mode 100644 index 000000000..975f31de7 --- /dev/null +++ b/site/guide/integrations/integrations-examples/create-jira-ticket.qmd @@ -0,0 +1,85 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Create a Jira ticket" +date: last-modified +--- + +Create a Jira ticket when model validation requires attention using an HTTP request workflow step. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure workflows.[^1] +- [x] You understand how to configure workflows and add steps to workflows.[^2] +- [x] A webhook secret is configured for your Jira Personal Access Token.[^3] +- [x] You have admin access to Jira. + +::: + +## Configure the workflow step + +::: {.column-margin} +![Create a Jira issue](integrations-examples-http-request-open-jira-ticket.png){width=80% fig-alt="Screenshot of the HTTP request step configured to create a Jira ticket, showing the required fields described in step 4." .screenshot} +::: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa shield >}} Governance, select **Workflows**. + +3. Select the **Model Workflows** tab. + +4. Click on a workflow to modify or click **{{< fa plus >}} Add Model Workflow**[^4] to create a new workflow. + +5. From the **Workflow Steps** modal, drag and drop an **HTTP Request** step[^5] onto the canvas, then connect it to your workflow. + +6. Double-click the step to open the **Configure HTTP Request** modal. + +7. Configure the required fields, replacing the placeholder values with your own: + + - **[url]{.smallcaps}** — `https://yourcompany.atlassian.net/rest/api/3/issue` + - **[method]{.smallcaps}** — POST + - **[headers]{.smallcaps}** — Add: + - `Content-Type`: `application/json` + - `Authorization`: `Bearer {{Jira Personal Access Token}}` + + ::: {.callout-tip title="Use webhook secrets for credentials"} + Instead of entering credentials in plaintext, use a webhook secret: `Bearer {{secret:jira_pat}}`. See [Manage secrets](../manage-secrets.qmd#webhook-secrets). + ::: + + - **[body type]{.smallcaps}** — JSON + - **[body]{.smallcaps}** — Use the following JSON payload: + + ```json + { + "fields": { + "project": { + "key": "MODEL" + }, + "summary": "Model validation failed: {{Model Name}}", + "description": "The model [{{Model Name}}|{{Model URL}}] failed validation. Review artifacts in ValidMind.", + "issuetype": { + "name": "Bug" + } + } + } + ``` + +8. Click **Update Step** to save your configuration. + +The HTTP request to create the Jira ticket is sent when the workflow executes the step. + + + +[^1]: [Manage permissions](../../configuration/manage-permissions.qmd) + +[^2]: [Introduction to workflows](../../workflows/introduction-to-workflows.qmd) + +[^3]: [Manage secrets](../manage-secrets.qmd) + +[^4]: [Add new workflows](../../workflows/configure-workflows.qmd#add-new-workflows) + +[^5]: [Workflow step types](../../workflows/workflow-step-types.qmd#http-request) diff --git a/site/guide/integrations/integrations-examples/create-servicenow-incident.qmd b/site/guide/integrations/integrations-examples/create-servicenow-incident.qmd new file mode 100644 index 000000000..7ecde2ead --- /dev/null +++ b/site/guide/integrations/integrations-examples/create-servicenow-incident.qmd @@ -0,0 +1,77 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Create a ServiceNow incident" +date: last-modified +--- + +Create a ServiceNow incident when a data drift issue is detected during ongoing monitoring using an HTTP request workflow step. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure workflows.[^1] +- [x] You understand how to configure workflows and add steps to workflows.[^2] +- [x] A webhook secret is configured for your ServiceNow credentials.[^3] +- [x] You have admin access to ServiceNow. + +::: + +## Configure the workflow step + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa shield >}} Governance, select **Workflows**. + +3. Select the **Model Workflows** tab. + +4. Click on a workflow to modify or click **{{< fa plus >}} Add Model Workflow**[^4] to create a new workflow. + +5. From the **Workflow Steps** modal, drag and drop an **HTTP Request** step[^5] onto the canvas, then connect it to your workflow. + +6. Double-click the step to open the **Configure HTTP Request** modal. + +7. Configure the required fields, replacing the placeholder values with your own: + + - **[url]{.smallcaps}** — `https://yourinstance.service-now.com/api/now/table/incident` + - **[method]{.smallcaps}** — POST + - **[headers]{.smallcaps}** — Add: + - `Content-Type`: `application/json` + - `Authorization`: `Basic {{ServiceNow Credentials}}` + + ::: {.callout-tip title="Use webhook secrets for credentials"} + Instead of entering credentials in plaintext, use a webhook secret: `Basic {{secret:servicenow_creds}}`. See [Manage secrets](../manage-secrets.qmd#webhook-secrets). + ::: + + - **[body type]{.smallcaps}** — JSON + - **[body]{.smallcaps}** — Use the following JSON payload: + + ```json + { + "short_description": "Data drift issue detected: {{Model Name}}", + "description": "A potential issue has been identified for model {{Model Name}} (link: [{{Model URL}}]({{Model URL}})). Please review the ongoing monitoring documentation in ValidMind.", + "urgency": "2", + "category": "Model Risk" + } + ``` + +::: {.column-margin} +![Create a ServiceNow incident](integrations-examples-http-request-open-servicenow-incident.png){width=80% fig-alt="Screenshot of the HTTP request step configured to create a ServiceNow incident, showing the required fields described in step 4." .screenshot} +::: + +The HTTP request to create the ServiceNow incident is sent when the workflow executes the step. + + + +[^1]: [Manage permissions](../../configuration/manage-permissions.qmd) + +[^2]: [Introduction to workflows](../../workflows/introduction-to-workflows.qmd) + +[^3]: [Manage secrets](../manage-secrets.qmd) + +[^4]: [Add new workflows](../../workflows/configure-workflows.qmd#add-new-workflows) + +[^5]: [Workflow step types](../../workflows/workflow-step-types.qmd#http-request) diff --git a/site/guide/integrations/integrations-examples-aws-sagemaker-linked-model.png b/site/guide/integrations/integrations-examples/integrations-examples-aws-sagemaker-linked-model.png similarity index 100% rename from site/guide/integrations/integrations-examples-aws-sagemaker-linked-model.png rename to site/guide/integrations/integrations-examples/integrations-examples-aws-sagemaker-linked-model.png diff --git a/site/guide/integrations/integrations-examples-aws-sagemaker.png b/site/guide/integrations/integrations-examples/integrations-examples-aws-sagemaker.png similarity index 100% rename from site/guide/integrations/integrations-examples-aws-sagemaker.png rename to site/guide/integrations/integrations-examples/integrations-examples-aws-sagemaker.png diff --git a/site/guide/integrations/integrations-examples-gitlab.png b/site/guide/integrations/integrations-examples/integrations-examples-gitlab.png similarity index 100% rename from site/guide/integrations/integrations-examples-gitlab.png rename to site/guide/integrations/integrations-examples/integrations-examples-gitlab.png diff --git a/site/guide/integrations/integrations-examples-http-request-open-jira-ticket.png b/site/guide/integrations/integrations-examples/integrations-examples-http-request-open-jira-ticket.png similarity index 100% rename from site/guide/integrations/integrations-examples-http-request-open-jira-ticket.png rename to site/guide/integrations/integrations-examples/integrations-examples-http-request-open-jira-ticket.png diff --git a/site/guide/integrations/integrations-examples-http-request-open-servicenow-incident.png b/site/guide/integrations/integrations-examples/integrations-examples-http-request-open-servicenow-incident.png similarity index 100% rename from site/guide/integrations/integrations-examples-http-request-open-servicenow-incident.png rename to site/guide/integrations/integrations-examples/integrations-examples-http-request-open-servicenow-incident.png diff --git a/site/guide/integrations/integrations-examples-webhook-run_step.png b/site/guide/integrations/integrations-examples/integrations-examples-webhook-run_step.png similarity index 100% rename from site/guide/integrations/integrations-examples-webhook-run_step.png rename to site/guide/integrations/integrations-examples/integrations-examples-webhook-run_step.png diff --git a/site/guide/integrations/integrations-examples/synchronize-aws-bedrock.qmd b/site/guide/integrations/integrations-examples/synchronize-aws-bedrock.qmd new file mode 100644 index 000000000..ef136a1d6 --- /dev/null +++ b/site/guide/integrations/integrations-examples/synchronize-aws-bedrock.qmd @@ -0,0 +1,99 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Synchronize models with AWS Bedrock" +date: last-modified +--- + +Link {{< var vm.product >}} models to foundation models and generative AI agents in Amazon Bedrock, supporting governance across your AI/ML ecosystem. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure connections.[^1] +- [x] You have AWS IAM credentials with permissions to access Bedrock. + +::: + +AWS Bedrock exposes two primary integration surfaces: + +- **Foundation model layer** — Access to AWS-hosted and custom foundation models through the Bedrock model catalog (Discover and Tune views). + +- **Application layer** — Bedrock primitives such as agents, flows, and knowledge bases that represent built generative AI applications and workflows. + +## Configure the connection + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa puzzle-piece >}} Integrations, select **Connections**. + +3. Click **{{< fa plus >}} Add Connection**. + +4. In the modal that opens, select **AWS Bedrock**. + +5. Complete: + + - **[integration name]{.smallcaps}** — How other admins can identify the connection. + - **[description]{.smallcaps}** (optional) — The intended usage or additional details. + - **[aws region]{.smallcaps}** — The primary region where your Bedrock resources are deployed, for example `us-east-1`. + - **[aws access key id]{.smallcaps}** — The secret generated by AWS IAM with permissions to access Bedrock. + - **[aws secret access key]{.smallcaps}** — The secret generated by AWS IAM with permissions to access Bedrock. + - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. + +6. Click **Save Integration**. + +7. Test the connection: + + a. Hover over the AWS Bedrock connection you just created. + b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. + + If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. + +## Link models from Bedrock + +Once the connection is configured, you can link {{< var vm.product >}} models to your Bedrock resources: + +::: {.callout title="Model dependencies"} +Bedrock agents, flows, and runtimes typically call foundation models (LLMs) under the hood. When you link these application-layer resources to {{< var vm.product >}}, consider also registering their underlying foundation models and creating dependency relationships between them. + +This builds a complete dependency graph showing how your AI applications relate to underlying models. Benefits include: + +- **Impact analysis** — See which applications are affected if a foundation model is deprecated or has compliance issues. +- **Full audit trails** — Documentation and risk assessments capture the entire model stack, not just the top-level application. +- **Governance visibility** — Track model versions and changes across your AI ecosystem. +::: + +1. In the left sidebar, click **{{< fa cubes >}} Inventory**. + +2. Select a model by clicking on it or find your model by applying a filter or searching for it.[^2] + +3. Scroll down until you locate the **Amazon Bedrock** connection box in the right sidebar. + +4. Hover over the Amazon Bedrock box. + +5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. + +6. In the modal that opens, use the tabs to filter by resource type: + + - **All** — View all available Bedrock resources. + - **Foundation Models** — AWS-hosted and custom foundation models from the Bedrock catalog. + - **Agents** — Generative AI agents you've built in Bedrock. + - **Flows** — Prompt flows and orchestration workflows. + - **AgentCore Runtimes** — Agent runtime environments. + +7. Click **[select model]{.smallcaps}** to choose the specific Bedrock resource to link. + +8. Optional: Click **Test Connection** to ensure the connection is working as expected. + + If the test is successful, the message **{{< fa check-circle >}} Connection Test Successful** displays. + +9. Click **Link Model**. + + + +[^1]: [Manage permissions](../../configuration/manage-permissions.qmd) + +[^2]: [Working with the inventory](../../inventory/working-with-the-inventory.qmd#search-filter-and-sort-records) diff --git a/site/guide/integrations/integrations-examples/synchronize-aws-sagemaker.qmd b/site/guide/integrations/integrations-examples/synchronize-aws-sagemaker.qmd new file mode 100644 index 000000000..cc87f119f --- /dev/null +++ b/site/guide/integrations/integrations-examples/synchronize-aws-sagemaker.qmd @@ -0,0 +1,82 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Synchronize models with AWS SageMaker" +date: last-modified +--- + +Synchronize models registered in the {{< var vm.product >}} model inventory with AWS SageMaker models. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure connections.[^1] +- [x] You have AWS IAM credentials with permissions to read the SageMaker model registry. + +::: + +## Configure the connection + +::: {.column-margin} +![Connect with AWS SageMaker](integrations-examples-aws-sagemaker.png){width=80% fig-alt="Screenshot of the AWS Sagemaker connection configured to synchronize models, showing the required fields described in step 5." .screenshot} +::: + +::: {.column-margin} +![A linked AWS SageMaker model](integrations-examples-aws-sagemaker-linked-model.png){width=60% fig-alt="Screenshot of the model linked to AWS SageMaker, showing the required fields described in step 4." .screenshot} +::: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa puzzle-piece >}} Integrations, select **Connections**. + +3. Click **{{< fa plus >}} Add Connection**. + +4. In the modal that opens, select **AWS Sagemaker**. + +5. Complete: + + - **[integration name]{.smallcaps}** — How other admins can identify the connection. + - **[description]{.smallcaps}** (optional) — The intended usage or additional details. + - **[aws region]{.smallcaps}** - The primary region where your SageMaker model registry lives, for example `us-west-2`. + - **[aws access key id]{.smallcaps}** — The secret generated by AWS IAM with permissions to read the model registry. + - **[aws secret access key]{.smallcaps}** — The secret generated by AWS IAM with permissions to read the model registry. + - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. + +6. Click **Save Integration**. + +7. Test the connection: + + a. Hover over the AWS SageMaker connection you just created. + b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. + + If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. + + +## Link the models + +1. In the left sidebar, click **{{< fa cubes >}} Inventory**. + +2. Select a model by clicking on it or find your model by applying a filter or searching for it.[^2] + +3. Scroll down until you locate the **Amazon Sagemaker** connection box in the right sidebar. + +4. Hover over the Amazon SageMaker box. + +5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. + +6. In the modal that opens, click the [select model]{.smallcaps} dropdown to pick the AWS SageMaker model to link. + +7. Optional: Click **Test Connection** to ensure the connection is working as expected. + + If the test is successful, the message **{{< fa check-circle >}} Connection Test Successful** displays. + +8. Click **Link Model**. + + + +[^1]: [Manage permissions](../../configuration/manage-permissions.qmd) + +[^2]: [Working with the inventory](../../inventory/working-with-the-inventory.qmd#search-filter-and-sort-records) diff --git a/site/guide/integrations/integrations-examples/synchronize-gitlab.qmd b/site/guide/integrations/integrations-examples/synchronize-gitlab.qmd new file mode 100644 index 000000000..c8a9095ee --- /dev/null +++ b/site/guide/integrations/integrations-examples/synchronize-gitlab.qmd @@ -0,0 +1,80 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Synchronize models with GitLab" +date: last-modified +--- + +Synchronize GitLab model registry with ValidMind model inventory for comprehensive model tracking. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure connections.[^1] +- [x] A secret is configured for your GitLab Personal Access Token with `api` or `read_api` scope.[^2] +- [x] You have access to the GitLab project containing ML models. + +::: + +## Configure the connection + +::: {.column-margin} +![Configure GitLab connection](integrations-examples-gitlab.png){width=80% fig-alt="Screenshot of the Configure GitLab dialog showing fields for integration name, description, project ID, GitLab instance URL, personal access token, and initial status." .screenshot} +::: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa puzzle-piece >}} Integrations, select **Connections**. + +3. Click **{{< fa plus >}} Add Connection**. + +4. In the modal that opens, select **GitLab**. + +5. Complete: + + - **[integration name]{.smallcaps}** — How other admins can identify the connection. + - **[description]{.smallcaps}** (optional) — The intended usage or additional details. + - **[project id]{.smallcaps}** — The GitLab project ID or path containing ML models (required). + - **[gitlab instance url]{.smallcaps}** (optional) — Leave empty to use GitLab.com, or enter your self-hosted GitLab URL. + - **[personal access token]{.smallcaps}** — Select a secret containing your GitLab Personal Access Token with `api` or `read_api` scope. + - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. + +6. Click **Save Integration**. + +7. Test the connection: + + a. Hover over the GitLab connection you just created. + b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. + + If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. + +## Link the models + +1. In the left sidebar, click **{{< fa cubes >}} Inventory**. + +2. Select a model by clicking on it or find your model by applying a filter or searching for it.[^3] + +3. Scroll down until you locate the **GitLab** connection box in the right sidebar. + +4. Hover over the GitLab box. + +5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. + +6. In the modal that opens, click the [select model]{.smallcaps} dropdown to pick the GitLab model to link. + +7. Optional: Click **Test Connection** to ensure the connection is working as expected. + + If the test is successful, the message **{{< fa check-circle >}} Connection Test Successful** displays. + +8. Click **Link Model**. + + + +[^1]: [Manage permissions](../../configuration/manage-permissions.qmd) + +[^2]: [Manage secrets](../manage-secrets.qmd) + +[^3]: [Working with the inventory](../../inventory/working-with-the-inventory.qmd#search-filter-and-sort-records) diff --git a/site/guide/integrations/integrations-examples/synchronize-with-databricks.qmd b/site/guide/integrations/integrations-examples/synchronize-with-databricks.qmd new file mode 100644 index 000000000..ac765fc9c --- /dev/null +++ b/site/guide/integrations/integrations-examples/synchronize-with-databricks.qmd @@ -0,0 +1,137 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Synchronize with Databricks" +date: last-modified +listing: + - id: whats-next + type: grid + grid-columns: 2 + max-description-length: 250 + sort: false + fields: [title, description] + contents: + - path: https://docs.validmind.ai/notebooks/databricks/validmind_databricks_quickstart.html + title: "Databricks quickstart" + description: "Install the {{< var validmind.developer >}}, load data from a Unity Catalog table via Spark, train a simple classification model, and run ValidMind tests to send results to the {{< var validmind.platform >}}." +--- + +Link {{< var vm.product >}} inventory records to models, datasets, and agents in Databricks Unity Catalog for governance across your ML ecosystem and bidirectional metadata synchronization. You can also run validation notebooks directly against Databricks-hosted data. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure connections.[^1] +- [x] A secret is configured for your Databricks Personal Access Token.[^2] +- [x] You have admin access to your Databricks workspace. + +::: + + +## How does the integration with Databricks work? + +Databricks Unity Catalog provides a unified governance solution for all data and AI assets across your Databricks workspaces. The integration exposes three Unity Catalog resource types: + +- **Models** — Registered ML models in Unity Catalog's model registry. +- **Datasets** — Tables and datasets managed by Unity Catalog. +- **Agents** — AI agents and applications built on Databricks. + +After linking your inventory record to Databricks, you can run validation tests directly against data hosted in Unity Catalog. + +```{mermaid} +%%| fig-cap: "Data flow between Databricks and ValidMind" +flowchart LR + subgraph databricks [Databricks] + UC[Unity Catalog] + Data[Tables/Datasets] + end + + subgraph notebook [Validation Notebook] + SDK[ValidMind SDK] + end + + subgraph validmind [ValidMind Platform] + Report[Validation Report] + Inventory[Inventory Record] + end + + UC --> Data + Data --> SDK + SDK --> Report + Report --> Inventory + Inventory -.->|linked| UC +``` + + +## Configure the connection + +::: {.column-margin .pt6} +![Configure the Databricks connection](configure-databricks.png){width=80% fig-alt="Screenshot of the Configure Databricks connection dialog showing the required fields described in step 5." .screenshot} +::: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa puzzle-piece >}} Integrations, select **Connections**. + +3. Click **{{< fa plus >}} Add Connection**. + +4. In the modal that opens, select **Databricks**. + +5. Complete: + + - **[integration name]{.smallcaps}** — How other admins can identify the connection. + - **[description]{.smallcaps}** (optional) — The intended usage or additional details. + - **[workspace url]{.smallcaps}** — Your Databricks workspace URL, found in the browser address bar, such as `https://adb-1234567890.azuredatabricks.net`. + - **[sql warehouse id]{.smallcaps}** — The ID of your SQL Warehouse, found in SQL Warehouses settings. + - **[personal access token]{.smallcaps}** — Select a secret containing your Databricks Personal Access Token. + - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. + +6. Click **Save Integration**. + +7. Test the connection: + + a. Hover over the Databricks connection you just created. + b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. + + If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. + +## Link records to Databricks + +Once the connection is configured, you can link {{< var vm.product >}} inventory records to your Databricks Unity Catalog resources: + +1. In the left sidebar, click **{{< fa cubes >}} Inventory**. + +2. Select a record by clicking on it or find your record by applying a filter or searching for it.[^3] + +3. Scroll down until you locate the **Databricks** connection box in the right sidebar. + +4. Hover over the Databricks box. + +5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. + +6. In the modal that opens: + + - **[select model]{.smallcaps}** — Choose the Databricks model to link from the dropdown. + - **[sync frequency]{.smallcaps}** — Set how often ValidMind automatically syncs data from the external system. + +7. Click **Link Model** to complete the link. + +8. Click **Link Model**. + +After linking, metadata from the Unity Catalog resource syncs to {{< var vm.product >}}. You can use linked fields in custom calculated fields to surface Databricks metadata directly in your inventory views. + +## What's next + +:::{#whats-next} +::: + + + +[^1]: [Manage permissions](../../configuration/manage-permissions.qmd) + +[^2]: [Manage secrets](../manage-secrets.qmd) + +[^3]: [Working with the inventory](../../inventory/working-with-the-inventory.qmd#search-filter-and-sort-records) diff --git a/site/guide/integrations/integrations-examples/use-webhooks-with-workflows.qmd b/site/guide/integrations/integrations-examples/use-webhooks-with-workflows.qmd new file mode 100644 index 000000000..22b7dd9a0 --- /dev/null +++ b/site/guide/integrations/integrations-examples/use-webhooks-with-workflows.qmd @@ -0,0 +1,128 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Use webhooks with workflows" +date: last-modified +--- + +Use webhooks to let external systems start {{< var vm.product >}} workflows or trigger paused workflows to continue. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to configure workflows.[^1] +- [x] You understand how to configure workflows and add steps to workflows.[^2] +- [x] You have admin access to the external system that will send webhook requests. + +::: + +## Start a workflow via webhook + +Start a {{< var vm.product >}} workflow from an external system by sending a POST request to trigger a new workflow. + +::: {.panel-tabset} + +### a. Configure workflow in {{< var vm.product >}} + +1. Add a new workflow, selecting the **Via Webhook** workflow start option.[^3] + +2. From the **Workflow Steps** modal, drag and drop a **Webhook** step[^4] onto the canvas, then connect it to your workflow. + +3. Double-click the step to open the **Webhook Step Trigger** modal. + +4. Copy or select the webhook details: + + - **URL** — Click **{{< fa regular copy >}} Copy** for the unique POST webhook URL to use when configuring your external system. + - **[select target model for payload]{.smallcaps}** — Select the model that is associated with the webhook payload from the dropdown. + - **Payload** — Click **{{< fa regular copy >}} Copy** for the JSON payload that external systems must send in their POST request, where the value for `target_cuid` is shown after you select a target: + + ```json + { + "action": "run_workflow", + "target": "", + "entity_name": "InventoryModel" + } + ``` + + - For the required authentication headers, click **{{< fa regular copy >}} Copy** for each of the following key-value pairs and paste them into your external system: + - `x-api-key`: `{{API Key}}` + - `x-api-secret`: `{{API Secret}}` + - **[wait for webhook trigger when reached]{.smallcaps}** — When enabled, the workflow pauses execution when it reaches this step and waits for the external system to send the POST request. + +5. Click **Save**. + +### b. Start workflow from external system + +Send a POST request to the webhook URL with a JSON payload that includes the `run_workflow` action for the target model CUID: + +```bash +curl -X POST https://api.prod.vm.validmind.ai/vm/api/v1/webhooks/xxxxxxxxxxxxxxxxxxxxxxxxx/xxxx -H 'Content-Type`: `application/json' -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -H 'x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' --data '{ + "action": "run_workflow", + "target": "", + "entity_name": "InventoryModel" +}' +``` +::: + +## Trigger a paused workflow to continue + +Trigger a waiting {{< var vm.product >}} workflow step to continue from an external system. Use this pattern when a workflow pauses at a webhook step and waits for external input before proceeding. + +::: {.panel-tabset} + +### a. Configure workflow in {{< var vm.product >}} + +1. Open the workflow you want to configure, or add a new workflow.[^3] + +2. From the **Workflow Steps** modal, drag and drop a **Webhook** step[^4] onto the canvas, then connect the step to your workflow. + +3. Double-click the step to open the **Webhook Step Trigger** modal. + +4. Copy or select the webhook details: + + - **URL** — Click **{{< fa regular copy >}} Copy** for the unique POST webhook URL to use when configuring your external system. + - **[select target model for payload]{.smallcaps}** — Select the model that is associated with the webhook payload from the dropdown. + - **Payload** — Click **{{< fa regular copy >}} Copy** for the JSON payload that external systems must send in their POST request, where the value for `target_cuid` is shown after you select a target: + + ```json + { + "action": "run_step", + "target": "", + "entity_name": "InventoryModel" + } + ``` + + - For the required authentication headers, click **{{< fa regular copy >}} Copy** for each of the following key-value pairs and paste them into your external system: + - `x-api-key`: `{{API Key}}` + - `x-api-secret`: `{{API Secret}}` + +5. Click **Update Step** to save your configuration. + +When the workflow reaches this step, it pauses and waits for the external system. + +### b. Trigger workflow to continue from external system + +Send a POST request to the webhook URL with a JSON payload containing the `run_step` action for the model CUID: + +```bash +curl -X POST https://api.prod.vm.validmind.ai/vm/api/v1/webhooks/xxxxxxxxxxxxxxxxxxxxxxxxx/xxxx -H 'Content-Type`: `application/json' -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -H 'x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' --data '{ + "action": "run_step", + "target": "", + "entity_name": "InventoryModel" +}' +``` + +::: + + + +[^1]: [Manage permissions](../../configuration/manage-permissions.qmd) + +[^2]: [Introduction to workflows](../../workflows/introduction-to-workflows.qmd) + +[^3]: [Add new workflows](../../workflows/configure-workflows.qmd#add-new-workflows) + +[^4]: [Workflow step types](../../workflows/workflow-step-types.qmd#webhook) diff --git a/site/guide/integrations/managing-integrations.qmd b/site/guide/integrations/managing-integrations.qmd index c4fc74182..2f15044cb 100644 --- a/site/guide/integrations/managing-integrations.qmd +++ b/site/guide/integrations/managing-integrations.qmd @@ -78,24 +78,48 @@ Link to models in external registries and development platforms and keep invento :::: {.flex .flex-wrap .justify-around} -::: {.w-25-ns} +::: {.w-20-ns} - AWS SageMaker ::: -::: {.w-25-ns} +::: {.w-20-ns} - AWS Bedrock ::: -::: {.w-25-ns} +::: {.w-20-ns} +- Databricks +::: + +::: {.w-20-ns} - MLflow ::: -::: {.w-25-ns} +::: {.w-20-ns} +  +::: + +:::: + +:::: {.flex .flex-wrap .justify-around} + +::: {.w-20-ns} - GitLab ::: ::: {.w-20-ns} -- Custom integrations +- Custom +::: + +::: {.w-20-ns} +  +::: + +::: {.w-20-ns} +  +::: + +::: {.w-20-ns} +  ::: ::::