Overview

Plans make easy to manage one's flowthings architecture. Access to Plans is provided via our command line interface tool, ft. Use cases for Plans include

  • downloading a project locally, editing it, and uploading it back to flowthings;
  • tracking a flowthings project in a version control tool such as Git; and
  • duplicating / moving branches of the project tree.

Plan Representation

Below is the directory structure of a small project.

$ tree plan/
plan/
├── base.flow.json
├── flows
│   ├── f1
│   │   ├── f1a
│   │   │   ├── t54160ae168056d1fd2a07546.track.js
│   │   │   └── t54160ae168056d1fd2a07546.track.json
│   │   └── f1a.flow.json
│   └── f1.flow.json
└── plan.yml

A Plan's directory structure corresponds directly to the project tree. Plan directories map to Flows of the same name. For a Flow of name F, the project directory will contain both a directory F and a F.flow.json, the latter of which contains Flow metadata. The root directory contains the file base.flow.json. This corresponds to the base Flow provided when creating the Plan.

Tracks are stored in the directory corresponding to their Source Flow. A track is represented as two files. These files are named <track id>.track.{js, json}. The former file contains the Track javascript and the latter contains Track metadata.

Best Practices and Limitations

Self-Containment

Users will get the most value out of Plans if they are treated as self-contained objects. A self-contained Plan can be seamlessly uploaded to new locations--even to entirely new accounts. Self-contained Plans require

  • using relative paths instead of absolute paths, and
  • interacting only with objects contained within the Plan base path.

Using absolute paths and paths located outside the Plan base path introduces the possibility that these references will break if the Plan is uploaded to a new location.

Relative Paths

Relative paths on flowthings work similarly to interacting with a computer's file system. For a Track located at /user/my/base/path/foo that wishes to reference Flow /user/my/base/path/bar, the Track should instead reference the path ./bar. Similarly, if the Track were located at /user/my/base/path/foo/child and wished to access the same Flow, it should use the path ../bar.

Validation

The platform does not edit or validate Track javascript. The platform will only validate Track destination paths if they are not specified in the javascript. Tracks in which the destination path is specified in the javascript can still be used in Plans, but the platform will not check whether the destination path is valid.

Nested Plans

Nested Plans are disallowed. A user cannot create a second Plan such that it overlaps with any of the branches of the existing tree. That is, if a Plan exists with base path /user/my/base/path, Plans with base path /user/my/base or /user/my/base/path/child are not allowed.

Plans Binary

Plans are managed using our Go binary, which you can get from our github.

Below is a list of the commands and options available.

$ ft
ft is the main command. It helps to build and manage your flowthings Plans. Complete documentation is available at flowthings.io/docs

Usage:
  ft [flags]
  ft [command]

Available Commands:
  version     Print the version of flowthings
  login       store your login credentials
  push        Push up to flowthings
  pull        Pull down updates to your plan from flowthings

Flags:
  -v, --api-version="v0.1": Api Version
  -p, --basepath="": Plan Base Path
  -c, --config="/Users/flow/.ft/creds.yaml": Config file
  -x, --dev[=false]: CLI Developement Version
  -d, --directory="/Users/flow/dev/demo": Plan Directory
  -e, --endpoint="https://api.flowthings.io": Api Endpoint
  -h, --help[=false]: help for ft
  -t, --token="": Your token
  -u, --username="": Your username

Use "ft [command] --help" for more information about a command.

Login

ft login -u <username> -t <token>

The first time you use the Plans application, you will need to log in with your flow username and master token. (Currently tokens other than the master token are unsupported).

Doing so will store your credentials in ~/.ft/creds.yaml.

Create

ft pull -p /flowAccountId/your/base/path

Creates a new Plan and downloads it to the present working directory.

Update

If your terminal's present working directory is home to a Plan, ft pull will instead refresh the directory with the latest copy of your project from flowthings.

Upload

ft push

Uploads locally-made changes to flowthings.