if the record was changed in the meanwhile, we get a 412 Precondition Failed error due to the If-Match header. we do not need authentication for this request since it cannot lead to collisions with respect to ids.
4.1.4 Reading person master records
To read all person master records, simply perform GET on /persons:
© PCS Systemtechnik GmbH 25 DEXICON Enterprise Webservice-Interface V5.2.0
Example 4.4 – Reading person master records For https please use https://host-IP:8093/...
Request: GET http://localhost:8090/persons HTTP/1.1 Host: localhost:8090 Accept: application/xml Accept-Charset: UTF-8, *;q=0 TE: trailers Response: (Please note, that XML data is indented in the examples for improved readability. However, the Webservice-Interface does not pretty-print XML data in any way) HTTP/1.1 200 OK Connection: close Date: Tue, 10 Dec 2013 08:14:14 GMT Trailer: Content-MD5 Transfer-Encoding: chunked Server: AMS-Web-Interface/1.0.0 (DEXICON Enterprise) Content-Type: application/xml; charset=UTF-8 ETag: "6qsNnUBuj5gHPL8wleN6ig"
f91b /persons/EXAMPLE/456 001 [… data of person records …] 0 Content-MD5: 8OL7YkqGdM1aFHrtJriVrQ== We can apply several filters to our request: Attendance status, e.g. for creating an attendance panel. Client Chapter 5.2.1.5 describes the possibilities in detail.
4.1.5 Deletion of a person master record A person master record can be deleted by a bulk synchronization. Records which are not supplied are deleted implicitly. Chapter 5.2.1.3 describes this behavior.
performing DELETE on the person resource. Example 4.5 – Deletion of a person master record For https please use https://host-IP:8093/... DELETE http://localhost:8090/persons/EXAMPLE/456 HTTP/1.1 Host: localhost:8090 Authorization: Basic RVhBTVBMRTpQYXNzd29yZA== Again, we need authentication. You might want to consider disabling the record (see chapter 5.4.2.1) instead of deleting it, so that personal authorizations are not lost.
4.2 Accesses
GET /accesses returns all access records. Filters for date and person are available.
26 10/2019 4 - Protocol examples
Example 4.6 – Query all accesses from Darth Vader For https please use https://host-IP:8093/... GET http://myhost:8090/accesses?person=%2Fpersons%2FEXAMPLE%2F789 HTTP/1.1 Host: myhost:8090 Accept: text/csv Beside CSV, XML and HTML representations are supported. Chapter 5.2.4.1 describes the settings. Regardless of the format, each access record contains our id, so we can easily assign the accesses to the corresponding persons. The Webservice-Interface supports a bookmark-style mechanism so that it is possible to periodically poll for new access records. Example 4.7 – Query for all new accesses For https please use https://host-IP:8093/... The following request returns all accesses of our client, which we have not yet processed. GET http://myhost:8090/accesses/EXAMPLE/.recent HTTP/1.1 Host: myhost:8090 Accept: text/csv Every record has an id. To mark the records, which we have processed, as “read”, we use the following request: Example 4.8 – Mark access records as “read” For https please use https://host-IP:8093/... POST http://localhost:8090/accesses/EXAMPLE/.read HTTP/1.1 Authorization: Basic RVhBTVBMRTpQYXNzd29yZA== Content-Type: text/uri-list; charset=utf-8 Host: localhost:8090
/accesses/EXAMPLE/UX%2B%2F-A1c /accesses/EXAMPLE/UPVwqAAB /accesses/EXAMPLE/UPVs6AAA This request simply contains the record ids, which are URIs, in a list; each URI in a line. Please note that the bookmark mechanism works on a per-client basis and we need authentication to avoid that some other process marks access records as read which we have not processed yet.
4.3 Attendance states DEXICON Enterprise maintains the following distinct attendance states for each person: Attendance according to time recording (at work, absent, off-site work, unknown). Spatial attendance. DEXICON Enterprise evaluates access records to defer in which area a person is attendant. Maintaining the spatial attendance is only possible for tracking areas.
4.3.1 Get attendance states Attendance states can be queried for both, a single person as well as collections of persons. This example demonstrates the latter case. Chapter 5.2.1.4 describes how to get the attendance status of a certain person. Example 4.9 – Get all persons who are attendant in Cloud City We want to get all persons, who are attendant in Cloud City. As a prerequisite, we need the URI of Cloud City, which is a tracking area (see chapter 5.2.2.3 for details): For https please use https://host-IP:8093/...
© PCS Systemtechnik GmbH 27 DEXICON Enterprise Webservice-Interface V5.2.0
GET http://localhost:8090/areas?purpose=tracking HTTP/1.1 Host: localhost:8090 Accept: text/csv Response: HTTP/1.1 200 OK Connection: close Date: Tue, 08 Apr 2014 09:39:10 GMT Trailer: Content-MD5 Transfer-Encoding: chunked Server: AMS-Web-Interface/1.0.0 (DEXICON Enterprise) Content-Disposition: attachment; filename=Areas.csv Content-Type: text/csv; charset=UTF-8; header=present
24e area,area-name /areas/vSdXNaubezQ,Alderaan /areas/B_hSSc62dus,Cloud City /areas/6N3segCsU-k,Death Star /areas/Ixwg_x6nqMo,Tatooine […]
0
Now we can issue the actual request: GET http://localhost:8090/persons?acStatus=%2Fareas%2F6N3segCsU-k HTTP/1.1 Host: localhost:8090 Accept: text/uri-list
Please note, that this request specifies text/uri-list as return media type, so that we do not get complete master records but only their URIs. If we got all person master records in a previous request, this is sufficient and reduces traffic. Response: HTTP/1.1 200 OK Connection: close Date: Tue, 08 Apr 2014 09:58:51 GMT Transfer-Encoding: chunked Server: AMS-Web-Interface/1.0.0 (DEXICON Enterprise) Content-Type: text/uri-list; charset=UTF-8 ETag: "5I1kULpJ+KI0+n9mb+xySw"
109 # URLs of person master records. Source URL: /persons # Use these URLs to get the master records or request the # media type application/xml # from this URL to get all relevant master records # /persons/DEXICON/4LrbLH /persons/EXAMPLE/123 /persons/EXAMPLE/789 […]
0
Now we know, that Luke Skywalker (URI /persons/EXAMPLE/123) and Darth Vader (URI /persons/EXAMPLE/789) are attendant at Cloud City.
If we want to monitor who is attendant at Cloud City, we can use the ETag in our next request: GET http://localhost:8090/persons?acStatus=%2Fareas%2F6N3segCsU-k HTTP/1.1 Host: localhost:8090 Accept: text/uri-list If-None-Match: "5I1kULpJ+KI0+n9mb+xySw" Response (provided, nothing changed): HTTP/1.1 304 Not Modified Connection: close Date: Tue, 08 Apr 2014 10:13:40 GMT Server: AMS-Web-Interface/1.0.0 (DEXICON Enterprise) ETag: "5I1kULpJ+KI0+n9mb+xySw"
28 10/2019 4 - Protocol examples
4.3.2 Set attendance states Attendance states are set per-record. Luke Skywalker left Cloud City through a chute. Therefore, his attendance status is unknown: Example 4.10 – Set attendance status of Luke Skywalker to “unknown” For https please use https://host-IP:8093/... PUT http://localhost:8090/persons/EXAMPLE/123/acStatus HTTP/1.1 Host: localhost:8090 Content-Length: 3
unk Chapter 5.2.1.4 describes the supported attendance state values.
© PCS Systemtechnik GmbH 29
5 - REST API reference
5 REST API reference
The following table summarizes the resources REST API of the Webservice-Interface. The resources are detailed in chapter 5.2. Please pay attention to the different media types since they may differ in the extend of provided data. As a rule of thumb use the XML media types to get most information.
Resource Methods /administration-units GET Returns all administration units which are defined in DEXICON Enterprise. /areas GET Returns all areas which are defined in DEXICON Enterprise. /companies GET Returns all companies which are defined in DEXICON Enterprise. /doors GET, POST Returns all doors which are available in DEXICON Enterprise and provides the possibility to release doors. /{id}/single-release POST Releases the corresponding door for a single entrance. /{id}/permanent-release POST Releases the corresponding door for a certain time or unlimited. /intuscom-admin-units GET Returns all administration units which are defined in INTUS COM. /readers GET Returns all readers which are available in DEXICON Enterprise. /reader-function-groups GET Returns all authorization groups which are defined in DEXICON Enterprise. /roles GET Returns all person roles which are defined in DEXICON Enterprise. /subsystem-groupings GET Returns all organization units which are defined in DEXICON Enterprise. /time-models GET Returns all time models which are defined in DEXICON Enterprise. Master records /base-supply/{source system}/{tid} PUT Bulk synchronization of person master records. /persons GET Returns all person master records from DEXICON Enterprise. /{source system} GET Returns all person master records from the superordinate system identified by {source system}. /{id} GET, PUT, Create, read, update, delete on a person master record. DELETE /pin PUT Sets a person’s pin. /taStatus GET, PUT Read or set a person’s attendance status according to time recording. /acStatus GET, PUT
© PCS Systemtechnik GmbH 31 DEXICON Enterprise Webservice-Interface V5.2.0
Resource Methods Read or set a person’s attendance status according to access control.
Booking data /accesses GET Returns all accesses. /{source system} GET Returns all accesses which are made by persons whose master records belong to the superordinate system identified by {source system}. /.recent GET Returns all “recent” accesses, i.e. all accesses which have not been marked as “read”. /.read POST Marks accesses as “read”. /declined-accesses GET Returns all declines accesses – analogous to /accesses. /{source system} GET /.recent GET /.read POST /employee-expenditures GET Returns all employee expenditures – analogous to /accesses. /{source system} GET /.recent GET /.read POST /time-events GET Returns all time events, e.g. clock-in – analogous to /accesses. /{source system} GET /.recent GET /.read POST /declined-bookings GET Returns all declined time events and employee expenditures – analogous to /accesses. /{source system} GET /.recent GET /.read POST
Table 5.1 – Resources of the REST API Please note that the operations are subject to the restrictions mentioned in 5.1.1.2.
5.1 Basics
5.1.1 Support for multiple superordinate systems DEXICON Enterprise can be connected to multiple superordinate systems, e.g. HR and visitor management. Master record data from these systems in managed separately as well as the corresponding accesses and bookings. 5.1.1.1 Authentication The Webservice-Interface allows access to all data regardless of the superordinate systems. However, if access to data across the system boundaries could interfere, authentication is required.
32 10/2019 5 - REST API reference
In these cases, the user name is the name of the client. The password is configured in the ams.ini. The DEXICON Enterprise Installation Manual this file. Please be aware of the character set issues of HTTP Basic Authentication as described in 5.1.4.2. 5.1.1.2 Available actions Depending on the way a superordinate system is interfaced to DEXICON Enterprise, certain operations may not be available via the Webservice-Interface.
Interface Webservice- HR-PDC DEXICON internal Operation Interface Master records Create Read Update Delete Bulk synchronization Accesses Read Mark as read Declined accesses Read Mark as read Time recording bookings Read Mark as read Employee expenditures Read Mark as read Declined time recording and employee expenditures Read Mark as read
Table 5.2 – Restrictions depending on interface of superordinate system
5.1.2 HTTP/1.1 5.1.2.1 Compliance The Webservice-Interface is a HTTP/1.1 (RFC 2616) compliant HTTP server. More specifically, according to RFC 2616 chapter 1.2, the Webservice-Interface is “conditionally compliant”, e.g. due to the aspects described in the next paragraph. 5.1.2.2 Connection handling The Webservice-Interface does not support pipelining (RFC 2616, chapter 8.1.2.2) and persistent connections.
© PCS Systemtechnik GmbH 33 DEXICON Enterprise Webservice-Interface V5.2.0
In case of errors, the Webservice-Interface sends an appropriate response and closes the connection without waiting until the client has finished sending data. In such a situation, the reset packet which the server sends may erase the client’s unacknowledged input buffer before it has been processed by the HTTP application. In this situation it may appear to the client as if the Webservice-Interface closed the connection without any response. RFC 2616 describes this situation in chapter 10.4.
5.1.3 Unicode The Webservice-Interface supports Unicode. However, DEXICON Enterprise supports only codepoints from within the Basic Multilingual Plane (abbr. “BMP”). If the Webservice- Interface receives data which codepoints are not within the BMP, these codepoints are replaced with the replacement character. DEXICON Enterprise normalizes all data to the Unicode Normalization Form C (abbr. “NFC”).
5.1.4 Character sets If not otherwise noted, the following character sets are supported: ISO-8859-1 UTF-8 UTF-16 UTF-16LE UTF-16BE 5.1.4.1 Byte order marks Please note in case of XML media types the requirements in RFC 3023 chapter 4 relating to Byte Order Marks (abbr. “BOM”): “Section 4.3.3 of [XML] specifies that XML MIME entities in the charset "utf-16" MUST begin with a byte order mark (BOM), which is a hexadecimal octet sequence 0xFE 0xFF (or 0xFF 0xFE, depending on endian). The XML Recommendation further states that the BOM is an encoding signature, and is not part of either the markup or the character data of the XML document. Due to the presence of the BOM, applications that convert XML from ‘utf-16’ to a non- Unicode encoding MUST strip the BOM before conversion. Similarly, when converting from another encoding into ‘utf-16’, the BOM MUST be added after conversion is complete. In addition to the charset ‘utf-16’, [RFC2781] introduces ‘utf-16le’ (little endian) and ‘utf-16be’ (big endian) as well. The BOM is prohibited for these charsets. When an XML MIME entity is encoded in ‘utf-16le’ or ‘utf-16be’, it MUST NOT begin with the BOM but SHOULD contain an encoding declaration. Conversion from ‘utf-16’ to ‘utf-16be’ or ‘utf- 16le’ and conversion in the other direction MUST strip or add the BOM, respectively.” 5.1.4.2 HTTP-Authentication There is no standard for how to encode characters in Basic Authentication which is required for certain operations. The Webservice-Interface interprets characters according to ISO-8859- 1.
34 10/2019 5 - REST API reference
5.1.4.3 URIs URIs are ASCII coded. However, by the use of percent encoding (e.g. the character “/” is encoded as “%2F”), it is possible to encode characters which are outside of the ASCII scope. The Webservice-Interface interprets such characters according to UTF-8.
5.1.5 Reliable transport If the Webservice-Interface talks to a HTTP/1.1 client, it sends data with chunked transfer coding. Optionally, if the TE: trailers header is given, the Content-MD5 header field in the trailer provides a checksum of the transmitted data.
If the Webservice-Interface receives messages which contain the Content-MD5 header it will use this checksum to verify the received data. Since the Webservice-Interface adheres to REST principles, no special client-side transaction handling is necessary.
5.1.6 Optimistic locking and caching
For certain resources, the Webservice-Interface supports ETags for optimistic locking caching.
The documentation of the respective REST method tells you whether ETags are supported.
5.1.7 Media type negotiation Several resources support more than one media type. Both ways of media type negotiation is supported:
server-driven, by using the Accept HTTP header
agent-driven, by using the query parameter forceType. The supported values for forceType are part of the REST method documentation below. If no media type is specified, a default is used. Since the default can change between different versions, please always specify the media type and do not rely on a certain undocumented behavior.
5.2 REST methods
5.2.1 Person master records
All person master record data is located under the base path /persons. The resources are subdivided by source system under the path /persons/{name of source system}. The URI of a person master record is /persons/{name of source system}/{id} where {id} is an identifier unique within the source system, e.g. a personnel number. Please see 5.1.4.3 how to encode identifiers with characters which cannot be ASCII encoded. 5.2.1.1 Operations on a single master record
HTTP Method GET, PUT, DELETE REST URI /persons/{source system}/{id}
A person master record is created and changed by a PUT on the respective URI: If the specified {id} does not exist, a new record is created. Otherwise, it will be changed. The {id} must have the same value as the domain-entity-id attribute (see chapter 5.4.2.2) of the enclosed entity.
© PCS Systemtechnik GmbH 35 DEXICON Enterprise Webservice-Interface V5.2.0
If you create a person master record, the {id} is a value of your choice which can be at most 40 characters long. As a rule of thumb, this is the ID of the person in your system, e.g. a personnel number or a UUID. Please keep in mind the encoding issues of URIs as described in 5.1.4.3. If a field of the enclosed entity is not set, a default value is used as described in chapter 5.4.2.6. Authentication Creating a person master record requires HTTP Basic Authentication as described in 5.1.1. Media type Person master records have the media type application/xml, see chapter 5.4.2.2. If an optional node is not set, a default value is used. Parameters None. Conditional requests The following HTTP headers are supported for conditional requests:
ETag (Remark: The ETag of a single person master record does not cover the associated attendance states.)
If-None-Match for GET requests
If-Match for PUT and DELETE requests Warnings In case of PUT requests, the Webservice-Interface sends Warning headers with warn-code 199 and a corresponding warn-text in the following situations: The subsystem-grouping field specifies an unknown organization unit. The license is exceeded. 5.2.1.2 Setting the PIN of a single master record
HTTP Method PUT REST URI /persons/{source system}/{id}/pin
A pin can only be set. Valid pins consist of four decimal digits. Example 5.1 – Setting the PIN of a person For https please use https://host-IP:8093/... PUT http://localhost:8090/persons/DEXICON/4LrbLH/pin HTTP/1.1 Content-Type: text/plain; charset=ISO-8859-1 Host: localhost:8090 Content-Length: 4
1234 All terminals and ACMs always decline the pin “0000”. Consequently you can use this value as a secure default if a person has no pin. Media type Pins are transmitted as plain text with the media type text/plain (RFC 2046). The character sets ISO-8859-1 and UTF-8 are supported. Conditional requests Not supported since this could leak information about the current pin.
36 10/2019 5 - REST API reference
5.2.1.3 Bulk synchronization
HTTP Method PUT REST URI /base-supply/{source system}/{transaction-id} A so called “base supply” consists of all master records of the leading system, as identified by {source system}: If a master record is part of a base supply but does not exist in DEXICON Enterprise, it is created. If a master record is not part of a base supply but exists in DEXICON Enterprise, it is deleted. If a master record is part of a base supply and exists in DEXICON Enterprise, it is updated. However, only the fields specified in the ams.ini (see below) are updated. Therefore, a base supply provides a simple way for synchronizing data.
The {transaction-id} is a unique id of your choice, e.g. a UUID, for the submitted base supply. The Webservice-Interface logs this id so that problems with base supplies can be traced. Authentication This method requires HTTP Basic Authentication as described in 5.1.1. Media type Person master records have the media type application/xml, see chapter 5.4.2.3. Please note that only those fields are accepted and updated, which are configured for the corresponding source system in the ams.ini. Moreover, you can define defaults in the ams.ini for most fields. The DEXICON Installation Manual describes this setting; chapter 5.4.2.5 contains the supported fields. Parameters None. Conditional requests Not supported. Warnings The Webservice-Interface sends Warning headers with warn-code 199 and a corresponding warn-text in the following situations: The subsystem-grouping field of a record specifies an unknown organization unit. The license is exceeded. Master records are deactivated due to duplicate badge numbers. 5.2.1.4 Attendance status
HTTP Method GET, PUT REST URI /persons/{source system}/{id}/{type of status} For each person, there is an attendance status according to time recording and an attendance status according to access control. You can query and set both states with the above mentioned URI. {type of status} may be
taStatus: attendance according to time recording
acStatus: attendance according to access control
© PCS Systemtechnik GmbH 37 DEXICON Enterprise Webservice-Interface V5.2.0
Example 5.2 – Query the attendance status (access control) of a single person For https please use https://host-IP:8093/... Request: GET http://localhost:8090/persons/DEXICON/4LrbLH/acStatus HTTP/1.0 Response: HTTP/1.1 200 OK Connection: close Date: Mon, 07 Apr 2014 08:50:42 GMT Server: AMS-Web-Interface/1.0.0 (DEXICON Enterprise) Content-Type: text/plain; charset=UTF-8
unk
unk means, that the attendance status of the person is currently unknown, as described below. If you want to get the states of multiple persons, you might want to use the collection queries described in 5.2.1.5. Example 5.3 – Set the attendance status (access control) of a single person For https please use https://host-IP:8093/... The following request sets the attendance status of a person to a certain area, identified by its URI. Chapter 5.2.2.3 describes how to get the available areas. PUT http://localhost:8090/persons/DEXICON/4LrbLH/acStatus HTTP/1.1 Host: localhost:8090 Content-Length: 18
/areas/eN7nxF_CuzM Media type The states are set and returned with the media type text/plain where the charset is either UTF-8 or ISO-8859-1. The supported values depend on the type of the status: Time recording:
att: Attendant abs: Absent off: Off-site work brk: Break unk: Status unknown Access control:
abs: Absent unk: Status unknown The URI of any tracking area. Chapter 5.2.2.3 describes how to get the available URIs. Parameters None. Conditional requests Not supported. 5.2.1.5 Collections of person master records
HTTP Method GET REST URIs /persons /persons/{source system} Chapters 4.1.4 and 4.3.1 provide examples.
38 10/2019 5 - REST API reference
Media types Collections of person master records are available as
application/xml, see chapter 5.4.2.4.
text/uri-list, see RFC 2483 Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=xml: Returns a document of media type application/xml. forceType=uri-list: Returns a document of media type text/uri- list. acStatus Filters person master records by attendance statuses according to access control. The filter can be a comma-separated list which may include the following attendance statuses: att: Attendant abs: Absent unk: Status unknown Example: acStatus=att,unk would return the records of all persons who are attendant or whose status is unknown. the URI of a tracking area, optionally followed by the parameter recursive. Chapter 5.2.2.3 describes how to get the available tracking area URIs. Example 1: acStatus=%2Fareas%2FMQRMAwAAUNAAMDl would return the records of all persons which are attendant in the corresponding area. Example 2: acStatus=%2Fareas%2FMQRMAwAAUNAAMDl;recursive would return the records of all persons which are attendant in the corresponding area and all subordinate areas. taStatus Like acStatus but for attendance statuses according to time recording. Attendance statuses: att: Attendant abs: Absent off: Off-site work brk: Break unk: Status unknown
Table 5.3 – Parameters of the persons collection resource Conditional requests For /persons, the following HTTP headers are supported for conditional requests: ETag
Remark: If the persons collection resource is filtered by attendance status, the ETag also covers the corresponding attendance states so that changes in the attendance states are reflected in the ETag.
If-None-Match
© PCS Systemtechnik GmbH 39 DEXICON Enterprise Webservice-Interface V5.2.0
5.2.2 Authorizations and building logic The Webservice-Interface provides access to following data sets: Administration units Roles Areas Time models Organization units Reader function groups Companies With the exception of organization units, these objects are identified by URIs. The DEXICON user manual describes the objects and their use. 5.2.2.1 Administration units
HTTP Method GET REST URIs /administration-units Administration units are identified by URIs like /administration-units/AE021X0C12. The second part of the URI is the id of the administration unit as seen in the DEXICON Client. An administration unit can have different purposes in DEXICON. For the HTTP-Interface the following purpose is relevant: Assignment to persons Example 5.4 – Query administration units which can be used to assign to persons Request: GET http://localhost:8090/administration-units?purpose=persons HTTP/1.0 Administration units are the base on which user authorizations in the DEXICON Client are restricted. They are irrelevant to access control and time recording. Media types The list of administration units is available as text/html
text/csv, see RFC 4180
application/xml, see chapter 5.4.3.2. Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document. purpose Filters administration units according to their purpose. The filter may contain the following value: persons: The administration unit can be assigned to persons.
Table 5.4 – Parameters of the administration units collection resources
40 10/2019 5 - REST API reference
5.2.2.2 Roles
HTTP Method GET REST URIs /roles Roles are identified by URIs like /roles/DE02100E45. The second part of the URI is the id of the role as seen in the DEXICON Client. Roles are the preferred concept of DEXICON Enterprise to assign rights for access control and time recording. Media types The list of roles is available as text/html text/csv, see RFC 4180
application/xml, see chapter 5.4.3.2. Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document.
Table 5.5 – Parameters of the roles collection resources 5.2.2.3 Areas
HTTP Method GET REST URIs /areas Areas are identified by URIs like /areas/eN7nxF_CuzM. An area can have different purposes in DEXICON. For the Webservice-Interface the following purposes are relevant: Tracking, i.e. maintenance of attendance states Assignment of authorizations Example 5.5 – Query areas which can be used to assign access authorizations For https please use https://host-IP:8093/... Request: GET http://localhost:8090/areas?purpose=ac HTTP/1.1 Media types The list of areas is available as text/html
text/csv, see RFC 4180
application/xml, see chapter 5.4.3.2. Parameters Parameter Meaning
© PCS Systemtechnik GmbH 41 DEXICON Enterprise Webservice-Interface V5.2.0
forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document. purpose Filters areas according to their purpose. The value is a comma- separated list which may contain the following values: auth: The area can be used for assigning authorizations to persons. No distinction is made between authorizations for access control and time recording. Therefore, the returned URIs can be used in access- auth/area and time-recording-auth/area elements. ac: The area can be used for assigning access authorizations to persons. Therefore, the returned URIs can be used in access- ac/area elements. ta: The area can be used for assigning time recording authorizations to persons. Therefore, the returned URIs can be used in time- recording-auth/area elements. tracking: The returned areas are tracking areas. Therefore, the returned URIs can be used for querying and setting attendance statuses, see chapters 5.2.1.4 and 5.2.1.5. If multiple filters are applied, they are and-ed.
Table 5.6 – Parameters of the areas collection resources 5.2.2.4 Time models
HTTP Method GET REST URIs /time-models Time models are identified by URIs like /time-models/-7xMaSpNW64. A time model can have different purposes in DEXICON. For the Webservice-Interface, the only relevant purpose is assignment of authorizations. Media types The list of time models is available as text/html text/csv, see RFC 4180
application/xml, see chapter 5.4.3.4 Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document. purpose Filters time models according to their purpose. The value is a comma- separated list which may contain the following values: auth: The time model can be used for assigning authorizations to persons. No distinction is made between authorizations for access control and time recording. Therefore, the returned URIs can be
42 10/2019 5 - REST API reference
used in access-auth/time-model and time-recording-auth/time- model elements. ac: The time model can be used for assigning access authorizations to persons. Therefore, the returned URIs can be used in access- auth/time-model elements. ta: The time model can be used for assigning time recording authorizations to persons. Therefore, the returned URIs can be used in time-recording-auth/time-model elements. If multiple filters are applied, they are and-ed.
Table 5.7 – Parameters of the time-models collection resources 5.2.2.5 Organization units
HTTP Method GET REST URIs /subsystem-groupings Media types The list of organization units is available as text/html text/csv, see RFC 4180
application/xml, see chapter 5.4.3 Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document.
Table 5.8 – Parameters of the subsystem-groupings collection resources 5.2.2.6 Reader function groups (Authorization groups)
HTTP Method GET REST URIs /reader-function-groups Reader function groups are identified by URIs like /reader-function-groups/-wtqgXrzAAI. Authorization groups are created in the DEXICON Client automatically by the HR-PDC interface. Due to technical reasons, this collection resource only list authorization groups which are created in the DEXICON Client. However, if you are processing person master records, your client must be able to handle authorization groups which are not part of this resource. Media types The list of reader function groups is available as text/html text/csv (see RFC 4180)
application/xml, see chapter 5.4.3.6
© PCS Systemtechnik GmbH 43 DEXICON Enterprise Webservice-Interface V5.2.0
Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document.
Table 5.9 – Parameters of the reader-function-groups collection resources 5.2.2.7 Companies
HTTP Method GET REST URIs /companies Companies are identified by URIs like /companies/dOa2AkxUM_A. Media types The list of companies is available as text/html text/csv (see RFC 4180)
application/xml, see chapter 5.4.3.7 Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document.
Table 5.10 – Parameters of the companies collection resources
5.2.3 Infrastructure The Webservice-Interface provides access to following data sets: INTUS COM administration units Readers Doors Please use the INTUSCOM-Monitor to configure these items. 5.2.3.1 INTUS COM administration units
HTTP Method GET REST URIs /intuscom-admin-units The resource provides a XML document which contains information about INTUS COM administration units and the readers which are assigned to them. Both, INTUS COM administration units and readers are managed in INTUSCOM-Monitor Media types The information is available as
44 10/2019 5 - REST API reference
application/xml, see chapter 5.4.4.1 Parameters None. 5.2.3.2 Readers
HTTP Method GET REST URIs /readers Readers are identified by URIs like /readers/000400. The second part of the URI is the reader number as seen in the DEXICON Client and INTUSCOM-Monitor. Readers are managed in INTUSCOM-Monitor Media types The list of readers is available as text/html text/csv (see RFC 4180)
application/xml, see chapter 5.4.4.2 Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document.
Table 5.11 – Parameters of the readers collection resources 5.2.3.3 Doors
HTTP Method GET REST URIs /doors /doors/{id} Doors are identified by URIs like /doors/000400. The second part of the URI is the number of the reader which controls the door as seen in the DEXICON Client and INTUSCOM-Monitor. Doors are managed in INTUSCOM-Monitor. Media types The single door resource is available as application/xml, see chapter 5.4.4.3. The list of doors is available as text/html text/csv (see RFC 4180)
application/xml, see chapter 5.4.4.3 Parameters for collection resource Parameter Meaning
© PCS Systemtechnik GmbH 45 DEXICON Enterprise Webservice-Interface V5.2.0
forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document.
Table 5.12 – Parameters of the doors collection resources
Releasing a door for a single entrance HTTP Method POST REST URI /doors/{id}/single-release
A single door release takes no parameter. The duration of the release is determined be the reader’s parameter setting. Example 5.6 – Releasing a door for a single entrance For https please use https://host-IP:8093/... POST http://localhost:8090/doors/010101/single-release HTTP/1.1 Content-Type: text/plain; charset=ISO-8859-1 Host: localhost:8090 Content-Length: 0
Please note that a 2xx response does not imply that a door is effectively released. If you need to monitor the door state, please use the status elements of the corresponding door resource. Releasing a door for a longer time HTTP Method POST REST URI /doors/{id}/ permanent-release There are several ways for a permanent door release: Specifiying a timer in tenths of seconds Starting and stopping without timer The mode is passed as plain text in the body of the request: Number in [1;9999]: Release the door for the number of tenth of seconds
unlimited: Releases the door without expiration.
stop: Undoes a door release. Example 5.7 – Releasing a door for 1 minute For https please use https://host-IP:8093/... POST http://localhost:8090/doors/010101/permanent-release HTTP/1.1 Content-Type: text/plain; charset=ISO-8859-1 Host: localhost:8090 Content-Length: 3
600
Please note that a 2xx response does not imply that the command is executed as expected. If you need to monitor the door state, please use the status elements of the corresponding door resource.
46 10/2019 5 - REST API reference
5.2.4 Booking data The Webservice-Interface provides access to following data sets: Accesses Declined accesses Time recording bookings Employee expenditure bookings Declined time recording and employee expenditure bookings These data sets are available in distinct collections which can be filtered. The collections are subdivided by clients and by records which are recent and those which have already been marked as “read”. This features allows secure subsequent read operations without duplicates or data losses. DEXICON Enterprise automatically deletes booking data, when its retention period expires. Optionally, the deletion can be deferred until the record has been marked as “read” by another system. The DEXICON Enterprise User Manual describes the configuration of retention periods.
Each record has a URI: /{type}/{source system}/{id}
{type}: type of the booking (accesses, declined-accesses, time-events, employee- expenditures, declined-bookings)
{source system}: client of the master record to which the record refers. 5.2.4.1 Reading bookings
HTTP Method GET REST URIs /{type} /{type}/{source system} /{type}/{source system}/.recent where {type} may be accesses, declined-accesses, time-events, employee-expenditures, declined-bookings The URI /{type}/{source system}/.recent returns only “recent” bookings. A booking is considered “recent” if has not been marked as read. Chapter 5.2.4.2 describes how to mark a booking as read. Media types Booking data is available as text/html text/csv, see RFC 4180
application/xml, see chapter 5.4.4 Parameters Parameter Meaning forceType Agent-driven content negotiation: This parameter overrides the normally applied content negotiation based on the Accept header field: forceType=html: The data is returned as HTML document. forceType=csv: Returns a document of media type text/csv. forceType=xml: The data is returned as XML document. year Year (4 digits) at which the record was recorded.
© PCS Systemtechnik GmbH 47 DEXICON Enterprise Webservice-Interface V5.2.0
month Month (2 digits) at which the record was recorded. Requires that the year parameter is set. day Day of month (2 digits) at which the record was recorded. Requires that the year and month parameters are set. person If the person={master record URI} parameter is set, only those records are returned which refer to the given master record. Please note, that it might not be possible to assign records to persons.
Table 5.13 – Parameters of the booking collection resources Conditional requests Not supported. 5.2.4.2 Marking bookings as read
HTTP Method POST REST URI /{type}/{source system}/.read where {type} may be accesses, declined-accesses, time-events, employee-expenditures, declined-bookings You can mark bookings that you have already processed as “read”. The next time you load booking data via a /{type}/{source system}/.recent URI, you only get records which you have not marked as read. Chapter 4.2 provides an example. Authentication This method requires HTTP Basic Authentication as described in 5.1.1. Media types The Webservice-Interface expects an entity of type text/uri-list (RFC 2483). The character sets ISO-8859-1 and UTF-8 are supported. A single POST request may contain up to 1,200,000 URIs. Conditional requests Not supported. A record can be marked as “read” several times.
5.3 HTTP error codes The Webservice-Interface currently uses the following status codes as specified in RFC 2616.
Status code Description 100 Continue The Webservice-Interface supports client requests with the header Expect: 100-continue and answers appropriately. 200 Ok 201 Created Returned for base-supplies (see chapter 5.2.1.3) and if a single master record has been created (see chapter 5.2.1.1). 204 No Content The Webservice-Interface normally responds with this code if PUT, POST, or DELETE operations succeed. 304 Not Modified See RFC 2616, chapter 10.3.5.
48 10/2019 5 - REST API reference
400 Bad Request See RFC 2616, chapter 10.4.1. The Webservice- Interface includes an HTML page with an error description. 401 Unauthorized The request requires user authentication. Chapter 5.1.1 describes the cases which require authentication. 403 Forbidden The following operations are forbidden: Creating or deleting person master records for the client DEXICON or clients which are connected via another interface, e.g. HR-PDC. Therefore, base supplies for these clients are also forbidden. Marking time recording bookings or employee expenditures as read for HR-PDC or KK1 clients. 404 Not Found Self-explanatory. This status is also returned, if the resource exists but query parameters are invalid. The HTML error page contains an error description. 405 Method Not Allowed See RFC 2616, chapter 10.4.5. As required by the RFC, the Allow header contains a list of supported methods. 406 Not Acceptable The server-driven content negotiation failed with respect to the media type or the character set. The documentation of the corresponding resource contains the list of supported media types and character sets. This status is also returned, if the media range or list of character sets is invalid. If you cannot change the Accept header, you might want to use client-driven negotiation. See chapter 5.1.7 for details. 412 Precondition Failed The ETag given in the If-Match header does not match the current version. Please see RFC 2616, chapter 14.24 for a discussion. 413 Request Entity Too Large See RFC 2616, chapter 10.4.14. If marking bookings as read fails with this status code, please see chapter 5.2.4.2 for limitations on the maximum number of booking URIs. 414 Request URI Too Large The Webservice-Interface supports URIs up to 1,000 characters. 415 Unsupported Media Type See RFC 2616, chapter 10.4.16. The documentation of the REST methods contains for each resource a list of supported media types. 417 Expectation failed Currently, the only accepted Expect header value is 100-continue. 500 Internal Server Error Presumably a bug in the Webservice-Interface or inconsistent data in the database. 501 Not Implemented Unsupported Transfer-Encoding (supported: chunked) or HTTP method (supported: DELETE, GET, POST, PUT). 503 Service Unavailable The Webservice-Interface could not access the DEXICON database due to the following reasons:
© PCS Systemtechnik GmbH 49 DEXICON Enterprise Webservice-Interface V5.2.0
There is no connection to the database. The Webservice-Interface tries to reconnect every 20 seconds. The database is currently locked, see chapter 2.1. 505 HTTP Version Not Supported The Webservice-Interface currently supports HTTP/1.0 and HTTP/1.1.
Table 5.14 – HTTP status codes Future version may use further HTTP status codes.
5.4 XML Schemata DEXICON Enterprise validates XML data against corresponding XML schemata. However, please be advised, that if your client validates data received from the Webservice-Interface it might not be compatible with newer versions of DEXICON Enterprise.
All elements are in the namespace http://www.pcs.com/2014/dexicon. The XML schema files are available for download from the Webservice-Interface under /documentation.
Picture 5.1 – HTML page with XML schema documentation
5.4.1 Notation The following documentation contains pictures for describing XML schemata. These pictures should be quite self-explanatory. Please pay attention to the used grouping constructs:
Symbol Name Description
The sequence group requires that each element in the group sequence appears in the specified order.
50 10/2019 5 - REST API reference
all In case of an all group, the order of the elements is not important. Table 5.15 – Notation of groups in XML schemata
5.4.2 Master records 5.4.2.1 Basic type
Regardless of single records or collections, all person master records refer to personType:
Attribute
domain-entity-id
dx:selfdx:
dx:groupingdx:
personType dx:namedx:
DEXIC O N Enterprise master record dx:authenticationdx:
dx:authorizationdx:
dx:personnel-numberdx:
dx:mailtext-on-bookingdx:
dx:customer-fieldsdx:
dx:info-fieldsdx:
dx:disableddx:
dx:visitordx:
dx:remarkdx:
Picture 5.2 – Overview of personType Most elements are optional because they can be filled with defaults. domain-entity-id
The domain-entity-id is the entity identifier of the person in the source client. Its value is opaque to DEXICON Enterprise. It is a constant set at creation time. The id is used amongst others in access records, so that a client can assign accesses to the corresponding entities.
The domain-entity-id can have up to 40 characters. self
The self element contains the URI of the record when accessed via the Webservice-Interface. It is ignored by the Webservice-Interface when receiving a record.
© PCS Systemtechnik GmbH 51 DEXICON Enterprise Webservice-Interface V5.2.0
grouping
dx:administration-unitdx:
dx:subsystem-groupingdx:
C orresponds to the organization unit in DEXIC O N Enterprise. dx:groupingdx: dx:company-codedx:
dx:costcenterdx:
dx:companydx:
Picture 5.3 – Overview of the personType/grouping element
The grouping element encapsulates all different types of groups to which a person can belong:
administration-unit (URI): Administration unit to which the person belongs, e.g. /administration-units/DE02100D44.
Administration units define which DEXICON users have access to the record. Chapter 5.2.2.1 describes how to get a list of administration units. Please note that only administration units can be used, which have the purpose “persons”.
subsystem-grouping (3 characters long): Organization unit to which the person belongs. A person can be assigned to an organization unit. If this element is not set, a default can beor used (see chapter 5.4.2.6). Chapter 5.2.2.5 describes how to get a list of organization units. Please note that it is possible for this field to refer to organization units which do currently not exist in DEXICON Enterprise. This exception is due to the HR-PDC interface.
company-code (4 characters long): The company code. The value of this field is not evaluated by DEXICON Enterprise.
costcenter (10 characters long): The costcenter. The value of this field is not evaluated by DEXICON Enterprise.
company (URI): Company of the person, e.g. /companies/dOa2AkxUM_A. Chapter 5.2.2.7 describes how to get a list of companies. name
dx:surnamedx: dx:namedx: dx:first-namedx:
Picture 5.4 – Overview of the personType/name element The name element groups surname and first name of the person. Both elements can have up to 40 characters.
52 10/2019 Attribute
dx:selfdx:
URL of the record w hen accessed v ia the DEXIC O N HTTP-Interface. Ignored by 5 - REST API reference DEXIC O N Enterprise w hen receiv ing a record.
dx:groupingdx:
authentication dx:namedx:
dx:badgeType (extension)
dx:numberdx: personType dx:badgedx: dx:dateTimeType DEXIC O N Enterprise master record dx:datedx: dx:valid-todx: dx:timedx:
dx:dateTimeType
dx:datedx: dx:valid-fromdx: dx:timedx:
dx:authenticationdx: dx:badgeType
dx:numberdx:
dx:substitutedx: dx:dateTimeType
dx:datedx: dx:valid-todx: dx:timedx:
dx:allowdx: ed dx:biometricsdx: dx:alternative-authenticationdx: dx:remarkdx: dx:authorizationdx: Picture 5.5 – Overview of the personType/authentication element dx:personnel-numberdx: Every person must have a badge and can optionally have a substitute badge. If biometrics are used, dx:mailtext-on-bookingdx: certain persons might need an alternative. For example, the fingerprints of certain persons dx:customer-fieldsdx: cannot be evaluated electronically.
dx:info-fieldsdx: badge
dx:disableddx: number (up to 20 digits): The badge number. Padding with leading zeros is not dx:visitordx: required. Please note that the effective maximum length of the number is determined
dx:remarkdx: by a parameter of the configuration file ams.ini. The DEXICON Installation Manual describes this setting. valid-to and valid-from: Validity period of the badge. The period is given as interval [valid-from;valid-to[ and is not timezoned. Both elements consist of the sub- elements date (yyyy-mm-dd) and time (HH:MM, 24:00 is supported). substitute: A badge can be temporarily substituted with another one. The substitute becomes active as soon as the record is saved. Therefore, only the valid-to element is available. biometrics Use this element to allow or deny a person alternative authentication, e.g. using a PIN instead of fingerprint. The configuration of the readers determine, what is meant by “alternative authentication”.
allowed: One of not-available (denies alternative authentication), available (allowes alternative authentication) or governed-by-profile (alternative authentication is allowed or denied based on profiles, i.e. it is decided based on time and location). remark (up to 100 characters): An optional remark, which gives reason why alternative authentication is allowed. authorization A person’s authorization consists of
© PCS Systemtechnik GmbH 53 DEXICON Enterprise Webservice-Interface V5.2.0
Attribute
dx:selfdx:
URL foflags the record whether w hen the person may use access control and/or time recording. accessed v ia the DEXIC O N HTTP-Interface. Ignored by DEXICreader O N Enterprise function w hen groups which define the functions which a person may use at a reader, e.g. receiv ing a record. open the door or disarm the EMA. dx:groupingdx: role based spatial and temporal authorizations which are established by roles. dx:namedx:
dx:authenticationdx:personal spatial and temporal authorizations.
dx:accessdx:
dx:time-recordingdx: personType dx:reader-function-groupdx: DEXIC O N Enterprise master record C orresponds to the authorization group in DEXIC O N Enterprise.
dx:areadx:
dx:time-modeldx:
dx:from-datedx: dx:additional-access-authdx: dx:access-authdx: dx:to-datedx: 0..¥
dx:toggle-opendx: dx:authorizationdx:
dx:toggle-closedx:
dx:areadx:
dx:time-modeldx: dx:additional-time-recording-a...dx: dx:time-recording-authdx: dx:from-datedx: 0..¥
dx:to-datedx:
Attribute
id
source
dx:rolesdx: dx:role-assignmentdx: dx:roledx: 0..¥
dx:from-datedx:
dx:to-datedx: dx:personnel-numberdx: Picture 5.6 – Overview of the personType/authorization element The dx:mailtext-on-bookingdx: optional authorization element consists of the following optional sub-elements: dx:customer-fieldsdx: access (boolean): Specifies whether the person is authorized for access control. This flag dx:info-fieldsdx:is only a main switch. A person’s effective authorization is defined by profiles and allowed dx:disableddx:reader functions.
dx:visitordx: Please note that DEXICON is licensed for a certain number of records used in access
dx:remarkdx: control. If this flag is set, the record is counted in this regard. time-recording (boolean): Specifies whether the person is authorized for time recording and employee expenditures. This flag is only a main switch. A person’s effective authorization is defined by profiles and allowed reader functions. Please note that DEXICON is licensed for a certain number of records used in time recording. If this flag is set, the record is counted in this regard.
reader-function-group (URI): Specifies the set of reader functions which the person may use. Chapter 5.2.2.6 describes how to get a list of reader function groups.
54 10/2019 Attribute
dx:selfdx:
URL of the record w hen accessed v ia the DEXIC O N HTTP-Interface. Ignored by 5 - REST API reference DEXIC O N Enterprise w hen receiv ing a record.
dx:groupingdx: Please be prepared to receive person master records from the Webservice-Interface which
dx:namedx: use URIs which are not part of the collection resource /reader-function-groups. additional-access-auth: Contains pairs of areas and time models (both given as URIs) dx:authenticationdx: which form an access authorization. Each pair can optionally be time limited with the interval [from-date;to-date]. Dates are given as yyyy-mm-dd. dx:accessdx: Chapter 5.2.2.3 describes how to get a list of areas; chapter 5.2.2.4 describes how to get list dx:time-recordingdx:of time models. Please note that only areas and time models can be used, which have personType the purpose “authorization”. dx:reader-function-groupdx: DEXIC O N Enterprise master The toggle-open and toggle-close elements (boolean) apply to readers which allow to record C orresponds to the authorization toggle group ain DEXICdoor O permanently N Enterprise. open. With these flags you can specify whether open and/or close is allowed. dx:areadx: additional-time-recording-auth: Analogous to additional-access-auth but for time recording authorizations. dx:time-modeldx:
dx:from-datedx: area dx:additional-access-authdx: dx:access-authdx: dx:to-datedx: time-model additional-time-recording-auth time-recording-auth0..¥ from-date 0..¥ dx:toggle-opendx: dx:authorizationdx: to-date dx:toggle-closedx: Picture 5.7 – Overview of the personType/authorization/additional-time-recording-auth dx:areadx: element
roles: Contains roles (given as URIs) which form an authorization. Each role dx:time-modeldx: can dx:additional-time-recording-a...dx: dx:time-recording-authdx: optionally be time limited with the interval [from-date;to-date]. Dates are given as yyyy- dx:from-datedx: mm-dd. 0..¥ Chapter 5.2.2.2 describes how to get a list of roles. dx:to-datedx:
Attribute
id
source
dx:rolesdx: dx:role-assignmentdx: dx:roledx: 0..¥
dx:from-datedx:
dx:to-datedx:
dx:personnel-numberdx: Picture 5.8 – Overview of the personType/authorization/roles element dx:mailtext-on-bookingdx: Attribute “source” defines, from which source the role is assigned. Sources for role assignments can be: dx:customer-fieldsdx: "http" dx:info-fieldsdx: from Webservice-Interface
dx:disableddx: "user" from DEXICON dx:visitordx: "default-role"
dx:remarkdx: from DEXICON script (for default roles by change of organization unit assignment to a person)
© PCS Systemtechnik GmbH 55 DEXICON Enterprise Webservice-Interface V5.2.0
"hr-pdc-config" from DEXICON script (for person from SAP clients) "script" from external scripts Usage of role assignments differ for operation on base supply (bulk synchronization) and on a single master record. Role assignments in base supply In base supply, there is no need to specify “id” and “source” attributes for role assignments. They will be ignored internally and are deprecated. Via base supply you can add, change or delete role assignments to persons. Roles assigned by DEXICON client or other sources like scripts will not be modified by the base supply. Example 5.8 – Role assignment in base supply PUT http://localhost:8090/base-supply/EXAMPLE/EF9C3C72-D652AEE33FF0 HTTP/1.1 …
/roles/Imp0000007 2018-04-01 2021-06-30 /roles/Imp0000008
Role assignments in single person master record Version 2.1.0 or higher: For single master record only “source” attribute is needed for old assignments as received from the GET method. If the “source” attribute is omitted, the Webservice-Interface is assumed to be the source. Version 2.1.0 is compatible to Version 2.0.x. The “id” attribute will be ignored. For compatibility the “deliver-role-assignment-id” switch has to be set to “1” if your application needs the “id” attribute. Otherwise set the switch to “0” and implement requirements from the newer version. Version 2.0.x: For single master record, “id” and “source” attributes are needed for old assignments as received from the GET method. The received role assignments for the person can originate from different sources like DEXICON client, scripts or Webservice-Interface. To add new role assignments please omit its attributes. To delete a role assignment omit the role assignment. Only roles assigned by Webservice- Interface and DEXICON can be deleted. Role assignments from other sources like scripts remain unaffected. Role assignments are not mutable. Therefore its attributes are not mutable. If you want to change a role assignment simply remove its attributes and make your changes. Example 5.9 – Role assignment in single person master record in Version 2.1.0 ff PUT http://localhost:8090/persons/EXAMPLE/456 HTTP/1.1
…
56 10/2019 5 - REST API reference
/roles/Imp0000007 2019-04-01 2021-06-30 /roles/Imp0000008
/roles/6060606060 2019-04-15 2025-06-18 /roles/cccccccccc /roles/Imp0000099 Example 5.10 – Role assignment in single person master record in Version 2.0.x PUT http://localhost:8090/persons/EXAMPLE/456 HTTP/1.1 …
/roles/Imp0000007 2019-04-01 2021-06-30 /roles/Imp0000008
/roles/6060606060 2019-04-15 2025-06-18 /roles/cccccccccc /roles/Imp0000099 personnel-number Personnel number of the person, 8 characters long. mailtext-on-booking An integer [0;14]. The number corresponds to a text in the parameter settings of the readers. When the person makes a booking, the terminal displays the appropriate text. customer-fields Customer fields can be used for any purpose the customer likes to. The labels of these fields in the DEXICON Client can be configured in the configuration file ams.ini.
© PCS Systemtechnik GmbH 57 DEXICON Enterprise Webservice-Interface V5.2.0
dx:customer-field-1dx:
dx:customer-field-2dx: dx:customer-fieldsdx: dx:customer-field-3dx:
dx:customer-field-4dx:
Picture 5.9 – Overview of the personType/customer-fields element Each field can have up to 100 characters. info-fields
The info-fields contain the balance values which can be displayed at terminals. Therefore, the values and their order has to match the parameter settings of the terminals. Please note that the order of the balances may differ between the Webservice-Interface and the HR-PDC interface because of the info-field-order parameter in the configuration file ams.ini. This parameter re-sorts the balances received from the HR-PDC interface.
dx:info-field-1dx:
dx:info-field-2dx:
dx:info-field-3dx:
dx:info-field-4dx:
dx:info-field-5dx: dx:info-fieldsdx: dx:info-field-6dx:
dx:info-field-7dx:
dx:info-field-8dx:
dx:info-field-9dx:
dx:info-field-10dx:
Picture 5.10 – Overview of the personType/info-fields element Each field may have up to 13 characters. disabled
dx:manuallydx:
dx:badge-number-ambiguousdx: dx:disableddx: dx:too-many-failed-attemptsdx:
dx:too-long-inactivedx:
Picture 5.11 – Overview of the personType/disabled element A master record can be disabled due to different reasons:
manually (bool): Can be set to disable a master record.
badge-number-ambiguous (bool, read-only): DEXICON Enterprise automatically disables master records if a badge is assigned to more than one master record. This field is read- only and always provided by the Webservice-Interface.
58 10/2019 5 - REST API reference
too-many-failed-attempts (bool, read-only): DEXICON Enterprise can disable master records if a certain number of access attempts is exceeded. This field is read-only and always provided by the Webservice-Interface.
too-long-inactive (bool, read-only): DEXICON Enterprise can disable master records if a certain duration of inactivity is exceeded. This field is read-only and always provided by the DEXICON Webservice-Interface. visitor If the element exists, the person is a visitor. Visitors are listed separately in the DEXICON Client.
dx:visitordx: dx:hostdx:
Picture 5.12 – Overview of the personType/visitor element
If a person is a visitor, a host has to be specified. The host element is a plain text element and may contain up to 40 characters. remark
The remark element may contain up to 1,000 characters for a remark – including line breaks. 5.4.2.2 XML Schema for a single person record
A single person record, e.g. the resource http://myhost:8090/persons/EXAMPLE/123 is represented by a single person element of type personType: 5.4.2.3 XML Schema for bulk synchronization Bulk synchronizations (chapter 5.2.1.3) use the following schema:
© PCS Systemtechnik GmbH 59 DEXICON Enterprise Webservice-Interface V5.2.0
Picture 5.13 – XML Schema of a base supply
Normally, a base supply is a sequence of person elements of personType type. The unique- entity-id constraint enforces that entity ids (attribute domain-entity-id) have to be unique within a client and consequently within a base supply.
Since PINs are not part of personType, they are transmitted separately within the pins element, which is a sequence of pin elements. Each pin element references a person master record via the domain-entity-id and contains the actual PIN, which consists of 4 digits. All terminals and ACMs decline the pin “0000”. Consequently you can use this value as a secure default if a person has no pin. Example 5.11 – Base supply document with PINs
Skywalker Luke […] Vader
60 10/2019 5 - REST API reference
Darth […]
