Introduction

Alloy is all about actions. Whether you need to launch an app or automate some repetitive and complex tasks - Alloy makes it simple and handy. Just create corresponding actions and use them again and again. 

An Action represents work need to be done on the user request; it would be considered as a mini app or an applet. Actions would be as simple as just launching some apps or as complex as launching big workflows involving the user input, some system, and Cloud services.

Alloy presents actions in an usual multi-page grid layout. Use swipe gesture to move between pages. To launch an action - just tap on it. To rearrange actions and move them between folders - turn ON the Edit mode and use drag&drop to move actions on desired place.

Please check the Alloy Getting Started Guide for more introduction.

Action | Options

Input

It is possible to specify, which kind of data is acceptable for an action input via the "Options | Input". This option allows prompting the user only actions compatible with particular data type (e.g. image or URL) in Action Extension, "Open with", Paste or "Open Shared Data" commands. For example, an action working with photos should have the "Input" = "Photo". By default, action's output will be returned to the host app, potentially changing shared data. To avoid this (if it's not desired) the action's "Output (Extension)" property should be turned OFF.

Family

If some tasks are grouped together by their goal and they should share the same data - you  may specify that those tasks are belong to the same Family via the "Options | Family".

Tags

Tags allow to simplify action's finding and discovery either via actions search or "Add | Actions by Tag" list. You can specify comma-delimited list of Tags via the "Options | Tags". It is recommended to check list of existing tags first to avoid introducing unwanted tags just by typing possibly misspelled words.

Description

It is possible to specify action's Description via the "Options | Description". If you want to share an action with other people then you should specify the description. This would allow other people to better understand what those action does.

Short UID

Alloy allows launching its actions from other apps using URL Schemes. To achieve that, a correct action URL should be formed and opened. The simplest form of action URL is alloy://<actionUID> where actionUID is action's unique identifier. Sample URL would be:

alloy://6A7478D7-7915-4BB9-B662-B808108E3EC5 

To make action URLs more simple and human readable it is possible to specify short UID for an action via the "Options | Short UID". In that case sample URL would be as simple as:

alloy://smsKate

Test URL

Some actions may require presence of particular app in the device. Such actions can be accessed via the "Add | Actions for Installed App" list. To setup such an action a URL corresponding to that app should be specified via the "Options | Test URL".

Arguments

This option allows defining input and output arguments can be utilized when this action called from another action using a "Launch Action" task.

Version and Author

These options define action's version and author information.

Include in Favorites

This option defines whether the action should be presented in Favorites. You can turn this option OFF to avoid certain test or sample actions to be shown in Favorites.

Action | Log

Action | Privacy

Glances

Glance is an alternative way to render actions on screen that allows to present summary of information obtained by actions or related to them. Sample Glances would be: weather forecast, stock quote, time left, last tip calculation etc. Any Glance can be composed using finely laid-out styled texts, photos and icons and can be regenerated at any time by a workflow. Glance usually substitutes action icon and title, though icon and title can be optionally preserved to keep the action easily identifiable.

Glance may be composed of several items (text, icons or images) and Glance Groups. Each Glance Group can contain other items/Groups and defines layout and visibility attributes for them. Any item or Group will be visible only if there is enough space to fully present it. Though, the first item in Glance or in a Glance Group will be always shown.

Glances can be created or updated by any workflow. For example:

• Main Workflow for the Tip action creates glance that shows the latest tip calculation summary
• Background Workflow for the Clock action creates glance that shows current time and date

Glance creation starts from an "Add Glance" task. Then such tasks like "Add Glance Group" or "Add Glance Text" should be added to the "Add Glance" task to define glance content. For example, the Background Workflow for the Clock action would look like:

It is possible to provide different content for different icon (Glance) sizes. It can be done via the Show for Icon Size option for any Glance Group or Glance itself. For example, the Weather action shows 5 days forecast for Large icon size and today's weather for other sizes. Glance size can be changed to provide optimal space for its content. It can be done either manually using action's context menu or by a workflow using a "Change Action Icon Size" task.

Some Glance Groups may have a Workflow associated with them. In such cases, those Glance Groups will be rendered as buttons. When the user taps on such a button it will lead launching an appropriate Workflow. For example, taping on the "Anna Haro" button inside a "Birthday Today" action launches a workflow that prompts to greet her.

Debugging of Glances is pretty easy with help of Data Inspector, which is enhanced to support live preview of them. To debug Glances you can:

• Add a breakpoint, which inspects the $glance variable
• Run a Workflow in the Workflow Editor and inspect Workflow results

Workflows

Entire action activity is represented by a workflow consisting of a list of tasks. Task is a minimal piece of work needs to be done. Each task can obtain or modify some data, gather the user input or present some data to the user. Workflow is performed by executing one task per time, each task after another; output from a task goes to input of following one (aka. piping). Workflow (by default) stops if any task is failed due to an error or the user cancelled workflow's execution. 

Workflow ends when the last task is performed. If some task leads leaving the app (e.g. "Open URL" task) and the workflow is not completed - it would be suspended and its action's data will be persisted. The suspended action can be resumed at later time to continue performing the rest of workflow.

Each action can contain several workflows that cover different aspects of action. To add a workflow - tap the "Add Workflow" button. The following workflows are supported:

• Main (Workflow hereafter) - tasks that should be executed on action launch and represents main action's activity
• Installation - tasks that should be executed on action's install
• Background - tasks should be executed in background to post quick changes or update glance
• Clear Glance - tasks should be executed in order to clear glance
• Menu - named tasks should be executed from the action's context menu
• Widget - tasks should be executed when an action is launched from Alloy Widget without leaving it
• Drop - tasks should be executed to handle dropped data
• iMessage  - tasks should be executed when an action is launched from iMessage Extension

It is possible to define conditions for any individual tasks. So if task's condition is defined and evaluates to FALSE - this task will not be executed. Though, this functionality is deprecated as of v1.2 - use IF/ELSE tasks instead.

Many of the tasks are able to internally process arrays, which would replace the need to apply loop operations. For example, a "Convert Text" task can automatically convert single strings as well as all elements of the arrays.

Many tasks are quite flexible and can accept input data in different formats. For example "Save Photo" task accepts images specified as binary data, file paths or URLs. In more complex cases there is a need to convert data from one format to another using one of "Convert..." tasks or "Set Variables" task. 

All tasks use some variables to change and access data. Most of tasks use Input and Output properties to define task's input and output. Some tasks may use other variables as well. For example, an "Open URL" task introduces the Browser variable that allows specifying a variable defining which browser should be used to open links with.

The Input property defines a variable that should be used to obtain input for a task. If the Input property is not specified - the task uses output from previous task, which is equivalent of defining Input = input. Some tasks may support similar behavior for another task's properties too. For example, if both Text and Attachments properties are not defined for a "Send Email" task - the task will try to use input to fetch email's attachments first; if no attachments are found - input will be used to define text of the email. 

To instruct a task to ignore input value - specify minus sign as Input property. 

The Output property defines a variable that should be used to store output for a task. Even if the Output property is specified output from the task goes to input of the following task.

To change value of the same variable - state that variable for both Input and Output properties.

Use of piping allows quickly building of simple workflows with minimal need to change task's properties. For example, the following workflow prompts the user to enter text, converts that text to HTML and sends email with converted HTML text. Everything is done with no need to care about variables:

1. "Enter Text".
2. "Convert Text" - Markdown to HTML.
3. "Send Email" in HTML format.

It is possible to exclude a task from execution but preserve it in the workflow. You can do it by making that task Disabled via Task's "Options | Disabled".

Some tasks may require the user to enter data in a specific format. To hint users about such requirement you may specify detailed description via the Task's "Options | Hints".

Main Workflow

Main Workflow is tasks that should be executed on action launch and represents main action's activity. For example, a Call action would contain the following Tasks:

1. Prompt for a contact if t was not selected during action initialization.
2. Prompt for a phone number if t was not selected during action initialization.
3. Form a tel:// URL and open it to initiate a call.

Installation Workflow

Installation Workflow represents tasks that should be executed on action's install. Using Installation Workflow allows gathering user input and preparing data only once to be reused each time when action is launched. For example, a Call Action would include the following tasks in Installation Workflow:

1. Prompt the user to choose a contact and save it.
2. Prompt the user to compose the action icon based on the contact's photo.
3. Prompt the user to choose a phone number and save it.

As result of Installation of such Action:

• Action gets human readable title e.g. "Call Kate".
• Action gets clearly readable icon that shows properly arranged and scaled contact photo.
• Phone number is known, so when the user launches the action - app just initiates a phone call without a need of any additional user input.

It is possible to re-launch Installation Tasks for an action by turning ON the Edit mode, taping the Share button and choosing the "Reset" action. This allows to basically reset the action and initialize it with fresh set of data. For example, re-initializing the "Call Kate" action would allow choosing different contact e.g. John Doe, which effectively turns the action to be "Call John". 

Background Workflow

Background Workflow represents tasks should be executed in background to post quick changes or update glance without any user involvement. Example of Background workflows can be:

• Workflow that counts new photos and updates action's budge
• Workflow that gets weather forecast from Yahoo and renders it in the Glance

Background Workflow must not require any input from the user. So it allows to have only subset of tasks, which doesn't show any UI. Though, some tasks, that usually show UI, were modified to be silent when launched from Background Workflow. For example, a "Show Message" task will log a message instead of showing alert. The "New Task Chooser" was modified to show only allowed tasks, when maintaining a Background Workflow.

A new "Toggle Background Workflow" task allows to enable/disable Background Workflow and optionally allows to force it to run immediately. This task is very useful to toggle Background Workflows only when certain criteria are meet - for example after Installation Workflow completes.

The following are Background Workflow options (accessible via the  button in Workflow Editor):

• Priority - defines how often a workflow would run. Note: you should keep priority as low as suitable.
• Network - network requirements. It allows to running Background Workflows only if required network is available.
• Bound Variables - system variables this Background Workflow is bound to. Any change in bound variables will lead the Workflow to run disregarding its Priority.

The following are running schedule of a Background Workflow according to its Priority:

• High: runs on each app launch and then every 1 minute.
• Medium: runs on each app launch and then every 10 minutes.
• Low: runs once a day and then every 1 hour.

It is important to carefully design Background Workflows to let them complete as quickly as possible. Avoid doing long running tasks like big data uploads - reserve them to the Main Workflow. Alloy app will prompt to terminate long running Background Workflows after some timeout but you can let them keep running if desired. Though Alloy Widget will try to terminate such Workflows automatically without any prompt.

Note, due to luck of suitable background mode in iOS, Background Workflows run only when Alloy app or Widget are active.

Clear Glance Workflow

Menu Workflow

"Menu Workflow" represents named tasks should be executed from the action's context menu. It is possible to have any number of Menu Workflows that can be shown in the action's context menu. This would allow to have supplemental action activities. There's also a new "Call Workflow" task that allows calling any Menu (or Main) Workflows from other workflows of the same action, effectively implementing the "call a function" pattern.

The following are Menu Workflow options (accessible via the  button in Workflow Editor):

• Name - name to display
• Include in Context Menu - controls if this workflow should nbe shown in action's context menu.
• Arguments - list of arguments used by this workflow. A "Call Workflow" can utilize those arguments to let the user provide some values for them.

Widget Workflow

Widget Workflow represents tasks should be executed in Alloy Widget without leaving it. If the user taps an action in the Widget and the action has the Widget Workflow specified - that workflow will be executed, keeping Today Screen visible. Otherwise Alloy app will be activated and the Main Workflow will be executed.

Widget Workflow must not require any input from the user. So it allows to have only subset of tasks, which doesn't show any UI. Though, some tasks, that usually show UI, were modified to be silent when launched from the Widget Workflow. For example, a "Show Message" task will log a message instead of showing alert. The "New Task Chooser" was updated to show only allowed tasks, when maintaining the Widget Workflow.

In addition, there's the "Open URL" task available to allow opening of Alloy (alloy://) or some iOS System (like App-Prefs:) URLs.

Drop Workflow

The Drop Workflow represents tasks should be executed to handle dropped data. This Workflow is optional and it will be launched instead of the Main Workflow if present; dropped data will be passed as the action_in variable. For example, the "Open News" action provides the Drop Workflow to allow adding dropped URLs to its feeds list. Also this Workflow forces update of the Glance to incorporate and show news from a just added feed.

iMessage Workflow

iMessage Workflow represents tasks should be executed when an action is launched from iMessage Extension. If no iMessage Workflow is specified - the action's Main Workflow will be launched instead. 

In many cases similar Workflows with minimal changes can be utilized as the Main Workflow and, for example, iMessage Workflow. To avoid having two Workflows and copy-pasting tasks between them it is (sometimes) feasible to have just one Main Workflow with some differences based on the type of the project (e.g. the App or the iMessage Extension) the Action is running in. A "Get Project Type" task allows getting the project type and handling it in the following Switch to make desired project specific behavior.

Note: use "Open URL" tasks should be avoided in the iMessage Workflow as it results leaving the iMessage Extension.

Maintaining Workflows

Variables

Alloy uses variables to store and access state of the workflows and actions. Variables can be accessed by app, actions, and their tasks. Each variable is referred by its name. Variable’s name may contain letters, digits, and underscores.

Variables may have no value (aka. nil, NULL, etc.). It is about particular task’s implementation how to interpret such values: some tasks may ignore it, others may use default values in such case - e.g. 0 or empty string.

Type defines kind of data held by variables. Alloy supports dynamic-typing, which means that Type of variable is exactly defined by its data after assignment. Each Type defines its own set of properties, which can be accessed by . operator. For example, to access address of a location stored in the homeLocation variable you may use homeLocation.address expression. Access to non-existent properties is safe and returns no result.

In addition to property access operator, other operators can be used with variables. The following are all allowed operators:

Note: Alloy tries to guess Type of variables in the Action and Task editors, and presents available properties in the Variables' Keyboard. Though, current implementation may not discover correct Types in some cases. So if you know correct type of a variable - you can manually type its properties.

Macro

Alloy allows using macros to compose textual values, such as action’s name, URLs, etc. Macros can be embedded in free-form text and each macro can be defined as $(<expression>). In the simplest case, expression is a variable’s name. For example, text “Call $(contactName)” would be expanded to “Call Kate”.

Complete definition of macro is:

$(<variable>[| variable1 | variable2…][%format][=default])

To define a simple macro for variable:

$(contactName)

To define default value should be used when variable has no value - use = operator:

$(lastName = “Noname”) - either last name or “Noname” if last name is not defined.

If default value is not surrounded by quotes - it is interpreted as a variable:

$(lastName = fistName) - either last name or first name if last name is not defined.

To define several variables to choice use | operator. The first variable in the list that has value will define the result for macro:

$(lastName | firstName) - either last name or first name if last name is not defined.

$(lastName | firstName = “Noname”) - last name or first name or “Noname” if both names are not defined.

By default, macro uses textual representation of variables as implemented in the variable’s Type. Though, it is possible to define format for Date and numeric variables using the % operator - $(variable%format).

Date format is defined as dateFormat<,timeFormat><@timeZone> where dateFormat and timeFormat is one of the following format specifiers:

For example:

$(date%n,s) - 3:50 PM 

$(date%s,s) - 1/23/14, 3:50 PM

Time zone can be either a variable holding time zone or a string representing offset in seconds from GMT. For example:

$(date%n,s@location.timeZone) - 1:50 PM for GMT-2

$(date%n,s@-7200) - 1:50 PM for GMT-2

Number format is defined in printf specification. For example:

$(bill%.02f) - 123.25

$(bill%d) - 123

Action Environment

In Alloy each action executes in its dedicated environment, which provides all the required data. Action environment is composed as a set of nested contexts, where each context holds its own set of variables. To simplify things, there is no need to deal with a particular context - instead each variable should be prefixed to tell runtime where to find and store variable’s data.

The following are detailed description of contexts and their variables supported by Alloy.

Runtime Context

Runtime Context is a temporary context that exists only during a workflow execution. Variables (runtime), belonging to that context, have no prefix and they will be discarded upon a workflow completion. You can use Runtime variables to hold and transfer data meaningful only during workflow execution. For example, “Web Search” action, that prompts for a search term each time, may store and use search term as a runtime variable (searchTerm).

Built-in Runtime variables are:

Action Context

Action Context is a persistent context that is bound to an action it belongs to. Variables (action), belonging to that context, have the a: prefix and they will be persistent as long as the action is present in the app. You can use Action variables to hold data that should be re-used during several action launches. For example, a “Call” action may store a contact (e.g. a:contact) and a phone number (e.g. a:phone) as action variables to prompt the user only once to choose contact and phone number.  

Action Family Context

Action Family Context is a persistent context that is bound to an action family. Variables (family), belonging to that context, have the f: prefix and they will be persistent indefinitely until the user explicitly decides to delete them. Family variables are shared between several actions belonging to the same family. For example, different “SMS” actions, belonging to the same “sms” family may share the same list of canned SMS’s stored as f:smsList.

System Context

System Context is a persistent context that is bound to entire system (app). Variables (system), belonging to that context, have the s: prefix and they will be persistent indefinitely. That is why it is very important to think twice before introducing new System variables. You can use System variables to hold data that should be re-used by any actions in the app. For example, various location specific actions may use global list of saved locations (s:locations) accessible for any actions that need it. 

Built-in System variables are:

Working with Accounts

Accounts provide a way to guardedly and securely store and retrieve sensitive data like passwords, security tokens etc. Accounts should be created first using “Add/Update Account” task and then they can be accessed using “Load Account” task. If an action makes use of an account then the user will be prompted to grant access to that account. 

To access properties of an account - use common dot operator followed by a property name e.g. account.password. Only textual properties are currently allowed for account. Due to security reasons, it is not possible to list all the properties of an account, making impossible to utilize Variable Keyboard. So you must remember property names to access them.

Some accounts may allow authorization in order to provide access to third-party cloud services. For such accounts, appropriate authorization actions (sign-in and sign-out) must be provided. Usually, a sign-in action should utilize the AOuth protocol to prompt the user to sign-in, handle sign-in result, store user credentials and access token in the account. Optional sign-out action should remove user credentials and access token from the account and optionally notify cloud service about sign-out.

All the accounts are listed in the Alloy’s “Settings | Accounts | Custom Accounts” sections. Any account may be deleted using common swipe gesture. For accounts that allow authentication, it is possible to check their status, see signed-in users and perform sign in/out actions.

For complete sample, check "Action Directory/Samples" for “Dropbox Browser”, “Dropbox Sign-in” and “Dropbox Sign-out” actions.  

Including and Launching Actions

Alloy provides several ways to reuse existing workflows in other actions: 

Including Actions

“Include Action” task provides ability to include some (target) action to workflow. This is done at runtime by replacing every “Include Action” tasks with their target action’s Runtime Workflow tasks. This is rough equivalent of “inline function” concept.

Note: Initialization Workflow of target action is completely ignored. Inlined tasks maintain no relation with their originated action and they will be integral part of a workflow they are inlined to.

Launching Actions

A “Launch Action” task provides ability to launch other (target) actions from a workflow. This is rough equivalent of the “spawn process” concept.

Target action will be launched in their own isolated context with no relation to the source action’s context. To share data between source and target actions you may use clipboard, family and system variables.You may provide arguments to a target action in the form of HTTP Query string. For example, to pass contactID and prompt arguments to a “Contact” action the following query should be used:

contactID=$(contact.contactID)&prompt=Greet

Source action will be suspended (by default) till completion of a target action. To immediately finish source action - turn ON the “Finish Action” property of a “Launch Action” task. Suspended source action will be resumed even if the target action is failed or cancelled. Result of the target action launch can be obtained via the x-status variable, which can have one of the x-success, x-error or x-cancel values.

Target action can return some values. To set it up - define target action’s “Options | Output Arguments” in the form of HTTP Query string, similar to the sample above.

Working with Arrays and Maps

Initializing Arrays and Maps

1. Using an “Initialize Variables” task with JSON encoded value:

array = [1, 2 3, 4, 5, 6]

dictionary = {“value1” : 1, “value2” : 2}

2. Using a delimited text and a “Convert Text” task with the “Split to Array” or “Split to Dictionary” functions.

Filtering Arrays

There are number of tasks that provides ability to filter arrays using some logical expression. Use self variable to denote an element of array. For example, to find only contacts having birthday today, a “Find Contacts” task should have the following filter:

self.birthday.isThisDay == YES and self.birthday.isThisMonth == YES

Check the Predicate Format Syntax article for the description of expression format. 

Arrays Transformation

The “TransformArray” task provides ability to create a new array containing transformed values of original array. Use self variable to denote an element of original array. For example, to get an array containing only only birthdays of contacts, a “Transform Array” task should have the following expression:

self.birthday

Dynamic Choices

A “Choice” task provides ability to have dynamic choices sourced from the task’s “Source” property. Use self variable to denote an element of source collection. 

The following are a sample of a task showing contacts. For example, choice name, composed of a contact’s name and birthday, would be:

$(self)|$(self.birthday)

To sort contacts by name, use the following expression:

self.lastName,self.organization