2 guides to peruse

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' },
+				}
 			],
 		}),
 	],

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**
+
+<Image src={image1} alt="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:
+
+<Image src={image2} alt="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.
+
+<Image src={image3} alt="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.
+
+<Image src={image4} alt="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.
+
+<Image src={image5} alt="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
+
+<CardGrid>
+    <LinkCard
+        title="Authorization & Authentication"
+        description="Learn how to authorize your requests"
+        href="../../reference/03-authentication-authorization/"
+    />
+    <LinkCard
+        title="calling the Endpoint"
+        description="Read the specification of the people import API"
+        href="../../reference/04-endpoint/"
+    />
+</CardGrid>

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`.
+
+<Image src={image1} alt="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. 
+
+<Image src={image2} alt="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**.
+
+<Image src={image3} alt="The personal space" />

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