Skip to content

Commit 2650a5b

Browse files
dkastldkastl
committed
Adss docs
Signed-off-by: Daniel Kastl <[email protected]>
1 parent 78b747d commit 2650a5b

16 files changed

+333
-47
lines changed

‎.markdownlint.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"MD029": false,
3+
"MD033": false,
4+
"MD038": false,
5+
"MD041": false
6+
}

‎README.md‎

Lines changed: 2 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -38,53 +38,8 @@ More information on installing (and uninstalling) Redmine plugins can be found
3838

3939
## How to use
4040

41-
- Make sure REST web services is enabled: http://localhost:3000/settings?tab=api
42-
- Enable the plugin in project settings
43-
44-
To allow **public** access to NGSI-LD context documents, it's necessary to grant *View*
45-
permissions to the *Anonymous* role.
46-
47-
![Plugin permissions](doc/permissions.png)
48-
49-
### "Context" API endpoints
50-
51-
| Context | URL |
52-
|------------------|-----------------------------------------------------------|
53-
| General Redmine | `http://localhost:3000/ngsi/data-models/redmine-context.jsonld` |
54-
| GTT Redmine | `http://localhost:3000/ngsi/data-models/redmine-gtt-context.jsonld` |
55-
| Issues | `http://localhost:3000/ngsi/data-models/redmine-issues-context.jsonld` |
56-
| Projects | `http://localhost:3000/ngsi/data-models/redmine-projects-context.jsonld` |
57-
| Users | `http://localhost:3000/ngsi/data-models/redmine-users-context.jsonld` |
58-
| Versions | `http://localhost:3000/ngsi/data-models/redmine-versions-context.jsonld` |
59-
| Categories | `http://localhost:3000/ngsi/data-models/redmine-categories-context.jsonld` |
60-
| Trackers | `http://localhost:3000/ngsi/data-models/redmine-trackers-context.jsonld` |
61-
| Statuses | `http://localhost:3000/ngsi/data-models/redmine-statuses.jsonld` |
62-
| Priorities | `http://localhost:3000/ngsi/data-models/redmine-priorities-context.jsonld` |
63-
| Attachments | `http://localhost:3000/ngsi/data-models/redmine-attachments-context.jsonld` |
64-
| Relations | `http://localhost:3000/ngsi/data-models/redmine-relations-context.jsonld` |
65-
| Journals | `http://localhost:3000/ngsi/data-models/redmine-journals-context.jsonld` |
66-
| Details | `http://localhost:3000/ngsi/data-models/redmine-details-context.jsonld` |
67-
68-
### NGSI-LD and NGSIv2 API endpoints
69-
70-
- `.json` returns NGSIv2
71-
- `.jsonld` returns NGSI-LD (The Optional query parameter `?normalized=true|false`
72-
can be set to switch between normalized and not-normalized format for NGSI-LD.)
73-
74-
| Entity | NGSI-LD/NGSIv2 |
75-
|------------|-----------------------------------------------------------------|
76-
| Issue | GET `http://localhost:3000/ngsi/issues/{id}.{jsonld,json}` |
77-
| Project | GET `http://localhost:3000/ngsi/projects/{id}.{jsonld,json}` |
78-
| User | GET `http://localhost:3000/ngsi/users/{id}.{jsonld,json}` |
79-
| Version | GET `http://localhost:3000/ngsi/versions/{id}.{jsonld,json}` |
80-
| Category | GET `http://localhost:3000/ngsi/categories/{id}.{jsonld,json}` |
81-
| Tracker | GET `http://localhost:3000/ngsi/trackers/{id}.{jsonld,json}` |
82-
| Status | GET `http://localhost:3000/ngsi/statuses/{id}.{jsonld,json}` |
83-
| Priority | GET `http://localhost:3000/ngsi/priorities/{id}.{jsonld,json}` |
84-
| Attachment | GET `http://localhost:3000/ngsi/attachments/{id}.{jsonld,json}` |
85-
| Relation | GET `http://localhost:3000/ngsi/relations/{id}.{jsonld,json}` |
86-
| Journal | GET `http://localhost:3000/ngsi/journals/{id}.{jsonld,json}` |
87-
| Detail | GET `http://localhost:3000/ngsi/details/{id}.{jsonld,json}` |
41+
Detailed instructions on how to use the plugin and its API endpoints can be
42+
found in the [documentation](doc/index.md).
8843

8944
## Contributing and Support
9045

‎doc/api_endpoints.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# API Endpoints
2+
3+
## "Context" API endpoints
4+
5+
| Context | URL |
6+
|------------------|-----------------------------------------------------------|
7+
| General Redmine | `http://localhost:3000/ngsi/data-models/redmine-context.jsonld` |
8+
| GTT Redmine | `http://localhost:3000/ngsi/data-models/redmine-gtt-context.jsonld` |
9+
| Issues | `http://localhost:3000/ngsi/data-models/redmine-issues-context.jsonld` |
10+
| Projects | `http://localhost:3000/ngsi/data-models/redmine-projects-context.jsonld` |
11+
| Users | `http://localhost:3000/ngsi/data-models/redmine-users-context.jsonld` |
12+
| Versions | `http://localhost:3000/ngsi/data-models/redmine-versions-context.jsonld` |
13+
| Categories | `http://localhost:3000/ngsi/data-models/redmine-categories-context.jsonld` |
14+
| Trackers | `http://localhost:3000/ngsi/data-models/redmine-trackers-context.jsonld` |
15+
| Statuses | `http://localhost:3000/ngsi/data-models/redmine-statuses.jsonld` |
16+
| Priorities | `http://localhost:3000/ngsi/data-models/redmine-priorities-context.jsonld` |
17+
| Attachments | `http://localhost:3000/ngsi/data-models/redmine-attachments-context.jsonld` |
18+
| Relations | `http://localhost:3000/ngsi/data-models/redmine-relations-context.jsonld` |
19+
| Journals | `http://localhost:3000/ngsi/data-models/redmine-journals-context.jsonld` |
20+
| Details | `http://localhost:3000/ngsi/data-models/redmine-details-context.jsonld` |
21+
22+
## NGSI-LD and NGSIv2 API endpoints
23+
24+
- `.json` returns NGSIv2
25+
- `.jsonld` returns NGSI-LD (The Optional query parameter `?normalized=true|false`
26+
can be set to switch between normalized and not-normalized format for NGSI-LD.)
27+
28+
| Entity | NGSI-LD/NGSIv2 |
29+
|------------|-----------------------------------------------------------------|
30+
| Issue | GET `http://localhost:3000/ngsi/issues/{id}.{jsonld,json}` |
31+
| Project | GET `http://localhost:3000/ngsi/projects/{id}.{jsonld,json}` |
32+
| User | GET `http://localhost:3000/ngsi/users/{id}.{jsonld,json}` |
33+
| Version | GET `http://localhost:3000/ngsi/versions/{id}.{jsonld,json}` |
34+
| Category | GET `http://localhost:3000/ngsi/categories/{id}.{jsonld,json}` |
35+
| Tracker | GET `http://localhost:3000/ngsi/trackers/{id}.{jsonld,json}` |
36+
| Status | GET `http://localhost:3000/ngsi/statuses/{id}.{jsonld,json}` |
37+
| Priority | GET `http://localhost:3000/ngsi/priorities/{id}.{jsonld,json}` |
38+
| Attachment | GET `http://localhost:3000/ngsi/attachments/{id}.{jsonld,json}` |
39+
| Relation | GET `http://localhost:3000/ngsi/relations/{id}.{jsonld,json}` |
40+
| Journal | GET `http://localhost:3000/ngsi/journals/{id}.{jsonld,json}` |
41+
| Detail | GET `http://localhost:3000/ngsi/details/{id}.{jsonld,json}` |

‎doc/broker_scripts.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Broker Scripts
2+
3+
This document describes the scripts available in the `scripts` directory that
4+
help manage the context broker.
5+
6+
## Register All Subscriptions
7+
8+
**File:** `register_all_subscriptions.sh`
9+
10+
**Description:** This script registers all subscriptions from the context broker
11+
with a Redmine instance. It fetches all subscriptions, filters those with the
12+
`X-Redmine-GTT-Subscription-Template-URL` header, and makes a GET request to the
13+
URL specified in the header for each subscription.
14+
15+
**Usage:**
16+
17+
```bash
18+
./scripts/register_all_subscriptions.sh <api_key>
19+
```
20+
21+
**Arguments:**
22+
23+
- `api_key`: The API key for your Redmine instance. This can also be provided
24+
through the `REDMINE_API_KEY` environment variable.
25+
26+
**Environment Variables:**
27+
28+
- `REDMINE_API_KEY`: The API key for your Redmine instance. This is used if the
29+
`api_key` argument is not provided.
30+
- `ORION_URL`: The base URL for your Orion Context Broker. Defaults to
31+
`http://app.local:1026` if not set.
32+
33+
**Note:** Make sure to set the `REDMINE_API_KEY` and `ORION_URL` environment
34+
variables before running this script if you're not providing them as arguments.
35+
36+
To prepend an environment variable to a command in the terminal, you can do so
37+
like this:
38+
39+
```bash
40+
REDMINE_API_KEY=your_api_key ORION_URL=your_orion_url ./scripts/register_all_subscriptions.sh
41+
```
42+
43+
Replace `your_api_key` with your actual Redmine API key and `your_orion_url`
44+
with the correct URL. This will set the `REDMINE_API_KEY` and `ORION_URL`
45+
environment variables for the duration of the `register_all_subscriptions.sh` script.
46+
47+
## Delete All Subscriptions
48+
49+
**File:** `delete_all_subscriptions.sh`
50+
51+
**Description:** This script deletes all subscriptions from the context broker.
52+
It makes a GET request to the `/v2/subscriptions` endpoint to retrieve all
53+
subscriptions, and then makes DELETE requests to the
54+
`/v2/subscriptions/{subscriptionId}` endpoint to delete each one.
55+
56+
**Usage:**
57+
58+
```bash
59+
./scripts/delete_all_subscriptions.sh
60+
```
61+
62+
**Environment Variables:**
63+
64+
- `ORION_URL`: The base URL for your Orion Context Broker. Defaults to
65+
`http://app.local:1026` if not set.
66+
67+
**Note:** This script does not require any arguments. Make sure to set the
68+
`ORION_URL` environment variable to your context broker URL before running this script.
69+
70+
To prepend an environment variable to a command in the terminal, you can do so
71+
like this:
72+
73+
```bash
74+
ORION_URL=your_orion_url ./scripts/delete_all_subscriptions.sh
75+
```
76+
77+
Replace `your_orion_url` with your actual Redmine API key. This will set the
78+
`ORION_URL` environment variable for the duration of the
79+
`delete_all_subscriptions.sh` script.

‎doc/curl_examples.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# cURL Examples
2+
3+
This section provides examples of how to interact with the FIWARE Broker using cURL.
4+
5+
## Prerequisites
6+
7+
Before running the cURL commands, make sure you have the following:
8+
9+
- The FIWARE context broker URL.
10+
- An entity type (e.g., `TemperatureSensor` for temperature and `LocationSensor`
11+
for location).
12+
13+
```bash
14+
export BROKER_URL="your_broker_url"
15+
```
16+
17+
Replace `your_broker_url` with the actual URL of your FIWARE broker. After
18+
running this command, the BROKER_URL environment variable will be
19+
available to all subsequent commands in the same terminal session.
20+
21+
### Entity Types
22+
23+
In this walkthrough, we will be using two entity types:
24+
25+
- `TemperatureSensor`: Represents sensors that measure temperature.
26+
- `LocationSensor`: Represents sensors that provide location data.
27+
28+
### Creating an Entity with Temperature
29+
30+
```bash
31+
curl -iX POST \
32+
'http://${BROKER_URL}/v2/entities' \
33+
-H 'Content-Type: application/json' \
34+
-d '{
35+
"id": "urn:ngsi-ld:TemperatureSensor:001",
36+
"type": "TemperatureSensor",
37+
"temperature": {
38+
"value": 25.0,
39+
"type": "Number"
40+
}
41+
}'
42+
```
43+
44+
### Creating an Entity with Location
45+
46+
```bash
47+
curl -iX POST \
48+
'http://${BROKER_URL}/v2/entities' \
49+
-H 'Content-Type: application/json' \
50+
-d '{
51+
"id": "urn:ngsi-ld:LocationSensor:001",
52+
"type": "LocationSensor",
53+
"location": {
54+
"value": {
55+
"type": "Point",
56+
"coordinates": [40.418889, -3.691944]
57+
},
58+
"type": "geo:json"
59+
}
60+
}'
61+
```
62+
63+
## Example cURL Commands
64+
65+
### Update Temperature
66+
67+
```bash
68+
curl -iX PATCH \
69+
'http://${BROKER_URL}/v2/entities/urn:ngsi-ld:TemperatureSensor:001/attrs' \
70+
-H 'Content-Type: application/json' \
71+
-d '{
72+
"temperature": {
73+
"value": 28.0,
74+
"type": "Number"
75+
}
76+
}'
77+
```
78+
79+
### Update Location
80+
81+
```bash
82+
curl -iX PATCH \
83+
'http://${BROKER_URL}/v2/entities/urn:ngsi-ld:LocationSensor:001/attrs' \
84+
-H 'Content-Type: application/json' \
85+
-d '{
86+
"location": {
87+
"value": {
88+
"type": "Point",
89+
"coordinates": [41.376944, 2.185556]
90+
},
91+
"type": "geo:json"
92+
}
93+
}'
94+
```
95+
96+
### Get Entities
97+
98+
```bash
99+
curl -iX GET \
100+
'http://${BROKER_URL}/v2/entities' \
101+
-H 'Accept: application/json'
102+
```
103+
104+
### Get Subscriptions
105+
106+
```bash
107+
curl -iX GET \
108+
'http://${BROKER_URL}/v2/subscriptions' \
109+
-H 'Accept: application/json'
110+
```
111+
112+
## Notes
113+
114+
- Ensure that the FIWARE context broker is running and accessible.
115+
- The coordinates in the location examples are in [longitude, latitude] format.
116+
117+
These cURL commands should help you interact with the FIWARE broker and test the
118+
Redmine GTT FIWARE plugin effectively. If you encounter any issues or need
119+
further assistance, please let me know!

‎doc/form_subscription_template.png‎

162 KB
Loading

‎doc/form_subscription_template_general.png‎

28.8 KB
Loading

‎doc/form_subscription_template_issue.png‎

91.7 KB
Loading

‎doc/form_subscription_template_subscription.png‎

52.4 KB
Loading

‎doc/index.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Redmine GTT FIWARE Plugin Documentation
2+
3+
This documentation provides detailed instructions on how to use the Redmine GTT
4+
FIWARE plugin and its API endpoints.
5+
6+
## First Steps
7+
8+
- Make sure REST web services is enabled: <http://localhost:3000/settings?tab=api>
9+
- Enable the plugin in project settings
10+
11+
To allow **public** access to NGSI-LD context documents, it's necessary to grant
12+
*View* permissions to the *Anonymous* role.
13+
14+
![Plugin permissions](permissions.png)
15+
16+
## Table of Contents
17+
18+
- [Plugin Settings](plugin_settings.md)
19+
- [Project Settings](project_settings.md)
20+
- [Subscription Templates](subscription_template.md)
21+
- [API Endpoints](api_endpoints.md)
22+
- [FIWARE Broker Scripts](broker_scripts.md)
23+
- [cURL Examples](curl_examples.md)

0 commit comments

Comments
 (0)