From b05fab5071a5d0479172237cb3d5803dcd8f6447 Mon Sep 17 00:00:00 2001 From: frank Date: Wed, 22 Nov 2023 15:46:00 +0100 Subject: [PATCH] taken in all content from the word document --- documentation/src/content/docs/index.mdx | 4 +- .../content/docs/reference/04 endpoint.mdx | 80 +++++++++++++++---- .../docs/reference/05 person-json-object.mdx | 47 ++++++++++- .../docs/reference/06 sending-files.mdx | 40 ++++++++++ 4 files changed, 153 insertions(+), 18 deletions(-) create mode 100644 documentation/src/content/docs/reference/06 sending-files.mdx diff --git a/documentation/src/content/docs/index.mdx b/documentation/src/content/docs/index.mdx index 01b8d1f..e6bfd8b 100644 --- a/documentation/src/content/docs/index.mdx +++ b/documentation/src/content/docs/index.mdx @@ -21,7 +21,7 @@ import { Card, CardGrid } from '@astrojs/starlight/components'; [Get an overview](reference/01-background/) and start browsing how to authorize API-calls and browse the request & response specification. - - [Visit the endpoint's description](reference/04-endpoint/). + + [Visit the endpoint's description](reference/04-endpoint/) and understand how to form an import request. diff --git a/documentation/src/content/docs/reference/04 endpoint.mdx b/documentation/src/content/docs/reference/04 endpoint.mdx index 9537e2d..607727a 100644 --- a/documentation/src/content/docs/reference/04 endpoint.mdx +++ b/documentation/src/content/docs/reference/04 endpoint.mdx @@ -1,17 +1,19 @@ --- -title: Endpoint +title: Endpoint description description: How to reach the endpoint and basic settings around the HTTP Headers --- -import { Card, LinkCard } from '@astrojs/starlight/components'; +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; :::note

The API URL of the import is

https://connect.aheadintranet.com/api/PeopleImport
::: -It accepts **PUT**s With the following headers. +## Request -## x-functions-key +The API accepts **PUT**s with the following headers. + +### x-functions-key The API-Key necessary to authorize the request @@ -20,14 +22,11 @@ The API-Key necessary to authorize the request href="../03-authentication-authorization/" /> -## Content-Type - -Supported are +### Content-Type -* multipart/form-data -* application/json +Supported content types are -### multipart/form-data +#### multipart/form-data :::tip The structure of a multipart/form-data request is formally described at https://www.rfc-editor.org/rfc/rfc2388. It forms the basis of e.g., file uploads from HTML form submissions. @@ -38,12 +37,63 @@ Each part of a multipart request also defines its own content-type. Currently su * application/json - An update of a profile in the form of a **Person update JSON object**. * application/pdf - A *.pdf document for upload to the personal section of a user +A request may contain up to 50 parts. Each part corresponds to the update of one person or the addition of a file for a person. + + + + + + +#### application/json + +Send a JSON array of **person update JSON objects**. The array may only contain up to **50 objects**. + +:::tip +This kind of API usage only supports the update of fields directly related to profiles. It will **not** allow the upload of files. +In this case, you will need to send `multipart/form-data`-requests +::: + -### application/json +## Response + +:::caution +Imports will be accepted on an employee-by-employee basis. That means that when the API returns the `422` error code, some of the sent employees may have been successfully imported. In such cases, you will need to identify the proper logs that are correlated with the GUID provided in the body of the response through ahead’s “Integrations” section in the management pages. +::: + +### Status Code 200 + +The complete request has been processed without issues. The body of the response will contain a GUID with which this import call can be identified in the import logs (which will be accessible through ahead’s admin interface). + +### Status Code 400 + +If there’s any issue with the request at a basic level (e.g. wrong content type), a status code of `400` (Bad request) will be returned. Another possible reason is when all parts of the request failed to be processed. + +### Status Code 403 + +A request without API-Key or an unknown API-Key will cause a return of `403`. Such calls will not appear in the protocol. + +### Status Code 413 + +A request contains more than 50 people updates. + +### Status Code 422 + +If there are issues with the data itself, which may only apply to a part of the sent data, a status code of `422` (unprocessable content) will be returned. The body of the response will contain a GUID with which this import call can be identified such that it can be analyzed which specific import command went wrong. -Send a JSON array of **person update JSON objects**. \ No newline at end of file +Typical conditions that would lead to a 422 response are: +• A particular JSON object could not be correlated with an existing entry (missing / wrong employeeId field) +• A JSON object contains fields that are not known as defined in the People Profile Definition +• A field is known, but contains the wrong kind of data \ No newline at end of file diff --git a/documentation/src/content/docs/reference/05 person-json-object.mdx b/documentation/src/content/docs/reference/05 person-json-object.mdx index 7418088..b2f3d17 100644 --- a/documentation/src/content/docs/reference/05 person-json-object.mdx +++ b/documentation/src/content/docs/reference/05 person-json-object.mdx @@ -3,4 +3,49 @@ title: The person update JSON object description: Learn about the JSON object that updates a single person in the ahead people store --- -TOOD \ No newline at end of file +A person update JSON object may appear as + +* part with content-type: application/json in a multipart +* as element of a JSON array within the body of a request whose content-type is application/json. + +Each JSON object must contain one of +• the **“employeeId”** field. This field needs to correlate with a person’s “employeeId” value as stored in MS Entra. +• the **“userPrincipalName”** (UPN). This field needs to correlate with a person’s user principal name in MS Entra. + +Given that the following field has been defined in the people profile definition: + +```json +{ + "name": "birthDate", + "fieldType": "Date", + "source": "Api" +} +``` + +Then the following update JSON would update the user with the UPN `joe@company.com` and add (_or update_) its birthday field. + +```json +{ + "userPrincipalName": "joe@company.com", + "birthDay": "1985-10-03", +} +``` + +Sending a null for a supported field effectively deletes the value + +```json +{ + "userPrincipalName": "joe@company.com", + "birthDay": null, +} +``` + +In other words, the update object may contain values for all or a subset of the fields that are marked with source = API +in the people profile definition. + +Provided that ahead is successful in correlating the person via one of the correlation fields, the provided values will be +merged with the existing values. In short, the following rules apply: + +* Any fields not referenced will be left untouched. +* Provided fields will overwrite any previously existing values. +* If the API call sends “null” for a field, ahead will take this value and use it to overwrite / reset that specific value. diff --git a/documentation/src/content/docs/reference/06 sending-files.mdx b/documentation/src/content/docs/reference/06 sending-files.mdx new file mode 100644 index 0000000..ea84ef3 --- /dev/null +++ b/documentation/src/content/docs/reference/06 sending-files.mdx @@ -0,0 +1,40 @@ +--- +title: Sending files through the import API +description: Learn how to send files to ahead +tableOfContents: false +--- + +In order to send a file to ahead, a field needs to be specified in the people profile definition to accept a certain kind of file. + +```json +{ + "name": "salary", + "fieldType": "File", + "source": "Api", + "isList": true +} +``` + +In this example, files of type **salary** can be sent to ahead. The filename of the file(s) being sent via a +`multipart/form-data` request needs to follow a certain structure: + +```text +{userIdentifier}__{fieldName}__{fileName}.pdf +``` + +Note the **2** underscores between the pieces of information. Following the example, +the following would be a valid file name: + +```text +joe@company.com__salary__March 2023.pdf +``` + +It would upload a new file named **March 2023.pdf** under the **salary** category for the user with the UPN joe@company.com + +You can send up to **50 files** per multipart request. + +:::danger +Regardless of whether you send 50 files on a request or, please note that the +total size of the request should **not** exceed **104 Megabytes**. +The request will not be processed if it exceeds that size. +::: \ No newline at end of file