Schindler Elevator Integration to Access Expert

[JonGreen]

Issue

This is a project to support integration with the Schindler PORT system. It should be deployed on a customer site to directly connect to the Schindler PORT firewall and be configured to connect to the customer instance on the Access Expert (AX) side to add, update, or remove people from Schindler PORT based on which access levels they belong to in AX. 

Product Line

EcoStruxure Access Expert

Environment

Access Expert Hosted software

Cause

Please read all the instructions to properly deploy and configure this service.

Resolution

Card formats

The Schindler reader produces a 16-digit hexadecimal value after reading a card and sends it to the Schindler Port system for validation. The value from the Schindler reader is a different value from what is entered as the encoded card number in AX. Therefore, there needs to be an additional entry of the hexadecimal value in AX in the Hex Value field of a card assignment. The Hex Value will be sent to the Schindler Port system as the card number so that it matches with the Schindler reader value to get access.

To find out what the Hex Value needs to be, the process was to send Schindler 10 cards from a particular project then they get back to us with the correct hexadecimal representation of those cards. This will need to be done between you and Schindler for your project.

Prior to version 22.3.1 of the AX Schindler service, the service was used to encode the Encoded Card Number from AX using a 16-digit value of 0100000020000000, then replace the zeroes at the end with the hexadecimal representation of the Encoded Card Number. The service will still do that if no Hex Value is specified for a card but that may not be the correct encoding for your project.

In short, you need to enter the Hex Value of a card assignment in AX as the value that is generated by the Schindler card reader.

Deployment

The Schindler service is deployed using Docker. If you are using Windows, we recommend having WSL2 installed and enabled for Docker. The installer needs to pull the images for both Seq (for logging) and the Schindler service from the Docker hub.

The installer also needs to create a Docker network called ax-net.

1. To create the network, execute:
   1. docker network creates ax-net
2. To get the Seq image:
   1. docker pull datalust/seq
3. To get the Schindler service:
   1. docker pull feenics/feenics-keep-schindler
4. To install Seq (replace /path/to/seq/data with the actual path of a directory on disk, this is the linux notation):
   1. docker run -d --name seq --restart unless-stopped --network keep-net -e ACCEPT_EULA=Y -v /path/to/seq/data:/data -p 5341:80 datalust/seq
5. To install Schindler (env.txt is in the same directory where you are executing the docker run in this case):
   1. docker run -d --name feenics-keep-schindler --restart unless-stopped --network ax-net --env-file env.txt feenics/feenics-keep-schindler

Environment configuration

The following environment variables can be specified in a file (env.txt in the example above) that is passed to the container when launching it from Docker.

In the file, each of these properties will be followed by an equal sign then its value.

ClientInstance=

ClientUsername=

ClientEncryptedPassword=

ClientWSS=

ClientAddress=

Company=

TagName=

SchindlerServerIp=

SchindlerServerPort=

Below is the description of each property:

1. ClientInstance - the name of the client instance
2. ClientUsername - the username to login the client instance
3. ClientEncryptedPassword - the encrypted password obtained from the service password utility
4. ClientWSS - the address of the MQTT event publisher (for USA: wss://keepevents.feenicshosting.com/mqtt)
5. ClientAddress - the address of the API (for USA: https://keepapi.feenicshosting.com)
6. Company - the company name as configured in the PORT system
7. TagName - the tag name that will be assigned to the Schindler access levels in Access Expert
8. SchindlerServerIp - IP address of the Schindler PORT firewall
9. SchindlerServerPort - Port to use to connect to the Schindler PORT firewall

Password

The password in the environment configuration needs to be encrypted. The service has an embedded encryption utility. If you start the service with an additional parameter called "password", it will run the password encryption utility instead. Copy the encrypted password and add it to the configuration.

1. To run it, execute the following:
   1. docker run --rm -it --name feenics-schindler-utility feenics/feenics-keep-schindler password
      1. The --rm will remove this container after it exists so you do not have to delete it manually.

Permissions

The service user needs to have permission to read access levels, read people, read event messages and publish all Schindler event types.
This is done by creating a group that has those permissions and assigning that group to the service user in Access Expert. The service will monitor the changes in the current instance and all the instances below it in the hierarchy.

Operation

1. The Schindler PORT integration limits the configuration capabilities that can be performed from AX. We are able to add, update, or remove people from profiles in PORT.
2. The Schindler PORT system has profiles defined with particular access to certain floors. These profiles need to have access levels in AX with the exact same name as the profile in order to add, update, or remove people from these profiles in PORT automatically.
3. An access level matching a profile needs to be tagged with a tag name agreed upon and configured in the Schindler service (TagName).
4. A person can only be in ONE profile in the Schindler system. This means that a person can only be in one access level tagged for Schindler sync. If a person is in more than one Schindler tagged access level, only one of the access levels will be chosen.
5. If a person needs to have access to additional Schindler access levels, this needs to be performed from the Schindler system by defining a profile with all the required access and then adding an access level in AX with that profile name and Schindler tag.
6. The Schindler service listens to changes in people and checks if they belong to a Schindler tagged access level then sends an update to Shindler PORT (first name, last name, 3 card assignments, profile name, start and expiry date)
7. PORT only supports one start and expiry date for all three cards so we take the union of the three
8. The Schindler service also listens to changes in access levels that have the defined TagName, whether a Schindler tag was added or removed to either send or remove the people in that access level from the Schindler system
9. Warning: DO NOT delete an access level that has a Schindler tag. You need to remove the tag first in order for the service to know which updates it needs to send to PORT.
10. Schindler command and response numbers (logged in Seq)
11. The first three numbers in the command are an index, it is incremented with each command sent, and the PORT systems reply with the same command index.
12. The next two numbers are the command type or the reply type as follows:
    1. SendAlive = "00"
    2. SendAliveSuccess = "01"
    3. ChangeInsertPerson = "06"
    4. ChangeInsertPersonSuccess = "03"
    5. ChangeInsertPersonError = "07"
    6. DeletePerson = "08"
    7. DeletePersonSuccess = "05"
    8. DeletePersonError = "09"

Important

Add a permission restriction that an access level tagged with the Schindler tag cannot be deleted. This is important because we need to remove the people in Schindler PORT before deleting the access level. The workflow would be to delete the Schindler tag first, then you are allowed to delete the access level.

Recommendations

The enterprise should review all access levels tagged with the Schindler tag to audit the entities that are giving elevator access.
The enterprise creates the profile (access level) in the PORT system. If the tenant has a shared instance, the enterprise informs the tenant of the access level name and the Schindler tag to automatically send their people to the PORT system.