Skip to main content

Introduction to Entryfy Entities

Patrik Sjödin
  • Updated

 

Below will be a description of our entities defined in our protocol buffer files. 

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto

The first link for each entity is to the protocol buffer files for the service code for each entity that can be manipulated through the gRPC interface.

BizOperation

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L12

As Entryfy works in an asynchronous way we use BizOperations to track status of operations throughout our services. BizOperations can be sent over webhooks to communicate the process through an entity is going, this is configured when the organization account is created or BizOperations can be listened to over a gRPC stream. 

A BizOperation has several attributes which are important to take note of:

  • UUID is a unique identifier for the object. 
  • Kind is what type of action the BizOperation describes.
  • Status is in what state the action described in the BizOperation is in. 
  • Payload is the actual data that is being processed. Here the UUID submitted upon creation of an entity will be displayed. 

Organization

https://github.com/Entryfy/protobuffers/entryfy/org/api/v1/entities.proto#L82

An organization in Entryfy is an entity used to comprise users with certain hardware and assign access rights through user groups and schedules. 

Organizations can be hierarchical and does not necessary need to different customers but can be used to logically segment a company into different departments to delegate administration of users and hardware. 

  • UUID is a unique identifier for the object. If not set then the system will generate one. It is recommended that you set your own identifiers and keep track of them on your end.
  • Slug is used to namespace for which organization you wish to modify entities. This needs to be included in each API request.
  • Name is a descriptive text field that will be displayed in the mobile application after logging in for end. users. 
  • Maintenance is a boolean value which can be activated in case of misuse of the API to disable requests or usage of the API.
  • Active is a boolean to display if the current organization is enabled or disabled in the API.

User

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L92

A user in Entryfy is an organization member which can log in to either the mobile application and/or web interface based on their roles.

  • UUID is a unique identifier for the object. If not set then the system will generate one. It is recommended that you set your own identifiers and keep track of them on your end.
  • First & Last name is used to store the name of the user.
  • Email address is used to login to the system and is required to be valid to enable to reset passwords. 
  • Valid_from & Valid_to can be used to restrict the date & time a user is valid and can use their credentials to gain access through hardware. Be aware this is a start and stop rather than fine grained control to limit which hours a user can access a facility. That is controlled either by schedules in user groups or through use of Temporary Accesses.
  • Passcode is a unique generated PIN that be used as a credential if the user has access through a user group with PIN as authentication type. This is the preferred use of PIN instead of the Pincode entity which is to be used in combination with another authentication type such as a key card.
  • Qrcode is a unique generated hash that is represented as a QR code in the mobile application. These can be to gain access when combined with a Door Station that acts as a QR scanner. 
  • Status is which state the user is in at the moment. 
  • PostLoginScreenType is which screen should be the landing page when a user logs in to the mobile application. 
  • Pincode are the pin code(s) this user has generated upon creation for them or created themselves through the mobile application.
  • Keycards are physical access cards that was added upon creation for them or have registered themselves through the mobile application.
  • Role is which type of access rights a user should have when working with the system. It is divided in to three types;
    • Guest
    • User
    • Operator
    • Hardware Manager
    • Administrator

Pincode

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L131

A user in Entryfy gets an 4 digit pincode generated by default to their user upon creation. This pin code can be used for authentication if a user is in a user group with the authentication type pin code. Users can update or create their own pin code(s) through the mobile application. 

  • UUID is a unique identifier for the object. If not set then the system will generate one. It is recommended that you set your own identifiers and keep track of them on your end.
  • Kind is used to trace if the pin code was either created upon creation of the user (DEFAULT) or if the pin code was generated by a user (CUSTOM).
  • Label is a description for the pin code, default label is Default for system generated pin codes.
  • Value is the value of the actual pin code.
  • Status is the life cycle state of the pincode. 

KeyCard

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L169

A user in Entryfy can be assigned a key card during the user creation process or they can register themselves through the mobile application to apply to doors which they have access to and permits key card authentication. 

  • UUID is a unique identifier for the object. If not set then the system will generate one. It is recommended that you set your own identifiers and keep track of them on your end.
  • Nr is the Card Number of the key card.
  • Value is the hexadecimal value of the card. This is what is transformed into a Card Number through the door controllers Card Format rules when a key card is presented against a reader. 
  • Label is a description for the pin code, default label is Default for system generated pin codes.
  • Status is the life cycle state of the key card.

Schedule

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L202

A schedule is used to define which times an access should allow access to the users with the chosen authentication types. 

  • UUID is a unique identifier for the object. If not set then the system will generate one. It is recommended that you set your own identifiers and keep track of them on your end.
  • Name is text field to name the schedule.
  • Description is a text field to describe the schedule.
  • Slug is only used to define default schedules that are on an Axis Door Controller hardware. This does not need to be defined. 
  • Schedule definition is where the RFC5445 structure should be submitted. This for when the user group should allow users to use the authentication types to enter a door.
  • Exception definition can be used to exclude when users in a user group should not be able to use authentication types to enter a door. This can be used to exclude holidays or vacation days from regular schedules definitions. 
  • Status is the life cycle state of the key card.
Notes on the implementation of schedules in Entryfy
 

The schedule syntax is based on RFC5545 (iCalendar) but the RFC5545 specification is quite extensive and only the subset that is relevant, see below:

  • Only local time is used.

  • No support for UTC time

  • No support for VTIMEZONE

  • No support for VALARM

  • DTSTART;VALUE=DATE is converted to a 24h interval event

  • Overlapping RDATE /RRULE instances within a single VEVENT are undefined

  • The following RRULE parameters are supported:

    1. HOURLY, MINUTELY, SECONDLY

    2. DAILY

    3. WEEKLY, WEEKLY;BYDAY

    4. MONTHLY, MONTHLY;BYMONTHDAY

    5. YEARLY, YEARLY;BYMONTH

SecurityDevice

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L226

Security Devices is a way to logically segment the axis hardware. It is divided into several kinds, such as site, section, door controller (which is the actual hardware) and doors which are the software implementation in the door controller that handles access. Security Devices of the kind door is the one developers should use for when handling accesses through user groups. 

  • UUID is a unique identifier for the object. If not set then the system will generate one. It is recommended that you set your own identifiers and keep track of them on your end.
  • Parent_uuid is used to link a child to a parent. 
    • Sites can sections as children
    • Sections can  door controllers as children
    • Door controllers have doors as children
  • Name is text field to name the security device.
  • Description is a text field to describe the security device.
  • Kind is what type of security device
    • Site is used to logically segment sections into a geographical location
    • Section is used to segment door controllers into for example a floor or building at a Site. 
    • Door Controller is a Axis Door Controller hardware connected to Entryfy.
    • Door is a software representation of a door in the Axis Door Controller hardware, this is what is the type used to link users through a user group to a door.
  • Latitude  & Longitude is used to present sites on the map view under Access Logs in the Entryfy dashboard or to restrict Scan QR or Remote Open to only be used in the vicinity of the site. 
  • Max_radius defines how large radius we should allow when comparing a users GPS coordinates (through the mobile application) with the site defined when validating Scan QR or Remote Open.
  • Remote_access_enabled is used to define if remote access methods such as Remote Open should be allowed for hardware at the site.
  • Online is only used for door controllers to record if they are accessible through Axis One-Click Services.
  • Entry_qrcode & Exit_qrcode is an automatically generated string represented as a QR code in the administrative panel. This is used as an identifier for which door the user is trying to either open through Scan QR or trying to register a key card at. 
  • Preferences is a key/value store used to be able to store metadata about security devices to enable filtering for the developer. 

Accesses

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L451

An access is the way Entryfy handles giving users permissions to resources whether it is a physical lock for a door or a relay to control a function. In an access you can define which users have access to which doors during what times. You can also customize which authentication types users can be allowed when either entering or exiting through the door, gate, locker or storage unit. 

  • UUID is a unique identifier for the object. If not set then the system will generate one. It is recommended that you set your own identifiers and keep track of them on your end. 
  • Name is text field to name the access.
  • Description is a text field to describe the access.
  • Kind is whether the access is permanent or temporary. Temporary accesses are removed from the hardware once it expires to save resources of the embedded devices.
  • Valid_from defines from when the access should be valid.
  • Valid_to defines to the access should be valid. Required if kind is temporary. Will be removed from the hardware 60-90 minutes after it expires.
  • Schedule defines when the users should have access to the doors. 
  • AccessDoors contains a list of doors and allowed authentication types based on direction.
  • AccessUsers contains a list of users to be allowed to authenticate for the doors. 

Access Logs

https://github.com/Entryfy/protobuffers/blob/master/entryfy/org/api/v1/entities.proto#L322

Access logs are Entryfy representation of the Axis Door Controllers Event Log. These are fetched every 15 seconds from each device and are processed in the backend to perform notifications or display in the administrative dashboard.

  • AccessDescription describes if the access attempt was successful or not.
  • Section_uuid, site_uuid & security_device_uuid is to display for which security devices the access was logged.
  • User_uuid is which user attempted the access process.
  • Direction is to show from which direction the access process was initiated.
  • User_email & user_name is to display users attributes directly in the log messages for ease of presentation.
  • Pincode is to display which pincode was used in the access process.
  • AuthType is which authentication type was used for the access process.
  • Reason why request was denied

Comments

0 comments

Article is closed for comments.

Powered by Zendesk