This article will guide you through setting up Data Sync in HowNow On Premise for Xero Practice Manager or WorkflowMax.
Note that this process is the same for firms changing practice management to XPM/WFM from another system, i.e. MYOB, APS, or Handi, but does require additional steps which are outlined where necessary.
IMPORTANT:
Xero has introduced strict API request limiting. If you preview all too much you may encounter HTTP error 429, this means that you have timed out the connection with Xero. Stop setup and resume tomorrow.
What you need:
Admin access to the clients server that hosts the HowNow Database.
Access to Support Downloads.
1-2 hours of time (excluding HowNow Server setup time).
A user in the firm with the "3rd Party Full Access" permission in Xero to be available during the process.
Chrome browser installed on the client server (Internet Explorer is not supported), set as default.
TABLE OF CONTENTS
1. Check the firms Record Storage Field.
The Record Storage Field is the identifier that HowNow uses to create the backend client folders when Records are saved.
The standard fields used by HowNow are either ClientCode or EntityName however, long-term clients may have multiple fields used for storage, i.e. ClientCode and EntityName in the format of [ClientCode] - [EntityName].
To check this from HowNow, go to File > System Tools > Advanced > Record Storage Fields.
If this is set to ClientCode, confirm with the client if they will be maintaining client codes after moving to Xero.
If the client is not going to maintain client codes after moving to Xero, notify them that this will be changing to Xero's unique identifier as part of the process.
If this is set to any other value, like EntityName, continue the process.
The implications of this field are:
If ClientCode is not maintained, all records will be saved in a NULL folder, regardless of client.
If ClientCode or EntityName are changed, this will cause a duplicate folder for the client in the backend.
2. Install the HowNow Server.
If the HowNow Server service is not installed, please follow the process linked below.
Setting up HowNow Server for API Integration and/or Data Sync
3. Obtain the API key from HowNow.
If HowNow Server was already installed and the previous step wasn't necessary:
Open the HowNow Support Utility.
Input the Daily Support Code.
Run SELECT USERID, PASSCODE FROM MEMBERS WHERE ISADMINISTRATOR = 'Y' AND ISACTIVE = 'Y'
Open HowNow and input the credentials of one of the administrators.
Navigate to File > System Tools > Advanced > API Integrations.
Enable the switch for Data Sync, copy the key to a notepad.
Click OK to enable the key.
If you are prompted that the firm is not enabled for API access, you will need to apply the Account ID from CRM to the FirmID field in Options. These instructions are found in the article linked in 2. Installing HowNow Server.
4. Create the PracticeID and PracticeIDTemp fields.
In HowNow, go to File > System Tools > General > Display Field Editor.
Hold Ctrl and click the Help button.
Enter the daily support code.
Set the drop-down to Contacts.
Click Add Field.
Enter the below settings, if the setting isn't mentioned leave the setting as default.
Display Title: Practice ID
Tab through Field Name and Select Name, leave these as default
Field Size: 100
Show on Contact Other: Checked
Click Add Field once more.
Display Title: Practice ID Temp
Tab through Field Name and Select Name, leave these as default
Field Size: 100
Show on Contact Other: Checked
Click Close.
5. Install the Data Sync tool.
Confirm with the client/their IT if they are happy for Data Sync to be installed in the default directory of Program Files (x86), change the path if necessary.
Navigate to Support Downloads.
Copy the link address for Data Sync General.
Paste this into the browser on the client server.
Run the downloaded file, input the required fields.
Firm Name must match HowNow.
API Key is the one you created and copied in 3. Obtain the API key from HowNow.
DAV Server must match the DAV Server line in the HowNow.ini file. Format is [ServerName]:[Port].
This is detailed in the 2. Install HowNow Server step if you require details.Domain can be left blank, this field is not used.
Username will need to be [Domain]\[Username].
If you require a username, you can retrieve this from the Control Panel tab in HowNow Server GUI.Installation path can be updated if required, or left as default.
Ensure that HowNow Server is running as either GUI or Service.
Click finish on the installer, ensuring that Launch Data Sync is ticked.
6. Configure the Data Sync tool.
With Data Sync open, enter the daily support code.
Click Add Service.
Select either Xero Practice Manager, or WorkflowMax.
The top identifier field will need to be set to Client Code if the firm is changing to Xero from another practice management system. If this is a new setup and no contacts exist in HowNow, set this to PracticeID.
This field is used to match the clients coming in from Xero to those in HowNow.Call the contact at the firm that will be logging you in to Xero, get them connected to the server via TeamViewer or any means they have.
Click the login button, ensure this opens in Chrome, then give control to the client.
Once the client has logged in, select Allow Access. You should then be greeted with a login successful screen.
Close the browser, and request the client disconnect so that setup can continue.
Leave the lower identifier field blank, but tick the Disable Filtering by Last Update checkbox.
Click OK to return to the main view.
Click Field Mappings on the connection that was just created.
Skip to step 6.16 if no contacts exist in HowNow.Input the below fields.
HowNow: CLIENTCODE Third Party: [ClientCode]
HowNow: PRACTICEID Third Party: [UUID]
HowNow: ENTITYNAME Third Party: [Name]
Click Preview All and wait for details to populate.
Once details have populated, sort by Client Code, ensure that there are no blanks.
If there are blanks:Click in the first blank Client Code field.
Scroll to the bottom of the missing codes.
Hold Shift and click the Entity Name of the last client without a code.
Press Ctrl+C and paste this into a blank Excel sheet on your local machine.
Click OK in Data Sync, then close the tool.
In Excel, remove the UUID from the results, insert a table over the results and save the file.
Send the file to the client advising that we cannot continue setup until matching client codes are added to the listed clients in Xero. The codes input to Xero must match those in HowNow.
Disconnect from the remote session and wait for the client to advise the clients have been updated.
Once the client has confirmed that the codes have been added to Xero, reconnect to the server and repeat from step 6.13. If all client codes are present, continue to the next step.
Download the JSON file attached to this article, transfer this to the client server.
Click Load Fields in Data Sync, select the file you just transferred.
Click OK to save the fields.
Click Refresh All and wait for the Status in the bottom left corner of the Data Sync window changes back to Ready.
Check HowNow to ensure that the Practice ID has synced against a few clients, or, if no contacts existed in HowNow, that clients are now present.
If no contacts existed in HowNow previously, skip to step 6.22.Click Settings against the connection, change the identified field from ClientCode to PracticeID, click OK.
Click Settings against the connection, untick the option to Disable Filtering by Last Update, click OK.
Close the Data Sync tool.
7. Create the scheduled task.
These steps will setup the scheduled task to run the sync automatically for the firm.
Open Task Scheduler.
Create a new task, name this HowNow DataSync - Incremental.
Select Run whether user is logged on or not.
Under Triggers, click New.
Configure the settings below:
Daily, recur every 1 day.
Start today, 07:00:00.
Repeat task every 1 hour for a duration of 12 hours.
Ensure that Enabled is ticked.
Click OK.
Under Actions, click New.
Configure the settings below:
Action, Start a Program.
Browse to the install location of Data Sync, select the exe.
Add arguments: /RUNDATAREFRESH
Click OK.
Click OK and have the firm/IT input the password of the user account.
Request they stay on the phone as you require the password once more.
Create a new task, name this HowNow DataSync - Full.
Select Run whether user is logged on or not.
Under Triggers, click New.
Configure the settings below:
Daily, recur every 1 day.
Start tomorrow, 03:45:00.
Ensure that Enabled is ticked.
Click OK.
Under Actions, click New.
Configure the settings below:
Action, Start a Program.
Browse to the install location of Data Sync, select the exe.
Add arguments: /RUNDATAREFRESH /FORCE
Click OK.
Click OK and have the firm/IT input the password again.
Right-click the Incremental task, select Run.
Refresh using F5, the Last Run Result will display 0x41303, this means it is running.
Refresh again using F5, the last run result should change to 0x0 when this is complete.
0x0 is successful, 0x2 is unsuccessful.When 0x0 is shown, close Task Scheduler.
8. Removing the old sync from External Connections.
These steps will remove their existing Practice Management Sync from HowNow.
Login to HowNow as a HowNow Administrator.
Go to File > System Tools > Advanced > External Connection.
Input the daily advanced access code.
On your machine, open a blank Notepad++ or VS Code.
Select the first connection, click Next.
Note the match field used here, copy the connection string to your notepad.
Click Next.
Select the script and copy to your notepad.
Click Next twice.
Select the customisations (if any), copy to your notepad.
Click Next to return to the main External Connections screen.
Repeat steps 5-11 for any remaining connections. Note that Customisations should only be present in the first connection.
Once all connections have been copied and saved, delete all connections, then create a new connection named blank.
Close the External Connections screen.
9. Removing the Data Updater permission from users.
These steps will remove the Data Updater permission from users, thus removing the Data Refresh button for them in the Contacts tab of HowNow. This button is no longer required as the Data Sync runs automatically, and is not associated to the button in any way.
In HowNow (as administrator), go to File > System Tools > Advanced > HowNow Support Utility.
Enter the Daily Support Code.
Run SELECT * FROM MEMBERS WHERE ISDATAUPDATER = 'Y'
Go to HowNow, File > Administration > Organisation > Employees.
Reference the list of employees the script produced, select the first employee and click Edit.
Go to Privileges.
Untick Contact Data Updater and click OK.
Repeat steps 5-7 for remaining employees.
Rerun the script in Support Utility to ensure that no users remain with the Data Updater privilege.
Close Support Utility.
Close the Employees window.
Close HowNow.
Setup for Data Sync is now complete, let the client know that they have now been transitioned to syncing with Xero and that their previous connection is no longer used. Advise that the Data Refresh button has been removed as the sync is run automatically every hour, and that the button isn't connected to the Xero sync at all.
You will need to advise the person that provided you access to the server that you have completed setup and have disconnected from the server. Advise about the scheduled tasks to ensure that they are aware of them and their schedule, and make sure they are aware of the last run result codes if the firm reports issues with the sync.