Skip to content

Commit 5126a1a

Browse files
author
Frederic Mercier
committed
review the webhook sample documentation
1 parent b1f5d28 commit 5126a1a

File tree

3 files changed

+190
-117
lines changed

3 files changed

+190
-117
lines changed

‎decisioncenter/webhooknotifier/README-DOCKER.md

Lines changed: 13 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11

22
### Introduction
3-
This readme explain the step to step to run this sample in Docker.
43

5-
We will use the ODM for developper image. No needs to have an ODM installed.
6-
We needs to have build the image as explain in the [README.md](README.md) file.
4+
This readme explains how to run the webhook sample in Docker.
75

8-
### Run the sample
6+
Doing so, you do not need to have ODM installed. Instead we are relying on the 'ODM for developper' container image.
7+
8+
Before following the steps below, make sure you have built the images as explained in [README.md](README.md).
9+
10+
### Running the sample
911

1012
1. Run ODM and Notifiers docker images
1113
```bash
@@ -21,38 +23,27 @@ We needs to have build the image as explain in the [README.md](README.md) file.
2123
-H 'accept: */*' \
2224
-H 'Content-Type: application/json' \
2325
-d 'null' \
24-
-u odmAdmin:odmAdmin
26+
-u odmAdmin:odmAdmin
2527
```
2628

2729
2. For the Slack Notifier:
2830

29-
* Generate the Token :
3031
```shell
31-
kubectl exec -ti webhooknotifier-slack -- curl -X 'GET' \
32-
'http://localhost:3000/token.generate' \
33-
-H 'accept: */*' \
34-
-H 'Content-Type: application/json'
35-
```
36-
xxxxxx.xxxxxx.xxxxxxxx -> Token
37-
38-
This command return a token that should be injected in the next command line.
32+
export SLACK_TOKEN=`curl 'http://localhost:3000/token.generate' -H 'accept: */*' -H 'Content-Type: application/json'`
3933
40-
* Register the webhook with the generated token
41-
```shell
4234
curl -X 'PUT' \
4335
'http://localhost:9060/decisioncenter-api/v1/webhook/notify?url=http%3A%2F%2Fslack%3A3000%2Fslack' \
4436
-H 'accept: */*' \
4537
-H 'Content-Type: application/json' \
46-
-d '<GENERATED_TOKEN>' \
38+
-d "$SLACK_TOKEN" \
4739
-u odmAdmin:odmAdmin
4840
```
49-
### Using the Sample
5041

51-
Once the webhook is set up, events from the Decision Center will trigger the notifications and either post messages to Slack or generate log files in the `results` directory.
42+
### Using the Sample
5243

53-
You can trigger an event by deploying a rule app for example.
44+
Once webhooks are set up, various events in Decision Center trigger notifications.
5445

55-
You can see the notification in the docker-compose windows.
46+
For instance, deploying a rule app triggers a notification with a content as follows in the docker-compose windows:
5647

5748
```bash
5849
slack-1 | {
@@ -83,7 +74,7 @@ slack-1 | }
8374
slack-1 | ],
8475
```
8576
86-
Log file structure:
77+
The Slack webhook notifier forwards the notifications to Slack and the log files notifier saves them in the `results` directory in the log files below:
8778
- `deployments.txt`: Deployment details.
8879
- `rules.txt`: Rule changes.
8980
- `releases.txt`: Release details.

‎decisioncenter/webhooknotifier/README-KUBERNETES.md

Lines changed: 165 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,183 @@
1-
### Run this sample on Kubenetes
2-
1. Push the images to the Kubernetes registry
3-
```bash
4-
docker login $REGISTRY_HOST -u <REGISTRY_USERNAME> -p <REGISTRY_PASSWORD>
5-
docker tag webhooknotifier-slack $REGISTRY_HOST/webhooknotifier-slack
6-
docker tag webhooknotifier-logfile $REGISTRY_HOST/samples/webhooknotifier-logfile
7-
docker push $REGISTRY_HOST/samples/webhooknotifier-logfile
8-
docker push $REGISTRY_HOST/webhooknotifier-slack
9-
```
10-
11-
2. Instanciate the pods
12-
```bash
13-
kubectl run webhooknotifier-logfile --image=image-registry.openshift-image-registry.svc:5000/samples/webhooknotifier-logfile:latest --port 3000 --expose --port 3000
14-
kubectl run webhooknotifier-slack --image=image-registry.openshift-image-registry.svc:5000/samples/webhooknotifier-slack:latest --port 3000 --expose --port 3000
15-
```
16-
17-
3. Declare the services
18-
1. The logs files notifier
19-
```shell
20-
curl -k -X 'PUT' \
21-
'https://my-odm-release-odm-dc-route-samples.apps.odm-dev-ocp.cp.fyre.ibm.com/decisioncenter-api/v1/webhook/notify?url=http%3A%2F%2Fwebhooknotifier-logfile.samples.svc.cluster.local%3A3000%2Fprint' \
22-
-H 'accept: */*' \
23-
-H 'Content-Type: application/json' \
24-
-d 'null' \
25-
-u odmAdmin:odmAdmin -k
26-
```
27-
28-
2. For the Slack Notifier:
29-
30-
* Generate the Token :
31-
```shell
32-
kubectl exec -ti webhooknotifier-slack -- curl -X 'GET' \
33-
'http://localhost:3000/token.generate' \
34-
-H 'accept: */*' \
35-
-H 'Content-Type: application/json'
36-
```
37-
xxxxxx.xxxxxx.xxxxxxxx -> GENERATED_TOKEN
38-
39-
This command return a token that should be injected in the next command line.
40-
41-
* Register the webhook with the generated token
42-
```shell
43-
curl -X 'PUT' -k \
44-
'https://<DC_URL>/decisioncenter-api/v1/webhook/notify?url=http%3A%2F%2Fwebhooknotifier-slack.<NAMESPACE>.svc.cluster.local%3A3000%2Fslack' \
45-
-H 'accept: */*' \
46-
-H 'Content-Type: application/json' \
47-
-d '<GENERATED_TOKEN>' \
48-
-u <USERNAME_PASSWORD>
49-
```
50-
{"id":"57896361-62f8-4a0e-a86b-3da46417f493","url":"http://webhooknotifier-slack.svc.cluster.local:3000/slack","authToken":"*****************************************************"}%
51-
```
52-
Where:
53-
* DC_URL : The URL where decision center is accessible.
54-
* NAMESPACE : The namespace where the sample has been deployed.
55-
* GENERATED_TOKEN : The token generated in the previous step.
56-
* USERNAME_PASSWORD : If you installed the demo or starter mode you can put odmAdmin:odmAdmin
1+
### Introduction
572

58-
### Using the Sample
3+
This readme explains how to run the webhook sample in Kubernetes.
4+
5+
Doing so requires to have Decision Center set up in Kubernetes beforehand.
6+
7+
Also, before following the steps below, make sure you have built the images as explained in [README.md](README.md).
8+
9+
### Running this sample on Kubenetes
10+
11+
1. Push the webhook notifier images to your Docker registry
12+
13+
```bash
14+
docker login $REGISTRY_HOST -u $REGISTRY_USERNAME -p "$REGISTRY_PASSWORD" --tls-verify=false
15+
16+
docker tag webhooknotifier-logfile $REGISTRY_HOST/samples/webhooknotifier-logfile
17+
docker tag webhooknotifier-slack $REGISTRY_HOST/webhooknotifier-slack
18+
19+
docker push $REGISTRY_HOST/webhooknotifier-logfile
20+
docker push $REGISTRY_HOST/webhooknotifier-slack
21+
```
22+
23+
where `$REGISTRY_HOST` should be set to the hostname of the Docker registry optionally followed by the relevant repository depending on your Docker registry.
24+
25+
For instance $REGISTRY_HOST has the following format for an Openshift registry: `default-route-openshift-image-registry.apps.<cluster>/<namespace>`.
26+
27+
2. Start one pod for each image
28+
29+
Set the current context to the namespace the Decision Center pods are running, and then run:
30+
31+
```bash
32+
kubectl run webhooknotifier-logfile --image=image-registry.openshift-image-registry.svc:5000/samples/webhooknotifier-logfile:latest --expose --port 3000
33+
34+
kubectl run webhooknotifier-slack --image=image-registry.openshift-image-registry.svc:5000/samples/webhooknotifier-slack:latest --expose --port 3000
35+
```
36+
37+
>NOTE: These commands also create one service (of type ClusterIP) for each pod, allowing to send requests to the pods using the following URLs:
38+
> - http://webhooknotifier-logfile.NAMESPACE.svc.cluster.local:3000
39+
> - http://webhooknotifier-slack.NAMESPACE.svc.cluster.local:3000
40+
>
41+
> where `NAMESPACE` is the namespace in which the pods and the servives have been created.
42+
43+
Additionally, you may need to specify the secret containing the Docker registry credentials in the pods definition (in the parameter `spec.imagePullSecrets`) if this is not done automatically.
44+
45+
To do so, first create the secret:
46+
```bash
47+
kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>
48+
```
49+
50+
Then run `kubectl edit pod webhooknotifier-logile` and add the two lines below under `spec:` :
51+
```bash
52+
spec:
53+
imagePullSecrets:
54+
- name: regcred
55+
```
56+
57+
Do the same for the pod `webhooknotifier-slack`.
58+
59+
3. Configure the webhook notifications in Decision Center
60+
61+
1. Log files notifications
62+
63+
```shell
64+
curl -k -X 'PUT' \
65+
'https://$DC_HOST/decisioncenter-api/v1/webhook/notify?url=http%3A%2F%2Fwebhooknotifier-logfile.$NAMESPACE.svc.cluster.local%3A3000%2Fprint' \
66+
-H 'accept: */*' \
67+
-H 'Content-Type: application/json' \
68+
-d 'null' \
69+
-u odmAdmin:odmAdmin
70+
```
5971

60-
Once the webhook is set up, events from the Decision Center will trigger the notifications and either post messages to Slack or generate log files in the `results` directory.
72+
where
73+
- `$DC_HOST` should be set to the hostname of Decision Center,
74+
- `$NAMESPACE` should be set to the name of the namespace/project in which the webhook notifier pods and service have been created,
75+
- `odmAdmin:odmAdmin` should be replaced by the actual username and password of a user with rtsAdministrator role.
6176

62-
You can trigger an event by deploying a rule app for example.
77+
2. Slack Notifications
78+
79+
```shell
80+
export SLACK_TOKEN=`kubectl exec -ti webhooknotifier-slack -- curl 'http://localhost:3000/token.generate' -H 'accept: */*' -H 'Content-Type: application/json'`
6381
64-
You can see the notification in the docker-compose windows.
82+
curl -X 'PUT' -k \
83+
'https://$DC_HOST/decisioncenter-api/v1/webhook/notify?url=http%3A%2F%2Fwebhooknotifier-slack.$NAMESPACE.svc.cluster.local%3A3000%2Fslack' \
84+
-H 'accept: */*' \
85+
-H 'Content-Type: application/json' \
86+
-d "$SLACK_TOKEN" \
87+
-u odmAdmin:odmAdmin
88+
```
89+
90+
where:
91+
- `$DC_HOST` should be set to the hostname of Decision Center,
92+
- `$NAMESPACE` should be set to the name of the namespace/project in which the webhook notifier pods and service have been created,
93+
- `odmAdmin:odmAdmin` should be replaced by the actual username and password of a user with rtsAdministrator role.
94+
95+
The expected output looks like:
96+
```
97+
{"id":"57896361-62f8-4a0e-a86b-3da46417f493","url":"http://webhooknotifier-slack.<NAMESPACE>.svc.cluster.local:3000/slack","authToken":"*****************************************************"}%
98+
```
99+
100+
### Using the Sample
101+
102+
Once webhooks are set up, various events in Decision Center trigger notifications.
103+
104+
For instance, deploying a rule app triggers a notification with a content like:
65105

66106
```bash
67-
slack-1 | {
68-
slack-1 | "version": "1.0",
69-
slack-1 | "id": "cc66c9e8-9905-486d-99e9-7ab89af3d976",
70-
slack-1 | "author": "odmAdmin",
71-
slack-1 | "date": 1725633110628,
72-
slack-1 | "type": "SnapshotCreated",
73-
slack-1 | "content": [
74-
slack-1 | {
75-
slack-1 | "id": "dcf08c59-877c-42d4-9360-2189345577c8",
76-
slack-1 | "internalId": "dsm.DsDeploymentBsln:103:103",
77-
slack-1 | "name": "test_deployment_2024-09-06_16-31-45-855",
78-
slack-1 | "createdBy": "odmAdmin",
79-
slack-1 | "createdOn": 1725633110000,
80-
slack-1 | "lastchangedBy": "odmAdmin",
81-
slack-1 | "lastChangedOn": 1725633110000,
82-
slack-1 | "parentId": "1558f25b-daa6-4982-8b0b-48a388c7c202",
83-
slack-1 | "documentation": null,
84-
slack-1 | "buildMode": "DecisionEngine",
85-
slack-1 | "kind": "DeploymentSnapshot"
86-
slack-1 | }
87-
slack-1 | ],
88-
slack-1 | "details": [
89-
slack-1 | {
90-
slack-1 | "targetURL": "http://172.22.0.4:9060/decisioncenter/t/library#overviewsnapshot?id=dsm.DsDeploymentBsln%3A103%3A103&datasource=jdbc%2FilogDataSource&baselineId=dsm.DsDeploymentBsln%3A103%3A103"
91-
slack-1 | }
92-
slack-1 | ],
107+
{
108+
"version": "1.0",
109+
"id": "cc66c9e8-9905-486d-99e9-7ab89af3d976",
110+
"author": "odmAdmin",
111+
"date": 1725633110628,
112+
"type": "SnapshotCreated",
113+
"content": [
114+
{
115+
"id": "dcf08c59-877c-42d4-9360-2189345577c8",
116+
"internalId": "dsm.DsDeploymentBsln:103:103",
117+
"name": "test_deployment_2024-09-06_16-31-45-855",
118+
"createdBy": "odmAdmin",
119+
"createdOn": 1725633110000,
120+
"lastchangedBy": "odmAdmin",
121+
"lastChangedOn": 1725633110000,
122+
"parentId": "1558f25b-daa6-4982-8b0b-48a388c7c202",
123+
"documentation": null,
124+
"buildMode": "DecisionEngine",
125+
"kind": "DeploymentSnapshot"
126+
}
127+
],
128+
"details": [
129+
{
130+
"targetURL": "http://172.22.0.4:9060/decisioncenter/t/library#overviewsnapshot?id=dsm.DsDeploymentBsln%3A103%3A103&datasource=jdbc%2FilogDataSource&baselineId=dsm.DsDeploymentBsln%3A103%3A103"
131+
}
132+
],
93133
```
94134
95-
Log file structure:
135+
The Slack webhook notifier forwards the notifications to Slack and the log files notifier saves them in the `results` directory in the log files below:
96136
- `deployments.txt`: Deployment details.
97137
- `rules.txt`: Rule changes.
98138
- `releases.txt`: Release details.
99139
- `activities.txt`: Activity details.
100140
101141
### Stopping the Sample
102142
143+
To remove the webhooks configured in Decision Center, first list them:
144+
145+
```bash
146+
curl -X 'GET' \
147+
'https://$DC_HOST/decisioncenter-api/v1/webhooks/notify' \
148+
-H 'accept: */*'
149+
```
150+
151+
where `$DC_HOST` should be set to the hostname of Decision Center.
152+
153+
The expected output looks like:
154+
155+
```bash
156+
{
157+
"elements": [
158+
{
159+
"id": "d2808ed5-f074-45ff-8905-a20d90279378",
160+
"url": "http://webhooknotifier-slack.default.svc.cluster.local:3000/slack",
161+
"authToken": "*************************************************************************************************************************************************************************************"
162+
},
163+
...
164+
```
165+
166+
You can then remove a webhook from Decision Center, by running the command below:
167+
103168
```bash
104-
oc delete svc,pods webhooknotifier-logfile
105-
oc delete svc,pods webhooknotifier-slack
106-
# TODO Delete the notification hook.
169+
curl -X 'DELETE' \
170+
'https://$DC_HOST/decisioncenter-api/v1/webhooks/$WEBHOOK_ID/notify' \
171+
-H 'accept: */*'
172+
```
173+
174+
where
175+
- `$DC_HOST` should be set to the hostname of Decision Center,
176+
- `$WEBHOOK_ID`should be set to the id of the webhook you want to remove (eg. `d2808ed5-f074-45ff-8905-a20d90279378` in the example above)
107177
178+
Finally, remove the notifier pods and their services:
179+
180+
```bash
181+
oc delete svc,pod webhooknotifier-logfile
182+
oc delete svc,pod webhooknotifier-slack
108183
```

‎decisioncenter/webhooknotifier/README.md

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
11

22
# Webhook Notification Setup Sample
33
### Introduction
4-
This sample demonstrates how to use webhooks within the IBM Operational Decision Manager (ODM) to send notifications or data to external systems whenever certain rules are executed. Webhooks allow for real-time data sharing and integration, making it easier to trigger actions or workflows in other applications based on decision outcomes.
4+
This sample demonstrates how to use webhooks within the IBM Operational Decision Manager (ODM) to send notifications or data to external systems whenever the following events occur:
5+
- When actions that are related to the decision governance framework happen in Decision Center, for example when a user creates a release, or approves an activity.
6+
- When a deployment ends, you are notified of its status: completed, failed, or aborted.
7+
- When a user creates or updates a rule or a decision table.
58

6-
In this sample, you'll learn how to configure and use the Webhook Notifier to send notifications to an external URL, providing seamless integration between IBM ODM and Slack or log files using a Node.js server.
9+
Webhooks allow for real-time data sharing and integration, making it easier to trigger actions or workflows in other applications.
10+
11+
In this sample, you will learn how to configure and use the Webhook Notifier to send notifications:
12+
- either to a Slack channel,
13+
- or to a Node.js server which records the notifications into log files.
714

815
## Prerequisites
916

@@ -15,17 +22,17 @@ Before you begin, ensure you have the following:
1522

1623
### 1. Build the samples
1724

18-
This NodeJS sample code will be packaged in 2 docker images.
25+
This NodeJS sample code will be packaged in two docker images.
1926

2027
1. Navigate to the Slack webhook sample directory:
2128
```bash
2229
cd decisioncenter/webhooknotifier
2330
```
2431

25-
2. Edit your Slack webhook URL and token in the `endPoints.json` file to be able to notify on slack. You can skip this step if you are don't want to use slack. Only file notifier will work will work.
32+
2. Edit the `endPoints.json` file to set the URL of your Slack channel and the token to use for authentication. You can skip this step if you do not want to use Slack and only want to use the example based on notifications saved into files.
2633
3. Build the docker images
2734
```bash
28-
docker-compose build
35+
docker-compose build
2936
```
3037

3138
### Run the sample

0 commit comments

Comments
 (0)