Xero Integration

Learn how to Integrate with Xero within Maica

How do I integrate with Xero within Maica?

To learn how to configure the Xero integration in Maica, please follow the steps detailed below.

Please note that whilst completing the integration within Maica, there are further pointers and steps to assist you. This article breaks these steps down further and into more detail, hence the step numbers seen here and within Maica may vary.

To begin configuring your Xero Integration, go to the Maica Settings tab in the Menu bar. When there, select the Xero Management tab to see the following.

Here, we can see the Active Connections and Webhooks sections. To complete the Xero Integration, we must first set up both of these areas.

Before proceeding, make sure that the Xero Management toggle in the top right corner of your interface is set to Enabled, as shown below.

Active Connections

1. Begin Adding a New Xero Connection

The first section to complete is the Active Connections section. You can now begin to do so by adding a new Xero Connection by simply clicking the + Add New Xero Connection button within the Active Connections section, as shown below.

Once clicked, the following Xero OAuth Connection Setup pop-up will be displayed.

For privacy reasons, the Company or Application URL and Redirect URI have been obscured; however, they will be visible and pre-populated in your organisation.

2. Create a custom Web App

Using the links above, you can now create a custom Xero Web App. To do so, follow the link shown in the above image (or here: developer.xero.com). Once on the link, you will be presented with the following screen:

Here, you can add a Custom Name for you App, and then copy and paste the Company or Application URL and Redirect URI from Maica into the related input fields on Xero. Once done, check the Terms & Conditions box and click Create App.

Make sure your Integration Type is set to Web App. It should be selected by default.

3. Import Web App Identification Codes

Once you have created your Web App, head to the Configuration tab on the left hand side of Xero interface. There, you will see the following:

Click Generate a secret, and then copy both the Client ID and Client Secret back into the relevant fields within Maica. These fields are shown in Xero OAuth Connection Window screenshot in Step 1 of this article.

4. Confirm Redirect URI configuration

Before proceeding any further, confirm the Redirect URI shown in Maica matches that of the Redirect URI on the Configuration page within Xero (the above page). If they do, it has been configured correctly and you can proceed to the next step, if not, copy the Redirect URI from Maica and paste it into the field in Xero.

Once you have completed Steps 1, 2 and 3, click the Save button in the bottom right hand corner of the interface. This will trigger the creation of a Manage Xero Permission Set and create Named Credential Records required to finish the remaining set up steps of the Integration. Once saved, the Xero OAuth Connection Setup module on Maica will dynamically update, displaying the final remaining stages. Simply reopen it after saving to view these steps.

5. Actions to the Named Credential Record

As mentioned above, when creating a connection with Xero, Maica will create an associated Credential Record.

To learn about Credential Records in Salesforce, click here.

Two actions are required on the Credential Record, these include:

1. Enable for Callouts toggle = TRUE

2. maica_cc to be added as a value to the Allowed Namespaces for Callouts field

To complete the above actions, first click the hyperlink to the Named Credential record in the Xero OAuth Connection Setup pop-up.

This will open up the Named Credential record where the specified actions can be completed, as shown below.

Note, The Created By Namespace field shows which managed package a component belongs to. This field is automatically populated by Salesforce and reflects Maica’s managed package namespace (maica_cc). It does not require any action.

Once done, click Save and move onto the next step.

6. Assign Users to the Created Permission Set

As also mentioned above, when creating a connection with Xero, Maica creates a Permission Set. Maica will automatically assign it to the current user, however you can assign all necessary users you desire to access the Xero Connection.

To begin, click the hyperlink to the Permission Set in the Xero OAuth Connection Setup pop-up, as shown below.

This will open up the Permission Set. Once open, click the Manage Assignments button in the menu in order to add additional users to the Set, as shown below.

Then, click the Add Assignments button in the top right hand corner of your interface, and select the checkbox for all Users you wish to assign the Permission Set to. Once done, click Next.

After clicking the Next button, Maica will take you to a summary screen of your selected Users where you can set an expiration option if desired. This allows for the ability to set a date in which the Permission to the specified Users will expire, as shown below.

By default, Permission Set assignments never expire.

To finalise your assignments, click the Assign button in the bottom right hand corner of your interface. Once done, an Assignment Summary page will show with a Success Status by each Assigned User.

7. Authenticate

Once completed, you can click the Authenticate button to finalise the Connection.

If Step 5 or Step 6 are not available in the Xero OAuth Connection Setup, you may need Authenticate prior to completing them. If so, simply navigate back to the Xero Management Settings and complete these steps after Authenticating. Do not Authenticate again in this instance, once the steps are done, simply close the window.

Webhooks

1. Add a Notifications Endpoint (Site)

The second section to complete is the Webhooks section. You can now begin to do so by first populating the Site field with your configured Site.

To learn how to configure a Site, click here.

Please make sure the associated Guest User of the selected Site has Handle Xero Notifications permission set assigned.

2. Link to Xero

Once you have selected your Site, Maica will generate a URL that will be used to connect back with Xero. Copy the URL from Maica and open your previously created Xero Web App. On the side menu bar of the Web App, navigate to the Webhooks section and paste the URL in the Delivery URL field, as shown below.

Maica is only connected to the Invoices webhook, so ensure that this is the only option ticked from the Notify this app about changes to options.

3. Return Webhooks Key to Maica

Finally, from Xero, copy the Webhooks Key shown under the the Delivery URL and paste back into the Webhooks Key field in Maica, as shown below:

Test the Status in Xero to ensure that the process has been completed and is configured properly, then click Save within Maica to begin receiving Invoice Notifications.

Once you have finished setting up the Connection and Webhook, it is essential that you configure your Support Items in order to facilitate the integration. The integration will fail if the associated Support Items are not also configured. Please see the linked article to learn how to do this.

How do I removed my Xero Connection and establish a new one?

In order to establish a completely new Xero connection within Maica, you first must remove the following:

1. The Named Credential

2. The External Credential

3. The Xero Authentication Provider record

To do so, re click the + Add New Xero Connection button in the Active Connections section, and follow the hyperlinks within Maica, as shown below.

When you click on each link, the corresponding record will open. Simply delete the record and repeat the process for all three before attempting to establish a Xero new connection.