Action Configuration

Table of Contents

1. Configuration Basics
2. Editing Configurations
3. Authoring Configurable Actions
   1. “Configured Value” Action Step
   2. Using Configured Values in Templates
   3. Using Configured Values in Scripts

Configuration Basics

Actions can be built with configurable values that can be modified for each user installation. Configured values might control some aspect of the action’s behavior or information needed to identify your personal accounts and services. These configured values allow an action to tailor its functionality without requiring the action itself to be edited.

Editing Configurations

If an action has configurable values, the context menu on the action in the action list will contain a “Configure” command. To access this command:

• iOS: Long press the action in the action list and select “Configure”
• Mac: Secondary (right) click the action in the action list, and select “Configure”

iOS Mac

If the action’s contextual menu does not have a “Configure” option or it is disabled, then that action has no configurable options.

If you install a new action that requires configuration before it is used, the configuration prompt will automatically be displayed the first time you attempt to run the action.

Configurations are specific to an individual action. You could, for example, have the same action installed twice with different configuration options selected.

Authoring Configurable Actions

Configurable actions are created in two steps:

• Add one or more “Configured Value” action steps to your action, and set them up to describe your value.
• Use the configured values in other action steps, either via script or using template tags, to customize the behavior of the action.

Let’s break down what that means…

“Configured Value” Action Step

Each “Configured Value” action step in an action defines a single option that will be available to users in the configure prompt. A single action can have more than one such step, and they can appear in any location in the action.

The options to set up on each step are as follows:

• Name: A user-friendly name for the value to display in the configuration prompt.
• Description: A longer description, if needed, to explain how the value is used and what is expected to be entered by the user. Use this to give details on valid values or instructions on locating the value to assist the user in successfully configuring the action.
• Key: An alphanumeric key used to identify the value when retrieving it in code or templates in the action. This key is used in your scripts and templates to retrieve the current value the user has configured (more on retrieving values below). Key values should each be unique if an action has multiple configured value steps and they avoid conflicts with existing template tags.
• Value Type: Data type of the value. Currently, the step supports storing strings, numbers, and boolean values.
• Default Values: Optional default values. If provided, these values will be pre-filled when the user first configures the action. If no default value for the type associated with this step is provided, the initial value will be blank. Useful if your option has a logical default value to suggest.
• Example Value: Placeholder text. Displayed as the empty field placeholder text for empty string and number values in the configuration prompt.
• Requires configuration: If enabled, the user will be prompted to configure the action before running the first time. If disabled, it is assumed your action has a logical default for this value and only provides configuration as an option. Consider disabling this if your value is only for the purposes of customization and not a required value to make the action functional.

Using Configured Values in Templates

Each configured value key will create a custom template tag available to other action steps in the action.

If you have a key folderName, you can insert the value a user configured in a template using [[folderName]]. For example, an action that saves to a file could have this configured value step and use the [[folderName]] tag in a File action step’s “path” property to incorporate the value in a path.

Using Configured Values in Scripts

More commonly, configured values will be accessed in Script steps. Any values defined will become available as keys in the context.configuredValues object (docs).

Say you are creating an action to apply Markdown emphasis to selected text in the editor. You might want to make a configured value available to select whether the action uses an asterisk or underscore as the emphasis character. In the action, create a string type Configured Value step, with the key property markupCharacter – then you can load and use the configured markup character in your script like:

// setup a variable with a default value
let markup = "_";
// check if a user-configured value is available and override if so...
if (context.configuredValues["markupCharacter"]) {
	markup = context.configuredValues["markupCharacter"]
}

Here’s in an example Markdown Emphasis action that demonstrates.

It is also possible to load configured values from another action, for advanced use-cases where you want to be able to share configured values across multiple actions. To load the configured values from another action:

let otherAction = Action.find("OTHER-ACTION-NAME")
let myValue = otherAction.configuredValues["myValueKey"]

Note that loading values from another action will not trigger configuration of the other action’s values, so your action should gracefully handle missing values.

For examples, see these two actions in the directory that have been updated to utilize configured values:

• Markdown Emphasis: Allows the markup character used for emphasis (_ or *) to be configured.
• Markdown List: Allows the markup character used for lists (- or *) to be configured.