Intacct Plugin Estimated Reading Time: 16 Minutes Ubersmith Intacct Plugin Usage Installation When enabled for your Ubersmith installation, the plugin will appear in the Ubersmith plugin list (Settings -> Plugins). Enabling the plugin The plugin can only be enabled in one brand. The chosen brand will be the one you will use to access the plugin home page The plugin will be able to work on other brands, it just does not require to be installed in each of them. Brand specific configurations are made within the plugin. Ubersmith Plugin: Global Config Once the plugin is enabled, you will need to configure each module that the plugin requires access to work. Modules are a concept from the Ubersmith Plugin system. They control what information the plugin is allowed to be received from Ubersmith hooks(events). Brand Access You must at least give access to the brand you are installing the plugin in. Optionally, you can give access to more brands you wish to export in Sage Intacct. Intacct Exporter In this module, you must select the Ubersmith SDK Exporter you wish to use. In this case, you only have one option since the plugin defines only one exporter that connects to Sage Intacct. Configuration [!IMPORTANT] Updating existing credentials will not automatically reset the current authorized session the plugin may have with your Sage Intacct company. It is important to reset it manually after updating them. See Update Credentials for more details. You need to enter the Sage Intacct API credentials. As described in the requirements, you will need your Sage Intacct Web Service credentials and Web Service User. Sender ID Sender Password The Sender ID must be given access to your Sage Intacct company you want to connect to. Sage Intacct Company ID Then, you need to provide the Web Service User credentials. This is a special user that only has API access to your Sage Intacct Company and operations will be executed under its identity. Web Service User ID Web Service User Password Service Plan Access [!NOTE] Only applicable to Contract Module Integration It is recommended to select Apply to all. That way, any new service plans will be automatically accessible by the plugin. While technically, access to service plan can be granted individually to the plugin, you will need to remember to come here and grant access to new service plans if you need to export them. Order Queue Access [!NOTE] Only applicable to Contract Module Integration Select the order queue(s) that you wish to add the plugin's order action into. Once granted access, you can go to the selected order queue in Ubersmith and configure a new action using the plugin. Configuring the plugin for Export. Once all the modules have been given the desired access, you can go on the plugin home page by clicking Go to Plugin Home button, at the top of the page. Plugin Home Page This is an overview of each tabs within the Plugin Home Page. Connection Setup Export Logs Reporting Manual Contract Cancellation (Contract Integration Only) Mapping Connection If the API credentials are correct, the tab will display the current Intacct company the plugin is connected to and the username in used. Update Credentials [!IMPORTANT] When the credentials are updated, resetting the API token is strongly recommended. This is currently not done automatically by the plugin. When you update the Sage Intacct credentials From the global plugin configuration, for them to take effect immediately, you need to reset the connection already established to Intacct by clicking the Reset API Token button. Otherwise, the old API token will still be used until it expires. This is particularly important if you change the company id. If you don't reset the API token, the plugin will remain connected to the old company until the token expired by itself. Setup The setup is where most of the plugin configuration is done. The setup must be completed before the plugin can export any data to Intacct. Step: Integration Method This is where you select the integration method. The plugin will switch "mode" immediately when the selection is modified. The available tabs and the setup steps will change accordingly. Step Intacct Settings This section covers some of the settings related to Intacct. Accounts Receivable Configuration This setting should reflect how the connected Intacct company is configured. For example, if account labels are enabled in Intacct, the setting should be enabled as well. This information is used to determine if the plugin should use GL account label or number when communicating with Intacct. Depending on whether it is enabled or not, Intacct will accept one or the other, but not both. External IDs For the plugin to work, it requires to have specific custom fields created in Intacct. Those custom fields will hold unique identifiers that allows the plugin to effectively map an Ubersmith entity to an Intacct entity. IMPORTANT: The value of those fields should never be changed manually. They should be considered reserved by the plugin. Changing the values directly in Intacct will break the plugin exports. For that reason, it is recommended to hide those custom fields from the user interface. Default Integration Intacct Object Field ID Customer UBERSMITH_PLUGIN_CLIENT_ID Item UBERSMITH_PLUGIN_SERVICE_PLAN_ID Invoice UBERSMITH_PLUGIN_INVOICE_ID Contract Integration Intacct Object Field ID Customer UBERSMITH_PLUGIN_CLIENT_ID Item UBERSMITH_PLUGIN_SERVICE_PLAN_ID Contract UBERSMITH_PLUGIN_EXTERNAL_ID Contract Line UBERSMITH_PLUGIN_SERVICE_ID Ubersmith Settings Custom Payment Types (Contract Integration Only) The plugin will automatically create a custom payment type per brand. It will be used to mark invoices as paid. The default name will be Paid via Intacct but can be updated from the Ubersmith settings. If there was a problem creating the custom payment types, an error will be displayed and the a Retry Button will be available. Ubersmith Custom Fields The plugin is using custom service fields. Each custom field will be displayed here with their status if they have been created successfully or not. By clicking on the "Load/Reload" button, the plugin will create and/or update the fields as needed. In the case of a select box with options taken from Intacct, clicking the "Reload" button will pull the latest options from Intacct. Setup Brands This step will require to configure each brands individually to know how their data should be exported in Intacct. The internal steps will be different based on the selected integration method. Configuring Matching Rules Matching rules are supported for service plans and clients. They provide a way to find already existing Intacct entities that should be linked to existing Ubersmith entities. The matching rule is a simple comparison using one field from Ubersmith and one from Intacct. If both fields are equal, there is a match. You can select which field should be used from both sides, Ubersmith and Intacct for the comparison. The matching rule should be strict enough so only one entity from both systems should give a match. For example, you could have a custom field in Ubersmith holding the corresponding Intacct entity id. As a rule, you would select the Ubersmith custom field and the Intacct entity id field. To know more about how the matching rules are used during an export, see Exporting Into Existing Entities In Intacct Contract Definition (Contract Integration Only) This is an optional step. It allows creating and/or updating contract definitions in bulk by uploading a CSV file. This step is meant to be used for existing services which have a custom Reference Id already assigned. See Contract Definition CSV Import for more details. Export The export tab is where the continuous sync can be turned on or off and also schedule manual export. Export Sync This is the continuous sync. When ON, changes made in Ubersmith will be queued and process by a background export job. The exporting results are displayed per entity. The result numbers are a sum. For example, if a client failed to be exported, it will show as: Entity Success Failures Client 0 1 Then, if it succeeds afterward, the results will display: Entity Success Failures Client 1 1 It is possible to reset the results with the Reset results button so each counter restart at 0. This is useful when you acknowledge the results and are interested only on the new results going forward. Manual Exports There are three manual exports. Preliminary Export Complete Export Partial Export 1. Preliminary Export This export is meant to be used as the first one. It will export the basic entities to Intacct, which other depends on. This will export clients and service plans. It can be scheduled as many times as required until those two entities are exported as expected. When clients and service plans are in Intacct, the risk of errors when exporting on the dependent entities is much lower. 2. Complete Export As its name implies, the complete export will export everything to Intacct. A date from is required to only export financial data that occurred from that date and onwards. 3. Partial Export The partial export is used to export a subset of entities. There are two ways to schedule a partial export.The first one is by client. This means that all entities related to the client ids provided will be exported. The second way is by entity. This allows for a more granular export, where one can specify exactly which entities will be exported. The goal of this export is mostly to retry exporting that failed previously, especially those who cannot be processed in the continuous sync with an update(i.e. invoices). For that reason, there is an auto populate feature that will find errors in the logs and automatically add the related entities in the partial export id inputs. The auto populate search can be done by export type and by date range. Use case example:Let's say the plugin is already set up and the continuous sync has been ON for many months now. Ubersmith generates a batch on invoices as usual but for some reason, Intacct is unreachable and all invoices fail to be exported. In this case, the auto populate feature could be used to search for errors in the Sync export, from the date the last batch of invoices has been generated until now. This should find all the invoice ids that failed to be exported. Entities Exported By Export Type Default Integration Preliminary Complete Partial - By Client Service Plan X x Client X x x Invoice x x Account Credit x x Payment x x Refund x x Contract Integration Preliminary Complete Partial - By Client Service Plan X x Client X x x Service x x Invoice x x Logs There are two possible ways to view and search the logs. The first one is by log files. There is one log file a day. This offers a quick overview of what kind of logs were recorded for each day. When selecting a log file, the search will be limited to that day. The second way to search is by date range. This offer more powerful searching and filtering capabilities than the first option. In particular, the Filter log records by: Entity Export Status. When filtering by Entity Export Status: only the log records referring to an entity export result will be displayed. In other words, errors or infos unrelated to the result of an export action will be filtered out. This is particularly useful to narrow the logs to only see what has been exported with success or not. Reporting This is where you can configure the automatic reporting and also generate report on demande.See Reporting for more details. Manual Contract Cancellation (Contract Integration Only) This is a global list displaying all Intacct contract lines requiring a manual cancellation. Mapping This section describes how to troubleshoot and fix incorrect mappings between Ubersmith and Intacct entities.It is intended for advanced users dealing with mapping errors during export. Mapping Errors When exporting Ubersmith entities (such as Service Plans or Clients) to Intacct, the plugin tries to find the corresponding Intacct entity using either an External ID or a matching rule. If the plugin finds more than one matching Intacct entity, it skips the export and logs an error to avoid making the wrong choice. Common Causes of Mapping Errors Matching rule is too broadThis commonly occurs during initial setup. If many mapping errors appear, your matching rules may be too generic. Adjust them to use more specific fields to ensure only one match per entity. Duplicate External ID in IntacctManual edits in Intacct may lead to multiple entities having the same External ID. You’ll need to remove duplicates so that only one record retains the correct ID. Fixing Mapping Errors When mapping errors are logged, they are summarized with a count per entity type. To fix them: Go to the Mapping tab. Click the edit icon for the affected entity type. On the edit page, you can: Manually enter a Ubersmith ID to check its current mapping. Click "search" to run the matching rule and fetch potential matches from Intacct. Example: Multiple Matches Found In this example, the matching rule returned multiple Intacct entities: The current mapping is missing the linked Intacct entity. The plugin found several possible matches on the right. You can either: Click "select" on the correct Intacct entity. Or enter the correct ID manually using the "+" (plus) icon. After selecting the correct match, you'll see it appear under the current mapping. You can now: Revert all changes (note: this undoes all edits, not just the last one), or Click "continue" to return to the Mapping tab. Example: Duplicate External ID In this case, the same External ID is found on two Intacct entities: This is usually caused by manual duplication in Intacct. The plugin never creates duplicate External IDs so it can also be the result of someone entering manually a value in the External ID field on Intacct without knowing it is already linked. The left side shows the current mapping. Both Intacct items have the same External ID (UB-1244). You need to delete one of the mappings in Intacct. ⚠️ Important:Keep the mapping that was already used in past exports.For example: If Item ID: 3% Convenience Fee was created manually and not used in any exported invoices, it can be deleted. If Item ID: UB-1244 is used in existing Intacct invoices, it should be kept. Changing mappings of exported entities that are already cross-referenced in Intacct may cause issues in future exports. Once the mapping is corrected, click "continue." Back on the Mapping tab, you will see an indicator showing that mapping changes are pending.To apply them: Schedule the next export. The plugin will assign the correct External IDs in Intacct. Exports will resume as usual, using External IDs for matching going forward. Troubleshooting While primarily used for resolving mapping errors, the mapping edit page can also help verify existing mappings. For example, to find which Intacct customer a specific Ubersmith client is linked to: Go to the Mapping tab. Click the edit icon next to the Client mapping. Search for the Ubersmith client ID. The linked Intacct entity will be shown, including its External ID. Core Concepts Exporting Into Existing Entities In Intacct Exporting into existing entities in Intacct is supported for service plans and clients. To find the existing entity in Intacct, the plugin will use a matching rule. The matching rule will compare one field from the Ubersmith entity and compare it against one field from the Intacct entity. There is a match when both fields are equal. The fields to use within the matching rule is configurable. [!NOTE] If more than one match is found for a single Ubersmith entity, the plugin will not export anything. The plugin will not decide for you which one is the correct match. If that happens, this means the matching rule is not strict enough, or there are potential duplicate entries in Intacct. Once a match has been found via the matching rule, the plugin will update this Intacct entity instead of creating a new one. When the plugin update (or create) an entity in Intacct, it will create a link between this Intacct entity and the Ubersmith entity via an External Id. The form of this External Id will depend on the entity type but typically, this will translate to the plugin storing the Ubersmith entity Id into an Intacct custom field on the Intacct entity. When using the default integration, the plugin will use Intacct entity built-in unique field as Reference Id when possible. This is the case for Account credits and Payments. Once an External Id has been created on the Intacct entity, the matching rule won't be used anymore in favour of the more robust matching by External Id. In other words, this means that the matching rule will most likely be used only during the initial export, when we want to sync over existing Service Plans/Clients to existing Intacct Items/Customers. Entity Matching Flow During Export The following diagram illustrate the process of exporting an Ubersmith entity and determining if it should be created or updated in Intacct. flowchart TD flowstart([Entity Export Start]) flowend([Entity Export End]) error[Log error and skip Entity] --> flowend create[Intacct Create] --> flowend update[Intacct Update] --> flowend flowstart --> B[Intacct lookup using the External Id] B -->|Zero Match| E{Does the entity has a matching rule?} B -->|More Than One Match| error F --->|More Than One Match| error E --->|Yes| F[Intacct lookup using the matching rule] E -->|No| create F --->|Zero Match| create F --->|One Match| update B -->|One Match| update Reporting Goal The plugin can periodically generate a report of all the errors that occured since the last report. This is to give visibility to more users on problems that occurred during previous exports. Configuration The Configuration is in the Reporting tab, on the plugin home page. Automatic report Error reporting (toggle):Disabled or enabled the reporting feature. Report generation interval in days:This is the number of days between each new report generation. Example:Setting it to 2 days will generate a report every two days. Report time generation:The time of the day when the report should be generated. This will not affect the reporting range, only when the report is made. Example:04 hour 30 minute will execute the report generation at 4:30 AM. The report's range will start from where the last one stopped up to today midnight. In this example, errors that occurred between 00:00 and 04:30 would not be included in the report. Support department:The report will be sent to that support department. The ticket will contain a breakdown of the errors and the full list of errors as a CSV attachment. Manual Report You can request a report to be generated with a custom range. When you request a report generation, it will be executed in the background within ~5 minutes. The report will be available in the configured support department, the same as the automatic report.