Gallagher API 

1. Import API Features
2. Import or update API Card Holder
3. Import or update API Card Holder Information
4. Import or update API Doors (Devices) Information
5. Import or update API Event Groups Information
6. MAP Gallagher devices (doors) to Eco Time devices (option)
7. API Logs
8. Application Service Options

Run the APi application by clicking on the Eco Gallagher API shortcut on the desktop or running the application called EcoGallagherAPI32 or EcoGallagherAPIMs

Select the Settings Tab on the Eco Time Gallagher API Client :

• Server: The API server URL or IP address and port number as supplied by the client.
• Authorization: The code is generated on the Gallagher server's rets client settings and supplied to Eco Time by teh client.
• Version Number: The current API version number and cannot be changed.
• Client Code: The client code defaults to "Gallagher" and cannot be changed.
• Receive Format: The receive format is json and for information purposes only.
• Stop timed events: This stops time based events. Typically, useful when doing fault finding or analysing data on the client response screen.

• Client API Type:This setting defaults to "Gallagher" and cannot be changed.
• Client API Status:This is the default setting and cannot be changed.
• Events Collect Interval: Events collected interval in hours and minutes.
• Events / API Call: The maximum events collected with every events' API call.
• Events Collect Position: The next position number where the API will collect events from. Set this value back to recollect all events.
• Events Duplicate Threshold(ms): An event will not be saved as an Eco Time clocking if there is already and event with the current event time less this value (100ms = 1 second). Duplicate events are saved as Info (Status = H) clockings.
• Don't Save Duplicate Events : Duplicated invents will be rejected and not be saved as Info clockings.
• Don't Save Events To Clockings Table: Events are only stored in the Events table and not processed for Eco Time.
• Events History Days: The number of days (defaults is 61), events must be stored in the Events table before they are deleted according to the event date.
• Log History Records: The log history will be truncated at this number of records (default 2000).
• Stop timed events: This stops time based events. Typically, useful when doing fault finding or analysing data on the client response screen.

• Last Sync Date: The last date all card holders and card holders info was synced.
• Last Sync Time: The last time all card holders and card holders info was synced.
• Last Collect Date: The last date a timed collect of events was performed.
• Last Collect Time: The last time a timed collect of events was performed.
• 1st Sync Time: The 1st time of day all card holders and card holders info will be synced.
• 2nd Sync Time: The 2nd time of day all card holders and card holders info will be synced.
• Employee Division: Employees in Gallagher are allocated to this division.
• Process for this division only: Select this option to limit the import of cardholders and and events to the division set above.
• Stop timed events: This stops time based events. Typically, useful when doing fault finding or analysing data on the client response screen.

1. After the API Client has been configured, run the application and selects the features tab

   

2. Please Note that the "Stop timed events" check box is disabled by default on a new API installation. There is no point running timed events until the configuration and device mapping have been completed.

3. Press the API button on the features tab. This will open the API Request Window

   

4. Now Press the Rest (GET) button
5. You will see the request window is now populated with text. To verify the connection, select the response tab.
6. If the connection was successful, you should see at least a full page in the response field. Close API Request Window and verify that the Features List is now populated.
7. If the Features List is not populated, go back to the API Request Window and look at the response tab.
8. If the response is very short, then there are the following possible errors:
   1. Server connection cannot be opened: The Gallagher server connection details are incorrect or a firewall is blocking the connection.
   2. 403 Unauthorized: The API operator does not have privilege to view the monitored items.
   3. 403 Forbidden: The site does not have the RESTStatus licence:
9. The features tab displays all the API methods which are available to the REST API operator. Access to these are set by the Gallagher user privileges. Eco Time needs the following API methods for integration:
   1. Group cardholders
   2. Group alarms
   3. Group events
   4. Group doors
   5. Group eventGroups
10. The "Do Not Process Reponse" disables any results processing. No tables will be popluated. This is typically used for fauly finding and in cases where you want to inspec the request packet and result packet. 

1. Start by populating the following lists in order by pressing the API button on the respective tabs:
   1. CardHolders - Get CardHolders: The card holder button brings up the following popup menu:

      

      Select the Get "Cardholders" option by clicking on this item.

      
      The card holder table contains all the captured employees or visitors on the Gallagher system
      The following card holder table fields will be populated

      1. ID: Internal Gallagher CardHolder ID code
      2. firtName: Card holder firs name
      3. lastName: Card holder last name
      4. Authorised: Is the card holder authorised
      5. ID Number: Card holder ID or Passport number
      6. Import Date: Date added to the Card Holder's table.
      7. HRef: Card holder information API url.
   2. Doors

      
      The doors table contains all the device names where employees or visitors can clock
      The following doors table fields will be populated

      1. Enabled: Set to 0 (zero) for disabled and 1 (one) for enabled. If a device is disabled, events will not be saved for that device.
      2. ID: Internal Gallagher Door ID code
      3. Event Source Name: This is the door description, but according to the events collected. The Event Source Name is initially populated with the Doors API Name, but can be changed to match the actual event source name (which can differ depinding on the installer's). The Event Source Name here must match that of the event (inspecting the event to confirm), for the API to save to sucessfully save an event. IN other words the device by lookup on  Event Source Name has to exist.
      4. Doors API Name: Door description as per the API sync process
      5. HRef: Door Information API url.
      6. Verified Date: The date on which the last Doors API sync was manually run. If this date does not match the last  date on which the API was run, then the device was removed from the Gallagher system and can then manually be removed from this list. 

         Note: The Gallagher devices must be named with the extension Entry or Exit. This will enable the user in EcoTime to configure the corresponding device correctly.

   3. Event Groups

      
      The event groups table contains all the event groups, types and descriptions contained in the events for the site.
      The following event group table fields will be populated

      1. ID: Internal Gallagher System ID
      2. Name: Events Group descriptions
      3. HRef: Even Group Information API url.
      4. Event Type ID: Internal Gallagher System ID.
      5. Event Type Name: Gallagher Event Type Name.
      6. HRef: Even Type Information API url.
          
   4. CardHolders - CardHolders Info: The card holder button brings up the following popup menu:

      

      1. Select the "Get All Cardholders Info". This process will take some time and progress will be displayed at the bottom left of the Gallgher API Window.
      2. The Card Holders Info option adds and updates the card holder's personal and custom information to the Cardholders table:
         1. Sites: If configured, the Gallagher card holder's site is populated
         2. Emp Number: This field is a mandatory configuration for Gallagher and Eco Time integration:"
            1. This field is used to match the Eco Time employee number and if a match is found, the Eco Time fields will be populated.
            2. If an Emp Number is not imported, no matching attempt will be made.
            3. If an Emp Number is imported, the corresponding Eco Time details will be populated in the card holder table:
               1. Eco Emp Number
               2. Eco Emp First Name
               3. Eco Emp Last Name
            4. If an Emp Number is imported, the API validates the employee surname and employee number.
               1. If employee surname do not match, an error image will appear next to the card holder.
               2. The AP tries to match first names. If the firstnames do not match, the API tries to resolve initials or initials in combination with firstnames. But if this fails a warning image will appear next to the card holder.
         3. Division: Divisions which the employee is allocated in the Gallagher system.
         4. Department Business Unit: Department/Business Unit which the employee is allocated in the Gallagher system.
         5. Job Title: Job Title which the employee is allocated in the Gallagher system.
         6. Gender: gender of the employee is allocated in the Gallagher system.
         7. Verified Date: The last date the card holder info was updated.
      3. "Get Current Card Holders" Info option updates the currently selected card holder's personal and custom information to the Cardholders table.
      4. "Get Current Card Holder Events" retrieves all the events of a selected card holder and updates the Events table according to the rules configure in the Doors Browse. 

1. The Gallagher API interface you allows the user to map the Gallagher devices to a corresponding Eco Time device.
2. In terms of using the Gallagher API, we recommend setting up and Eco Time API device, but you may use and existing device to ease the process or cutting over.
3. The browse has five fields which may be edited:
   1. Enabled: Only enabled devices' events will be collected an displayed in the Events Browse. Enter a 1 to enable the device.
   2. Event Source Name: This is the door description, but according to the events collected. The Event Source Name is initially populated with the Doors API Name, but can be changed to match the actual event source name (which can differ depinding on the installer's). The Event Source Name here must match that of the event (inspecting the event to confirm), for the API to save to sucessfully save an event. IN other words the device by lookup on  Event Source Name has to exist.
   3. Eco Device: To map this device name to the corresponding Eco Time device, for example Eco Time Clock 1, simply enter 1 in this field.
   4. TNA Clock: Enter 1i f events for this device must be assigned for TNA.
   5. Access Clock: Enter 1 if events for this device must be assigned for Access.
   6. Clock Direction: Assign direction to an event by enter 0 for not applicable (eg for Access), 1 for In, 2 for Out and 3 for toggle direction -  must always be set
4. Once a Gallagher device has been mapped to an Eco Time Device, the event collected for that device is allocated all the attributes ascribed to that Eco Time device, for example if it is a Access, TNA or Job etc device. NOTE: The event direction will always be determined by the Gallagher Device Setting
5. If an Eco Time device mapping is not found for an enabled Gallagher device, the device settings configured in the doors browse for that device, will be used.

1. An API call can be manually triggered at any time by pressing the API button at the bottom of each browse.
2. An API call triggered will depend on the current tab selected (eg Events).
3. All manually triggered API calls are not automated. This means the API Client Request Window will open and you would manually have to press the Res (Get) button. Afterwards press the close button to exit the API call.
   1. API Client Request Window Request:
      
   2. API Client Request Window Response:
      
4. The API Status message at the bottom left of the browse will be updated with the current action or process.
5. Manually triggering an API is used during the configuration and setting up phase of the API.
6. It is also very helpful when doing fault finding. See the FAQ for more details about this.

1. Timed events are automated events trigger either by time or an interval duration, in other words automated API calls.
2. During timed events the API Client Request Window is hidden but the API status message is updated.
3. There are three timed events:
   1. New events are collected from the Gallagher server every two minutes.
   2. The cards holders list is synced twice a day. Once at 1am and once at 1pm.
   3. The cards holders information is updated once twice a day. Once at 1.30am and once at 1.30pm.
4. Timed events can be disabled be selecting the "Stop timed events" check box on the Gallagher API Window. 

1. The logs browse displays general information about the API requests, responses and processes.

   

2. The log display information about:
   1. Details about a collected event.
   2. The total events collect with each API call.
   3. If the event was processed or rejected. If rejected, it provides a reason.
   4. If the event was added as a clocking to Eco Time.
   5. When manual or timed events were triggered.

1. In which Eco Time version is this feature available?
   From version 22.04.28 onwards.
2. How can the API Client Request Window be used for fault finding?
   1. This windows displays the request link in the server fields. You can use his value to determine if the correct link is being used durig the rest call.
   2. Consider selecting the "Do Not Process Reponse" diables eny results processing. No tables will be popluated. This is typically used for fauly finding and is used in cases where you want to inspec the request packet and result packet. 
   3. The Gallagher API Server response is displayed in the reponse window's text field. This reponse is the raw unprocessed data from the Gallagher API Server and represents the true data transmitted and received by the APi Client. 
   4. The reponse packet is json and is unformatted (one long string) and is in the body of the response. Copy this body to your clipboard and use an online formatter like https://jsonformatter.org/ to make the reponse easier to read.
   5. By inspecting the raw formatted json reponse, you can validate the values eventually stored in Eco Time and the Gallagher API Client.
3. There is an Error Image next to a card holder. What must I do?
   1. An error means that either the surname or employee number assigned in Gallagher does not match.
   2. This means that the surname in Eco Time is different or spelled incorrectly, or
   3. that the surname in Gallagher is different or spelled incorrectly (highly unlikely if ID's are used to capture employee details) or
   4. that the employee number assigned in Gallagher is incorrect.
4. There is an Events Browse in the Gallagher API Client. What does this display?
   1. Events are the equivalent to clocking in Eco Time.
   2. In the case of Gallagher, any system related events is transmitted, whether it is workstation login, or masterfile update etc.
   3. The Gallagher API Client filters out the non Entry and Exit related events and displays the entry and exit related events in the Events browse. 
   4. The Events browse is essentially a formatted Entry and Exit data log. It is formatted according to the rules setup for that device in the doors browse.
   5. Once the event is stored in the events file, it is then then added as a Eco Time as a clocking and processed.
5. What is Gallagher's Rest Client?
   1. The Gallagher Rest Client is a registered user on the Gallagher System
   2. Eco Time's Gallagher API Client logins in as this user using the Authorization string provided by the Gallagher System.
   3. The Gallagher Rest Client has access rights very similar to a windows user. So if the Eco Time's Gallagher API Client is not able to view or update certain information, it is most likely a Gallagher Rest Client permissions issue, to be reseollved by the Gallagher support team.