This article describes how to configure the ARX Service, to enable integration between Smart ID Identity Manager, Physical Access and ARX.

ARX is an Access Control System provided by ASSA ABLOY and managed by a GUI and the service interacts with ARX through a web-based API. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in ARX.

For details on which data can be imported and exported from ARX, see About import and export to Physical Access.

Prerequisites

The following prerequisites apply:

Physical Access and the ASSA ARX service are deployed. See Deploy Smart ID.
ARX client version 4.1 is required.
The message queue server must be running.
If MIFARE card technology is used, the PACS MIFARE number must be available as raw data (not encrypted, truncated, or similar).
A working network connection to the connected physical access control systems (PACS) must be in place.

Configure ARX Service data fields

The ARX data is configured in the configuration table in the Physical Access database. All configuration is cached when the service starts so any configuration changes will require the service to be restarted in order to take effect.

Configure database

To connect to a PACS system:

Log in to Physical Access admin panel as an admin user.
All configured PACS connector services are listed, as well as Generic configurations to define the messaging queue.
Click on a system to do updates.
All database entries are listed.
To update an entry, click on the icon. Edit as needed and then click Update.
To create an entry, click on +Create. Select Group, enter Key, Value and Index, and then click Create.

group: messagingqueue

key	Data type	Required or Optional	Description
server	string	Required	IP Address of Message Queue Server. If it is installed on the local server then we can use localhost. If we are accessing this server remotely then need to mention IP address.
username	string	Required	Username of message queue server. Default value: “guest”
password	string	Required	Password of message queue server. Default value: “guest”
system	string	Required	Defines which messaging queue to be used, either "rabbitmq" or "azureservicebus". Default value: "rabbitmq"

group: general

key Data type Required or Optional Description

deleteUserOnNoEntitlement

string

Optional

Defines if the user shall be deleted if no active entitlement assignment are present for that user.

Valid values: true or false.

Default: true

deleteUserOnNoAccessToken

string

Optional

Defines if the user shall be deleted if no active access tokens are present for that user.

Valid values: true or false.

Default: true

heartbeatInterval

int

Optional

Heartbeat interval is the time difference between two successive heartbeats, and it is used to know if the system is in active (running) or in inactive (stopped) state.

Default value and minimum value: 60 seconds. If it is set less than 60 seconds, it will be considered as 60 seconds to update the status.

group: general

key

Data type

Required or Optional

Description

updatesPerPoll

int

Optional

The maximum number of messages read from the message queue.

Default: 100

group: webApi

key	Data type	Required or Optional	Description
baseUrl	string	Required	The base URL where to find the webApi of ARX. Example of baseUrl "https://localhost:5004"
username	string	Required	Username for authenticating to the ARX webApi.
password	string	Required	Password for authenticating to the ARX webApi.

group: card

key	Data type	Required or Optional	Description
defaultCardFormat	string	Required	A default card format in ARX, which all cards without an explicit mapping in cardFormatMappings will receive when exporting. Default: “Solid prox”
cardNumberIdentifierTypes	string	Required	A list of identifier types in AccessToken that can be used as card number for the cards. All cards that should be exported must have a value in at least one of the specified identifiers, otherwise a transfer error will be reported back to Physical Access. Default: “mifare”
encoding	string	Required	ARX supports different formats for the card number. If no value is specified, the card number will be sent as-is. The following values are valid: “EM-PROX” (default) “EM-PROX-HEX” All other values are treated as "send as-is".
length	string	Required	The length of the card number to send to ARX. If the card number is shorter than the specified length, then it will be padded with 0's. ARX supports card number lengths of maximum 10 digits. The card number length must not exceed the value 4294967295. Physical Access will throw an error if the card number exceeds this value.

Example

Example values for required fields of ARX:

Id	Group	Key	System	Value
1	general	updatesperpoll	Arx	100
2	webApi	baseUrl	Arx	https://localhost:5004
3	webApi	username	Arx	nexus
4	webApi	password	Arx	nexus
5	card	defaultCardFormat	Arx	Solid prox
6	card	cardNumberIdentifierTypes	Arx	Mifare
7	card	length	Arx	10
8	card	encoding	Arx	EM-PROX

group: cardFormatMappings

The ARX server has a set of card formats to which we can map, based on the identifier types that are configured in the setting cardFormatMappings.cardNumberIdentifierTypes. Each configured mapping has four different required parameters.

If no additional mapping exists, all cards will be exported using the default card format configured in card (see above). Each cardFormatMappings setting must have a unique index number as shown in the example below.

key	Data type	Required or Optional	Description
cardNumberIdentifierTypes	string	Required	A list of identifier types in AccessToken that can be used as card number for the cards. All cards that should be exported must have a value in at least one of the specified identifiers, otherwise a transfer error will be reported back to Physical Access.
format	string	Required	The format in ARX to map the card to. This setting is case sensitive on ARX.
encoding	string	Required	ARX supports different formats for the card number. If no value is specified, the card number will be sent as-is. The following values are valid: “EM-PROX” (default) “EM-PROX-HEX” All other values are treated as "send as-is".
length	string	Required	The length of the card number to send to ARX. If the card number is shorter than the specified length, then it will be padded with 0's. ARX supports card number lengths of maximum 10 digits. The card number length must not exceed the value 4294967295. Physical Access will throw an error if the card number exceeds this value.

Example

Example configuration for card format settings:

Id	Group	Index	Key	System	Value
1	cardFormatMappings	0	cardNumberIdentifierTypes	Arx	mifare
2	cardFormatMappings	0	format	Arx	Solid prox
3	cardFormatMappings	0	length	Arx	10
4	cardFormatMappings	0	encoding	Arx	EM-PROX
5	cardFormatMappings	1	cardNumberIdentifierTypes	Arx	magnetic stripe
6	cardFormatMappings	1	format	Arx	Solid prox
7	cardFormatMappings	1	length	Arx	10
8	cardFormatMappings	1	encoding	Arx

group: extraField

In addition to the standard fields, ARX can have extra fields for persons.

For each configured extraField, all properties defined below are required in the database.

key Data type Required or Optional Description

name

string

Required

The name of the extra field in ARX. This must match the name exactly of an extra field which is already configured in ARX.

The list of extraField names are located in the ARX menu bar in System > Extended fields for person. Use the value of the name column for this setting.

value

string

Required

The value to use for this field. This has two possible values depending on the value of the static property:

If static is true, then the value can be any string value and this will be used for all persons that are exported to ARX.
If static is false, then the value must refer to any of the following table fields:
- user.{name of column in user table}
- useradditionalfield.{type of field}
- address.{type of field}
- phone.{type of field}
- email.{type of field}

For more details see the example below.

static bool Required Set to true if a static value should be exported to ARX for all persons, or false if a user additional field is configured.

Example

Example configuration for extraFields:

Id	Group	Index	Key	System	Value
1	extraField	0	name	Arx	Title
2	extraField	0	value	Arx	user.title
3	extraField	0	static	Arx	false
4	extraField	1	name	Arx	PhoneNumber
5	extraField	1	value	Arx	phone.home
6	extraField	1	static	Arx	false
7	extraField	2	name	Arx	Department
8	extraField	2	value	Arx	IT
9	extraField	2	static	Arx	true

ARX field mapping

The service mainly transfers user data including related access tokens and entitlement assignments. The tables below show the default field mapping.

If needed, additional fields can be configured, using the SCIM API and extraFields in the database configuration.

User field mapping

By default, the following data is mapped between the USER table in the Physical Access and the ARX service:

SR No	Physical Access field (Web API)	ARX field (UI)
1	UserReferenceId column value of USER table	ID
2	givenName	First Name
3	FamilyName	Last Name
4	Pin	Pin Code
5	Ssn	Description

Access token field mapping

By default, the following data is mapped between the ACCESSTOKEN and ACCESSTOKENIDENTIFIER tables in the Physical Access and the ARX service:

SR No

Physical Access field (Web API)

ARX field (UI)

1

Based on configuration setting for card.

See more details in group: cardFormatMappings above.

Credentials > Credential Format

2

Default Configuration for cardFormat

Credentials > Credential Number

Entitlement assignment field mapping

By default, the following data is mapped between the ENTITLEMENTASSIGNMENT table in the Physical Access and the ARX service:

SR No	Physical Access field (Web API)	ARX field (UI)
1	DisplayName (entitlement-DisplayName)	Access Categories > Name

Restart ARX service

Restart service

Restart the ASSA ARX connector service:
Restart Physical Access with ASSA ARX connector
```
cd <SMARTIDHOME>/compose/physicalaccess
docker-compose restart smartid-pa-arx
```

This article is valid for Smart ID 21.10 and later.

Related information

Integrate physical access control system (PACS) with Identity Manager

Space shortcuts

Page tree

Visit Nexus to get an overview of Nexus' solutions, read customer cases, access the latest news, and more.

Prerequisites

Configure ARX Service data fields

group: messagingqueue

group: general

group: general

group: webApi

group: card

Example

group: cardFormatMappings

Example

group: extraField

Example

User field mapping

Access token field mapping

Entitlement assignment field mapping

Restart ARX service

Related information

Contact Nexus

Space shortcuts

Page tree

Visit Nexus to get an overview of Nexus' solutions, read customer cases, access the latest news, and more.

Set up integration with ASSA ARX

Prerequisites

Configure ARX Service data fields

group: messagingqueue

group: general

group: general

group: webApi

group: card

Example

group: cardFormatMappings

Example

group: extraField

Example

User field mapping

Access token field mapping

Entitlement assignment field mapping

Restart ARX service

Related information

Contact Nexus