# mia_template_service_name_placeholder

Welcome to Java Spring Boot example service for Mia-Platform!

## Current Version

This example is currently based on Java SE 11 (LTS)

## Summary

%CUSTOM_PLUGIN_SERVICE_DESCRIPTION%

## Local Development

This example allow you to learn how to create a pre/post microservice that can be added to Mia-Platform Pre/Post Orchestrator (Microservice Gateway) to enrich APIs Calls. More details here [https://docs.mia-platform.eu/development_suite/api-console/api-design/decorators/]().

This example sends a message to a Slack channel each time you send a POST message to a CRUD collection.

## Setup Mia-Platform

When you have created this microservice you need to setup Mia-Platform in order to use this service.

This guide will help you to:

- setup the Env Variables for this service
- create an App on Slack
- add an external proxy that points to the Slack App
- create a CRUD Collection
- create a Post Hook that points to this microservice
- add to the CRUD Collection the Post Hook

Are you ready? Follow the next steps to complete the setup and run in production your first hook!

> :warning:
> Please once the service is installed in your project verify **Probes** confiugration, boot time of Springboot applications may be long
> so you might want to propertly tune readiness and liveness probes.

### Step 1 - Create the Notifier Service

From the Mia-Platform Marketplace on DevOps Console select this service and Create it. In this example give to the microservice the name **SendNotifications** (you can use any name)

Once created go in *DevOps Console -> Design -> Microservices -> your just created microservice (SendNotifications)* and add to it the following environment variables in the table *Environment variable configuration* (Key=Value)

```json
SERVICE_NAME=api-gateway
SERVICE_PORT=8080
```

Press *Commit & Generate* to save the configuration.

### Step 2 - Slack App

You need a Slack App to send a message to a Slack Channel. In order to setup the App on Slack go to Slack API [https://api.slack.com/apps]() and press **Create New App**.

Give a name to the App and select the *Slack Workspace* where you want to install

Once created select ***Incoming Webhooks** -> Activate It (On) -> Add New Webhook to Workspace -> Select the Channel (example general)*. Slack generate for you the URL to post a message to Slack

`https://hooks.slack.com/services/lsjkfdkdfsbfjkbadkl/fshdklfddshfadfshdfskl`

> Note: this is a fake url. Don't use it :-)

Try if it works with a Curl

```bash
curl -X POST -H 'Content-type: application/json' --data '{"text":"Hello, World!"}' https://hooks.slack.com/services/lsjkfdkdfsbfjkbadkl/fshdklfddshfadfshdfskl
```

You should see on channel general the *Hello, World!* message.

Now you can pass to the DevOps Console.

### Step 3 - Post Hook

The Post hook will be triggered after an API call. To create it go to *DevOps Console -> Design -> Pre/Post Microservices -> POST -> Add New*.

Use the following parameters:

- name: notify (but you can use whatever)
- protocol: http
- microservice: the microservice you have created at Step-1, **SendNotifications**
- port: 80
- path: /notify (is the path exposed by **SendNotifications**, you can change it changing the *index.js* of this microservice)
- Require request body: true
- Require response body: true

> Note: *Require request body* and *Require response body* must be checked otherwise you obtain unexpected error `invalid protocol in post`.

### Step 4 - External Proxy

The External Proxy decouple the url generated by Slack from the Microservices that runs inside Mia-Platform. In this way you have more control on the external call made by services and the reverse proxy is centralized in one point of the k8s namespace and not spread across all microservices.

To create a proxy go to *DevOps Console -> Design -> Proxies -> Create New Proxy -> External and create it with the following values:

- name: notify-slack
- url: `https://hooks.slack.com/services/lsjkfdkdfsbfjkbadkl/fshdklfddshfadfshdfskl` (the url you just created for the new Slack App)

> Mod: you can change the name of *notify-slack* but you need to modify  *notifications-sender.js - line 22* or pass the name via environment variables.

Once created add it to Endpoints. Go to *DevOps Console -> Design -> Endpoints* and Create a new Endpoint with the following values:

- base path: /notify-slack
- type: external Proxy
- microservice: notify-slack

> Note: this configuration is valid for test, in production you need to protect the endpoint

### Step 5 - CRUD Collection and Expose it

The CRUD service stores all messages sent to Slack. We will add to POST the post to hook created before.

To create a CRUD go to *DevOps Console -> Design -> CRUD -> Create new CRUD* and give the name *Messages* (or whatever you prefer).
Add to it two String fields:

- mymsg
- who

> Mod: you can change the fields names but if you do it you must update this file *notifications-sender.js - lines 19,22* and the related test files. You can also change the source code and pass the field names as environment variables to this microservice.

### Step 6 - Expose the CRUD Collection and add Post Hook

To expose the CRUD Collection go to *DevOps Console -> Design -> Endpoints -> Create new Endpoint* and with the following values:

- name: **/messages**
- type: CRUD
- collection: *Messages*

Once created set **Default State** to PUBLIC and go to **Routes** section on the Endpoint just created and select **POST/**. Go to **Add Pre/Post Microservice** and the Hook with the following values:

- Type of decorator: POST
- Select the decorator: the name of the Hook you just created at Step 3, *notify*

### Step 7 - Deploy and Test

That's all! Now you can Commit and Deploy.

- Press *Commit & Generate* and save your configuration
- Go to *DevOps Console -> Deploy*, select your branch and environment e press deploy

In less that one minute all will be up and running!

To test it go to  *DevOps Console -> Documentation -> The Environment where you deployed the configuration. This will open the API Portal.

On API Portal locate your CRUD service named *Messages*. Select POST and send a message filling *mymsg* and *who* fields.

```bash
curl --request POST \
  --url https://your-url/v2/messages/ \
  --header 'accept: */*' \
  --header 'content-type: application/json' \
  --data '{"who":"Giulio","mymsg":"Ciao from Mia-Platform"}'
```

This will generate a message on your Slack channel!

> Note: be aware that all is not protected! Don't use those configuration in production! You need to protect your CRUD endpoint before going in production.

## Improvements

You can do a lot of modifications on this example:

- protect your routes with API Secrets and Auth!
- connect the CRUD to the Mia-Platform Headless CMS to trace the messages and visualize analytics.
- enrich the CRUD Messages with GeoData to visualize the messages on Maps
- send notification to other Apps instead of Slack
- create a rich configuration of this service via Env Vars and Config Maps
- and a lot more!

### Run locally

To run locally this example just run the

```bash
mvn spring-boot:run
```

To change server port

```bash
mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=8000
```

To launch tests locally

```bash
mvn test
```

To build it

```bash
mvn clean package
```

To force mvn package update

```bash
mvn clean install -U
```

### Routes

The following routes are exposed

- [http://localhost:3000/hello]() - hello controller
- [http://localhost:3000/-/ready]() - the service is ready (used by k8s)
- [http://localhost:3000/-/healthz]() - the service is healthy (used by k8s)
- [http://localhost:3000/documentation/json]() - the Open API 3 specification

### Tag new project version

Please use the `tag.sh` to update the `pom.xml` project version and commit release to git.

Respect the following syntax to invoke the script:

```bash
./tag.sh [options] [rc]
```

According to [semver](https://semver.org/), *options* could be:

- _major_ version when you make incompatible API changes
- _minor_ version when you add functionality in a backwards-compatible manner
- _patch_ version when you make backwards-compatible bug fixes.

According to Mia-Platform release process *rc* could be:

- _rc_ add `-rc` to your release tag
- omitted

#### Promote `rc` release

When your service is ready to production you can promote your rc version invoking the scritp with `promote` option.

```bash
./tag.sh promote
```

#### Push changes

Don't forget to push commit and tag:

```bash
git push
git push --tags
```

#### Examples

Assuming your current version is `v1.2.3`

|command   | result  |
|---|---|
|`./tag.sh major`   |`v2.0.0`   |
|`./tag.sh minor`   |`v1.3.0`   |
|`./tag.sh patch`   |`v1.2.4`   |
|`./tag.sh major rc`   |`v2.0.0-rc`   |
|`./tag.sh minor rc`   |`v1.3.0-rc`   |
|`./tag.sh patch rc`   |`v1.2.4-rc`   |

Assuming your current version is `v1.2.3-rc`

|command   | result  |
|---|---|
|`./tag.sh promote`   |`v1.2.3`|