SOFI bill to Primmo

Installation

The sofi-bill-to-primmo tool is a script installed on the same server as the Primmo software and allows you to automate the transfer of billable A la carte services accepted in SOFI to the Primmo software. This avoids having to generate the transfer file (MDG format) manually in the “Billing Services” tile for each residence, thus eliminating the loss of time and the risk of human error.

In order to import into Primmo the care services dispensed in SOFI that will be billable, the client must purchase a “Master D” billing import module (MDG) from Hopem.

This script performs the following operations:

For each of the residences configured in the configuration file.
Obtain through the SOFI API the list of VS with the status “Accepted” (in reference to the “Billing Services” tile) in the date range configured in the sofi-bill-to-primmo config file (if there are no dates specified, then sofi-bill-to-primmo takes all the services with the status “Accepted” regardless of the dates)
Enter in a file compatible with Primmo import (MDG format) all accepted VS found in the previous step in order to bill them in Primmo. Note that as long as the transaction is not completed for the residence, then the results file is marked as temporary (.tmp).
Assign by the SOFI API the status “Archived” to all VS that have been extracted in the file (only if sofi-bill-to-primmo is not run in DryRun mode).
Remove the temporary status from the results file (csv).

The tool generates a log file locally (no email transmission). This log file is cycled every day and gives a summary of the operations and transactions performed.
No billing data is generated for a resident who does not have an ExternalID.
If there are no accepted ACSs identified for a residence, then sofi-bill-to-primmo generates an empty results file.
The name of the generated results files as well as the contents of the results files are in accordance with the MDG format.
The log files generated by sofi-bill-to-primmo are saved in the directory specified in the “FilePath” configuration
The billing files are generated in the directory specified in the “OutputDirectory” configuration.

For a fixed frequency execution of the tool, you need to use an external task scheduler, such as Windows task scheduler.

To protect against import errors, sofi-bill-to-primmo will not do any processing if it is run when one or more .csv or .tmp files are still present in its billing file directory (OutputDirectory).

Prerequisites

Installation of Node.js is required for the tool to work properly.

The operation of the tool requires a user with the rights and key to access the SOFI data.

You must create an employee properly identified in the SOFI instance with the API key and the secret used in the application that needs access.

Make sure that the user created has the Allowed API Login checkbox checked and that the access group for that user has all the rights required to use that tool, see below. For security reasons, use a different user in the residence(s) for each tool with limited access rights to that tool only.

App Installation

Download the latest version of the tool. Follow the link: https://gitlab.telemedic.ca/client-tools/sofi-bill-to-primmo/-/releases

Extract the content of the compressed file into a subdirectory at the root of the C: drive (e.g. c:\telemedic\billtoprimo)

Configuration to do for each residence

To configure sofi-bill-to-primmo, you need to have the following information.

The information from the SOFI instance that will allow sofi-bill-to-primmo to access the data and the information from Primmo that identifies the institution that needs to be synchronized.

Parameter	Description
From SOFI instance
url	URL to SOFI API access point
apiaccesskey	API access key.

From Primmo
VendorId	Vendor ID (according to the value configured in MDG)
MdgFormatCol values must be enclosed in quotation marks
MdgFormatCol09	Value to be entered in column 9 of the MDG file
MdgFormatCol11	Value to be entered in column 11 of the MDG file
MdgFormatCol14	Value to be entered in column 14 of the MDG file
MdgFormatCol15V	Value to be entered in column 15V of the MDG file
MdgFormatCol15P	Value to be entered in column 15P of the MDG file

Global configuration to sofi-bill-to-primmo

All these values are optional

Parameter		Description
“StartDate”:	YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ	Start date and time for the search for accepted VS. Optional parameter.
“EndDate”:	YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ	End date and time for the search for accepted VS. Optional parameter.
“Language”:	“FR” ou “EN”	Language used for the description of services in Primmo files. Optional parameter (default=“FR”) .
“DryRun”:	true or false	Allows to run the program in simulation mode, i.e. without archiving the accepted VS. Optional parameter (default=false).
“OutputDirectory”:	“output”	Allows you to specify the directory where the billing files will be generated. Optional parameter (default=“output”).
“FileLogging”:	{ “FilePath”: “log” }	Allows you to specify the directory where the log files will be generated. Optional parameter (default=“log”).
“_comment”	“_comment”: “StartDate 2023-01-01T00:00:00Z”	Allow you to comment the line.

The backslash (\) is used as an escape character for special characters such as tab, line feed and others. In order to correctly interpret backslashes in a directory for a JSON file, it is necessary to double them.

The directory paths in the configuration for OutputDirectory and FileLogging must therefore contain doubled backslashes in order to interpret the backslash literally. For example, “\\ordi\chemin1\chemin2” should be written as “\\\\ordi\\chemin1\\chemin2”.

Example of a configuration file

{
	"Companies": [
		{
			"url": "https://siteduclient1.telemedic.ca",
			"apiaccesskey": "COMPANY1_API_ACCESS_KEY",
			"apisecret": "API_SECRET",
			"PrimmoBilling": {
				"VendorId": null, 
				"MdgFormatCol09": null, 
				"MdgFormatCol11": null, 
				"MdgFormatCol14": null, 
				"MdgFormatCol15V": null, 
				"MdgFormatCol15P": null
			}
		},
		{
			"url": "https://siteduclient2.telemedic.ca",
			"apiaccesskey": "COMPANY1_API_ACCESS_KEY",
			"apisecret": "API_SECRET",
			"PrimmoBilling": {
				"VendorId": null, 
				"MdgFormatCol09": null, 
				"MdgFormatCol11": null, 
				"MdgFormatCol14": null, 
				"MdgFormatCol15V": null, 
				"MdgFormatCol15P": null
			}
		}
	],
	"DryRun": true,
	"_comment": "StartDate 2023-01-01T00:00:00Z",
	"_comment": "EndDate 2023-08-16T23:59:59Z",
	"Language": "FR",
	"OutputDirectory": "output",
	"FileLogging": {
		"FilePath": "log"
	}
}

Usage

Execute «run.cmd»

Rights required

Module	Rights
Admin	See
Billing	See
General Information	See

The access group used must have the necessary authorisations to carry out archiving in its list of rights.

 {
   "Billing": {
        "CanArchive": true
    }
 }

Warnings, information and errors in logs

[WARN] IMPORTANT! DryRun will create the files but will not set archived status for charges. : Indique que sofi-bill-to-primmo s’exécute en mode DryRun et donc ne fera pas l’archivage des SAC facturables.

[ERROR] Files found in the output directory, check logs and clean output directory before retrying : sofi-bill-to-primmo arrête son exécution puisqu’il y a déjà des fichiers de type .csv ou .tmp dans le répertoire de sortie.

[ERROR] Invalid client credentials for VendorId X : L’information de clé-secret fournie pour se connecter à l’API du vendor ID est erronée ou l’utilisateur n’a pas les droits d’accès sur l’API.

[ERROR] default - Invalid output directory 'XXXX' : Le répertoire de sortie pour les fichiers de facturation n’existe pas.

[INFO] default - Log directory 'XXXX' created : L’outil sofi-bill-to-primmo informe de la création du répertoire de journalisation XXXX.

[INFO] default - Output directory is set to 'output' : L’outil sofi-bill-to-primmo informe que le répertoire par défaut ‘output’ est utilisé pour la génération des fichiers de facturation.

[INFO] default - Company XXXX, VendorId: 901. 1 resident(s) not processed (missing ExternalId) : indique que sofi-bill-to-primmo a détecté un (des) résident(s) qui a(ont) des services facturables, mais qui n’ont pas d’ExternalID. Ces services ne seront pas traités par sofi-bill-to-primmo.