Zapier
Start Zaps from Velocity events, and create and update issues, comments and projects from thousands of other apps.
Overview
Velocity's Zapier app is listed in Zapier as Velocity Quest, because a different app already uses the name “Velocity”. It has 8 triggers, 4 actions and 3 searches. Triggers are instant: Velocity pushes each event to Zapier as it happens. Actions go through the same code as edits in the app, so they send Slack notifications, fire webhooks and run your automations, just as a person's edit would.
Zapier works on every Velocity plan.
Velocity Quest isn't in Zapier's public app directory yet: it's going through Zapier's publishing review. Until then it's available by invite, and it won't show up when you search Zapier unless you've been invited.
Connecting
You connect Velocity from inside Zapier, not from Velocity.
Add Velocity to a Zap
In the Zap editor, search for Velocity Quest as the trigger or action app and choose Sign in.
Sign in to Velocity and choose a workspace
A Velocity window opens. Sign in, pick the workspace this connection should use, and approve access. Zapier gets permission to read your workspace's issues, comments, projects and cycles, and to write to them. It gets nothing else: this connection can't call the rest of Velocity's API.
Build the Zap
Zapier labels the connection with the workspace and your email, for example Acme · ada@acme.com. Dropdowns for teams, statuses, members, labels, projects and cycles load from that workspace.
One workspace per connection
Each connection is tied to the one workspace you picked when you signed in, and can't read or change any other. To automate a second workspace, add another Velocity connection in Zapier and pick that workspace. A connection acts as you: what it creates is attributed to you, and it can only do what you can do in that workspace.
Triggers
When a Zap with a Velocity trigger is turned on, Zapier subscribes to that one event. Velocity then sends each event the moment it happens. When you click Test trigger in the Zap editor, Zapier fetches recent records instead, so you can map fields before anything new happens.
| Trigger | Fires when |
|---|---|
| New Issue | An issue is created. |
| Updated Issue | An issue's status, priority, assignee, title, due date, estimate, team, project or cycle changes. Not on creation, imports, board reordering or label-only changes. |
| Issue Status Changed | An issue moves to another status. The record includes the status it left and the one it entered (from_status, to_status), each with its name and type, so a Zap can filter on “moved to a completed status” without a lookup. |
| New Comment | Someone comments on an issue. The record includes the issue. |
| New Project | A project is created. |
| Updated Project | A project is saved, other than when it's created. Every save counts, even one that changed nothing. |
| Cycle Started | A cycle becomes active on its start date. See cycle timing. |
| Cycle Completed | A cycle is completed on its end date. |
The issue and cycle triggers take an optional Team, so a Zap fires only for that team.
Actions from a Zap count as edits. An Update Issue step fires Updated Issue triggers, including in the same Zap if it starts from one, so use a Zapier filter to avoid a loop.
Cycle timing
Velocity moves cycles along by date once an hour, using UTC calendar days. A cycle becomes active on its start date and is completed at the start of its end date. So Cycle Started and Cycle Completed fire within an hour of midnight UTC on those dates, not the moment a date changes. Only recent dates count: editing a cycle so its start is already a week past moves it along without firing Cycle Started. See Cycles.
Actions
| Action | What it does |
|---|---|
| Create Issue | Creates an issue in a team. Title and team are required. You can also set the description, priority, status, assignee, project, cycle, parent issue, labels, due date and estimate. Without a status, the issue gets the team's default. |
| Update Issue | Changes an existing issue, found by identifier (ENG-12) or ID. Only the fields you fill in change. Labels can be replaced, added to or removed. To empty a field, choose it under Clear Fields. Leaving a field blank never clears it. |
| Create Comment | Adds a comment to an issue, optionally as a reply to another comment on that issue. |
| Create Project | Creates a project. If you leave the identifier out, Velocity derives one from the name (“Website Redesign” becomes WR, then WR2 if that's taken). |
Actions return the record they created or changed, including a url to the issue in Velocity, so later steps can link to it.
Searches
| Search | Finds |
|---|---|
| Find Issue | An issue by exact identifier or ID, or by text in its title, identifier or description. Also available as Find or Create Issue. |
| Find User | A member of the workspace by email address. |
| Find Project | A project whose name or identifier contains the text, exact matches first. Also available as Find or Create Project. |
Suggested Zaps
Settings → Integrations → Zapier suggests a few starting points:
- Gmail → Create Issue: turn labelled or starred emails into issues, with the email as the description.
- Issue Status Changed → Slack: tell a channel when an issue moves to a completed status (filter on
to_status.typeiscompleted). - Typeform → Create Issue: file bug reports and requests from a form straight into a team.
- New Issue → Google Sheets: keep a running log of every new issue in a spreadsheet.
Managing the Connection
Settings → Integrations → Zapier shows whether Zapier is connected to the workspace and lists:
- Connections: each person who has signed in to Zapier with this workspace, when they connected, and when the connection was last active.
- Active Zaps: each Zap listening for a Velocity event, with its trigger, who created it, its last delivery and its status.
Disconnecting
Workspace admins and owners can click Disconnect. That signs Zapier out of the workspace for everyone and removes every Zap trigger listening to it. Zaps that use Velocity stop working until someone reconnects them in Zapier. The Zaps themselves stay in your Zapier account.
When someone is removed from the workspace, the Zap triggers they created are removed too, and their connection stops working.
Troubleshooting
A Zap turned off, and its entry vanished from Active Zaps
That's expected. When you turn a Zap off or delete it, Zapier unsubscribes, and Velocity removes the Zap's entry. Turning the Zap back on subscribes it again.
“Forbidden”, or a workspace's data is missing
A connection only sees the workspace chosen when it signed in. Check the connection's label in Zapier, and add a new connection for the other workspace. The person who connected also has to still be a member of that workspace.
The connection asks you to sign in again
Its access was revoked, usually because an admin disconnected Zapier from the workspace. Reconnect in Zapier.
A field wasn't cleared
Blank fields are ignored, because Zapier sends every unmapped field as blank. Use Clear Fields on Update Issue.
“Invalid reference”
The status, cycle, label, member or project isn't in this workspace, or the status or cycle belongs to a different team than the issue. Set Team first so the dropdowns show the right team's options.
An issue identifier isn't found
If two issues share an identifier (after a team's key changed, for example), Velocity won't guess which one you meant. Use the issue's ID instead.
Rate limits
Zapier calls count toward a limit of 300 requests a minute per person, shared by all of your Zaps and your automation API keys. Past it, Velocity answers 429 with Retry-After, and Zapier retries.