Skip to content

Commit 7d18e38

Browse files
e-pettersson-ericssone-pettersson-ericsson
authored
Add examples in subscription docs (#402)
* Add json examples of multiple requirements + conditions in subscriptions * Add links to front-end docs * Add flowContext condition in REST POST susbcription * Remove unnecessary fields in example subscriptions * Add examples of how to extract data from aggregation within a subscription
1 parent 91e4045 commit 7d18e38

6 files changed

+433
-331
lines changed

‎wiki/markdown/step-by-step-subscription-notification.md

Lines changed: 38 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@ and [adding subscriptions via Eiffel Intelligence frontend GUI](https://github.c
66

77
{
88
"created": "2017-07-26",
9-
"notificationMeta": "http://127.0.0.1:3000/ei/test_subscription_rest",
9+
"notificationMeta": "http://127.0.0.1:3000/api/send",
1010
"notificationType": "REST_POST",
1111
"restPostBodyMediaType": "application/x-www-form-urlencoded",
1212
"notificationMessageKeyValues": [{
13-
"formkey": "e",
14-
"formvalue": "{parameter: [{ name: 'jsonparams', value : to_string(@) }, { name: 'runpipeline', value : 'mybuildstep' }]}"
13+
"formkey": "data",
14+
"formvalue": "{parameters: [{ name: 'jsonparams', value : to_string(@) }, { name: 'artifact_identity', value : @.identity }]}"
1515
}],
1616
"repeat": false,
1717
"requirements": [{
@@ -22,7 +22,6 @@ and [adding subscriptions via Eiffel Intelligence frontend GUI](https://github.c
2222
"jmespath": "testCaseExecutions[?testCase.conclusion == 'SUCCESSFUL' && testCase.id=='TC5']"
2323
}
2424
],
25-
"type": "ARTIFACT_1"
2625
},
2726
{
2827
"conditions": [{
@@ -32,18 +31,16 @@ and [adding subscriptions via Eiffel Intelligence frontend GUI](https://github.c
3231
"jmespath": "testCaseExecutions[?testCaseStartedEventId == '13af4a14-f951-4346-a1ba-624c79f10e98']"
3332
}
3433
],
35-
"type": "ARTIFACT_1"
3634
}
3735
],
3836
"subscriptionName": "Subscription_Test",
3937
"userName": "ABC"
4038
}
4139

42-
4340
In this subscription, two requirements are given, where each requirement in turn
4441
contains two conditions. As per subscription logic, when all the conditions in
4542
any one of the given requirements are met in an aggregated object then the
46-
subscription is triggered. Triggering means that the subscriber will be notified
43+
subscription is fulfilled. This means that the subscriber will be notified
4744
with the chosen notification method. It should be noted that conditions are given
4845
as JMESPath expression. Let us suppose that an aggregated object, as shown below,
4946
is created:
@@ -73,11 +70,10 @@ is created:
7370
"identity": "pkg:maven/com.mycompany.myproduct/sub-system@1.1.0"
7471
}
7572

76-
7773
When this aggregated object is evaluated against the subscriptions stored in
78-
database, then it fulfills our subscription criteria. It can be seen that both
79-
conditions of the first requirement are satisfied by the aggregated object.
80-
More specifically, in the first condition, JMESPath rule is looking for:
74+
the database, then it fulfills our subscription criteria. It can be seen
75+
that both conditions of the first requirement are satisfied by this aggregated
76+
object. More specifically, in the first condition, JMESPath rule is looking for:
8177

8278
identity=='pkg:maven/com.mycompany.myproduct/sub-system@1.1.0'
8379

@@ -86,28 +82,32 @@ and in the second condition it looks for
8682
testCaseExecutions.testCase.conclusion == 'SUCCESSFUL' && testCase.id=='TC5'
8783

8884
Both strings can be found in the aggregated object JSON. Consequently, the process
89-
is started to send notification to specified subscriber. For this, 'notificationMeta'
90-
and 'notificationType' field values are extracted from the subscription.
85+
is started to send notification to the specified subscriber. For this,
86+
'notificationMeta' and 'notificationType' field values are extracted from
87+
the subscription.
9188

9289
## Notify via REST POST
93-
In the example subscription above, the notification is sent as **REST POST** to
94-
the url http://127.0.0.1:3000/ei/test_subscription_rest. The notification message
95-
in this subscription is prepared as key value pairs in the request.
90+
In the example subscription above, the notification is sent as **REST POST**
91+
to the url `http://127.0.0.1:3000/ei/test_subscription_rest`. The notification
92+
message in this subscription is prepared as key value pairs in the request body.
9693

9794
"notificationMessageKeyValues": [{
98-
"formkey": "e",
99-
"formvalue": "{parameter: [{ name: 'jsonparams', value : to_string(@) }, { name: 'runpipeline', value : 'mybuildstep' }]}"
95+
"formkey": "data",
96+
"formvalue": "{parameters: [{ name: 'jsonparams', value : to_string(@) }, { name: 'artifact_identity', value : @.identity }]}"
10097
}]
10198

102-
The key is 'jsonparams' and the value is the full aggregated object. These are part
103-
of the notification message for this particular subscription. Below is a list of the
104-
key value pairs which will be sent for this subscription.
99+
The key is 'jsonparams' and the value is the full aggregated object. The
100+
second parameter is the artifact identity which is extracted from the
101+
aggregation, These are part of the notification message for this particular
102+
subscription. Below is a list of the parameters defined in the above notification
103+
message which will be sent for this subscription.
105104

106105
parameters:
107-
jsonparameters: {full aggregated object}
108-
runpipeline: mybuildstep
106+
jsonparams: {full aggregated object}
107+
artifact_identity: pkg:maven/com.mycompany.myproduct/sub-system@1.1.0
109108

110-
If it was sent as raw JSON body, the notification message would look like below:
109+
If it was sent as raw JSON body, the first parameter of the notification
110+
message would look like below:
111111

112112
{
113113
[
@@ -149,40 +149,39 @@ also be set for individual subscriptions using the Eiffel Intelligence front-end
149149

150150
As with the conditions, it is also possible to write JMESPath expressions
151151
for the notification message. If we use the example subscription above, the
152-
notification could be to send parameters which contains only some of the
153-
information from the aggregated object. We could for example use the below
154-
JMESPath expression in the subscription notification message:
152+
notification could be to send data extracted from the aggregated object.
153+
We could for example use the below JMESPath expression in the subscription
154+
notification message:
155155

156-
"{parameter: [{ name: 'artifactIdentity', value : to_string(@.identity) }, { name: 'testCase', value: to_string(@.testCaseExecutions[0].testCase.id) } { name: 'runpipeline', value : 'mybuildstep' }]}"
156+
"{parameters: [{ name: 'artifactIdentity', value : to_string(@.identity) }, { name: 'testCase', value: to_string(@.testCaseExecutions[0].testCase.id) }]}"
157157

158-
This expression only selects the field identity from the aggregated object
159-
and this is used as value for the parameter "artifactIdentity", and the
160-
complete notification message can be seen below:
158+
This expression selects the field identity from the aggregated object
159+
and this is used as value for the parameter "artifactIdentity". The second
160+
parameter is also extracted from the aggregation and results in a string
161+
value of the testcase id. The complete notification message can be seen below:
161162

162163
parameters:
163164
artifactIdentity: pkg:maven/com.mycompany.myproduct/sub-system@1.1.0
164165
testCase: TC5
165-
runpipeline: mybuildstep
166-
167166

168167
## Failed notifications
169168

170169
If the notification via REST POST fails, then a fixed number of attempts are
171170
made to resend successfully. The number of attempts are specified in the
172171
[application.properties](https://github.com/eiffel-community/eiffel-intelligence/blob/master/src/main/resources/application.properties)
173172
as “notification.failAttempt”. If message sending attempts fails for the
174-
specified number of time, then a failed notification is prepared and stored
175-
in database. The name of the collection is specified in the application.properties
176-
file as “failed.notification.collection-name”. The message is stored in the database
177-
for a certain duration before being deleted. This time can be configured in
178-
application.properties as “notification.ttl.value”.
173+
specified number of time, then a failed notification is prepared and stored in
174+
the database. The name of the collection is specified in the application.properties
175+
file as “failed.notification.collection-name”. The message is stored in the
176+
database for a certain duration before being deleted. This time can be
177+
configured in application.properties as “notification.ttl.value”.
179178

180179
**Failed notification in the failed notification database with TTL value:**
181180

182181
[
183182
{
184183
"subscriptionName": "Sub1",
185-
"aggregatedObject": {},
184+
"aggregatedObject": { full aggregation at the time of notification attempt },
186185
"notificationMeta": "http://localhost:9999/some-endpoint",
187186
"_id": {
188187
"$oid": "5d807a1d821b960af311fab3"

‎wiki/markdown/subscription-API.md

Lines changed: 9 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -11,100 +11,19 @@
1111

1212
## Create subscriptions
1313

14-
Takes the subscription rules, the name for subscription and the user name of
15-
the person registering this subscription and saves the subscription in
16-
subscription database. The subscription name needs to be unique. Multiple
17-
subscriptions may be sent through a json array.
14+
Takes one or several subscriptions in a JSON array as input. If LDAP is
15+
activated, the username of the person registering this subscription is
16+
included when saving the subscription in the database. The subscription
17+
name needs to be unique.
1818

1919
POST /subscriptions
2020

21-
Curl command example
21+
### Curl command example:
2222

2323
curl -X POST -H "Content-type: application/json" --data @<path to file> http://<host>:8090/subscriptions
2424

25-
Example subscriptions
26-
27-
[
28-
{
29-
"subscriptionName": "Subscription_Test",
30-
"ldapUserName": "ABC",
31-
"created": "2018-08-13",
32-
"repeat": false,
33-
"notificationMeta": "http://127.0.0.1:3000/ei/test_subscription_rest",
34-
"notificationType": "REST_POST",
35-
"restPostBodyMediaType": "application/x-www-form-urlencoded",
36-
"notificationMessageKeyValues": [
37-
{
38-
"formkey": "e",
39-
"formvalue": "{parameter: [{ name: 'jsonparams', value : to_string(@) }, { name: 'runpipeline', value : 'mybuildstep' }]}"
40-
}
41-
],
42-
"requirements": [
43-
{
44-
"type": "ARTIFACT_1",
45-
"conditions": [
46-
{
47-
// notice single quotes surrounds the value to be checked
48-
// this tells jmespath that this is a constant and not
49-
// an object from the aggregated object
50-
"jmespath": "identity=='pkg:maven/com.mycompany.myproduct/artifact-name@1.0.0'"
51-
},
52-
{
53-
"jmespath": "testCaseExecutions[?testCase.conclusion == 'SUCCESSFUL' && testCase.id=='TC5']"
54-
}
55-
]
56-
},
57-
{
58-
"type": "ARTIFACT_1",
59-
"conditions": [
60-
{
61-
"jmespath": "identity=='pkg:maven/com.mycompany.myproduct/artifact-name@1.0.0'"
62-
},
63-
{
64-
"jmespath": "testCaseExecutions[?testCaseStartedEventId == '13af4a14-f951-4346-a1ba-624c79f10e98']"
65-
}
66-
]
67-
}
68-
]
69-
}
70-
]
71-
72-
73-
// this subscription will trigger a REST POST CALL
74-
// when an artifact for issue JIRA-1234
75-
// has passed testcase TC5 successfully
76-
{
77-
"created": "2017-07-26",
78-
"notificationMeta": "http://127.0.0.1:3000/ei/test_subscription_rest",
79-
"notificationType": "REST_POST",
80-
"restPostBodyMediaType": "application/json",
81-
"notificationMessageKeyValues": [
82-
{
83-
"formkey": "",
84-
"formvalue": "@"
85-
}
86-
],
87-
"repeat": false,
88-
"requirements": [
89-
{
90-
"description" : "A subscription that will notify when an artifact for given issue id, has passed a certain test successfully",
91-
"conditions": [
92-
{
93-
"jmespath": "incomplete_path_contains(@, 'issues.id','JIRA-1234')"
94-
},
95-
{
96-
"jmespath": "(length(testCaseExecutions[?(outcome.id == 'TC5' && outcome.conclusion == 'SUCCESSFUL')]) > `0`)"
97-
}
98-
],
99-
"type": "ARTIFACT_1"
100-
}
101-
],
102-
"subscriptionName": "artifactRequirementSubscription",
103-
"ldapUserName": "ABC"
104-
}
105-
106-
107-
Example of a subscription array
25+
Eiffel Intelligence takes a JSON list of one or several subscription objects.
26+
Example of a subscription array input:
10827

10928
[
11029
{
@@ -115,6 +34,8 @@ Example of a subscription array
11534
}
11635
]
11736

37+
38+
11839
## Get all subscriptions
11940

12041
Retrieves all the subscriptions

0 commit comments

Comments
 (0)