This article describes technical details on how to set up an external REST API endpoint for receiving HR data exported from Nepton via a scheduled person export. Details about setting up a scheduled task for person export including the REST API settings are described in Scheduled task – person export page and data format specific pages for CSV and JSON.
Request message
This section describes the HTTP requests sent by Nepton platform when contacting an external REST API endpoint for exporting HR data. The contents of the data sent – according to selected data format – are described in Export persons - Default CSV data format and Export persons - JSON data format pages.
REST API address
Scheduled person export task is using HTTP PUT method when contacting the REST API endpoint. The endpoint must support TLS protocol (address must be defined with https:// prefix).
Authentication type
The selected authentication method determines the Authorization header value used when contacting the REST API service.
No authentication
If "No authentication" is selected as the authentication type, the data is sent to service and no authentication options are expected to be required.
Basic HTTP authentication
Basic HTTP authentication adds an Authorization header with value "Basic" followed by a space and the "username" and "password" parameter values separated by colon – in username:password format – encoded as UTF-8 bytes converted to Base64 string.
Example:
Authorization: Basic c2FtcGxldXNlcm5hbWU6YW0jbWFhNmZtMjh2bWYmR2xo
where c2FtcGxldXNlcm5hbWU6YW0jbWFhNmZtMjh2bWYmR2xo is the sampleusername:am#maa6fm28vm&Glh (parameter values username and password from scheduled task settings combined with colon) converted to Base64 string.
OAuth 2.0 (Basic HTTP authentication)
OAuth 2.0 authorization contacts the given authorization service with HTTP POST method first, using Authorization header similar to Basic HTTP authentication. Authorization server must support TLS protocol (address must be defined with https:// prefix).
A successful response from authorization server should have a JSON object as the body of the response. The object should have at least access_token field defined. The format of the response (there may be more HTTP headers):
HTTP/1.1 200 OK Content-Type: application/json;charset=utf-8 Content-Length: 119 { "access_token": "secret_access_token_value", "token_type": "token_type", "expires_in": 999999, "scope": "scope" }
The access_token field value is then passed to the given REST API service in Authorization header:
Authorization: Bearer secret_access_token_value
where secret_access_token_value is the access_token field value from the authorization server response.
Token authorization
Token authorization adds the parameter apikey value to Authorization header with TOKEN prefix.
Example Authorization header:
Authorization: TOKEN secret_api_key_provided
where secret_api_key_provided is the value of the apikey parameter from scheduled task settings.
Scheduled task for person export will contact the service defined in REST API address using HTTP PUT method and adding an authorization header value based on the selected authentication type of the scheduled task.
Security protocols
Endpoint and possible OAuth 2.0 authorization service must support TLS protocol and their addresses must be defined with https:// prefix. Currently we support TLS 1.2 and TLS 1.1 security protocols.
100-Continue behaviour
Before sending data, an initial request with HTTP PUT method is made with an Expect header with value "100-continue", with all the other request headers included but without data as request body:
Content-Length: 25959 Expect: 100-continue
A HTTP response 100 (continue) is expected as indication for successful authentication and acceptance of the details in the headers before sending the actual data:
HTTP/1.1 100 Continue
If the server cannot accept the request, it can respond with HTTP response 417 (expectation failed):
HTTP/1.1 417 Expectation Failed
or another appropriate response, e.g., HTTP response 401 (unauthorized):
HTTP/1.1 401 Unauthorized
Content type
Content type of the request is presented as Content-Type header value as the media type of the contents to be sent ("application/json" for JSON format, "text/csv" for CSV format), followed by ";charset=" and the encoding of the contents (either "utf-8" for UTF-8 (Unicode character set) encoding or "iso-8859-1" for ISO-8859-1 ("Latin 1") encoding).
Examples:
Content-Type: application/json;charset=utf-8
Content-Type: text/csv;charset=iso-8859-1
Content length
The length of the exported HR data file in bytes is sent as Content-Length header value.
Example:
Content-Length: 3909
Response message
This section describes the HTTP responses expected by Nepton platform when it has exported HR data to an external REST API endpoint.
Responses for sending a JSON file
Transport was successful – reports by individual entries
Nepton platform expects an HTTP response status code of a success (status code in range 200 – 299) (e.g. status code 200: OK), if the service handling the remote endpoint received the transported data successfully.
The response body must be a JSON object – and the object must contain statuses for the individual person entries in the export message. The key names expected in the JSON object response:
- "Status" key. It should have a matching value with text "Success" to indicate the export file could be processed – there could still have been problems in handling individual persons' information entries. If the Status value is "Error" – or anything else than "Success" – then it is reported to platform that no information could be processed.
- "StatusByEmployee" key as an array of JSON objects matching each individual person included in the person export file. Each person JSON object should then contain the following key names:
- "EmployeeNeptonId" – mandatory key with a matching string value containing the Nepton Id, NeptonPersonGUID field value from the person export file.
- If the handling of the individual person's information was successful, there should be one or more of the following key names in the StatusByEmployee object so that the individual person export is considered a success. The values for these keys should be JSON objects with at least one key name. Format of information of the values is currently not limited:
- Added
- Modified
- NoChanges
- RemovedInfo
- If the handling of the individual person's information was a failure or there were any kinds of warnings, one or both of the following key names should be included. Their values are logged in the service log warning entry and the export for the individual person is considered a failure:
- FatalError (errors preventing the whole handling)
- Warnings
- There may be other keys included either in the main object or within the StatusByEmployee objects. This information is not currently handled, but any information in the response may end up in a corresponding service log entry.
Example (there may be more HTTP headers):
HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Content-Length: 917 { "Status": "Success", "StatusByEmployee": [ { "EmployeeNeptonId": "206894AF-E2E6-5F11-B988-DD9E52BD067A", "Added": { "Field1": "Success", "Field2": "Success", "Field3": "Success" }, "Modified": { "Field4": "Success" }, "NoChanges": { "Field5": "Success" }, "RemovedInfo": { "Field6": "Success" }, "AnyInformation": "There may be additional member fields - they won't interfere with the interpretation" }, { "EmployeeNeptonId": "D9D6AA30-58A9-43E4-A66A-12193A71C25E", "Modified": { "Field1": "Success" }, }, { "EmployeeNeptonId": "2CA5D9DF-5B57-446A-879B-FC8F704FA0F7", "FatalError": "Mandatory field missing: \"Personal identity code\" is required by the XX system", }, { "EmployeeNeptonId": "FEE31CF4-B4BF-4DDF-ADAD-5ACB1B8CD130", "Warnings": "Invalid value: \"Additional administrative information\" (\"1CC\")" } ] }
Transport failed
It is recommended that a HTTP response status code of a success (status code in range 200 – 299) is sent if there was no transport related error and inform about the specific details in the format described below. If the server just needs to inform that receiving failed or the service could not process information at all, it may alternatively send an error response – HTTP client error response (status code in range 400 – 499), a HTTP server error response (in range 500 – 599) or any other response classified as an error – and it will be logged in service log error entry.
If the response body consists of a JSON object with "Status" key name with matching value of "Error" – or anything else than "Success" – or if there is a message included in the matching value for "ErrorMessage" key name, the whole export operation is considered as failed. Any error message in "ErrorMessage" value will be logged in service log error entry.
Example (there may be more HTTP headers):
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Content-Length: 64 { "Status": "Error", "ErrorMessage": "Error message for log" }
Errors and warnings for individual person entries within the person export file should not be reported as a failure in general but using the "FatalError" and "Warnings" keys within "StatusByEmployee" array objects, see Transport was successful – reports by individual entries.
Responses for sending a CSV file
Transport and handling were successful
If the service handling the remote endpoint received and could process the contents like expected, an HTTP response status code of a success (status code in range 200 – 299) is expected (e.g. status code 200: OK. No other information than the successful HTTP status code is required for a successful response when the contents were sent in CSV format. If any information is provided in the message body, it is logged as informational message in service log success entry.
Example (there may be more HTTP headers):
HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Content-Length: 2 OK
Transport or handling failed
A non-success HTTP code is expected in case there was any problem either in transporting to or handling of the data in the service handling the remote endpoint. That code may be a HTTP client error response (status code in range 400 – 499), a HTTP server error response (in range 500 – 599) or any other response classified as an error. The response code and any information received in the body of result is then included in service log error entry.
Example (there may be more HTTP headers):
HTTP/1.1 500 Internal Server Error Content-Type: text/plain; charset=utf-8 Content-Length: 54 An unexpected error occurred while processing the data