Integrations are a big part of any software, but they’re crucial to the functionality of a tool like Productive.

That’s why we decided to dedicate a post series to discussing the importance of integrations in Productive. From enhancing functionality by connecting different tools to streamlining processes and improving user experience, integrations make life easier. We’ll showcase one of our most-used integrations, the one between Productive and Xero, which allows users to seamlessly transfer invoices and synchronize payments between the two tools.

Your agency uses Productive for managing client projects and project financials. At month’s end, you face the daunting task of issuing and sending invoices upon invoices, then replicating the process in Xero. Afterward, you also have to individually mark each payment as received.

And this is where the power of integrations kicks in. With one simple integration, invoices are synced between Xero and Productive, and any payment received in Xero is automatically recorded in Productive.

The integration between Productive and Xero looks interesting, right?

But before actually using the integration, we need to set it up first, and that’s the main focus of this blog post! We’re exploring the implementation of the OAuth 2.0 protocol.

Let’s dive right in!

First, How Do You Connect Xero and Productive?

OAuth 2.0 (Open Authorization 2.0) is an authentication protocol that is considered an industry standard.

Utilizing the OAuth protocol, Productive is granted access to the Xero account without accessing the user’s credentials.

Key features of the OAuth 2.0 protocol:

• Granular access control

• Authentication without sharing credentials

• Token-based authentication (access_token & refresh_token)

In the following steps, the authentication process is explained:

1. The user authorizes Productive, granting access to their own data on the Xero platform:

2. After successful authentication, the user is redirected back to the redirect_uri defined in the previous step with two values added as query params:

• code → short-lived token that needs to be exchanged for access_token
• state → serves as protection against Cross-Site Request Forgery (CSRF) attacks: if the received state attribute value does not match the value submitted in the previous step, the authentication process is terminated

Ensuring the redirection of users back to the Productive app is a crucial aspect of the OAuth flow due to the sensitivity of the information contained in the redirect_uri.
To ensure the user’s redirection to the correct location, we have securely stored the redirect URI within the Xero app.

3. Exchanging the verification code (code) for an access token (access_token):

4. Retrieving the generated tokens:

access_token is used to call the Xero API, while the refresh_token is used to refresh the access token once it has expired.

5. Retrieving and selecting the tenant whose resources are being accessed:

Each user can have multiple Xero organizations (referred to as tenants).
Xero requires that the xero_tenant_id field is sent as a header param in every HTTP request.

The following code snippet shows the retrieval of all available tenants, from which the user later selects a tenant for current integration in the Marketplace settings:

Now, Let's Create an Integration

In Productive, as well as in many other applications, there is a list of applications called the marketplace. In the marketplace, customers choose the integration they want to use. When the integration is selected, the connection process begins by clicking the “Connect app” button. The connection flow will be demonstrated using the example of Xero.

1. Creating and Connecting An Integration

When establishing an integration, it’s generated in the system. However, to ensure its successful creation, it must align with the authentication requirements on the backend. All integrations require a redirect URI. This URI is used to redirect to Productive after connecting the integration to adjust the settings of each integration. After generating the URI, the integration creation process begins.

If the organization has branches or subsidiaries, you’ll first need to select the subsidiary (branch) for which you want to use Xero.

When creating an integration on the backend, authentication verification is performed, and if all requirements are met, the integration process begins.

During the integration connection, the customer is directed to the interface of the system they want to integrate with, where they also need to provide information to verify if the user is existing and valid. Once completed, the process returns to the marketplace via the redirect URI, initiating the setup of the integration.

2. Redirect

After the customer is redirected to Productive, the data obtained from the external tool is set on the integration model. For example, Xero requires that there is always a code and org representing the code and organization to which the integration connects and exports data in Xero.

Once the integration model has been updated, a call to the backend occurs again to update the integration with new data.

After updating the model, if there are no errors, we set the parameters of the model to transition to the integration setup route, i.e., editing the integration settings.

Conclusion

With successful authentication and integration connection, we’re finishing the first part of the integration posts series. As described in this blog post, understanding OAuth 2.0 becomes not just a necessity but a powerful tool to enhance user experience, safeguard sensitive information, and foster a more trustworthy digital ecosystem. After successful authentication, due to settings related to the external system redirect, in this case, Xero, it brings us back to Productive to continue with further integration setup.

Before we end this blog post, I want to emphasize that the backend part was written by my colleague @bartic.

In our next post, we’ll break down data mapping and show you why it’s a must-know for smooth integrations. Don’t miss out!