Commitments forecaster WHMCS module

• Description and definitions.
• How to start using
• Requirements
• Installation
• Activation
• Deactivation
• Configuration of module parameters
• Counterparties
• Add counterparty
• Edit counterparty
• Information contained in the counterparty's profile.
• Commitments
• Adding a commitment
• Edit the commitment
• Documents
• Adding a document
• Bulk PDF upload
• Classification of PDF files
• Viewing/Editing the Agreement
• Viewing/Editing an Invoice
• Viewing/Editing an annex to the Agreement
• Unmapping documents
• Deleting PDF files
• Accounting systems
• Adding the WHMCS System
• Sync/Full Sync
• Creating an API user in WHMCS
• Tools
• Reindex commitment dates
• Reindex agreements dates
• Synchronization income invoices
• About us

Description and definitions.

Purpose of the project

The project was created out of the need to plan, classify, organize and report costs in the company, based on commitments and fixed contracts.

The system helps to know the real income by counting the income from invoices issued in WHMCS with invoices or cost documents uploaded and described manually to the module without leaving the WHMCS. The system is based on the concept of contracts and obligations and enables the presentation of financial flows over a longer period of time.

WHMCS adequately manages and reports revenues, but does not have a mechanism to track and report costs. That is why we decided to prepare our own module, because we did not find one that would meet the functions we need.

The project was created as an inside project, but with a professional approach.
The project is entirely financed by PUQ sp.z o.o. https://puq.pl/

The project needs your support to function and develop further.
If you wish to help in the development of the project, be it financially, content-wise, translating, writing / proofreading documentation or in any other way, let us know cf@puq.info

---

---

The main purpose of the module is to collect documents in PDF format, correctly describe documents (contracts, invoices) in the context of contractors and obligations towards partners. Based on the entered data and imported invoices from the WHMCS system (also many WHMCS systems at the same time), WHMCS generates in a readable form reports and forecasts on the company's finances.

To save files, the module uses a connection to the WebDAV server, which means that the files are not physically stored on the WHMCS server and will be available even after removing the module.

The system requires use and has been fully tested with NEXTCLOUD, a recognized opensource software. You can use your own Nextcloud installation or use our free solution available at this link: https://crm.puq.pl/store/za-darmo

The module uses the API connection to WHMCS to synchronize invoices.
This means that the module can be installed not on the WHMCS production server, but e.g. on the developer's server, which in no case will affect the functionality of this module. It is also possible to combine several WHMCS systems to synchronize invoices.

The module creates the necessary tables in the WHMCS database and only uses them in its work.
It does not use any other WHMCS tables.

The module sends data to the project server only for the installation code, which is generated during installation for statistical purposes. In response, the servers provide data about the new version and important information displayed in the module's dashbord Panel.

The module supports multilingualism. The language settings can be changed in the WHMCS user configuration.
Available languages: English, Polish, Russian.

Definitions

Counterparty (contractor) - an object in the system, means a natural or legal person who is a party to an agreement or invoice.

Data for classifications in the system.

• Company name
• VAT number

Documents - PDF files in unclassified form and their classification (invoice, contract, contract annex)

Commitments - an object in the system that characterizes a group of costs incurred in relation to the contractor on the basis of an agreement and / or invoices.

Data for classifications in the system:

• Commitment name
• Start date (The value is calculated from invoices or contracts)
• End date (The value is calculated from invoices or contracts)
• Indefinite time (The value is calculated from the contract or set manually)

Commitment as the basis for the organization of documents

The commitment is to group invoices and/or to link them to an appropriate contract.

Assumption 1

You can Map only one contract and invoices for the duration of the contract.
In this case, the parameters of the obligation (Start Date, End Date, Indefinite Time) are derived from the contract parameters.

Assumption 2

In the absence of an agreement, mapping only invoices related to the contractor.
In this case, the commitment parameters are taken from the linked invoices where:

• The start date is the date of the oldest invoice,
• The end date is the date of the most recent invoice.

If you select indefinite time, End date is the date of the latest invoice + 12 months.

Global assumption

Each invoice is to be mapped with a commitment.

Attention!!! Only one counterparty's invoices can be mapped to a commitment.

Accounting systems - A system that has a set of income invoices and can be exported.
-apiWHMCS: any WHMCS system with properly configured API.

 

 

How to start using

Requirements

Installed and correctly configured WHMCS

Module tested on WHMCS 8.1 version

NextCloud server account with WebDAV access - this module works properly only with NextCloud, for now. 

The system requires use and has been fully tested with NEXTCLOUD, a recognized opensource software. You can use your own Nextcloud installation or use our free solution available at this link: https://crm.puq.pl/store/za-darmo

For the correct operation of the module, PHP parameters are required:

PHP >= 7.2
file_uploads On
post_max_size 80M ;(Be guided by the size of the PDF files)
upload_max_filesize 80M ;(Be guided by the size of the PDF files)
max_file_uploads 40

Installation

At this stage, the module does not include a standalone installer.

The installation consists in uploading the module files to the appropriate addons directory in the WHMCS installation and then activating the plug-in.

Installation requires basic knowledge. If you are a WHMCS user and you do not have access to the server where WHMCS is installed, you will not be able to install the module.

Access to the server terminal with WHMCS installation or the ability to upload files via FTP is required.

Attention!!! We remind you - for the correct operation of the module you need a WebDAV server / account from NextCloud. Failure to do so makes it impossible to use the system.

PDF files are stored on the NextCloud server and cataloged by type and date of the document (date entered in the document, example: date of invoice receipt)

To install the module, copy the module folder to the WHMCS "modules/addons" folder.

git clone https://github.com/PUQ-sp-z-o-o/puq_commitments_forecaster.git
cp -r puq_commitments_forecaster WHMCS_DIR/modules/addons

or

wget https://cf.puq.info/whmcs-module/puq_cf_WHMCS-latest.tar.gz
tar -xzvf puq_cf_WHMCS-latest.tar.gz
cp -r puq_commitments_forecaster WHMCS_DIR/modules/addons/

Activation

In the WHMCS administrator panel, browse to:

System Settings -> Addons Modules

Activate the module by clicking the "Activate" button in the "Commitments forecaster" module.

Activating the module automatically creates tables in the WHMCS database with the prefix "puq_"

 

Deactivation

Attention!!!
Deactivating a module automatically deletes the tables in the database associated with that module.

In the WHMCS administrator panel, browse to:

System Settings -> Addons Modules

Deactivate the module by clicking the "Deactivate" button in the "Commitments forecaster" module.

 

Configuration of module parameters

In the WHMCS administrator panel, browse to:

System Settings -> Addons Modules -> Commitments forecaster

Click the "Configure" button

Enter your NextCloud server login details:

WebDAV URL HTTPS:// - {SERVER}/remote.php/dav/files/{USER}/
Note: link without "https: //" and at the end "/"
WebDAV user
WebDAV password
Access Control - select the user groups that must have access to the module.

After entering all the data, click the "Save Changes" button

Counterparties

Add counterparty

To add a counterparty go to the menu item "Counterparties" and click on "Add counterparty".

After completing the form, click the "Save" button

Attention! After the contractor has been created, it will not be possible to change the "Company name" nor "NIP" number.
If for some reason the contractor has changed its name and tax identification number, it is necessary to create a new contractor in the system.

Edit counterparty

To view a list of all contractors, go to the "Counterparties" menu and click "List counterparties".

Clicking on the counterparty will open a form with information about the counterparty, as well as the possibility of changing his data.

After completing the form, click the "Save" button

Attention! After the contractor has been created, it will not be possible to change the "Company name" nor "NIP" number.
If for some reason the contractor has changed its name and tax identification number, it is necessary to create a new contractor in the system.

Information contained in the counterparty's profile.

The counterparty profile contains information such as:

• Number of invoices
• Number of active commitments
• Financial information
• Invoice statistics chart
• etc.

Invoice list

Agreemets list

List of commitments

 

Commitments

Adding a commitment

To add a liability, go to the "Commitments" menu item and click "Add commitment".

After completing the form, click the "Save" button.

 

 

Edit the commitment

To view a list of all obligations, go to the "Commitments" menu and click "List of commitments".

By clicking on the commitment, a form will open with information about the commitment, as well as the possibility of changing the data.

After completing the form, click the "Save" button

Documents

Adding a document

Documents can be added in several ways:

1. We can use the bulk upload option and upload a few or a dozen files at once as unclassified documents to describe them correctly later
2. add directly from the contractor's window.

Documents that are not classified and await classification in the "List of unclassified" tabs are not processed by the system in any way and are not included in summaries and reports. Deleting them in no way affects the values stored in the system.

The document must be attached to the contractor to be analyzed by the system and be visible in reports and other summaries.

Go to the "Documents" menu item and click "Add Document".

Select the required counterparty from the list of counterparty and click the "Add document" button.

Then you need to select the file and classify it.

Finally, you have to click the "Save" button.

 

Bulk PDF upload

The system enables the batch upload of PDF files to the system.

Mass file upload helps in everyday work with the system.

Please keep in mind 2 things:

Documents that are not classified and await classification in the "List of unclassified" tabs are not processed by the system in any way and are not included in summaries and reports. Deleting them in no way affects the values stored in the system.

The document must be attached to the contractor to be analyzed by the system and be visible in reports and other summaries.

To use this functionality:

Go to the "Documents" menu item and click "List of unclassified".

Then press "Select Files".

In the window that will open, select the required files and confirm your selection.

Then hit the "Upload" button

The files are automatically uploaded to the system.

Attention! If the file already exists in the system, the system will not allow it to be uploaded.

 

 

 

Classification of PDF files

Go to the "Documents" menu item and click "List of unclassified".

Go to the viewing mode by clicking the "Classify" button. You can use the Next and Previous buttons to move from file to file.

In order to classify a document, select the counterparty and the type of document.
Then click the "Save" button.

Document types

There are currently 3 types of documents:

1. invoice
2. agreement
3. annex (used to correct / overwrite contract parameters)

Viewing/Editing the Agreement

Go to the "Documents" menu item and click "Agreement list".

Use the date buttons to select a sort date.

After selecting the desired agreement, click on the agreement number or the edit button.

A preview of the document will open and its data can be edited.

• Number (Document number, if any)
• Description
• Conclusion date (Date of signing the document)
• Commitment date (Date on which the subject of the contract comes into force)
• Expiry date (Date until which the subject of the contract is valid)
• Notice period (notice period in days)
• Indefinite period (Select this option if the contract is signed for an indefinite period or becomes indefinite after its expiry)

 

To save the changes, you must click the "Save" button.

 

 

Viewing/Editing an Invoice

Go to the "Documents" menu item and click "List invoices".

Use the date buttons to select a sort date.

After selecting the required invoice, click on the invoice number or the "Edit" button.

 

A preview of the document will open and its data can be edited.

• Number (Document number)
• Netto, Brutto, VAT (Actual invoice data)
• Document Date (Invoice issue date, actual invoice data)
• Receipt Date (Date when the document was actually delivered)
• Tags (Words or phrases that will help in the future in finding an invoice. For example: laptop, computer technology, office, Warsaw)

To save the changes, you must click the "Save" button.

 

Viewing/Editing an annex to the Agreement

The annex is used to change the terms of the contract without editing the contract itself and helps to maintain the proper hierarchy of documents in line with reality.

Go to the "Documents" menu item and click "List annexes".

After selecting the required annex, click on the number or the "Edit" button.

A preview of the document will open and its data can be edited.

• Agreement (Select the agreement to which the annex belongs)
• Number (Document number, if any)
• Description
• Conclusion date (Date of signing the document)
• Commitment date (Date from which the subject of the annex comes into force)
• Change the contract - check the box if the annex changes the terms of the agreement, such as:
  • Agreement expiry date (Date until which the subject of the agreement is valid)
  • Agreement notice period (Agreement notice period in days)
  • Agreement for an indefinite period (Select this option if the contract is indefinite or becomes indefinite after its expiry)

If you select the "Change contract" option, the annex will practically overwrite the contract values.

To save the changes, you must click the "Save" button.

 

Unmapping documents

If for some reason it is necessary to move the document to an unclassified state, for example, if the document has been incorrectly classified, we have this option in the system.

To unmap a document, make sure the document has no dependencies:

• Relationship Invoice -> Commitment
• Relationship Agreement -> Commitment
• Relationship Agreement -> Agreement annex.

Find the document you want to move to an unclassified state.
Open its Viewing/Editing.

Click the "Unmap" button

Then confirm the action by clicking the "OK" button

After a document is successfully unmapped, the document enters the unclassified state.
It will be in the menu item "Documents" -> "List of unclassified".

 

 

 

Deleting PDF files

To delete a PDF file, you must
Go to the "Documents" menu item and click "List of unclassified".

On the file you want to delete, click the "Delete" button
Then confirm the action by clicking the "OK" button

It is also possible to delete a file from the preview mode.

Go to the viewing mode by clicking the "Classify" button. You can use the "Next" and "Previous" buttons to move from file to file.
On the file you want to delete, click the "Delete" button.

Then confirm the action by clicking the "OK" button

Accounting systems

Adding the WHMCS System

Installed Commitment Forecaster module, although it is installed in WHMCS, retrieves data through the API mechanism and not through direct references to the database.

Only the data on income invoices is downloaded from WHMCS. FV numbers, dates, and numeric values are taken. This data is only used to report the total value of revenues. Contractors' data is not collected and contractors between WHMCS and Commitment Forecaster are not compared in any way.

Go to the "Accounting Systems" menu item and click "List of systems".

Then click the "Create apiWHMCS" button

Connection details

After creating the connection, you need to enter the connection details.

• Name
• Description
• URL (link to the API of the WHMCS system. Https: //XXX.XXX.XX/includes/api.php)
• Username (API user Identifier)
• Password (API user password Secret)
• Step (Number of invoices that will be synced for each sync step)
• Automatic synchronization (It is necessary to check the box for the automatic synchronization of invoices once a day, the synchronization follows all daily WHMCS cron tasks)
• Exchange rate (Specify the exchange rate if the currency is not the same as in the system. Set it to 1 if the currency is the same as in the system)

You must click the Save button to save the changes.

 

Sync/Full Sync

Full synchronization means that all invoices of the selected system will be completely synchronized.
Synchronization takes place step by step.
The number of steps depends on the number of invoices in the accounting system and the number of the STEP parameter.

Sync means that the missing invoices will be synchronized in the selected system.

Creating an API user in WHMCS

In order to be able to exchange information between the Commitment Forecaster and WHMCS, access to the API must be created.

Adding a new API access

1. Log in as an administrator to the WHMCS system.

System Settings -> Administrator Users

2. Add a new user

3. Move to: 

System Settings -> Manage API Credentials -> APIQ Roles

Create a new role and select only BILLING -> GETInvoices

4. Move to:

System Settings -> Manage API Credentials -> API Credentials

5. Create your API credentials

 

Select the previously created user and API role

Press the "Generate" button

6. Write the data they need to connect to apiWHMCS Identifier Secret

 

Access to WHMCS from IP number

Then you should allow access to the IP address of the server with the module installed in the WHMCS system

Move to: 

System Settings -> General Settings -> Security

Add the IP address of the server with the module installed to the API IP Access Restriction list

 

 

 

 

Tools

Reindex commitment dates

A commitment in the system has parameters such as a start date, end date,  indefinite period.

These parameters also change due to the related invoices.

The entire process is automated and takes place automatically during each daily WHMCS crontab job.

For the purpose of compulsory synchronization of commitment terms.

 

Go to the "Tools" menu item and click "Reindex commitment dates".

The indexing process will begin immediately after you make your selection.
As a result, a table with all commitments and new parameters will appear.
Items with "0" means that the parameter has not been changed.

 

Reindex agreements dates

In the system, the parameters of the contract, such as Commitment Date, Expiry Date, Notice Period, Indefinite Period, can be changed with another document, e.g. an annex to the contract.

The entire process is automated and takes place automatically during each daily WHMCS crontab job.

For the compulsory indexing of contract dates.

Go to the "Tools" menu item and click "Reindex agreements dates".

As a result, a table appears with all the annexes that changed the parameters of the contract and the new parameters.

Synchronization income invoices

Income invoices are automatically synchronized during each daily WHMCS crontab job.

For the purpose of compulsory synchronization of income invoices.

Go to the "Tools" menu item and click "Synchronization income invoices".

As a result, a table with all accounting systems and synchronization parameters will appear

About us

The project was created as an amateur, but with a professional approach.
The project is entirely financed by PUQ sp.z o.o. https://puq.pl/

If you would like to help, with the development of the project, financially or in any other way, please let us know cf@puq.info

Authors:

Ruslan Polovyi
Concept, PHP, CSS
language: english,poland,russian

Piotr Esse
Concept
Colors

---

Developed by: PUQ sp. z o.o.
Company site: https://puq.pl/