Components allow developers to build reusable fragments of Apps that can be shared with other developers and incorporated into their Apps. Components allow developers to quickly build their own customizable Activity Patterns out of the primitive building blocks already at their disposal. These Components then become the unit of re-use in Apps to avoid duplicating chains of tasks that commonly appear together.

Component Representation

Components can be thought of in the traditional terms of an interface and an implementation. Component authors craft the implementation much like they would craft a normal App. Then, authors may choose how consumers will interact with the Component by providing a configurable interface. Consumers of the Component then use the Component like a black-box, only seeing and adjusting the configuration properties in the interface.

The Component interface is represented as an instance of the activitypatterns resource, and a query for all activitypatterns will find a record for every Component in addition to one for every built in Activity Pattern. Consumers will interact with a Component interface in the same way they would interact with a built-in Activity Pattern pattern configuration.

The Component interface also includes a description of its output using Downstream events. Each Downstream represents a connection point the consumer can use to trigger other tasks. The combination of a Component’s configuration properties and downstream events fully describe the way consumers can interact with the Component.

The Component implementation is represented just like a normal app, as an instance of the collaborationtypes resource. A query for all collaborationtypes will return both Apps and Components. To distinguish between the two, check if the isComponent flag is set to true. When an App that references a Component is saved and code generation is performed, the Component implementation is generated into the consumer App before code generation is performed on the primitive Activity Patterns.

It is important to consider Components from two different perspectives: developers using existing Components and authoring new Components. These sections are separated below for clarity.

Using Components

When editing Apps, developers can add Components to their App just like they would add any other activity to the App. The list of available Components can be seen at the top of the Activity Pattern palette on the left side of the pane:

Drag a Component onto the App diagram and connect it by dropping it over an existing task or on a link between two tasks. The Component will be added to the graph as a pink rectangle, along with downstream triangle nodes representing the downstream connection points.

In the example above, there is only one exposed downstream (named WriteToDB); however, Components can expose multiple downstream events, in which case the App Builder will render a downstream triangle node for each like this:

Once a Component has been added to an app, edit the configuration just like any other task in the App by selecting the node and clicking the “Click to Edit” link to open the configuration modal. Note that clicking any node in an App Component diagram selects all nodes in the Component because the configuration applies to the entire Component.

Note: we sometimes refer to a developer using a Component in their App as a consumer of the Component. For instance, the configuration modal described in the previous paragraph may be referred to later as the Consumer Configuration Modal for the Component.

Importing and Updating Components

App Components can be added to projects the same way Apps can be added to projects. Components are represented as Collaboration Types (just like Apps), so they will appear in the collaborationtypes directory of an export. Importing Components works just like importing Apps.

Updating a Component works similar to updates to the built-in Activity Patterns. When a new
version is imported it does not immediately have any impact on any running apps that use the Component. The next time an update is made to an App that uses the Component, the updated version of the Component will be used. This gives the App developer a window of time between importing a new Component definition and updating their App to resolve any incompatibilities that the Author may have introduced into the new version. These incompatibilities should be described by the Component Author in the description, but ultimately that is up to the Author.

Expanding Components

While Components may be edited as single task in consuming apps, they are still implemented as a collection of one or more primitive tasks under the covers. After adding a Component to an App and saving it, developers can choose to show the Component as a single node (the way it was originally displayed), or they can expand the Component to show the complete sequence of tasks that implement the Component. To visually expand a Component, hover over the task box, and a green expand icon will appear at the top-left corner of the box like this:

Clicking the expand icon will show all the tasks in the Component implementation, which can be particularly useful on Components with multiple downstream events like the one pictured above. While the collapsed Component shows two downstream events at the same level, if you expand the Component you can see that the downstream events occur at different places in the implementation: