diff --git a/documentation/astro.config.mjs b/documentation/astro.config.mjs index 9767aab..7c26c0e 100644 --- a/documentation/astro.config.mjs +++ b/documentation/astro.config.mjs @@ -16,14 +16,14 @@ export default defineConfig({ email: 'mailto:support@aheadintranet.com', }, sidebar: [ - { - label: 'Guides', - autogenerate: { directory: 'guides' }, - }, { label: 'Reference', autogenerate: { directory: 'reference' }, }, + { + label: 'Guides', + autogenerate: { directory: 'guides' }, + } ], }), ], diff --git a/documentation/src/assets/use-postman-1.png b/documentation/src/assets/use-postman-1.png new file mode 100644 index 0000000..ab78966 Binary files /dev/null and b/documentation/src/assets/use-postman-1.png differ diff --git a/documentation/src/assets/use-postman-2.png b/documentation/src/assets/use-postman-2.png new file mode 100644 index 0000000..7465b28 Binary files /dev/null and b/documentation/src/assets/use-postman-2.png differ diff --git a/documentation/src/assets/use-postman-3.png b/documentation/src/assets/use-postman-3.png new file mode 100644 index 0000000..b93827f Binary files /dev/null and b/documentation/src/assets/use-postman-3.png differ diff --git a/documentation/src/assets/use-postman-4.png b/documentation/src/assets/use-postman-4.png new file mode 100644 index 0000000..a690660 Binary files /dev/null and b/documentation/src/assets/use-postman-4.png differ diff --git a/documentation/src/assets/use-postman-5.png b/documentation/src/assets/use-postman-5.png new file mode 100644 index 0000000..2e3a973 Binary files /dev/null and b/documentation/src/assets/use-postman-5.png differ diff --git a/documentation/src/assets/use-postman-6.png b/documentation/src/assets/use-postman-6.png new file mode 100644 index 0000000..84fce87 Binary files /dev/null and b/documentation/src/assets/use-postman-6.png differ diff --git a/documentation/src/assets/use-postman-7.png b/documentation/src/assets/use-postman-7.png new file mode 100644 index 0000000..295a268 Binary files /dev/null and b/documentation/src/assets/use-postman-7.png differ diff --git a/documentation/src/assets/use-postman-8.png b/documentation/src/assets/use-postman-8.png new file mode 100644 index 0000000..b6232b4 Binary files /dev/null and b/documentation/src/assets/use-postman-8.png differ diff --git a/documentation/src/content/docs/guides/01-get-apikey-and-use-postman.mdx b/documentation/src/content/docs/guides/01-get-apikey-and-use-postman.mdx new file mode 100644 index 0000000..643b46d --- /dev/null +++ b/documentation/src/content/docs/guides/01-get-apikey-and-use-postman.mdx @@ -0,0 +1,93 @@ +--- +title: Do profile updates with Postman +description: Here we describe how to get an API-Key from ahead and use it to perform test imports with the Postman tool +prev: false +--- +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; +import { Image } from 'astro:assets'; +import image1 from '../../../assets/use-postman-1.png' +import image2 from '../../../assets/use-postman-2.png' +import image3 from '../../../assets/use-postman-3.png' +import image4 from '../../../assets/use-postman-4.png' +import image5 from '../../../assets/use-postman-5.png' + +:::tip +You should know hot to perform an API request with the [postman tool](https://www.postman.com/) or something similar. +::: + +You have been tasked to call the ahead import API to add information to user profiles. Great! +Let us trace the necessary steps that you can successfully call the ahead API with a tool like postman. + +## Getting the API-Key + +First, you will need the API Key. To get it, you need to be an administrator in your ahead intranet +(or know somebody who is). Under **Company Settings / Integrations** you will find the **API-Keys** + +The API Keys view under Company Settings / Integrations + +When you add one, you need to select for which feature it will be used - relevant here is the feature +**Profile Import**. + +Once created, clicking the _eye_-Symbol will reveal the API-key. Pressing the _copy_-symbol will copy +the API Key to the clipboard. Now you are equipped to prepare an API-Call to ahead's import API. + +## Doing a profile update in Postman + +You will need the correct endpoint URL as well as HTTP Verb, namely PUT. See the following screenshot: + +The headers tab in postman + +We will first try an update via a JSON array. You need to add a custom header field named `x-functions-key`. +It's value is the one you copied from the **API-Keys**-section in ahead. +The `Content-Type` header will be set automatically when you go to the **Body**-Tab and set it +to **raw**, choosing **JSON** as the input. + +The body tab in postman + +The input should adhere to the structure specified under [The person update JSON object](../../reference/05-person-json-object/). + +Now you should be ready to send the request by pressing **Send**! + +If all went well, Postman will tell you that the http status code response was `200` and you also got an id +back as the response body. + +The response status in postman + +## The import log + +When you head back to the same page in ahead where you got the API-Keys you should notice that your import +was registered. + +The import logs view in ahead + +Clicking on the details accesses the log file relevant for the import. + +Its content would now look like this: + +```text +2023-11-22T15:47:38 - RequestId: 98e51b88-932d-4a33-8e13-58fc39d7faf1 +Success - PersonUpdated - 'joe@company.com' updated +``` + +:::tip +When you automate the profile import API calls e.g. in a nightly job, requests done within a short timeframe +will be listed under one entry in the **Import Logs** - hence, one log file may contain several +`request ID`s. That's where the search field comes in handy. +::: + +You should now know the basics of how to call the API. + +## Additional reading + + + + + \ No newline at end of file diff --git a/documentation/src/content/docs/guides/02-upload-files-with-postman.mdx b/documentation/src/content/docs/guides/02-upload-files-with-postman.mdx new file mode 100644 index 0000000..b1b39d3 --- /dev/null +++ b/documentation/src/content/docs/guides/02-upload-files-with-postman.mdx @@ -0,0 +1,49 @@ +--- +title: Upload files with postman +description: How to upload files in Postman +next: false +--- +import { Image } from 'astro:assets'; +import image1 from '../../../assets/use-postman-6.png' +import image2 from '../../../assets/use-postman-7.png' +import image3 from '../../../assets/use-postman-8.png' + +Provided you use ahead also for files to be shown to users in their personal section, +here you will learn how to do a file upload for a user with postman. This guide assumes that +you already had a look at [how to get an api-key and use postman to upload a profile update](../01-get-apikey-and-use-postman/). + +## Choose the correct content-type + +File uploads need to happen with the `Content-Type` set to `multipart/form-data`. + +Correct settings in the body + +This is most easily done by setting up the body tab correctly. This will automatically set the correct +`Content-Type` under the **Headers**-Tab. + +## Choose a file + +:::caution +Make sure you understand [how the files need to be named](../../reference/06-sending-files/). +::: + +Now you can choose a file to upload. + +uploading a file + +You could add additional files to repeating the file selection step in the next row. + +Pressing "Send" starts the request and if all goes well, the response status code should be a merry `200`. + +## Verifying the upload + +Such a request will also show up in the import logs as a file upload: + +```text +2023-11-22T16:20:09 - RequestId: 1bed586b-ed0e-4780-ad06-e9f831ebd3af +Success - FileUploaded - Uploaded file 'November 2023.pdf' for 'joe@company.com' +``` + +And of course, our test subject joe should now see the new file under their **personal space**. + +The personal space \ No newline at end of file diff --git a/documentation/src/content/docs/guides/get-apikey-and-use-postman.mdx b/documentation/src/content/docs/guides/get-apikey-and-use-postman.mdx deleted file mode 100644 index 36394d3..0000000 --- a/documentation/src/content/docs/guides/get-apikey-and-use-postman.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Howto - Do test imports with Postman -description: Here we describe how to get an API-Key from ahead and use it to perform test imports with the Postman tool ---- - -:::note -To be defined -::: \ No newline at end of file diff --git a/documentation/src/content/docs/index.mdx b/documentation/src/content/docs/index.mdx index e6bfd8b..180a928 100644 --- a/documentation/src/content/docs/index.mdx +++ b/documentation/src/content/docs/index.mdx @@ -7,8 +7,8 @@ hero: image: file: ../../assets/ahead_a.svg actions: - - text: Howto - Get started by doing imports with Postman - link: /guides/get-apikey-and-use-postman/ + - text: Get started by doing imports with Postman + link: /guides/01-get-apikey-and-use-postman/ icon: right-arrow variant: primary ---