Integrating a Project Management App On Zapier#

Overview#

For general concepts about how to create the best integration on Zapier, we recommend you read through the Planning Guide. You should also read the Style Guide, which provides a overview on best practices for how to implement your plan for your integration.

This guide discusses some unique key considerations (UX and technical) when building a Project Management integration with Zapier.

Triggers#

Trigger Copy#

The following are types of records or events that customers typically expect to have on a Project Management integration. Please adhere to the "New x" copy that we recommend for all apps, and the term that appears in your app’s UI.

  • New Project
  • New Task (also: Todo, Subtask, Card)
  • New File
  • New Comment (also: Note)
  • New Event
  • New Account (also: Member)

  • New Activity - a custom-configured trigger that will allow users to define specific events that they’d like to automate, such as a status change or a task being deleted. We recommend looking at Trello’s New Activity trigger for an example of this - a small sample of what you can do with that trigger is depicted below).

x

There are special kinds of updates that users typically want to trigger off of as well. Moreso than other apps, users really want to see updates triggers added to Project Management integrations because they’re frequently tracked between multiple apps and experience a lot of changes over their lifecycle as projects move towards completion - versus a contact on a contact management app, which will almost always have the same email and name when it was first added:

  • Updated Project
  • Updated Task (also: Todo, Subtask, Card)
  • Updated Event
  • Completed Task
  • Completed Project
  • Project moved to Stage (also: Project Changed Status)

For more advice on copy we expect from all apps, check out our Style Guide’s section on what language to use here.

Trigger behavior#

Permissions#

Because Project Management apps are frequently team-based, it’s important to ensure that Zaps will also trigger on teammates’ activity. For example, if user A creates a Zap that collects comments on projects, they’ll want to know if user B comments on projects as well.

Permissions may also fluctuate depending on if someone is an admin/creator of a record or not. Typically users expect to be able to automate off any record that is shared with them, regardless if they’re an admin/creator or not, so we strongly recommend ensuring that any trigger behavior encompasses all updates that are visible to a logged-in user in the UI. For example, if I can see that a teammate has made an update to a Project that we are all assigned to, their updates should trigger off Zaps connected to my account as well.

If this is not possible with your API, even with using hydration in scripting, we recommend making this clear in the Trigger description. For example, for the trigger New Note, you may say "Triggers when the connected user account adds a note to a project."

Setup options for your Triggers#

You can implement Trigger options so that users have more flexibility in filtering which kinds of records they’d like to receive. For example, if you have a Project object for which someone could create many tasks, your New Task trigger could have an optional trigger option that is a dynamic dropdown displaying the user’s current Projects. This is how Basecamp 3 does this for their Create To-Do action - their Project dynamic dropdown has an added benefit of having a search connector, which makes it an even smoother experience for users:

Consider ordering the dropdown list by the most recently added to make it easier for users to find the Project they are mostly likely to choose.

Trigger response format#

Obtaining Linked Information#

Project Management apps are unique because they can offer a wealth of records that are linked to other records. Getting the full context of linked information is useful. For example, if your trigger is "New Task" and newly added Tasks are linked to Projects, then users expect to get data about the Project itself as well.

Linked information should be provided as IDs so they’re easily mapped in your app’s action steps, as well as human-readable data like the name.

If the endpoint on a certain record type does not already return additional linked data beyond the ID or the name of the linked records, you can, implement z.request in scripting and use hydration/dehydration, as described here. This allows for a workflow where users trigger off New Tasks, but also get information from linked projects on the tasks, such as the project’s name or due date.

https://cdn.zapier.com/storage/photos/59663ea7e06d852d1346a482356d4f3e.png

Generally speaking, for each record type, users expect to get information that’s visible in the UI back in the response content. If a new Task includes detailed information like Due Date or Assignee in the UI, users will want this returned in the response content as well. For example, here’s what Task looks like within the Podio app:

x

And here’s what it looks like when you create a Task in the Podio editor. Notice that the fields available in UI are the same fields available here, which makes it easier for users to do what they want.

Searches#

Search Copy#

The following are types of searches that customers typically expect to have on a Project Management integration. Please adhere to the "Find x" copy that we recommend for all apps, and the term that appears in your app’s UI.

  • Find Project
  • Find Account (also: Member)
  • Find Event

A useful thing to bear in mind is that users will typically want to find top-level records so they can add child-level details. For example, let’s say that one Project can have many Tasks. It’s much more likely that users will want a Find Project search so they can add tasks to projects, rather than a Find Task search.

Search Behavior#

This should find an already existing record, and return it in the same format that the trigger returns the same record in. This ensures that the user gets a consistent experience, and there aren’t any fields in a trigger that don’t appear in the corresponding search.

Setup Options#

Consider providing multiple search options by providing two fields: a search key as well as a search value. The search key should be a static dropdown of different fields users can search by - for a "Find Project" type search, we suggest offering unique fields such as the Name or ID. It’s good to provide both options so users have flexibility depending on if the trigger is from your app or a different app.

Additionally, we recommend that the Name search returns exact matches first. This is because it’s likely that users will have similarly named projects - for example, "Promotional Advertisement November" and “Promotional Advertisement September.” This is how Asana organizes their search:

asanasearch

Action Copy#

Users typically expect to have the following types of create actions for Project Management integrations. These should follow the "Create x" or "Add x" we recommend.

  • Create Project
  • Create Task (also: Todo, Subtask, Card)
  • Create File
  • Create Comment (also: Note)
  • Create Event

Because projects are very dynamic and are often organized across several apps, we strongly recommend adding actions meant for updating as well, such as:

  • Update Project
  • Complete Task (also: Todo, Subtask, Card. You might try "Update Task Status" if it’s appropriate for your API as well.)
  • Update Event

For other advice on copy we expect from all apps, check out our Style Guide’s section on what language to use here.

Action behavior#

Multiple Linked Records#

Your integration will be especially powerful if users can link other record types when creating a record. For example, in your app’s UI, users may be able to create an Event and link it to existing Project.

It’s important to ensure that when a user creates a new Event through Zapier, this should only create new Events, and should not also create other linked records at the same time. This reduces opportunity for error as well as record redundancy for the user.

Setup template for your Actions#

Linked Records#

If your app’s UI allows for other record types to be linked, such as Projects and Tasks, or Accounts and Events, we recommend making that option available in the Zap template. Ensure that the linked record field is a dynamic dropdown populated with existing records. We strongly recommend that you add a search connector and a search step to make this the most streamlined experience for your users to set up.

An example of linking records is in Trello, where creating an card also allows you to associate a member. The member field in this case is also a dynamic dropdown with a search connector, which we strongly recommend for displaying linked record fields to the user and making it easy for them to set up.

x

Action response format#

Basic Expectations#

This should return at least the data that was created during the action step, to make it easier for users to map in subsequent steps and also see what was created. It should also include the ID of the created record as well as any linked records for faster mapping into subsequent steps.

For more information about what we like to see across all response content, check out our Style Guide section on it.

Implementation checklist#

  • Connect your integration with another project management app or two, to see if the data your integration returns blends well with our common apps. We recommend this because frequently, companies will use a blend of project management apps to keep track of their work.

  • If your integration supports events or tasks with due dates, try connecting them to a popular calendar or scheduling app to see if they integrate well.

  • If your integration has many nested items (such as projects containing subprojects which can contain tasks and then subtasks), try setting up a few Zaps to see if the behavior across nested objects is the same as parent objects. Data returned should always be the same format; if your API doesn’t enable access to nested objects, you should make a note of that in the help text for that trigger/search/action.** **

Next Steps#

  • See our Style Guide to learn more about other requirements for your integration such as branding.

  • Read our activation checklist to learn about making your app available globally.

Feedback#

Please let us know if you found this guide useful or have any feedback on how we can improve it.

↑ Was this documentation useful? Yes No