User Documentation for File-Based Integrations

Introduction

If your accounting system does not offer an API, Martus supports a File-Based Integration, with features listed below.

• Client-specific accounts and dimensions are defined in Martus, allowing you to take advantage of all Martus features for creating and maintaining budgets, and all Martus features for reporting budget vs actuals.
• Account Mappings are set up and maintained in Martus.  
  • For systems that do not have a natural chart of accounts, and for systems with segmented account numbers that assign specific accounts to specific dimensions, this mapping translates your accounting system’s chart of accounts to Martus accounts and dimensions. Additionally, this supports reverse mapping - automatically assigning the accounting system account number to each budgeted item in Martus.
  • Account Mappings may be automatically updated during a transaction file sync, depending on the consistency of the accounting structure. Otherwise, adding/editing account mappings is done in Martus or via an Excel template.
• Monthly GL transactions files are periodically imported into Martus from your accounting system. As part of implementation, Martus will define a mapping for the GL transaction file so that you can use a standard output from your accounting system for these updates.
• The Fund Balances Report feature of Martus is available, and requires periodically importing a trial balance for restricted and designated fund balances. As part of implementation, Martus will define a mapping for the trial balance report file so that you can use a standard output from your accounting system for these updates.
• Martus provides the standard capability to export budgets. For some accounting systems (Shelby Next, Sage 100, and Sage 300), Martus also provides a custom export in a format suitable for import directly into your accounting system.
• Multi-currency is supported.
  
  

Examples of file-based integrations that Martus integrated with:

• ACS Financials
• ACS Realm
• Aplos
• Fund EZ
• Great Plains
• MIP
• ShelbyNext
• Shelby v5
• Sage 100
• Sage 300

The Martus EZ Connector - Uploading and Syncing GL Transactions into Martus

The EZ Connector is used with file-based Integrations to automate the process of loading transaction files into Martus. The EZ Connector is a Martus application that is installed in a location of the customer’s choice on the customer network; this is the location where transaction files from the customer’s account system will be placed. In most cases, the customer’s IT team will be responsible for setting up the Martus EZ connector using the document found here. 

• To keep Martus’ accounting data current, you’ll periodically need to extract transactions from your accounting system and import them into Martus. 
  • There must be a separate transaction file for each month, and that file must contain all the transactions for that month. 
  • If importing activity for the current month, be sure to include all transactions to date in that month. 
  • The upload process will use the data in the file to replace 100% of the data in Martus for each month synced.
    
    

Requirements for the Format of the Transaction File  

• The transaction file must be saved as an 'xlsx' Excel file.
• The transaction file must be saved with the name in this format:
  • Transactions_yyyy_mm optional text.xlsx

• Any optional text is ignored by Martus and must come after yyyy_mm. Martus will allow both of these names:
  • Transactions_2024_09.xlsx
  • Transactions_2024_09 My Organization.xlsx
    

• The headers and data within this file must be in the format agreed upon at the time of implementation of your integration. Generally, this file must contain a single sheet with columns for GL account, date, amount (either one column with positives and negatives or in separate columns for debit and credit amounts), and a memo/description. This file can also include vendor information. 
• For clients with a natural chart of accounts, and for clients who use a segmented account number but also use additional dimensions such as project, this transaction file must also include columns with the appropriate dimension values for each transaction.  
• There must be a header line that identifies the data in each column; at the time of implementation, the column headers are mapped to the appropriate data within Martus.  
• There may be additional headings, report titles, blank lines, total lines, and subtotal lines.

The transaction upload and import process will not work properly if you change the headers within this file or format the amounts differently than agreed during the implementation. 

If changes are needed for the transaction file format, please contact Martus Support. There may be a charge for implementing those changes within Martus.

How to Import Transaction Files into Martus 

Navigate to Dashboard > Updater to upload and sync properly-formatted GL transaction files into Martus. 

1. Navigate to Dashboard > Updater.
2. In the Upload Files section, click Choose Files to browse for your transaction file and click Upload. You can select one or more files to be uploaded at the same time. The upload processes those files and starts the sync for those files.
   
   

3. You’ll see the process running in the Updater Task Queue section. The completed jobs will show the status of Success.

4. After you’ve uploaded files, they are listed in the Archived Files section.

If there are errors that indicate that accounts or dimension values in the transaction file are missing from Martus, add those to Martus. Then, return to Dashboard > Updater, enter the month or months to be reprocessed in the Actuals section, and click Sync Monthly Actuals. The previously uploaded file(s) for the selected month(s) will be reprocessed.

Files that were uploaded but could not be processed successfully are shown in Incoming Files. Files that have been successfully uploaded are listed in Archived Files.

Uploading and Syncing Designated Fund Information into Martus

If you are using the Fund Balances Report feature of Martus, you will periodically need to extract a trial balance from your accounting system and import this information into Martus. The file must be saved as an Excel file and be named: 

• Designated_yyyy_mm.xlsx or
• Designated_yyyy_mm optional text.xlsx

The headers and data within this file must be in the format agreed upon at the time of implementation of your integration. The file can contain an additional header. Examples below illustrate trial balance files from ShelbyNext and ACS Realm.

Sample from ShelbyNext Financials

Sample from ACS Realm

Notes about the Upload and Sync Process

Upload and sync transaction files and designated funds files as often as needed. If you make changes to transaction data in your accounting system (reclass an expense, change a transaction’s description, or add activity in a prior month, etc.), you will need to generate a new transaction file from your accounting system for that month and upload it into Martus to ensure the accuracy of the data.

Errors in the Sync Process

Errors are generally related to the file name, the file format, or missing account mappings. For assistance, please create a ticket through the Knowledge Base if you are a direct Martus customer, or contact your Martus reseller if you are supported through one of our Martus partners.  

Account and Dimension Maintenance

As part of implementation, Martus works with you to map your Chart of Accounts to identify natural accounts and determine the dimension structure that will support your reporting and budgeting needs. If your accounting system has a segmented account, the account mapping within Martus will determine how those segments are mapped to the Martus account and dimension values. When the implementation is completed, Martus will mirror your COA and dimension structure. Account mappings are then updated in Setup > Account Mappings directly or through an export/import process.

Defining Parent-Child Hierarchy within Dimensions

Martus allows you to define parent-child hierarchies within dimension values – even though those are not defined within your accounting system. For example, you may have several departments that you’d like to roll up into a parent department for reporting purposes. You can even create dimension values that don’t exist in your account system so that you can use them as parent dimension values within Martus.

How Account Mapping Works

Account Mapping is the Martus tool that relates the account numbers in your accounting system to Martus’ account numbers and dimensions. Navigate to Setup > Account Mappings to maintain account mappings.

Account Mapping is used in all file-based Integrations with accounting systems that have a segmented account number. It is not usually used if your accounting system has a natural chart of accounts. 

The Account Mapping screen is used to add new mappings and change existing mappings.  

• You can export existing mappings, make updates, save, and then import the file back into Martus.
• Use the Search box to find all mappings that contain specific text.
• Use the filters to limit the list by natural account or any of your dimensions.
• One of the key features of account mapping is the Account dimension.  All of your accounting system account numbers must be defined as values for that dimension. Each accounting system account number can only be assigned to a single account mapping; in other words, it can only be mapped one way.  
• Click Add Mapping to add new mappings. If you want to add a mapping manually, you must first add any new account and dimension values that will be used.
• When you add mappings via the file export/import method, be sure to add all necessary dimension and account values for the new mappings before importing the updated mapping file.
  
  

How to Add or Edit an Account Mapping

Navigate to Setup > Account Mapping to create or edit an account mapping.  The example below is for illustration only - your system’s configuration will determine the specific fields and field names. 

• External ID  – The External ID is usually the account number from your accounting system. This field has a maximum of 25 characters, so if the accounting system’s number is longer than 25 characters, you’ll need to truncate it to fit in this field.
• External Type – The account type. When adding a mapping, select this from the dropdown.
• Natural Account - The Martus account number.  When adding a mapping, select this from the dropdown.
• Dimensions – The dimensions (location, department, etc.) are represented by the accounting system’s account number. When adding a mapping, select these from the dropdown.
• [xxxx] Account – The accounting system account number for this mapping (from the Account dimension). When adding a mapping, select this from the dropdown.

Budgeting Considerations for File-Based Integrations

As part of the implementation, Martus will provide you with instructions to import your current budget into Martus. You will map your current budget into the new account number/dimensional format in the standard Martus budget import file and then import it into Martus.

If your accounting system has a segmented account number, your Martus instance is configured to limit the accounts that can be used on a budget worksheet to those valid for the dimensions of the budget worksheet.  Additionally, your Martus instance will typically be configured with what we call “reverse mapping”. With this, you will have a line item dimension that contains your accounting system account number, and the budgeting functions of Martus (the budget worksheet and SPWs) will automatically assign the appropriate accounting system account number to each budget item.

Exporting Your Budget from Martus

Budgets can be exported from Planner > Planner Setup > Budget Management, then be reformatted as necessary for import into your accounting system. Martus provides custom budget exports for ShelbyNext, Sage 100, and Sage 300. 

Notes:

• The updated budget file has the same name as the selected template file.
• The file is updated according to the Shelby fund and department on each Shelby account within the template file, even if that Shelby account is assigned to a different department in Martus.
• If there are any budget values already in the template for accounts that are not budgeted in Martus, they are not updated by this process.
• If there are any accounts budgeted in Martus that do not exist in the Shelby template, they are not added to the budget template file.

Provider Reporting Periods - Updating the Financial Calendar Tab

Users may manually type in their calendar dates based on the structure they would like to follow. These are the guidelines:

• Start/End Dates must honor the day of the week indicated in Setup > Calendar> Last Closed Month tab > Fiscal Year. This means Martus cannot support starting every year on July 1st no matter the day or ending on Dec 31 no longer the day. 
• Start Date will auto populate based on the ending day of the year prior. 
• Ending Date will auto populate based on the start day of the year following.
• Deleting a calendar will allow the year to be added.

File Based Transaction Uploads - Video Tutorial

With a file-based integration, GL transaction detail must be manually uploaded into Martus to support financial and budget-to-actuals reporting.  

You must title your transaction file Transactions_yyyy_mm and must be saved as an '.xlsx' file type in order to upload them into Martus successfully.

This tutorial also provides a special Excel tip for those Martus customers whose accounting system cannot provide a transaction file that has a date on each line.  With just a few clicks, you can ensure that each line is formatted appropriately for import!

Note:

• If a transaction date does not match the calendar month when loading the transaction file, Martus will append the actual transaction date to the beginning of the memo field.

Martus EZ Connector - Setup Instructions (IT Team)

The EZ Connector is used with File-Based Integrations to automate the process of loading transaction files into Martus. The EZ Connector is a Martus application that is installed in a location of the customer’s choice on the customer network; this is the location where transaction files from the customer’s account system will be placed. In most cases, the customer’s IT team will be responsible for setting up the Martus EZ connector, following the instructions below. 

Before reading this document, you should be familiar with File-Based Integrations. Refer to File-Based Integrations - User Documentation for more information.

Martus Instance Configuration 

The Martus implementation consultant will provision the Martus instance. This will include adding admin users to Martus. It’s typically best to have the person who will be installing the Martus EZ Connector (IT) temporarily set as an Admin so they can download the files needed on their computer. Once installed, those Admin privileges can be revoked. Martus Admin User An Admin will need to login to Martus, and generate the API token for the files to be uploaded via automation: 

1. Admin Login to Martus 
2. Dashboard > Updater 
3. Under File Upload API > Click Generate Token
   

Once that Token is generated, the Endpoint, API Token, and Curl Example will populate for the end users to supply to their IT department in order to script the automation. (shown below)

Download and Install EZConnector 

We recommend that the IT person who will be installing the Martus EZ Connector (IT) be added as a user in Martus and temporarily set as an Admin so they can download the files needed in the appropriate location and access the files needed. 

1. IT Admin user logs ino Martus 
2. Dashboard > Updater 
3. Click Martus EZ Connector Installer
    
4. Once the file downloads, click the file once to install EZ Connector 
5. Select Windows Service when prompted
    
6. Save in the desired location
   
7. In Martus, download MEC File
   
8. Save a transaction file in the same location where the Martus.Connector file was created
    

Launch Martus EZConnector – Add Connection String to Make Connection 

The company will now appear on the Martus Connector, but you will need to add the Connection String to make the connection. 

1. Open the Martus EZConnector 
2. Click checkbox under Auto Run
   

Confirm New Folders Have Been Created 

Once EZConnector recognizes the connection, new folders will be automatically created to be used in the automation. 

1. In the Martus.Connector folder confirm new folder has been created (environment - client number). In this example the Environment is QA and the Client is 1634.
   
2. Open folder and confirm appropriate subfolders have been created 
   • Archive 
   • Incoming 
   • Invalid
     
3. Files can now be placed in this folder and automation can begin! 

Test Connection 

Test the automation. Upload a file into Incoming and watch what happens in Martus! 

1. Place file(s) in the Incoming folder
    
2. To test automation - wait 60 seconds. Files will disappear from the Incoming folder and will appear in the Archived folder.
   
3. Review Martus Updater Screen (Success!)