Notifications documentation

content/app/guides/shared/api/altinn-token.md

@@ -0,0 +1,39 @@
+---
+headless: true
+hidden: true
+---
+
+
+The {0} API is secured using OAuth2 and all requests must include a valid Altinn token either in the Authorization header or
+in the _AltinnStudioRuntime_ cookie.
+
+For clients within the Altinn eco-system representing an external user or organization,
+the Altinn token in an incoming request can be forwarded to the {0} API.
+
+If you are using the API from an external system you will need to generate a maskinporten or id-porten token
+and exchange this for an Altinn token before calling the {0} API.
+
+Below are two guides on how to achieve this.
+
+{{% expandlarge id="guide-altinn-token-maskinporten" header="Guide on how to generate an Altinn token with Maskinporten" %}}
+
+<!--
+- fakta messig hvordan går man gjennom ting
+- gi en heads up om at vi også har en API-client for .NET
+-->
+{{% notice info %}}
+We are working on providing you with a guide.
+{{% /notice %}}
+
+
+{{% /expandlarge %}}
+
+
+{{% expandlarge id="guide-altinn-token-id-porten" header="Guide on how to generate an Altinn token with id-porten" %}}
+
+{{% notice info %}}
+We are working on providing you with a guide.
+{{% /notice %}}
+
+{{% /expandlarge %}}
+

content/app/guides/shared/api/base-urls.md

@@ -0,0 +1,24 @@
+---
+headless: true
+hidden: true
+---
+
+The following base urls correspond to each environment
+
+- AT (Private Altinn acceptance test environment)
+
+  ```http
+  https://platform.{environment}.altinn.cloud/{0}/api/v1
+  ```
+
+- TT02 (Application owner test environment)
+
+  ```http
+  https://platform.tt02.altinn.cloud/{0}/api/v1
+  ```
+
+- Production
+
+  ```http
+   https://platform.altinn.cloud/{0}/api/v1
+  ```

content/app/guides/shared/api/maskinporten-scopes.md

@@ -0,0 +1,24 @@
+---
+headless: true
+hidden: true
+---
+
+Some endpoints in the API may require additional authorization in the form of a Maskinporten scope.
+A scope represents a permission that a consumer has access to.
+
+You can connect a given set of scopes to the specific Maskinporten integration instance that
+provides your API client with Maskinporten tokens upon request.
+
+{{% expandlarge id="guide-mp-int-api" header="Guide on how to register a new Maskinporten integration through API" %}}
+
+Please reference [Maskinporten's own documentation](https://docs.digdir.no/docs/Maskinporten/maskinporten_guide_apikonsument) 
+on registering a new integration through their self service API.
+
+{{% /expandlarge %}}
+
+
+{{% expandlarge id="guide-mp-int-samarbeid" header="Guide on how to register a new Maskinporten integration in Samarbeidsportalen" %}}
+
+{{% insert "content/app/guides/shared/maskinporten-integration/maskinporten-integration-samarbeidsportal.md" %}}
+{{% /expandlarge %}}
+

content/app/guides/shared/api/platform-access-token.md

@@ -0,0 +1,11 @@
+---
+headless: true
+hidden: true
+---
+
+The access to a subset of endpoints in the API is limited to callers within the Altinn eco-system.
+These APIs require additional authorization in the form of a
+Platform Access Token.
+
+Please reference developer documentation for the client system on how to generate
+the token.

content/events/request-maskinporten-scopes.md → content/app/guides/shared/api/request-maskinporten-scopes.md

@@ -1,7 +1,12 @@
-The scope __{0}__ is required when {1}. 
+---
+headless: true
+hidden: true
+---
 
-Currently, access to this scope is limited to the development team and beta testers of generic events. 
-If you fall under one of these two groups and require access, please contact the development team directly. 
+The scope **{0}** is required when {1}.
 
-We are working on making requests for access to this scopes available to the public. 
+Currently, access to this scope is limited to the development team and beta testers.
+If you fall under one of these two groups and require access, please contact the development team directly.
+
+We are working on making requests for access to this scopes available to the public.
 [The progress of this work can be monitored here](https://github.com/Altinn/altinn-events/issues/319).

content/events/api/_index.en.md

@@ -1,67 +1,32 @@
 ---
 title: Altinn Events API
-linktitle:  API
+linktitle: API
 description: An overview of the Altinn Events API
 weight: 10
 toc: true
 ---
 
 The Altinn Events API is an HTTP-based RESTful API that provides endpoints and actions for publishing of events and subscribing to events from Altinn 3 Apps and other registered sources.
 
-
 ## Base URL
 
-- AT (Private Altinn Acceptance Test environment)
-
-    ```http
-    https://platform.{environment}.altinn.cloud/events/api/v1
-    ```
-- TT02 (Application owner test environment)
-
-    ```http
-    https://platform.tt02.altinn.no/events/api/v1
-    ```
-- Production:
-
-   ```http
-    https://platform.altinn.no/events/api/v1
-    ```
-
+{{% insert "content/app/guides/shared/api/base-urls.md" "events"%}}
 
 ## Authentication & Authorization
-### Altinn token
-The Events API is secured using OAuth2 and all requests must include a valid Altinn token either in the Authorization header or
-in the _AltinnStudioRuntime_ cookie. 
-
 
-{{% notice info %}}
-TODO: write the guides referenced below.Both with our client libraries and in postman maybe? 
-{{% /notice %}}
+### Altinn token
 
-Here is an overview of guides related to the generation of Altinn token for production and test purposes:
-- [Guide on how to generate an Altinn token with Maskinporten]()
-- [Guide on how to generate an Altinn token with id-porten]()
-- [Guide on how to generate an Altinn token with Altinn test tools]()
-
+{{% insert "content/app/guides/shared/api/altinn-token.md" "Events"%}}
 
 ### Maskinporten scopes
 
-{{% notice info %}}
-TODO: find docs to link to or create them.
-{{% /notice %}}
-
-Some endpoints in the API require additional authorization in the form of a 
-Maskinporten scope. [User documentation on setting up a maskinporten integration with a specific scope 
-is available here](). 
-
+{{% insert "content/app/guides/shared/api/maskinporten-scopes.md" %}}
 
 ### Platform Access token
-The use of some endpoints in the API is limited to callers within the Altinn eco-system.
-These APIs require additional authorization in the form of a
-Platform Access Token. Reference developer documentation for the client system on how to generate 
-the token.
 
+{{% insert "content/app/guides/shared/api/platform-access-token.md" %}}
 
 ### Private APIs
+
 The API contains a set of private APIs that are only accessible within the Events-component.
 These are marked as _Private API_ in the OpenAPI specification and require an access token in the request header.

content/events/publish-events/get-started/api-access/_index.en.md

@@ -7,4 +7,4 @@ description: A guide to requesting access to the event producer APIs
 
 ## Requesting required Maskinporten scope
 
-{{% insert "content/events/request-maskinporten-scopes.md" "altinn:events.publish" "publishing events to Altinn"%}}
+{{% insert "content/app/guides/shared/api/request-maskinporten-scopes.md" "altinn:events.publish" "publishing events to Altinn"%}}

content/events/subscribe-to-events/get-started/api-access/_index.en.md

@@ -8,5 +8,5 @@ description: Guide to requesting access to Altinns APIs
 ## Requesting required Maskinporten scope*
 \* Scope is only required when subscribing to events published to a non-Altinn App resource.
 
-{{% insert "content/events/request-maskinporten-scopes.md" "altinn:events.subscribe" "subscribing to events"%}}
+{{% insert "content/app/guides/shared/api/request-maskinporten-scopes.md" "altinn:events.subscribe" "subscribing to events"%}}
 

content/notifications/_index.en.md

@@ -0,0 +1,141 @@
+---
+title: Notifications
+description: Description of the notifications capabilities in Altinn 3.
+toc: true
+weight: 20
+aliases:
+  - /altinn-notifications/
+---
+
+{{% notice warning  %}}
+This section of the documentation is a work in progress.
+There are sub sections with missing and/or only partial documentation.
+{{% /notice %}}
+
+## Main benefits
+
+Reasons to consider using Altinn Notifications for communication with Norwegian citizens or businesses
+
+1. Contact information in national registries can be retrieved at send time based on
+   organisation number or person identification number.
+2. Altinn roles can be used to identify the correct recipients within an organisation.
+3. Notifications can have send conditions related to the state of, or actions performed on, an Altinn App instance
+4. A seamless integration for notifications in an Altinn App workflow.
+
+## Terminology
+
+- #### Notification order
+
+  A _notification order_ is the request to send  one or multiple notifications to one or multiple recipients.
+  A single order can result in the creation of one or multiple notifications.
+
+  Here is an example of a standard notification order:
+
+    ```json
+    {
+      "id": "a56c0933-d609-4b5c-a5da-bccfd407c9b8",
+      "creator": "ttd",
+      "sendersReference": "test-2023-1",
+      "requestedSendTime": "2024-01-02T13:49:31.5591909Z",
+      "created": "2024-01-02T13:49:31.5799658Z",
+      "notificationChannel": "Email",
+      "recipients": [
+        {
+          "emailAddress": "[email protected]"
+        },
+          {
+          "emailAddress": "[email protected]"
+        }
+      ],
+      "emailTemplate": {
+        "fromAddress": "[email protected]",
+        "subject": "A test email from Altinn Notifications",
+        "body": "A message sent from an application owner through Altinn.",
+        "contentType": "Html"
+      },
+      "links": {
+        "self": "https://platform.at22.altinn.cloud/notifications/api/v1/orders/a56c0933-d609-4b5c-a5da-bccfd407c9b8",
+        "status": "https://platform.at22.altinn.cloud/notifications/api/v1/orders/a56c0933-d609-4b5c-a5da-bccfd407c9b8/status"
+      }
+    }
+    ```
+
+- #### Notification
+
+  A _notification_ is the one instance of an email or SMS that is sent to a single recipient.
+
+  Here is an example of a set of notifications related to an order:
+
+    ```json
+    {
+        "orderId": "a56c0933-d609-4b5c-a5da-bccfd407c9b8",
+        "sendersReference": "test-2023-1",
+        "generated": 2,
+        "succeeded": 1,
+        "notifications": [
+            {
+                "id": "a141753c-557f-4bce-95fd-8fc715ca9a40",
+                "succeeded": true,
+                "recipient": {
+                    "emailAddress": "[email protected]"
+                },
+                "sendStatus": {
+                    "status": "Succeeded",
+                    "description": "The email has been accepted by the third party email service and will be sent shortly.",
+                    "lastUpdate": "2024-01-02T13:51:12.706808Z"
+                }
+            }
+               {
+                "id": "a9d159e2-6a89-4440-80da-7f2a99c775f4",
+                "succeeded": true,
+                "recipient": {
+                    "emailAddress": "[email protected]"
+                },
+                "sendStatus": {
+                    "status": "Sending",
+                    "description": "The email is being processed and will be attempted sent shortly." ,
+                    "lastUpdate": "2024-01-02T13:51:12.706808Z"
+                }
+            }
+        ]
+    }
+    ```
+
+- #### Notification channel
+
+  A _notification channel_ is the communication pathways through which Altinn enables you to
+  communicate with your end users.
+
+## Notification channels
+
+Currently, we support sending notifications through two channels:
+
+- email
+- sms
+
+#### Future improvements
+
+In the future, we plan to extend our notification channel options to provide even more flexibility and convenience.
+Our goal is to support a wider range of communication platforms. This expansion will allow both  your organisation 
+and the end users to communicate through the channels that best suit the end users preferences and communication habits.
+
+Stay tuned for updates as we continue to enhance our notification capabilities to better serve your needs.
+
+If you have any questions or feedback regarding notification channels,
+please don't hesitate to [reach out to us through GitHub](https://github.com/Altinn/altinn-notifications/issues/new?assignees=&labels=kind%2Fquestion%2Cstatus%2Ftriage&projects=&template=question.yml).
+
+## Who can use Altinn Notifications
+
+Altinn Notifications allows the following parties to send messages, 
+provided they have obtained authorization through Maskinporten:
+
+- Registered service owners
+- Altinn Apps 
+- Internal Altinn services
+
+
+## Guidelines for usage
+
+
+[Please reference our user guide on how and when to use Altinn Notitifcations](send-notifications/get-started/user-guide/)
+

content/notifications/api/_index.en.md

@@ -0,0 +1,30 @@
+---
+title: Altinn Notifications API
+linktitle: API
+description: An overview of the Altinn Notifications API
+weight: 10
+toc: true
+---
+
+The Altinn Notifications API is an HTTP-based RESTful API that provides endpoints and actions for ordering,
+managing and reviewing notifications sent through Altinn.
+
+## Base URL
+
+{{% insert "content/app/guides/shared/api/base-urls.md" "notifications"%}}
+
+## Authentication & Authorization
+
+### Altinn token
+
+{{% insert "content/app/guides/shared/api/altinn-token.md" "Notifications"%}}
+
+### Maskinporten scopes
+
+{{% insert "content/app/guides/shared/api/maskinporten-scopes.md" %}}
+
+
+### Platform Access token
+
+{{% insert "content/app/guides/shared/api/platform-access-token.md" %}}
+

content/notifications/api/openAPI/_index.en.md

@@ -0,0 +1,8 @@
+---
+title: OpenAPI (swagger) for Notifications
+linktitle: OpenAPI
+type: openapi
+spec: "/swagger/altinn-notifications-v1.json"
+tags: [swagger, openapi]
+---
+