m3terDocumentation

On this page

Configuring Xero Integrations

You can define and manage native integrations for sending your end customer Account Bills generated in m3ter outbound into your Xero system:

Note: Xero Integration in Beta Release! Please note that the Xero native integration is currently in beta release. If you intend to implement this integration for your m3ter Organization, please contact m3ter Support or your m3ter contact person to discuss. See section 7. of our Terms of Service for Beta Usage

Creating the Integration

To create and configure a native Xero integration, you can follow a three-stage workflow:

  • Stage 1. Select the Entity Type that the integration is for. Currently, only native integrations for Bills are supported.

  • Stage 2. Select the external system that is the destination for the integration.

  • Stage 3. Configure the details required for the selected integration destination and create the integration.

Tip: Reviewing Integration Runs! When you've set up an integration with Xero for your Organization in your production environment, you can review details of the integration runs performed for the integration. See Reviewing Integration Run Details.

To define a m3ter - Xero integration:

1. Select Integration>Configurations. The Integrations Configurations page opens.

2. Select Create Integration. The Create page opens at Stage 1: Select entity type.

3. On the Entity Type Settings panel,use the Entity Type drop-down to select the entity type you want to create the integration for:

  • Currently, only Bill is available for selection.

4. Select Next. The page adjusts to show Stage 1 as checked and completed and shifts your focus to Stage 2: Select destination.

5. On the Destination Settings panel, use the Destination drop-down to select Xero.

6. Select Next. The page adjusts to show Stage 2 as checked and completed and shifts focus to Stage 3: Configure and create. The Entity Type and Integration Destination you've selected are shown.

7. On the Global Configuration panel, select the Accounts you want the integration to apply to:

  • Account Ids. Select the Accounts you want to include - all selected Accounts are treated as allowed for the integration.

  • Restricted Account Ids. Select the Accounts you want to exclude - all selected Accounts are treated as disallowed for the integration.

Notes:

  • If you want to include all Accounts in the integration, leave both Accounts Ids and Restricted Account Ids empty.

  • Any filtering by Account Ids you define using these settings to control which Accounts the integration runs for will be in addition to any filtering you define using the Account Filter option - see the following step for Entity Configuration options.

8. Use the Entity Configuration panel to configure the m3ter entity you will be synchronizing with for the integration. In the case of an outbound Bill integration, this entity will be the Bill generated for a customer Account in m3ter:

  • Only Send Bill On Approval. Enable this if you only want Bills to be sent when they have been approved. If disabled, the Bill will be sent every time it is regenerated. Default is disabled. Note that:

    • The frequency of Bills sent will depend on the billing frequency defined for the Account Plan attached to the Account - such as daily/weekly/monthly/annually.

    • If an Account has a Prepayment on it and the billing for Prepayment fees is configured to run on a customized schedule, Bills will be sent when scheduled Bills are generated.

    • If a Bill is manually recalculated the updated Bill will be sent.

    • If you enable this, then the integration will not run for all Bill Jobs.

  • Use External Mapping Account Code. Enable this if you want the integration to look in the External Mappings for the Account identifier code, which means you can use an external Id. If this is disabled, the m3ter Account Id is used. Default is disabled.

  • Excluded Line Item Types. Optionally, filter the Bill line items you send to the destination system. For example, only send charges or credits and exclude all other line items.

  • Sort Line Items By. Optionally, select a property to sort line items by before they are sent out to the external system. Three options:

    • None

    • Subtotal

    • Aggregation ID

  • Account Filter. Optionally, enter an expression that is run on the Account to determine whether or not the integration is run. You can use this setting if you have multiple destinations for sending Bills outbound to your Xero system. For example:

    • customFields != null AND customFields.country = = UK

    • In this example, the integration will run for an Account only if you have created a Custom Field for the Account called country and given the field a value of UK.

Notes:

  • Other Account Fields for Account Filter Expression? You can reference other fields on the Account object in the Account Filter expression. For details and another example, see Managing Multiple Third Party Destinations for Integrations.

  • Additional filtering? Any global filtering you define using the settings to include/exclude Accounts for integration runs by Account Ids will be in addition to any filtering you define using the Account Filter option - see the previous step for Global Configuration.

9. Use the Destination Configuration panel to enter the settings specific to the destination system:

  • Split Usage Line Items. This setting determines how m3ter will create usage invoice items in Xero. Xero items can be mapped to an individual usage pricing band or to a product:

    • Item per usage band.

    • Item per product.

10. Select Create Integration. You are taken to the Integration Details page for the Bill - Xero integration, where you can immediately complete the configuration by setting up authentication to allow the integration to connect with your Xero system - see the following Setting Up Authentication section for details:

  • Note that if you are not ready to continue your workflow immediately and set up authentication, you can do this at a later time.

Setting Up Authentication for the Integration

When you've created a Xero integration, you can select an Integration Credential you've created for authentication allowing the integration to connect with your Xero system:

  • Note that if you've followed the workflow given in the earlier section for creating the integration, on creation you'll be taken directly to the Integration Details page to continue and immediately set up authentication. The procedure described in this section assumes you've returned at a later date to set up authentication for the integration - the main steps you need to follow if you're setting up authentication immediately after creation are the same.

To set up authentication for your m3ter - Xero integration:

1. Select Integration>Configurations. The Integrations Configurations page opens.

2. Select the ENTITY TYPE hotlink text of the Xero integration you want to set up authentication for. The Integration Details page opens:

  • Notes:

    • A warning is shown that the integration is not yet connected to your Xero system.

    • The ID of the integration configuration is shown at the bottom of the Details card, and you can copy the ID directly to your clipboard.

3. Select Add Credential. A Select One Integration Credential modal appears.

4. Select a Credential you created earlier and want to use to authenticate the integration with Xero. See Creating Xero Integration Credentials.

5. Select Confirm. The modal closes and on Integrations Details the integration now shows as CONNECTED:

  • If at any time you want to disconnect the integration, select Disconnect.

  • If you want to use a different Credential for connecting the integration, select Update Credential. The Select One Integration Credential modal appears and you can select a different Credential.

Tip: Testing your Native Integration Setup? Your Xero integration is now available for use. However, it remains in Beta release and we strongly recommend you test the implementation in your m3ter Sandbox or QA environment before releasing it to your Production environment. See section 7. of our Terms of Service for Beta Usage.

Tip: Integrations API Calls? When you have set up your Xero integration, you can review and manage the integration using a full set of API Calls. See the Integrations section of our API Reference Docs.

Next: Managing Multiple Third Party Destinations for Integrations


Additional Support

Login to the Support portal for additional help and to send questions to our Support team.