1.1 Purpose

The purpose of this Guide is to help understand how to implement an automated process which takes information from an external database source and puts it into BluB0X Security’s BluSKY platform using the BluSKY API.  

The intent of this process is to populate BluSKY with information about both employees and non-employees (vendors, contractors, visitors, etc.) from your on-premise Active Directory or other HR server(s).

Optionally, you may wish to also assign Access Rights, apply Application Permissions (Roles), and/or assign Credentials, based on a number of Business Rules as discussed later in the document.

This information will then be used to drive the Physical Access Control System.

For the abbreviated outline of this, please reference Appendix B – Quick Start Guide to Using the BluSKY API

1.2 Definitions, Acronyms, and Abbreviations

Access Right – A combination of a specific door/portal and a schedule that specifies when a cardholder can gain access to that door or portal.

Access Level – A group of one or more Access Rights that enable a card-holder to gain physical access through the Access Control System.  This Access Level has a name for easy identification.

Access Level Group – A group of Access Levels (see above definition of Access Level)

BB – BluB0X Security – the manufacturer of BluSKY and the access control system

BS – BluSKY – the website that allows authenticated users to manage the security system, monitor hardware, request visitors, etc.

Business Rules – Logic that XXX has agreed upon that will either alter the value of fields in BluSKY such that they do not directly reflect their counterpart value in the originating database, or logic that results in a single value in origin database automatically applying additional fields or attributes in BluSKY.

DB Integration – The application being developed to feed information from the original data source (Active Directory, Workday, etc.) to BluSKY

PACS, ACS, System – Physical Access Control System or Access Control System for short.

Role – A set of permissions within BluSKY that enables the end-user to perform various tasks such as requesting a visitor or administering personnel records.

Source Database – The database that data is being read from, such as Active Directory, Workday, etc. in order to send it to BluSKY

Working Database – The database that is maintained by the DB Integration to coordinate its efforts between the Source Database and BluSKY

1.3 References

This document pulls its requirements from various sources that have been added as appendices to this document.  

Appendix A – Fields Eligible For Import

Appendix B – Quick Start Guide to Using the BluSKY API

2.1 Data Structures - Overview

In order to start putting person-related records into BluSKY, several concepts need to be understood and the pre-requisite data structures need to be created.

2.1.1 Required Setup - Systems, Hardware, Companies, and Occupancies

BluSKY organizes data in a manner which is consistent with the real world.  In terms of hardware, everything centers around an Access Control System (ACS), which we often refer to as simply a “System”.

Systems can be created to control access around a single Facility (building) or around multiple Facilities (such as a campus environment).

Companies represent an entire organization (regardless of location), and can have a presence in one or more Facilities by creating an Occupancy for the Company in that Facility.

People are then added to these Occupancies and granted Access Rights to enter various Portals (doors, gates, turnstiles, etc.) within one or more Facilities.  This can be done by assigning Access Levels or Access Level Groups. 

In order to identify themselves when they approach a Portal, people will need Credentials assigned to them.  These can be traditional Prox Cards, Mobile Credentials (which exist solely on a smartphone), biometric scans, or other forms.

Additionally, People can be assigned Permissions to perform various tasks within the BluSKY Application (such as editing personnel records, requesting visitors, running reports, etc).  This is done by assigning Roles to those People.

This document is centered primarily around retrieving, adding, or updating records related to the above-mentioned topics.

For more information on these relationships, please see the documentation in our knowledgebase https://knowledge.blub0x.com/

2.1.2 Optional Setup

There is intrinsic functionality in BluSKY that allows people placed in a company occupancy to automatically be assigned Access Levels and/or Roles (permissions within BluSKY itself) simply because they belong to that occupancy.  This is done by checking off the “Apply by default” option in the Access Level or Role.  This is currently only possible in the UI of BluSKY, but will be added to the API in future versions.

Some examples of how automatically-applied Access Levels could be applied:

• Create one Access Level for Employees called “Global Access” with general access to all Facilities across the glob
  • Apply this by default to all people added to your company and then programmatically ADD any necessary additional Access Levels for each individual based on their individual needs/business rules (such as “all executives get the “Executive wing access level”).
• Create one Access Level for Consultants in each building, that contains only general access to a single building – each consultant will then have access only to the facility that contracted them.
• Create two Role
  • Employee – will contain all necessary permission plus visitor admission permissions
  • Consultant – will contain no permissions other than requesting visitors.

3.1 Initialization Sequence

Upon startup, the application will read its initial settings from its configuration file. The key bits of information that it will need are:

• Connection string for the BluSKY WebAPI – this will differ between QA and Production environments
• Credentials for the BluSKY WebAPI (encrypted)
• Connection string for the Source Database server – this may differ between QA and Production environments within your infrastructure
• Credentials for the Source Database, such as Active Directory, Workday, etc. (encrypted)
• Connection information for an application-specific database (Working Database) that helps enforce business rules and sync logic (note that this is a “working” database for the application, not necessarily on the same server as the personnel source database (AD, Workday, etc) – this will differ between QA and Production environments
• Connection information (path and credentials) for a photo repository folder with encryption as necessary.
• Frequency of sync’ing process – anything from “every 20 minutes” to “once a day at midnight” – this should be driven by business needs.
• EmployeeBadgeTemplateId(s)
• ConsultantBadgeTemplateId(s)
• Notification email string – a delimited string of valid email addresses to send error notifications to (on your side)

3.1.1 Occasional Query – Once a Day

There are a few reference tables in which the DB Interface may need to reference and keep updated via infrequent calls to BluSKY.  This includes keeping mapping tables for the Source Database’s locations/workplaces to the corresponding Systems, Facilities, and Occupancies in BluSKY. 

Note 1:  If you are only dealing with a single occupancy that all of your people will be going into, then you can simply set the ACSystemId, FacilityId, and OccupancyId in your configuration file and bypass the first three API calls listed below.

Note 2:  If you are not going to be adding Access Rights via the API, or are relying on automatically-assigned Access Levels only, then you can skip Access Levels and Access Level Groups below.

Note 3: If you are not going to be adding Roles via the API, or are relying on automatically-assigned Roles only, then you can skip the Roles item below.

Note 4: If you are not going to be adding Credentials (Cards) via the API then you can skip the Card Types item below.

In order to do this, the DB Interface Application will need to call the following methods once-a-day, or at most, once-an-hour:

1. Conditional: To get a list of Systems from BluSKY: Issue a GET call to https://qaapi.blub0x.com/api/v1/ACSystems (for development) or https://api.blub0x.com/api/v1/ACSystems (for Production)
2. Conditional: To get a list of Facilities:  Issue a GET call to https://qaapi.blub0x.com/api/v1/Facilities (for development) or https://api.blub0x.com/api/v1/Facilities (for Production)
3. Conditional: To get a list of Occupancies: Issue a GET call to https://qaapi.blub0x.com/api/v1/Occupancies?IncludeDeleted=false (for development) or https://api.blub0x.com/api/v1/Occupancies?IncludeDeleted=false  (for Production)
4. Optional: To get a list of AccessLevels: Issue a GET call to https://qaapi.blub0x.com/api/v1/AccessLevels (for development) or https://api.blub0x.com/api/v1/AccessLevels  (for Production)
5. Optional: To get a list of AccessLevelGroups: Issue a GET call to https://qaapi.blub0x.com/api/v1/AccessLevelGroups (for development) or https://api.blub0x.com/api/v1/AccessLevelGroups  (for Production)
6. Optional: To get a list of Roles: Issue a GET call to https://qaapi.blub0x.com/api/v1/Roles (for development) or https://api.blub0x.com/api/v1/Roles  (for Production)
7. Optional: To get a list of Card Types: Issue a GET call to https://qaapi.blub0x.com/api/v1/CardTypes (for development) or https://api.blub0x.com/api/v1/CardTypes  (for Production)

Once each of the above calls is completed, their data should be placed in the working table for the DB Integration (Working Database) for reference in future API calls that require Primary Key identifiers from BluSKY.  Some care should be taken as you may have additional columns you wish to store (such as the Primary Key identifiers from the Source Database), thus you don’t want to necessarily purge and repopulate the Working Database tables, but rather do an intelligent Update operation to it.

3.2 Running Logic

3.2.1 Overview

Based upon the frequency in the configuration information, similar logic to the following should run every x minutes (as configured):

DB Interface will read from its “working” database the last time that it ran.  This will be used to determine which rows might have changed in the Source Database since the last execution.

The DB Interface main function will connect to the Source Database server (using configuration information) and query for all rows whose “last changed date” value exceeds the last time the DB Interface ran (as retrieved above).

For all rows whose “last changed” value exceeds the last-ran value:

---------------------------------

Look in the Working Database and see if there is a row with the same EmployeeID field (or other unique identifier that is designated).

If there is NOT a matching Working Database field, then this is a new record:

• Generate a hash of all the fields listed in Appendix B
• Create a new row in the Working Database with the EmployeeID, the hash value, ManuallyDeletedDateTime = null, and the current datetime
• Call the BluSKY WebAPI to add this person (see section 3.2.2 Adding A Person Via WebAPI)
• Take the returned User Id from the API call and add it to your Working Database table to map the original EmployeeId/Unique Identifier to the BluSKY Primary Key

If there is already a matching Working Database field, then this is an existing record and we might need to update it. 

• Generate a hash of all columns in the Source Database record that are contained in Appendix B
• If the generated hash is different than the hash stored in the Working Database AND
  ManuallyDeletedDateTime is null, then:
  • Update the hash in the Working Database to new hash value
  • Follow procedures in 3.2.3 Updating A Person Via WebAPI

After running through all existing rows in Source Database, the DB Integration Application will compare all rows that currently exist in the Working Database with hash codes and see if there are still rows in the Source Database that match the employee id for that row in the Working Database.  If there is not a corresponding row in Source Database, then this will count as a terminated employee and the DB Integration shall remove this row from the Working Database and update the personnel record in BluSKY with an EndDateTime = now – 1 day and/or Delete the record (as determined by business policy.)

3.2.2  Adding A Person Via WebAPI

If you have more than one office location/Occupancy that you are dealing with - Start by looking at the Source Database field which indicates where the person works and find the corresponding ACSystemId, FacilityId, and OccupancyId values from your Working Database that helps map these items.

If there is a value not contained in your mapping table, then ignore this row and send an error to your application development team indicating that there are unmapped work locations.

Next, look at the EmployeeId field (or another unique identifier) to determine that this record can be uniquely identified.  If the value is not unique then ignore this row and send an error to your application development team indicating that there are missing unique identifiers for this person.

We should now be able to add the person:

AddUser method of API: https://knowledge.blub0x.com/Web_API/Person/AddUser

• FirstName = GivenName (Source Database)
• LastName = Surname (Source Database)
• MiddleInitial = Middle Initial (Source Database)
• sGenderId = 1 = Male, 2 = Female, 3 (Unspecified Gender)
• DefaultFloorId = xxx
• DefaultFloorStopId = xxx
• FacilityId = FacilityId for the Facility that matches in the Working Database’s mapping table
• CompanyInstanceType = 1 (Occupancy)
• CompanyInstanceId = OccupantId for the Occupancy that matches in the Working Database’s mapping table
• ACSystemId = ACSystemId for the System that matches in the Working Database’s mapping table
• StartDateTime = Employment Start Date (Source Database) or null.  If populated, the person’s access will not become valid until AFTER this value.
• EndDateTime = Employment End Date (Source Database) or null.  If populated, the person’s access will not be valid AFTER this value.
• AccessRightsSuspended (bool) = False if Source Database indicates this record is active
• AccessRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
• AccessRightsSuspendedEnd = null
• WebSiteRightsSuspended (bool) = False if Source Database indicates this record is active WebSiteRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
• WebsiteRightsSuspendedEnd = null
• BadgeTemplateId = EmployeeBadgeTemplateId or ConsultantBadgeTemplateId from configuration settings based appropriate business logic
• Employee Number = Employee Number from Source Database
• HasLoginRights = True for anyone that needs to login to BluSKY to administer or if they will need to request visitors, etc.
• Job Title = Title from Source Database
• Photo = To be handled in another thread.  See 3.3 Photo Population
• Deleted = false unless you are adding inactive people from the Source Database (Terminated Employee)

This method returns the PersonId that was assigned by the database to the Person that was just created.  Optionally, you can pass the PersonId as a parameter to the above function.

Once the record is created via the WebAPI, BluSKY will automatically apply any appropriate Access Levels and Roles depending on which Occupancy they were placed in (based on Apply-By-Default attributes of those ALs and Roles).

If additional Access Levels are required based on other business logic (such as department or other fields in the Source Database), then please refer to section 3.2.4 Adding Access Levels.

If additional Roles are required based on other business logic (such as department or other fields in the Source Database), then please refer to section 3.2.5 Adding Roles.

AddUserContactItem: https://knowledge.blub0x.com/Web_API/Person/AddUserContactItem

This will be called twice. Once for the email address:

• UserId = Person Object PersonId as returned from the AddUser method
• ContactType = WorkEmail
• Value = Primary work email address from Source Database
• IsDefault = true

Once for the Phone Number

• UserId = Person Object PersonId as returned from the AddUser method
• ContactType = WorkPhone
• Value = Office Phone from Source Database
• IsDefault = true

For the add methods, the Person Audit tables will automatically be populated with appropriate information.

3.2.3  Updating A Person Via WebAPI

If you have more than one office location/Occupancy that you are dealing with - Start by looking at the Source Database field which indicates where the person works and find the corresponding ACSystemId, FacilityId, and OccupancyId values from your Working Database that helps map these items.

If there is a value not contained in your mapping table, then ignore this row and send an error to your application development team indicating that there are unmapped work locations.

This will determine which building and occupancy the record will need to be in.  If this differs, we will have to “move” the record from one occupancy to another.

If the OccupancyId value has changed:

• This may also result in having to programmatically change any Access Levels that were previously applied automatically depending on if the person had those applied.
  • If this is desired, then:
    • Remove all programmatically added Access Levels using the
      RemoveAccessLevel method here:
      • https://knowledge.blub0x.com/Web_API/Person/RemoveAccessLevel
    • Remove all programmatically added Roles using the RemoveUserRole method here:
      • https://knowledge.blub0x.com/Web_API/Person/RemoveUserRole
    • Add the appropriate Access Level by calling the AddAccessLevel method here:
      • https://knowledge.blub0x.com/Web_API/Person/AddAccessLevel
    • Add the appropriate Role by calling the AddUserRole method here:
      • https://knowledge.blub0x.com/Web_API/Person/AddUserRole

Next, look at the EmployeeId field (or other unique identifier) to determine that this record can be uniquely identified.  If the value is not unique then ignore this row and send an error to your application development team indicating that there are missing unique identifiers for this person.

We should now be able to update the person:

UpdateUser method of API: https://knowledge.blub0x.com/Web_API/Person/UpdateUser

• FirstName = GivenName (Source Database)
• LastName = Surname (Source Database)
• MiddleInitial = Middle Initial (Source Database)
• sGenderId = 1 = Male, 2 = Female, 3 (Unspecified Gender)
• DefaultFloorId = xxx
• DefaultFloorStopId = xxx
• FacilityId = FacilityId for the Facility that matches in the Working Database’s mapping table
• CompanyInstanceType = 1 (Occupancy)
• CompanyInstanceId = OccupantId for the Occupancy that matches in the Working Database’s mapping table
• ACSystemId = ACSystemId for the System that matches in the Working Database’s mapping table
• StartDateTime = Employment Start Date (Source Database) or null.  If populated, the person’s access will not become valid until AFTER this value.
• EndDateTime = Employment End Date (Source Database) or null.  If populated, the person’s access will not be valid AFTER this value.
• AccessRightsSuspended (bool) = False if Source Database indicates this record is active
• AccessRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
• AccessRightsSuspendedEnd = null
• WebSiteRightsSuspended (bool) = False if Source Database indicates this record is active WebSiteRightsSuspendedStart = null if Source Database indicates this record is active, If “Enabled” = false, then now – 1 day
• WebsiteRightsSuspendedEnd = null
• BadgeTemplateId = EmployeeBadgeTemplateId or ConsultantBadgeTemplateId from configuration settings based appropriate business logic
• Employee Number = Employee Number from Source Database
• HasLoginRights = True for anyone that needs to login to BluSKY to administer or if they will need to request visitors, etc.
• Job Title = Title from Source Database
• Photo = To be handled in another thread.  See 3.3 Photo Population
• Deleted = false unless you are adding inactive people from the Source Database (Terminated Employee)

If either of the contact fields changes (OfficePhone or UserPrincipalName), then we will need to remove that contact item from the user first by calling RemoveUserContactItem (https://knowledge.blub0x.com/Web_API/Person/RemoveUserContactItem) and then re-adding it with the correct information:

AddUserContactItem: https://knowledge.blub0x.com/Web_API/Person/AddUserContactItem

This will be called twice.  Once for the email address:

• UserId = Person Object PersonId as returned from the AddUser method
• ContactType = WorkEmail
• Value = Primary work email address from Source Database
• IsDefault = true

Once for the Phone Number

• UserId = Person Object PersonId as returned from the AddUser method
• ContactType = WorkPhone
• Value = Office Phone from Source Database
• IsDefault = true