Overview

Documentation

Description

The Holidays API's aim is to build up a database of holidays of different types (national holidays, religious holidays, etc.) for countries across the globe.

In addition, Holidays API gives the user the ability to add countries, holidays, holiday types and country areas without using the API endpoints. This allows the user to use the module without being restricted by the API endpoints database.

The Holidays API uses the API endpoints provided by Calenderific (https://calendarific.com/).

Calenderific's API documentation can be found here: https://calendarific.com/api-documentation

Typical usage scenario(s)

Scenario 1

A client may not want to perform certain actions on holidays – e.g. bank money. By using the holiday collection the client can specify which holidays must be considered.

Scenario 2

An application may be used by multiple clients. Each client can build up a unique holiday collection.

Features and limitations

• Features
  • APIs for Countries and Holidays
  • Manually create Countries, Holidays, Country Areas and Holiday Types
  • Activate / Deactivate Countries
  • Create Holiday Collections
• Limitations
  • N/A

Dependencies

1. 7.23.19 (Module can be updated to later versions of Mendix, but caution should be exercised)
2. Community Commons (v 8.2.0)

Installation

1. Import 'HolidaysAPI' into the project and any other dependancies required.

1. Configure the 3 API constants found in the Constants USE_ME folder (API_Active, API_Key, APIBatchSize)

The API key can be acquired from the Calenderific website once registration on Calenderific has been completed. This key is required to perform any of the API calls contained in HolidaysAPI.

Please note that the pricing and rates for using the Calenderific API are determined by calenderific. For more information on pricing and rates please see here: https://calendarific.com/pricing

1. Link the following pages found in the USE_ME folder to the appropriate navigation location:

- API_Configuration > Page for activating/deactivating the 2 API endpoints. In addition, the 2 API endpoints can be run pre-maturely.

- Countries_Overview > Page for viewing and/or creating all the countries that exist in the system. In addition, countries can be activated and deactivated via this page (USE WITH CAUTION).

- HolidaysCollection_Overview > Page for viewing and creating new holiday collections.

- AlertLog_Overview > Page for viewing any errors or alerts that occur in the HolidaysAPI module. Mainly for API endpoint errors.

1. Link 'GET_HolidayAtDate_InCollection' or 'GET_HolidayAtDate_InSystem' into the system logic.

1. The Country and Holidays scheduled events are set to run on a monthly basis.

Configuration

General

1. Run the application.

1. Create a system user 'SchedulerUser'. This user will be used for executing the APIs in the background.

API Countries & Holidays

1. Navigate to the 'API_Configuration' page, and execute the following actions:

- Ensure that both the Country and Holiday Updater are active (set to 'Yes').

- Execute 'Country Updater'. This will create or update all of the countries in the system.

1. Navigate to the 'Countries_Overview' page and activate the countries that are required by clicking on the (x).

1. Navigate to the 'API_Configuration' page, and execute the following actions:

- Execute 'Holiday Updater'. This will update all the holidays on the activated countries.

Scheduled Events

The Country and Holiday APIs are, by default, executed on a monthly basis (31 days).

1. Navigate to 'HolidaysCollection_Overview' and create a 'New' collection.

Whilst creating a holiday collection, the holidays will be filtered by country, area and holiday type. This filtering occurs when selections are being made on the various pages.

Manual Countries & Holidays

1. Navigate to the 'Countries Overview' page.

1. Click '+ New' to start the process of creating a new country (manual). Capture the name and the short name of the country. These must be unique.

1. After creating the country click 'Details'. On the 'Country Overview' page, in the Holidays tab, click '+ New' to create a new holiday.

A new holiday must have a name, description, date, area and holiday type. If no holiday type or area has been created yet, the user will have the ability to add an area or type from the New Holiday page.

1. From the 'Areas' and 'Holiday Types' tabs a user can create new areas or holiday types for a country.

Holiday types can also be added to the country's collection from the broader system. Holiday types are related with many countries and many countries are related with holiday types (many-to-many).

Administration

1. On the Countries Overview page there are three buttons. The first is used to create new countries manually. The next two perform the following actions:

1. 1. Reset - clears all the last updated dates for all active countries. Clearing this date will mean that when the API runs again, these countries' holidays will again be updated.
   2. Countries - Removes all the countries from the system (active and inactive).

1. Alert Logs found on the alert logs page show what errors occur in the API. The alert logs page is automatically filtered to show the un-archived alert logs on loading the page. Updating the search parameters will show all the alert logs.

Alert Logs can be archived using the 'Archive Logs' button. Alert Logs are generally archived once they have been dealt with.

Known bugs

N/A.

Frequently Asked Questions

Question: Is there a limitation to the number of API calls that can be performed?

Answer: Yes, for the free plan calenderific account there is a limit of 1000 API requests that can be made.

More detail on the plans can be found at: https://calendarific.com/#pricing

Question: Do all the countries have to be used?

Answer: No, only activated countries will be used.