Before this configuration is set up, the basic installation of the Handyman API must be in place. That page can be found here: Setup of Handyman API
Handyman API is a service that gives external programs and/or services access to Handyman's data.
Some examples could be:
- Integrations with ERP systems
- Extraction of data for processing in external systems
- Handyman Office reports on mobile devices
- Setup and configuration of the Handyman Portal
In order for the Handyman API to be made available on the Internet, it must be set up with secure communication between the parties. In practice, this means that the API service must run on https (TCP 443) and not http (TCP 80), which would be good enough if only local services should have access to the Handyman API.
Running a service on https also includes that a certificate must be set up locally on the server where the service is to run. This is not something GSGroup AS offers, but the customer must install a certificate themselves which we can link to our service.
Below is the list of points that must be set up and configured
- Installation of certificate on server
The IT manager or the provider of the environment must obtain a certificate that can be used for https traffic. This must be installed following standard procedures. - Opening of traffic from the Internet to the server
Here, the customer's IT manager or supplier must do two preparatory tasks:
a. Connect a name in the domain that points to an external IP address that the customer disposes of. An example could be: hmapi.customer.com but this is completely optional.
b. Open for traffic https (TCP 443) from the Internet and route the traffic to the server where the Handyman API service is to run - Link certificate to Handyman API
This is done by finding the thumbprint of the certificate on the server via MMC (Microsoft Management Console) and connecting this to the GUID of the Handyman API.
a. Start MMC from "Run"
b. Add view for certificates
c. Find the certificate that is installed and copy the thumbprint
d. Thumbprints may contain invalid characters when copied. Paste it into a text editor and remove any characters so that only numbers and letters remain.
e. Run the following in a Command Prompt (must be run as administrator). The X's must be replaced with the thumbprint that was copied out earlier.
"netsh http add sslcert ipport=0.0.0.0:443 appid={C504379D-4D9A-436B-82B0-858FE26AB997} certhash=XXXXXXXXXXXXXXXXXXXXXXXX" - Configuration of the Handyman Control Center
In order for the Handyman API to respond to https, the following configuration must be changed (example in the image below):
a. URL to Handyman API: This must contain "https://" and the local IP address
b. Optional external address: The external URL must be entered here
c. URL to GSG Identity Management Server: Only link to GSGroup's IDM (https://idm.gsgroup.io) - Restart the service and testing
Start a browser on another machine connected to the Internet with the following address: https://hmapi.customer.com/swagger
If you bring up the website in a browser, the configuration and setup are in order.