# Use Actions in Workshop

Actions in Foundry allow users to edit, create, delete, and link object data based on defined rule sets (known as action types). For example, an Action might allow a user to do one or more of the following:

* Create a new `Flight` object and fill in its `Flight Number`, `Time of Departure`, `Origin`, and `Destination` properties.
* Modify an existing `Flight` object to change the `Destination` property.
* Link a specific `Flight` object to a specific `Passenger` object.
* Delete a `Flight` object that was created by mistake.

By creating a user-friendly wrapper for complex object data edits, Actions enables application creators to use meaningful and secure building blocks for user writeback to object data. These building blocks can then be:

* Used in multiple applications (such as Workshop or Object Views) to support business process workflows.
  * A Form component is automatically generated based on the Action definition, so writeback to object data and the user interface associated with it are not defined separately. The core interactions of Workshop and Actions are detailed below.
* Granularly permissioned to support different writeback permissions for different users and conditions.
  * For example, an analyst may be allowed to start a new investigation, but the ability to close investigations may be restricted to members of the manager user group.

## Define an Action in the Ontology Manager

This section provides a brief notional example of action configuration focused on using actions within Workshop; for full details on defining actions, see the [actions documentation](../../action-types/overview/index.md).

This example is illustrative and you may not be able to complete every step as written. Since your Foundry Ontology is customized to your needs and data, you may not have access to the ontology objects required to complete the tutorial.

:::callout{theme="warning"}
To create, configure, or edit an action type, a given Palantir Foundry user must belong to the `actions-admins` group. Applying an existing action in Workshop does not require this membership.
:::

Actions administrators can create, configure, and edit action types in the Ontology manager. To access, select **Ontology manager** from the Apps sidebar. The **Action types** tab (seen in the screenshot below) provides a list of existing action types, which can be selected to be viewed and edited. The **New action type** button allows you to define a new action type from scratch. Alternatively, you can also create action types right from the object type which it should be based on. Navigate to the object type and select **Create new action type** in the action types box.

Select the **Create new action type** button on the object type to begin. In this example, define a “Modify Flight Destination” action that will allow users to modify the `Destination` property on an existing Flight object.

The creation wizard walks you through the most important steps to bootstrap your new action type. Enter a **Display name** and select **Modify** under the **Change object(s)** option to configure your action type. From the object dropdown, select your previously created `Flight` object and then select the `Comment` and `Destination` properties which this action type should modify.

![action\_wizard](../../../assets/c76e36ab595b22822fa7f54315d942bad0f84458ca09d394706d0ca3242cf1bf.webp)

The first tab of an action type definition is called **Overview** and allows you to define the **API Name** (a unique ID), the user-facing **Display Name**, the user-facing **Description**, and **Status** of the action. Some of these fields will already be filled based on the previous step. Fill the missing fields with values such as those seen below. The API name **cannot be edited after saving**, so it is important to take care when choosing an API name.

![action\_type](../../../assets/1367c04d226240f853b5b37d4c2604a42b604a6c058b1a08175c38df9a710b41.webp)

Next, select the **Rules** tab of this action type definition. This is where you will configure the core of your action type: its **Rules** or outputs / execution. After selecting the object type and the kind of changes you want this action type to perform, you can see the Rule configured as a modification rule as well as the added properties. You can add additional properties from the dropdown if needed.

![The Rules tab of an action type definition, showing the modification rule and its added properties.](../../../assets/16a52847770a1fb022e243fbe5d0527e3f2a134783ddfb43418b805e9c8757d1.webp)

The **Parameters** tab lists the parameters, or inputs, of your action type. The parameters have already been added automatically by the **Rules** section.

![action\_form](../../../assets/fe074801891f213fc63d2fb9f2dd9ebe73f27a1c7a3d6c76988482057ad88354.webp)

Next, configure some basic **Submission Criteria** for your action type. In this example, the goal is to confirm that the user has entered a valid three-character airport code (like `EWR`) for their modified destination. Navigate to the **Security & Submission Criteria** tab and select **Add a condition** in the **Submission Criteria** section. Use the **Parameter** condition template in this example to compare the `Destination` property with a regular expression like `^[A-Z]{3}$`; this lets you confirm that the value entered for your destination parameter is exactly three characters. To give the user more information about why a submission is potentially failing on a condition, add an error message at the bottom of the sidebar.

![configure\_submission\_criteria](../../../assets/bfdd974abc811e1e62e35eb5ae4bbc725c0ab3c122a35549ff98ea6a8529fbcd.webp)

To test the new action type, navigate back to the **Parameters** tab and use the preview of the form on the right side of your screen to test your action type. You can enter different values and select the **Submit** button. This only tests whether an action would be submittable and does not actually submit an action.

![action\_form](../../../assets/fe074801891f213fc63d2fb9f2dd9ebe73f27a1c7a3d6c76988482057ad88354.webp)

You have now finished configuring your first action type and need to save it on our Ontology. To do so, select the **Save** button at the top right of the screen, review the list of modifications that appear in a modal, and then select **Save** again twice to confirm.

![save\_action](../../../assets/0975ee9e2c650e039e1d0cbc828b961054e49e5d478a4aa48686d42b6bb62dcd.webp)

Your first action type is now saved, and we can head to Workshop to build a module that will allow users to execute this action type.

## Use an Action within Workshop

:::callout{theme="success"}
The below section assumes familiarity with building Workshop modules. See [this page](../getting-started/index.md) for a tutorial covering these topics.
:::

Within Workshop, actions can be exposed to users through a number of different widgets, including Button Groups and the [Inline Action widget](../widgets-inline-action-form/index.md). The example below begins with a Flight Inbox module and describes how to trigger actions via a Button Group from within this Workshop module.

![flight\_inbox](../../../assets/58124bf6459962a2a54a3535c15ba6dbe631f1bd1661b248312428d240bc7291.webp)

### Button Groups

The Button Group widget in Workshop allows a module builder to add one or more buttons to their module. For this example, we focus on how Button Groups can be used to expose an action in Workshop.

#### Configuring an action in a Button Group

After a Button Group is added to your Workshop module, single-clicking on the Button Group within your on-screen module will open the widget's configuration panel in the right-hand side of your screen. The core configuration options can be found in the **Widget setup** tab and are divided into three sections — **Button type**, **Button configuration**, and **Display & formatting**. The **Button type** and **Display & formatting** sections control the button layout and advanced display options. This example focuses on the **Button configuration** section, where a module builder can configure basic display options and determine how actions are applied when a button is selected.

![button\_group](../../../assets/e959adbb00483849c754e7b1532ddfb005d7392021aa9245a7bcf19207aa50ae.webp)

Within the **Button configuration** section of the above, you can adjust the **Text**, **Color**, **Left icon**, and **Right icon** options to control the display of the button. As an example, configure these four options for the "Modify Destination" action we intend to trigger from the button.

![button\_config](../../../assets/6050128d3d904eecb1cfc4cebdc8f0fc407ae8e3238849f673d548002686175a.webp)

This above configuration will produce a button that looks like the below. Accurately labeling a button with appropriate text, color, and an icon will help users understand what will happen when they select it. You can choose a preset intent (**none**, **primary**, **success**, **warning**, or **danger**) or specify a custom color, including via a hex code.

![modify\_destination](../../../assets/82a5364bd549029ce0aae65d575a1a4cce3152933c2bc4ac0e7d3da63837b846.webp)

Now that our button is labeled, we proceed to the **On click** section to connect our intended action. To do so, select the **Select an action...** dropdown and then filter to and select the "Modify Destination" action. Doing so will cause the below to appear, which contains all three of the action parameters that we defined when creating the "Modify Destination" action above.

![on\_click](../../../assets/b61459bbf8ad6a76817cb0e79c17b55e490468b8583a1a3b08893bebef99f622.webp)

Use **Parameter defaults** to set optional default values for action parameters. Select **Add all parameters** to configure every parameter at once, or **Remove all parameters** to clear them. Each parameter corresponds to an input in the action type definition, such as an object list, object reference, integer, or string. You have two options for each parameter:

* **Set a default value equal to a variable in the Workshop module**
  * To do this we can select the **Selected Flight** parameter's "no default" value and set this instead to be the "Active object" variable output by our object table of flights. Once this is set, additional options will appear to set the parameter to be **Visible** (default value can be further modified by a user in the actions form), **Hidden** (the parameter is entirely hidden from the user in the actions form), or **Disabled** (parameter appears as read-only to the user in the actions form). In this example, keep the default option of **Visible**.
* **Leave no default**
  * Parameters with no default will initially appear as empty fields in the actions form, and the values will be input by the user.
  * In this example, we leave Modified Destination and Comment(s) fields without defaults.

![on\_click\_2](../../../assets/3d3da8fd55fa9f518445bae70d2689fb00dbb9c3e61ea025995e9481dc0a40ba.webp)

#### Applying an action from a Button Group

After configuring the action in the Button Group, when a user selects the **Modify Destination** button in the Workshop module they will see an actions form appear. The default values of a field are based on the above configuration; the **Selected Flight** field is auto-populated based on the module variable, while the **Modified Destination** and **Comment** fields are left empty for user input.

![modify flight](../../../assets/8dd2b82de1e7ab81c150b255875f9bc2ea1f422c7c41190b87296b9361325ff1.webp)

In the form above, **1 issue** is flagged at the bottom left of the actions form. By hovering over the **1 issue** text, the user can see that the issue is that the **Modified Destination** field is not currently a valid three-character airport code.

![validation](../../../assets/c34031d2cff7ad0bf22df76edae13c2737ae9f071bea1d0da53460db46bffc74.webp)

When the actions form is filled out and all parameters pass validation, the action can be submitted (the submit button will be available).

![action submit](../../../assets/e719f274e785bfeb9b535296865929621ee7466d33f326f5773caf939c60dea3.webp)

After selecting submit, a user will see a green toast appear on top of the module, indicating that the action was successfully completed and the selected `Flight` object was updated to reflect the changes entered.

![action complete](../../../assets/c58bff0d0c1f2b53fc634775d56f2c8a5c6a6bca5d31833a92f043d15cdf7e09.webp)

#### Chaining an event with an action

To run a Workshop event at a specific point in an action's lifecycle, select one of these event triggers at the bottom of the widget configuration:

* **On start of Action submission:** Runs the event when the action submission begins.
* **On successful completion of Action submission:** Runs the event after the action submission succeeds.

Use these triggers to refresh data, navigate to another page, or update variables during an action workflow.

### Trigger actions from the Media Uploader widget

Actions can also be triggered when users upload files via the Media Uploader widget. This is useful for workflows that depend on newly uploaded media, such as processing, enrichment, or linking workflows.

The Media Uploader widget is labeled **Media uploader (Legacy)** in the widget picker, and the media set destination is hidden when you configure a new one. To upload to media sets, use a Button Group to open an action form, or use the [Inline Action widget](../widgets-inline-action-form/index.md). Dataset and folder destinations remain available.

When configuring the Media Uploader to trigger an action on upload, you can reference the uploaded file in the action's parameter configuration using the special file identifier value:

* For uploads to datasets, the file identifier is the uploaded filename.
* For uploads to Compass folders, the file identifier is the uploaded file's RID.
* For uploads to media sets, the file identifier is the uploaded file's media reference.

If multi-file upload is enabled, the configured action triggers once for each uploaded file, with the file identifier corresponding to the specific file being processed.

For setup details including button configuration, upload destination, allowed file extensions, dynamic destinations, and multi-file options, see the [Media Uploader widget documentation](../widgets-media-uploader/index.md).