Docs: add Concepts page for Artifacts API

changes/issue5130.yml

@@ -0,0 +1,5 @@
+enhancement:
+  - "Expose container ports when using Prefect's DockerRun - [#5130](https://github.com/PrefectHQ/prefect/issues/5130)"
+
+contributor:
+  - "[Shahil Mawjee](https://github.com/s-mawjee)"

docs/.vuepress/config.js

@@ -199,7 +199,8 @@ module.exports = {
             'concepts/secrets',
             'concepts/automations',
             'concepts/cloud_hooks',
-            'concepts/services'
+            'concepts/services',
+            'concepts/artifacts'
           ]
         },
         {
@@ -248,6 +249,7 @@ module.exports = {
             'ui/flow',
             'ui/flow-run',
             'ui/task-run',
+            'ui/automations',
             'ui/interactive-api',
             'ui/team-settings'
           ]

docs/orchestration/README.md

@@ -15,7 +15,7 @@ Prefect Cloud and the Prefect Server are two ready-to-use state database and UI
 
 Prefect Core's server is an open source, lightweight version of our highly-available, production-ready product Prefect Cloud.
 
-Most users get the greatest benefit from signing up for the [free Prefect Cloud Starter tier](https://cloud.prefect.io/), which supports up to 3 users and 10,000 free runs every month. 
+Most users get the greatest benefit from signing up for the [free Prefect Cloud Starter tier](https://cloud.prefect.io/). 
 
 If your team needs support for additional users, automations, multi-tenant permissions, SSO, and other features, [scale up to a bigger Prefect Cloud license](https://www.prefect.io/pricing/). 
 

docs/orchestration/concepts/artifacts.md

@@ -0,0 +1,152 @@
+# Artifacts <Badge text="Beta"/>
+
+The [Artifacts API](/api/latest/backend/artifacts.html) enables you to publish data from task runs that is rendered natively in the Prefect UI, both Prefect Cloud and Prefect Server. 
+
+Using the Artifacts API, you can easily publish information directly to the Prefect UI. These published artifacts are linked to specific task runs and flow runs, and artifacts can render more sophisticated information than you'd typically log, such as reports, tables, charts, images, and links to external data.
+
+Currently, the Artifacts API enables you to render the following artifact types:
+
+- Links
+- Markdown
+
+Link artifacts render a clickable hyperlink as an artifact.
+
+Markdown artifacts render strings that can include [Github-flavored Markdown](https://github.github.com/gfm/) markup for formatting. 
+
+::: tip Artifacts render individually
+Note that each artifact you create in a task renders as an individual artifact in the Prefect UI. In other words, each call to `create_link_artifact()` or `create_markdown_artifact()` creates its own, separate artifact.
+
+Within a task, you may use these commands as many times as necessary, but they do not operate in the same manner as a `print()` command where you might string together multiple calls to add additional items to a report. 
+
+As a best practice, such as when using `create_markdown_artifact()` to create artifacts like reports or summaries, compile your message string separately, then pass to `create_markdown_artifact()` or `update_markdown_artifact()` to create the full artifact.
+:::
+
+For more background on the design goals for the Artifacts API, see the [Introducing: The Artifacts API](https://www.prefect.io/blog/introducing-the-artifacts-api) blog post and the [Great Expectations task](/api/latest/tasks/great_expectations.html).
+
+## UI
+
+In the Prefect UI, to view artifacts created by a flow run, navigate to a specific flow run, then click the **Artifacts** tab.
+
+![Screenshot showing the Artifacts tab for a flow run](/orchestration/concepts/artifacts_flowrun.png)
+
+You can navigate between the artifacts created for a flow run by clicking the dots or arrows above the artifacts.
+
+Each artifact is identified by task that created it.
+
+To view the artifacts created by a task run, navigate to the specific task run, then click the **Artifacts** tab.
+
+![Screenshot showing the Artifacts tab for a task run](/orchestration/concepts/artifacts_taskrun.png)
+
+You can navigate between the artifacts created for a task run by clicking the dots or arrows above the artifacts.
+
+## Creating Link Artifacts
+
+To create link artifacts, just import `create_link_artifact` from `prefect.backend.artifacts`, then add a call to `create_link_artifact()` to any task orchestrated through a Prefect API. 
+
+::: tip Import path
+If you are using a version prior to Prefect 0.15.8, import `create_link` from `prefect.artifacts`.
+:::
+
+Pass `create_link_artifact()` a string containing the absolute URL of the location to which you want to link. 
+
+```python
+from prefect import task, Flow
+from prefect.backend.artifacts import create_link_artifact
+
+@task
+def make_artifact():
+    create_link_artifact("https://www.prefect.io/")
+```
+
+After the task runs, navigate to the UI’s Artifacts tab to see the output.
+
+In addition to creating an artifact, `create_link_artifact()` returns the ID of the artifact it created. You can use the ID to:
+
+- Update the artifact using `update_link_artifact()`.
+- Delete the artifact using `delete_artifact()`.
+
+Note that `update_link_artifact()` updates an existing link artifact by replacing the entire current artifact string with the new data provided. See [Creating Markdown Artifacts](#creating-markdown-artifacts) and [Deleting Artifacts](#deleting-artifacts) for examples of these update and delete operations.
+
+## Creating Markdown Artifacts
+
+To create link artifacts, just import `create_markdown_artifact` from `prefect.backend.artifacts`, then add a call to `create_markdown_artifact()` to any task orchestrated through a Prefect API. 
+
+::: tip Import path
+If you are using a version prior to Prefect 0.15.8, import `create_markdown` from `prefect.artifacts`.
+:::
+
+Pass `create_markdown_artifact()` a string that will be rendered as an artifact. The string can contain any [Github-flavored Markdown](https://github.github.com/gfm/) markup including image references, links, and tables. 
+
+Note that any images referenced in your markdown must be linked by the absolute URL of a publicly available image. Linking to local files or by relative URL is not supported.
+
+```python
+from prefect import task, Flow
+from prefect.backend.artifacts import create_markdown_artifact
+
+@task
+def make_artifact():
+    create_markdown_artifact("# Heading\n\nText with [link]("https://www.prefect.io/").")
+```
+
+After the task runs, navigate to the UI’s Artifacts tab to see the output.
+
+`create_markdown_artifact()` accepts any valid Python string and variable interpolation including, for example, f-strings.
+
+In addition to creating an artifact, `create_markdown_artifact()` returns the ID of the artifact it created. You can use the ID to:
+
+- Update the artifact using `update_markdown_artifact()`.
+- Delete the artifact using `delete_artifact()`.
+
+Note that `update_markdown_artifact()` updates an existing markdown artifact by replacing the entire current markdown artifact with the new data provided. Here's an example of appending new report data to an existing artifact.
+
+```python
+from prefect import task, Flow
+from prefect.backend.artifacts import create_markdown_artifact, update_markdown_artifact
+
+@task(nout=2)
+def make_report():
+    report = "# My Report\n\nHello!"
+    artifact_id = create_markdown_artifact(report)
+    # Return both the ID of the new artifact and the original content
+    return artifact_id, report
+
+@task
+def add_to_report(artifact_id, current_report):
+    # Append new sections to the existing report
+    current_report += "\n\n## Subsection\n\ngoodbye!"
+    # Update artifact by ID with replaced text
+    update_markdown_artifact(artifact_id, current_report)
+
+with Flow(name="appending-artifact") as flow:
+    artifact_id, report = make_report()
+    add_to_report(artifact_id, report)
+```
+
+::: tip Markdown strings and line endings
+Explicit line endings and blank lins are important to rendering markdown correctly. When formatting markdown for artifacts, make sure that you include explicit line endings (`\n` or equivalent) where appropriate.
+:::
+
+## Deleting Artifacts
+
+To delete existing link or markdown artifacts, import `delete_artifact` from `prefect.backend.artifacts`, then add a call to `delete_artifact()` to any task orchestrated through a Prefect API, passing the ID of the artifact to delete.
+
+```python
+from prefect import task, Flow
+from prefect.backend.artifacts import create_markdown_artifact, delete_artifact
+
+@task
+def make_artifact(artifact_msg):
+    artifact_id = create_markdown_artifact(artifact_msg)
+    return artifact_id
+
+@task
+def remove_artifact(artifact_id):
+    delete_artifact(artifact_id)
+
+with Flow(name="deleting-artifact") as flow:
+    msg = "Space is big. Really big."
+    artifact_id = make_artifact(msg)
+    remove_artifact(artifact_id)
+```
+
+Artifacts cannot be retrieved once deleted.

docs/orchestration/concepts/automations.md

@@ -1,48 +1,67 @@
-# Automations 
+# Automations <Badge text="Cloud"/>
 
-Automations allow you to configure actions (such as cancelling a flow run or sending a notification to certain endpoints) when an event occurs in the Prefect ecosystem.
+Automations allow you to configure actions &mdash; such as cancelling a flow run or sending a notification to certain endpoints &mdash; when an event occurs in the Prefect ecosystem.
 
-For example, you can send a Slack message to your team when a run from a production critical flow has failed, along with the reason for the failure so that you can respond immediately. Or you can cancel a run that has been running (or scheduled) for more than an hour to enforce SLAs.  
+Automations are a feature of [Prefect Cloud](https://cloud.prefect.io) and are included with all Prefect Cloud plans. Some automation features are available only in Standard plan and above.
 
-The automations system is composed of events and actions. When an _event_ is paired with an _action_, we call it an _automation_. 
+- [Overview](#overview)
+- [Events](#events)
+- [Actions](#actions)
+- [Messages](#messages)
+- [Automations Reference](#automations-reference)
+
+## Overview
+
+Prefect automations enable you to kick off actions in response to events related to flow runs or agents.
+
+For example, you could use automations to: 
+
+- Create a Slack message to your team when a run from a production critical flow has completed so they can use the results of the flow. 
+- Send an alert through email or the [PagerDuty integration](/orchestration/integrations/pagerduty.html) if a flow run returns a Failed status, along with the reason for the failure so that you can respond immediately. 
+- Cancel a run that has been running (or scheduled) for more than a defined period to enforce SLAs.  
+
+The automations system is composed of events and actions. When an _event_ is paired with an _action_, you create an _automation_. 
+
+When creating an automation, you can:
 
-When creating an automation, you:
 - Choose an event type
 - Place filters or conditions on the event data
 - Select an action to fire when the event occurs and the conditions are met
 
 The following documentation will cover the various types of events and actions you can configure.
 
-We recommend creating and managing your automations in the [UI Automations page](https://cloud.prefect.io/?automations). You can also manage automations via the GraphQL API, but it requires a deeper understanding of the system then this document will cover.
+We recommend creating and managing your automations in [Prefect Cloud Automations](https://cloud.prefect.io/?automations) (Prefect Cloud login required). See the [Automations UI](/orchestration/ui/automations.html) documentation for an overview of creating and managing automations in Prefect Cloud.
+
+You can also manage automations via the [GraphQL API](/orchestration/concepts/api.html#graphql), but it requires a deeper understanding of the system than this document provides.
 
 ## Events
 
 An event is something that occurs in the Prefect backend. 
 
 Currently you can configure automations for the following events:
-- Flow runs from a single, multiple, or all flows enter a given state or states
-- A flow run fails to start after being scheduled for a certain amount of time (**Standard plan and above**)
-- A flow run fails to finish after running for a certain amount of time  (**Standard plan and above**)
-- Some number of agents with the same [`agent_config_id`](orchestration/agents/overview.html#health-checks) become unhealthy  (**Standard plan and above**)
+
+- Flow runs from a single flow, multiple flows, or all flows enter a given state or states.
+- A flow run fails to start after being scheduled for a certain amount of time (**Standard plan and above**).
+- A flow run fails to finish after running for a certain amount of time (**Standard plan and above**).
+- Some number of agents with the same [`agent_config_id`](/orchestration/agents/overview.html#health-checks) become unhealthy (**Standard plan and above**)
 
 ::: tip Hooks
 When you create an automation in the UI, you are actually creating a `Hook` between an `Event` type and an `Action` instance. This name difference will be apparent if you are attempting to work with automations by calling the GraphQL API directly
 :::
 
 ## Actions
 
-An _action_ is a response to the event. For each automation you can configure an action to happen when certain event conditions are met. For example, if your flow run fails (the event) you can cancel the run (the action).  
+An _action_ is a response to the event. For each automation, you can configure an action to happen when certain event conditions are met. For example, if your flow run fails (the event), then you can cancel the run (the action).  
 
-You can configure actions which send notifications using the following services:
+You can configure actions that send notifications using the following services:
 
 - Slack
 - Twilio
 - PagerDuty
 - Microsoft Teams
 - Email
 
-
-If you are on a Standard or Enterprise plan you can also configure Prefect API actions. These allow you to do the following:
+If you are on a Standard or Enterprise plan, you can also configure Prefect API actions. These allow you to do the following:
 
 - Cancel a flow run
 - Pause a flow's schedule
@@ -54,14 +73,13 @@ All events have a message associated with them. These events are templated when
 
 `Run {flow_run_name} of flow {flow_name} entered state {state} with message {state_message}. See {flow_run_link} for more details.`
 
-
-Actions with a message will generally default to using the event's message but allow you to override the message with a templatable string. For example, you may want to modify the above message to be more specific to your use-case:
+Actions with a message generally default to using the event's message, but allow you to override the message with a templatable string. For example, you may want to modify the message to be more specific to your use case, such as:
 
 `Run for client {flow_run_name} failed: {state_message}. Please investigate at {flow_run_link}.`
 
-See [the reference](#events-reference) for more details on the attributes you can use to template messages.
+See the [Events reference](#events-reference) for more details on the attributes you can use to template messages.
 
-## Reference
+## Automations Reference
 
 ### Events reference
 
@@ -121,7 +139,7 @@ This event fires if a flow is late to start or late to finish. Specifically, you
 
 #### Agent SLA failure
 
-This event fires if a group of agents have not queried the backend after an amount of time. The "agent config" abstraction allows us to link multiple agents to a single key. The UI will create an agent config for you when you create an agent SLA automation.
+This event fires if a group of agents have not queried the backend after an amount of time. The "agent config" abstraction allows linking multiple agents to a single key. The UI creates an agent config for you when you create an agent SLA automation.
 
 If _no_ agents linked to the config are querying the API for flow runs, the SLA failure event will fire. If _any_ of the agents are healthy, the SLA will pass.
 
@@ -140,19 +158,19 @@ If _no_ agents linked to the config are querying the API for flow runs, the SLA
 
 #### WebhookAction
 
-Sends a payload to the given url when an event fires. 
+Sends a payload to the given URL when an event fires. 
 
 Expects a 200 OK response or the action will be marked as failed.
 
 **Configuration**
 
 - `url`: The URL to send the payload to
 - `payload`: Optional, a JSON payload to send to the URL. If not specified, all event data is dumped. Templatable.
-- `headers`: Optional, JSON headers to include in the request. If not specified, defaults to include the event id: `{"X-PREFECT-EVENT-ID": "{id}"}`.  Templatable.
+- `headers`: Optional, JSON headers to include in the request. If not specified, defaults to include the event ID: `{"X-PREFECT-EVENT-ID": "{id}"}`.  Templatable.
 
 **Templating**
 
-Both the payload and the header JSON can be templated using event attributes. For example, we can include our tenant id in the headers instead of the event id.
+Both the payload and the header JSON can be templated using event attributes. For example, you can include a tenant ID in the headers instead of the event ID.
 
 ```json
 headers = {"X-PREFECT-TENANT-ID": "{tenant_id}"}
@@ -166,16 +184,16 @@ Send a notification using a Slack webhook.
 
 **Configuration**
 
-- `webhook_url_secret`: The name of the Prefect Secret with the Slack webhook URL
-- `message`: Optional, a custom message to send
+- `webhook_url_secret`: The name of the Prefect Secret with the Slack webhook URL.
+- `message`: Optional, a custom message to send.
 
 #### TeamsWebhookNotificationAction
 
 Send a notification using a Microsoft Teams webhook.
 
 **Configuration**
 
-- `webhook_url_secret`: The name of the Prefect Secret with the Teans webhook URL
+- `webhook_url_secret`: The name of the Prefect Secret with the Microsoft Teams webhook URL.
 - `message`: Optional, a custom message to send. Templatable.
 - `title`: Optional, a custom title to use for the message. Templatable.
 
@@ -185,7 +203,7 @@ Send an email notification.
 
 **Configuration**
 
-- `to_emails`: A list of email addresses to send an email to
+- `to_emails`: A list of email addresses to send an email to.
 - `subject`: Optional, a custom email subject. Templatable.
 - `body`: Optional, a custom email body. Templatable.
 
@@ -195,10 +213,10 @@ Send a text message notification with Twilio.
 
 **Configuration**
 
-- `account_sid`: The Twilio account SID
-- `auth_token_secret` The name of the Prefect Secret with the Twilio auth token
-- `messaging_service_sid`: The Twilio messaging service SID
-- `phone_numbers`: A list of phone numbers to message
+- `account_sid`: The Twilio account SID.
+- `auth_token_secret` The name of the Prefect Secret with the Twilio auth token.
+- `messaging_service_sid`: The Twilio messaging service SID.
+- `phone_numbers`: A list of phone numbers to message.
 - `message`: Optional, a custom text message. Templatable.
 
 #### PagerDutyNotificationAction
@@ -207,9 +225,9 @@ Send a notification using PagerDuty.
 
 **Configuration**
 
-- `api_token_secret`: The name of the Prefect Secret with the PagerDuty API token
-- `routing_key`: The PagerDuty routing key
-- `severity`: The PagerDuty severity to send a message on. One of: info, warning, error, critical
+- `api_token_secret`: The name of the Prefect Secret with the PagerDuty API token.
+- `routing_key`: The PagerDuty routing key.
+- `severity`: The PagerDuty severity to send a message on: `info`, `warning`, `error`, or `critical`.
 - `message`: Optional, a custom message. Templatable.
 
 #### CancelFlowRunAction
@@ -226,4 +244,4 @@ Pause scheduling additional flow runs for a flow group.
 
 **Configuration**
 
-- `flow_group_id`: Optional, the UUID of a flow group to pause the schedule of. If not provided, this action _must_ be hooked to an event that provides it.
+- `flow_group_id`: Optional, the UUID of a flow group for which you want to pause the schedule. If not provided, this action _must_ be hooked to an event that provides it.