Suomi
Platform status: -
  1. Nepton
  2. Support
  3. Integration
  4. HR data

Export HR data to a REST API endpoint

  • Updated

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).

mceclip4.png

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.

mceclip6.png

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.

mceclip5.png
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).


mceclip6.png
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.

mceclip7.png

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

 

 


Was this article helpful?
0 out of 0 found this helpful
Return to top