Building an app with the Teamwork Developer Portal?

Fast track the review process with these steps!

At Teamwork, we know that integrations between the products you use most are essential to speeding up workflows and saving you time on switching between multiple apps. So when we released the Teamwork Developer Portal earlier this year, we were really excited to finally unleash the power of API driven solutions, and give you a dedicated space to build custom workflows with the tools you use everyday.

Why build with us?

Building an app to enhance the capabilities of Teamwork not only allows you to unleash the power behind automated processes, but it gives you access to our growing customer ecosystem. Did you know we have 20,000 + customers?

Right now, we have a suite of 5 products, all with their own integrations to offer a seamless experience within our suite. With the ability to create your own apps, you have the opportunity to expand our suite, and grow with us. Whether you are trying to tackle an internal business process issue, or promote your company through integrations listings, we will support your development.

So if you’re interested in building an integration with Teamwork and would like to get listed in our integrations directory, then keep reading.

Firstly, your app must be created in the Developer Portal — you can learn more about how to get started here.

When your app is ready to go, it’s time to get it verified by Teamwork by reaching out to us at integrations@teamwork.com. For this step, it’s essential that you provide us with a way to test your app.

Since launching the Developer Portal, I’ve come across some common missing items in applications. So to speed up this process, I’ve outlined a checklist of everything you need to get a quick approval and listed on our integrations directory in no time.

Let’s get started!

Verification Checklist

1. App Sanity Checklist

It’s important that we check some app details in the Developer Portal:

• Name and description must be clear and honest
• Icon must be clear and visible
• At least one product scope must be listed, but no more than is necessary. For example, if your app creates tasks, no need to have Teamwork CRM as a product scope. It’s safer for our users to use only the scope(s) you need. You can change this later and it’s no trouble — the consent screen will show for any new scopes
• Redirect URI must be entered, but no more than necessary, https only

2. OAuth must be implemented

It’s important that you use the credentials from the Developer Portal for authentication, we require all apps to use our App Login Flow. In order to successfully implement this, you need to pass in the client_id and client_secret along with redirect_uri.

3. Check for your consent screen

It’s important that when testing your app, you consent the app to use your data. Consent screens look like this:

To test this, simply add a new user to your Teamwork site, or sign in with an existing user that has never logged into your app or used it before. A new user signing into a 3rd party app will always get a consent screen the first time they log in. Once they consent to the app, the consent screen for that user won’t bother them again unless you change the scope of the app. In that case, the user will need to give consent for the new scope.

Why isn’t my consent screen showing?

Are you certain you are logging in with a new user ? If the user has granted consent to the app previously, the consent screen won’t be shown again.

Why does my consent screen show a random string instead of my app name?

This is a very common occurrence, and the reason is:

• You are not sending the redirect_uri and client_id correctly. Ensure to check that it’s in your first call to launchpad/login?client_id=XXX&redirect_uri=YYY, and in your payload to token.json.

4. There is no impact to the Teamwork data on initial sign up or import

Your app should enhance the user’s experience. When they log in, they should not be met with drastic changes to their Teamwork account.

5. Certain API functionality is present

The most common issues we find with 3rd party apps when it comes to using our API is:

• API Implementation for paging requests: Lots of 3rd party apps don’t include paging on their API requests the first time around. It’s easy to implement, and you can find our paging under each of our API hubs: Teamwork, Teamwork CRM, Teamwork Desk, Teamwork Spaces
• API Implementation for rate limiting: OK, we had to add in rate limiting to keep you from hammering our poor servers. So if we receive more than 150 requests per minute, we will send you to the sin bin. ie. you will receive a HTTP 429 Error code in response. The status text returned will be “You have exceeded your rate limit. Please try again in a little while.” After 60 seconds, we’ll let you back in!
• We check for large imports: if your app requires an initial import of Teamwork data. Our testers when verifying your app will check a data-set that is large which would have more data than many single paged requests. Why? To catch two things, the paging & rate limiting, but also to ensure the doesn’t crash and the requests were closed out in an efficient way.

6. User permissions testing

This is super important to us! Our privacy features are used by many of our users and ensuring our 3rd party apps respect that privacy is key. Depending on the app, we will check that permissions based tests are carried out.

For example, with Marker.io, their app allows creation of tasks in Teamwork from their app. When testing this, we looked for features like:

• The projects rendered in the 3rd party app are the same as in Teamwork
• We turned off the ability to create tasks for a user and test the permission is handled in app respectively
• On tasks returned, we ensure tasks marked as private don’t appear

It’s important to note that any behaviour on the 3rd party app must match our web app, if you are making assumptions about privacy settings, or admin settings, the user must be notified. Any assumptions regarding permissions must be clearly documented and explained to the customer. For example, when adding a user to a project in order to assign them to a task, it must be clear to the user that they’re adding this person to the overall project as part of this step. For example, you want to assign a task to me, Holly, but I’m not in project Website Redesign. In order to add a task for me, it involves adding me to the project first. We need to ensure the user is aware of the change they are making, with a simple notification to say “You are adding Holly to this project by assigning this task”.

Finally, The app should enhance the Teamwork experience

The app should work alongside Teamwork to enhance the user experience in both products. The app should be an integration and any actions should involve some interaction with Teamwork.

Have you ticked all those boxes?

If you’ve covered off each item on the checklist above then it’s time to reach out us at intergations@teamwork.com with the following information:

• A detailed overview of the app: Explain exactly what the app does, in as much detail as possible
• Help docs on how to access the test app and how to use the integration: Our team needs them to get testing and verify the app as fast as possible
• A test account of your app: so we can access the integration inside your software

More often that not, apps don’t get verified first time around because of simple issues, such as:

• Not being able to log in
• Not having paging or permissions based API requirements
• Importing projects or tasks crashing
• No consent screen
• No help docs or test account provided

If we don’t encounter any issues, and all of the above information is included, then that’s it! We will mark your app as verified and you will see the tag in the Developer Portal change from “In Development” to “Published”.

If you are interested in listing your app? take a look below…

App Listing

Let’s take a deep dive into the content you need to provide once your app is verified. You’ll be notified once the app is verified by Teamwork .

1. Public help docs explaining how to enable the integration and how to use it

Help docs are one of the most important resources you can give us, and this can be provided as early as the first point of contact. While this seems similar to the point above, the help docs above will need to be polished for our customers. We will send these to our technical writers for review and list them under our help doc sites — similar to our Marker.io help docs.

2. Dedicated landing page for your new Teamwork App

A dedicated landing page for your new Teamwork app is required. This will be used to link your app to our integrations directory. Take a look at some of our partner landing pages as a place to start. The likes of Marker.io and Numerics are great examples!

3. Provide a short description and logo

You’ll need to provide a short description and a high resolution logo in order to be listed on our integrations directory. Your app will be listed on our integrations listings here. Here’s an example:

Our integrations directory is a growing collection of apps which showcase the work of Teamwork developers and integration partners. We pride ourselves in knowing that our platform is being transformed with new and innovative apps that help people work together beautifully and be more efficient day to day — and that’s why we take this process seriously.

I hope this helps you in getting an app approved on the first request. If you have any questions, please don’t hesitate to reach out to integrations@teamwork.com.