- Home /
- Working in m3ter - User Guides /
- Integrations /
- Setting Up and Managing Native and Notification Integrations
Creating and Managing External Mappings
When you integrate your 3rd-party systems with the m3ter platform, 3rd-party entities and fields are mapped to m3ter entities and fields. External Mappings are created and act as mapping reference lookups for which objects and fields have been mapped across two or more systems. You can review these mapping references on the External Mappings page under Integrations where they are listed.
When you are working to set up your Integrations and want to test or troubleshoot your implementation before going live, you might need to create External Mappings manually and, at a later date, edit or delete them. You can also create bulk mappings for specific mapping types.
This topic explains how to create and manage the External Mapping needed for the integrations with external systems you've set up for your Organization:
Tip: Reviewing External Mappings for Entities? On the Details pages for m3ter entities, any External Mappings created for an entity are listed on the Entity metadata panel. You can then create External Mappings for the entity directly from there. For an example of how to do this, see Creating and Managing External Mappings for Accounts.
Creating Single External Mappings
From the External Mappings page, you can create a single mapping of a specific mapping type:
To create a single External Mapping:
1. Select Integrations>External mappings. The External mappings page opens and lists the mappings in your Organization by M3TER ENTITY TYPE.
2. Select Create External mapping. To create a mapping, you must complete a two-stage workflow and the Create page opens ready for you to complete Stage 1.
Stage 1 - Select mapping type:
3. Enter External mapping settings:
Use the m3ter entity type drop-down to select the m3ter entity type you want to use to create the mapping type.
Use the External system drop-down to select the 3rd-party system referenced.
Use the External table drop-down to select the table in the selected 3rd-party system that you want to use for the mapping type:
In this example, we've chosen to create an Account <> Contact mapping for m3ter <> Xero.
Tip: External systems listed? Note that you can configure mappings for any of the integrations with 3rd-party systems set up for your m3ter Organization. This includes any custom integrations as well as native integrations.
4. When you've completed the mapping type set up, select Next. The page adjusts to allow you to complete Stage 2:
Stage 2 - Add mapping IDs:
The m3ter entity type, External System, and External table you configured for Stage 1 are shown.
5. On External mappings details:
Use the m3ter entity drop-down to enter the specific m3ter entity of the type you've selected in Stage 1 - in this example the m3ter Account - you want to create the mapping for.
Tip: m3ter entity field is a drop-down selection field?
Depending on the m3ter entity type you are creating the mapping for, the m3ter entity field might show as a drop-down selection field - for example if you are mapping Account entities. In this kind of case, you can select the m3ter entity by Name/Code. Note that the list of m3ter entities available for selection will be filtered to show only those entities of that type for which a mapping of the selected type has not yet been created.
If the m3ter entity field does not show as a drop-down selection, such as when you are creating a mapping for m3ter Bill Line Items, then you can enter the entity's ID.
In the External entity ID field, enter the ID of the 3rd-party system entity you want to map to.
Tip: Possibles values might show! Note that if the possible values for the External entity ID field can be fetched for the External system, then you can use a drop-down list to select the value for this field from the list of possible values returned.
6. Use the Parent integration field to select which of the Integration Configurations you've set up for the destination 3rd-party system will take precedence for the mapping you are setting up. Note that you must select an Integration Configuration you've set up for the same destination as you're creating the External Mapping for - in this example Xero. If you select an Integration Destination you've set up for a different destination, you'll receive an error when you try to create the mapping:
Tip: Multiple Integration Configurations for a single External system. Note that in this example, we have two Integration Configurations set up for sending Bills outbound to Xero. For example, you might have your Xero system set up for two invoicing locations for your end-customers - UK and Europe. Using the Parent integration setting, you can ensure any mappings that you configure for Xero Integration 1 are only made for Bills outbound to your Xero UK invoicing instance and any set up for Xero Integration 2 are only made for Bills outbound to your Xero Europe invoicing instance.
7. Select Create External mapping. The Create page closes and the new External Mapping is shown on the External mappings page. For example:
Note that if you open the Details page for the m3ter entity - in this example the Customer 1 Account - the External Mapping will be listed under Account metadata:
Creating Bulk External Mappings
From the External mappings page, you can create mappings in bulk for a specific mapping type:
To create External Mappings in bulk:
1. Select Integrations>External mappings. The External mappings page opens.
2. Select the three-dot menu button at top-right of the page and then select Create in bulk:
To create mappings in bulk, you must complete a two-stage workflow and the Create in bulk page opens ready for you to complete Stage 1.
Stage 1 - Select mapping type:
3. Enter External mapping settings:
Use the m3ter entity type drop-down to select the m3ter entity type you want to use to create the mapping type.
Use the External system drop-down to select the 3rd-party system referenced.
Use the External table drop-down to select the table in the selected 3rd-party system that you want to use for the mapping type:
In this example, we've chosen to create Account <> Subscription mappings in bulk for m3ter <> Chargebee.
4. When you've completed the mapping type set up, select Next. The page adjusts to allow you to complete Stage 2:
Stage 2 - Add mapping IDs:
The m3ter entity type, External system, and External table you configured for Stage 1 are shown.
5. On the External mappings panel, select Add. The page adjusts to add a row for the first mapping:
Use the m3ter entity drop-down to select the specific entity in your Organization you want to create the mapping for.
Tip: Selection is filtered! Note that the list of m3ter entities available for selection will be filtered to show only those entities of that type - here Accounts - for which a mapping of the selected type has not yet been created.
In the External entity ID field, enter the id of the 3rd-party system entity you want to map to.
Tip: Possibles values might show! Note that if the possible values for the External entity ID field can be fetched for the External system, then you can use a drop-down list to select the value for this field from the list of possible values returned.
Use the Parent integration drop-down to select which of the Integration Configurations you've set up for the destination 3rd-party system will take precedence for the mapping you are setting up.
Note that for each mapping you must select an Integration Configuration you've set up for the same destination as you're creating the bulk mappings for. If you select an Integration Destination you've set up for a different destination, you'll receive an error when you try to create the bulk mappings.
6. Select Add again and repeat up to a maximum of 20 mappings of the selected type:
In this example, we've added four mappings of the selected Account <> Subscription mapping type for m3ter <> Chargebee.
7. Select Create External mappings. You are returned to the External Mappings page where the bulk mappings of the selected type are now listed:
Managing External Mappings
From the External Mappings page you can manage you Organization's mappings and edit or delete them:
To manage External Mappings:
1. Select Integrations>External mappings. The External mappings page opens.
2. If you want to edit a mapping, select Edit:
3. On the Edit page, make your changes and select Update External mapping.
4. If you want to delete a single mapping, select Delete:
A confirmation pop-up appears. Select Yes to complete the delete action.
5. If you want to delete multiple mappings, check those you want to delete and click Delete selected:
Additional Support
Login to the Support portal for additional help and to send questions to our Support team.