From c842647759ece46f6cbd03e4cb154b19dd1cb4fe Mon Sep 17 00:00:00 2001 From: Musilah Date: Wed, 12 Feb 2025 15:37:46 +0300 Subject: [PATCH] restructure files Signed-off-by: Musilah --- docs/cli/users-cli.md | 273 --------- docs/{ => dev-guide}/api.md | 0 docs/{ => dev-guide}/authentication.md | 0 docs/{ => dev-guide}/authorization.md | 34 +- docs/{ => dev-guide}/benchmark.md | 0 docs/{ => dev-guide}/bootstrap.md | 12 +- docs/{ => dev-guide}/certs.md | 0 docs/{ => dev-guide}/cli/bootstrap-cli.md | 0 docs/{ => dev-guide}/cli/consumers-cli.md | 0 docs/{ => dev-guide}/cli/groups-cli.md | 85 ++- .../cli/introduction-to-cli.md | 5 +- docs/{ => dev-guide}/cli/messages-cli.md | 0 docs/{ => dev-guide}/cli/provision-cli.md | 0 docs/dev-guide/cli/users-cli.md | 570 ++++++++++++++++++ docs/{ => dev-guide}/dev-guide.md | 0 docs/{ => dev-guide}/edge.md | 4 +- docs/{ => dev-guide}/entities.md | 0 docs/{ => dev-guide}/events.md | 0 docs/{ => dev-guide}/getting-started.md | 0 docs/{ => dev-guide}/kubernetes.md | 0 docs/{ => dev-guide}/lora.md | 0 docs/{ => dev-guide}/messaging.md | 0 docs/{ => dev-guide}/opcua.md | 2 +- docs/{ => dev-guide}/provision.md | 0 docs/{ => dev-guide}/security.md | 0 docs/{ => dev-guide}/storage.md | 0 docs/{ => dev-guide}/tracing.md | 6 +- docs/{ => dev-guide}/twins.md | 4 +- docs/{ => user-guide}/architecture.md | 6 +- docs/{ => user-guide}/clients/bootstraps.md | 14 +- docs/{ => user-guide}/clients/channels.md | 48 +- docs/{ => user-guide}/clients/clients.md | 42 +- docs/{ => user-guide}/clients/groups.md | 36 +- docs/{ => user-guide}/clients/image.png | Bin docs/{ => user-guide}/clients/introduction.md | 0 docs/{ => user-guide}/dashboards/areachart.md | 15 +- docs/{ => user-guide}/dashboards/barchart.md | 11 +- docs/{ => user-guide}/dashboards/controls.md | 22 +- docs/{ => user-guide}/dashboards/countcard.md | 13 +- .../{ => user-guide}/dashboards/dashboards.md | 33 +- docs/{ => user-guide}/dashboards/gauges.md | 27 +- .../dashboards/introduction.md | 2 +- docs/{ => user-guide}/dashboards/linechart.md | 18 +- docs/{ => user-guide}/dashboards/maps.md | 45 +- docs/{ => user-guide}/dashboards/piechart.md | 15 +- docs/{ => user-guide}/dashboards/tablecard.md | 10 +- docs/{ => user-guide}/dashboards/valuecard.md | 12 +- docs/{ => user-guide}/dashboards/widgets.md | 48 +- .../domain-management/billing.md | 24 +- .../domain-management/domain.md | 14 +- .../domain-management/introduction.md | 0 .../domain-management/invitations.md | 0 docs/{ => user-guide}/index.md | 3 +- .../profile-management/users.md | 21 +- docs/{ => user-guide}/rules-engine.md | 14 +- docs/{ => user-guide}/users-quick-start.md | 31 +- docusaurus.config.ts | 6 +- sidebars.ts | 106 ++-- 58 files changed, 984 insertions(+), 647 deletions(-) delete mode 100644 docs/cli/users-cli.md rename docs/{ => dev-guide}/api.md (100%) rename docs/{ => dev-guide}/authentication.md (100%) rename docs/{ => dev-guide}/authorization.md (97%) rename docs/{ => dev-guide}/benchmark.md (100%) rename docs/{ => dev-guide}/bootstrap.md (97%) rename docs/{ => dev-guide}/certs.md (100%) rename docs/{ => dev-guide}/cli/bootstrap-cli.md (100%) rename docs/{ => dev-guide}/cli/consumers-cli.md (100%) rename docs/{ => dev-guide}/cli/groups-cli.md (54%) rename docs/{ => dev-guide}/cli/introduction-to-cli.md (90%) rename docs/{ => dev-guide}/cli/messages-cli.md (100%) rename docs/{ => dev-guide}/cli/provision-cli.md (100%) create mode 100644 docs/dev-guide/cli/users-cli.md rename docs/{ => dev-guide}/dev-guide.md (100%) rename docs/{ => dev-guide}/edge.md (99%) rename docs/{ => dev-guide}/entities.md (100%) rename docs/{ => dev-guide}/events.md (100%) rename docs/{ => dev-guide}/getting-started.md (100%) rename docs/{ => dev-guide}/kubernetes.md (100%) rename docs/{ => dev-guide}/lora.md (100%) rename docs/{ => dev-guide}/messaging.md (100%) rename docs/{ => dev-guide}/opcua.md (99%) rename docs/{ => dev-guide}/provision.md (100%) rename docs/{ => dev-guide}/security.md (100%) rename docs/{ => dev-guide}/storage.md (100%) rename docs/{ => dev-guide}/tracing.md (96%) rename docs/{ => dev-guide}/twins.md (99%) rename docs/{ => user-guide}/architecture.md (98%) rename docs/{ => user-guide}/clients/bootstraps.md (90%) rename docs/{ => user-guide}/clients/channels.md (79%) rename docs/{ => user-guide}/clients/clients.md (79%) rename docs/{ => user-guide}/clients/groups.md (82%) rename docs/{ => user-guide}/clients/image.png (100%) rename docs/{ => user-guide}/clients/introduction.md (100%) rename docs/{ => user-guide}/dashboards/areachart.md (88%) rename docs/{ => user-guide}/dashboards/barchart.md (89%) rename docs/{ => user-guide}/dashboards/controls.md (91%) rename docs/{ => user-guide}/dashboards/countcard.md (90%) rename docs/{ => user-guide}/dashboards/dashboards.md (82%) rename docs/{ => user-guide}/dashboards/gauges.md (86%) rename docs/{ => user-guide}/dashboards/introduction.md (91%) rename docs/{ => user-guide}/dashboards/linechart.md (84%) rename docs/{ => user-guide}/dashboards/maps.md (86%) rename docs/{ => user-guide}/dashboards/piechart.md (90%) rename docs/{ => user-guide}/dashboards/tablecard.md (92%) rename docs/{ => user-guide}/dashboards/valuecard.md (90%) rename docs/{ => user-guide}/dashboards/widgets.md (90%) rename docs/{ => user-guide}/domain-management/billing.md (87%) rename docs/{ => user-guide}/domain-management/domain.md (87%) rename docs/{ => user-guide}/domain-management/introduction.md (100%) rename docs/{ => user-guide}/domain-management/invitations.md (100%) rename docs/{ => user-guide}/index.md (98%) rename docs/{ => user-guide}/profile-management/users.md (78%) rename docs/{ => user-guide}/rules-engine.md (83%) rename docs/{ => user-guide}/users-quick-start.md (85%) diff --git a/docs/cli/users-cli.md b/docs/cli/users-cli.md deleted file mode 100644 index e3202eb..0000000 --- a/docs/cli/users-cli.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: Users ---- - - -Magistrala CLI provides a simple and efficient way to manage users. Below are the key commands to create, authenticate, and manage users within your system. - -### Create User - -To create a user using `Magistrala-CLI`, run the following command: - -```bash - -magistrala-cli users create - -``` - -This command registers a new user with the provided details. - -Example usage: - -```bash - magistrala-cli users create jane doe janedoe@example.com janedoe 12345678 -``` - -Expected response: - -```json -{ - "created_at": "2025-02-11T00:25:52.252742Z", - "credentials": { - "username": "janedoe" - }, - "email": "janedoe@example.com", - "first_name": "jane", - "id": "32632742-87e8-4ce1-b8ef-ace23b3683aa", - "last_name": "doe", - "role": "user", - "status": "enabled", - "updated_at": "0001-01-01T00:00:00Z" -} -``` - -> ⚠️ **Note:** Ensure that usernames are unique to prevent conflicts. - -### Login User - -To log in and obtain an access token: - -```bash -magistrala-cli users token [|] -``` - -Since v0.14.0, Magistrala supports domains. **Domains** are used to separate different tenants, and almost all the activities in Magistrala happen under a particular domain. -Only three major types of actions do not happen within a domain: login where you get to list domains and log in to them, and invitations management to accept domain membership sent by other users as well the creation of new users. -An access token with a domain is required for all the other actions on Clients, Channels, and Groups. -To authenticate within a specific domain, use: - -```bash -magistrala-cli users token -``` - -Example usage: - -Expected response: - -### Refresh User Token - -If the access token has expired, you can obtain a new one using the refresh token: - -```bash -magistrala-cli users refreshtoken -``` - -Example usage: - -Expected response: - -### Retrieve a Specific User - -To get details of a specific user: - -```bash -magistrala-cli users get -``` - -Example usage: - -Expected response: - -### Retrieve All Users - -To list all users: - -```bash -magistrala-cli users get all -``` - -Example usage: - -Expected response: - -### Update User Information - -Using the update flag can update the user's names, tags, metadata, email as well as username. - -#### **Update User Names** - -To update a user's names: - -```bash -magistrala-cli users update '{"first_name":"new first_name", "last_name":"new last_name"}' -``` - -Example usage: - -Expected response: - -#### **Update User Metadata** - -To update a user's metadata: - -```bash -magistrala-cli users update '{"metadata":{"value2": "value3"}}' -``` - -Example usage: - -Expected response: - -#### **Update User Tags** - -To update a user's tags: - -```bash -magistrala-cli users update tags '["tag1", "tag2"]' -``` - -Example usage: - -Expected response: - -#### **Update User Email** - -To update a user's email: - -```bash -magistrala-cli users update email -``` - -Example usage: - -Expected response: - -#### **Update Username** - -To update a user's username: - -```bash -magistrala-cli users update username -``` - -Example usage: - -Expected response: - -#### **Update Profile Picture** - -To update the user's profile-picture string `URL`: - -```bash -magistrala-cli users update -``` - -Example usage: - -Expected response: - -### Update User Password - -To update a user's password: - -```bash -magistrala-cli users password -``` - -Example usage: - -Expected response: - -### Reset User Password Request - -To send a request to reset a user's password: - -```bash -magistrala-cli users resetpasswordrequest -``` - -Example usage: - -Expected response: - -### Reset User Password - -To reset a user's password: - -```bash -magistrala-cli users resetpassword -``` - -Example usage: - -Expected response: - -### Enable User - -To enable a user's status: - -```bash -magistrala-cli users enable -``` - -Example usage: - -Expected response: - -### Disable User - -To disable a user: - -```bash -magistrala-cli users disable -``` - -Example usage: - -Expected response: - -### Delete User - -To delete a user: - -```bash -magistrala-cli users delete -``` - -Example usage: - -Expected response: - -### Get Profile of the User - -To get the profile details of the currently authenticated user: - -```bash -magistrala-cli users profile -``` - -Example usage: - -Expected response: - -### Search User - -To search for a specific user using queries: - -```bash -magistrala-cli users search -``` - -Example usage: - -Expected response: diff --git a/docs/api.md b/docs/dev-guide/api.md similarity index 100% rename from docs/api.md rename to docs/dev-guide/api.md diff --git a/docs/authentication.md b/docs/dev-guide/authentication.md similarity index 100% rename from docs/authentication.md rename to docs/dev-guide/authentication.md diff --git a/docs/authorization.md b/docs/dev-guide/authorization.md similarity index 97% rename from docs/authorization.md rename to docs/dev-guide/authorization.md index 558706c..89cfd7b 100644 --- a/docs/authorization.md +++ b/docs/dev-guide/authorization.md @@ -316,7 +316,7 @@ Users can have any one of the following relations with a domain **Let's take the below domain_1 with entities for explaining about user domain relationship.** -![domain_users](diagrams/domain_users.svg) +![domain_users](../diagrams/domain_users.svg) ### Domain Administrator @@ -325,7 +325,7 @@ Users with administrator relations have full control over all entities (things, **Example:** **user_1** is **administrator** of **domain_1**. **user_1 can view all entities created by others and have administrator access to all entities in the domain**. -![domain_users_administrator](diagrams/domain_users_administrator.svg) +![domain_users_administrator](../diagrams/domain_users_administrator.svg) ### Domain Editor @@ -334,7 +334,7 @@ Users with editor relations have access to update all entities (things, channels **Example:** **user_2** is **editor** of **domain_1**. **user_2 can view all entities and have edit access to groups and channel entities, view access to thing entities in the domain, and also able to create & manage new things, channels & groups**. -![domain_users_editor](diagrams/domain_users_editor.svg) +![domain_users_editor](../diagrams/domain_users_editor.svg) ### Domain Viewer @@ -343,7 +343,7 @@ Users with viewer relations have access to view all entities (things, channels, **Example:** **user_3 can only view entities that are created by others in the domain and also able to create & manage new things, channels & groups** -![domain_users_viewer](diagrams/domain_users_viewer.svg) +![domain_users_viewer](../diagrams/domain_users_viewer.svg) ### Domain Member @@ -354,7 +354,7 @@ Domain members will not have access by default to any of the entities in the Dom **user_4 , user_5, user_6, user_7, user_8, user_9** is **member** of **domain_1**. **These member relation users can able to create & manage new things, channels & groups in the domain. They can have access to the entities to which they have a relation in the domain. They could not view and manage other entities to which they don't have any relation in domain**. !!! note "Note: All other users having administrator, editor, viewer relation with domain will also have member relation inherit with domain, which allows them to create new things, channels & groups." -![domain_users_member](diagrams/domain_users_member.svg) +![domain_users_member](../diagrams/domain_users_member.svg) After the user sign-up to Magistrala, the user is allowed to create a new domain or join an existing domain via invitations, without domain user could not create _things_, _channels_, _groups_. @@ -662,7 +662,7 @@ EOF The user who creates the entity will be the administrator of the entity by default. So **user_3** is **administrator** of **thing_101, channel_101 and group_101.** -![group_users_administrator_1](diagrams/group_users_administrator_1.svg) +![group_users_administrator_1](../diagrams/group_users_administrator_1.svg) !!! Note "user_3 will also have domain viewer relation to thing_101, channel_101, and group_101" @@ -690,7 +690,7 @@ curl -sSiX POST 'http://localhost/channels//groups/assign' -H "C EOF ``` -![group_users_administrator_2](diagrams/group_users_administrator_2.svg) +![group_users_administrator_2](../diagrams/group_users_administrator_2.svg) **Members of domain 1 will not have access by default to any of the entities in domain 1, access shall be granted for specific entities by domain administrator or individual entity administrator.** @@ -707,7 +707,7 @@ curl -sSiX POST 'http://localhost/domains//users/assign' -H "Conte } ``` -![group_users_administrator_3](diagrams/group_users_administrator_3.svg) +![group_users_administrator_3](../diagrams/group_users_administrator_3.svg) ### Group Editor @@ -716,7 +716,7 @@ Group editor users have access to view, update, assign, and unassign to the grou **Administrator of group_101 (user_3/user_4), assigns user_5 with editor relation.** **When domain member user_5 becomes an editor of group_101, user_5 can able to update, assign, and unassign to group_101. Since group_101 has channel_101 and thing_101 as children. The user_5 has editor access to the group child entities channels, things, and groups. In this case, user_5 has editor access to group_101, and also has edit access to its child entities channel_101 and thing_101** -![group_users_editor](diagrams/group_users_editor.svg) +![group_users_editor](../diagrams/group_users_editor.svg) ### Group Viewer @@ -724,7 +724,7 @@ Group viewer users have access to view group and also have access to view all of **When domain member user_6 becomes a viewer of group_101, user_6 can able to view all the child and nested child entities in group_101. user_6 can assign child entities under group_101 and also assign child entities under any other group and channels that are children of group_101.** -![group_users_viewer](diagrams/group_users_viewer.svg) +![group_users_viewer](../diagrams/group_users_viewer.svg) ## Examples @@ -732,37 +732,37 @@ Group viewer users have access to view group and also have access to view all of user_6 creates new channel and thing with the names channel_201 and thing_201 respectively. Then connects both channel_201 and thing_201. -![group_users_viewer_1](diagrams/group_users_viewer_1.svg) +![group_users_viewer_1](../diagrams/group_users_viewer_1.svg) Now user_5 can able to assign group_101 as a parent for channel_201 -![group_users_viewer_2](diagrams/group_users_viewer_2.svg) +![group_users_viewer_2](../diagrams/group_users_viewer_2.svg) When channel_201 was assigned as a child of group_101, all the administrators, editors, and viewers of group_101 got the same access (relation) to channel_201 and thing_201 -![group_users_viewer_3](diagrams/group_users_viewer_3.svg) +![group_users_viewer_3](../diagrams/group_users_viewer_3.svg) ### Multiple Domain Members with Group, Channel & Thing user_8 creates a new group with the name group_301 user_9 creates a new thing and channel with the names thing_301 and channel_301 respectively, then connects both thing and channel. -![group_users_member_11](diagrams/group_users_member_11.svg) +![group_users_member_11](../diagrams/group_users_member_11.svg) user_8 can able to assign channel_301 as a child of group_301 -![group_users_member_12](diagrams/group_users_member_12.svg) +![group_users_member_12](../diagrams/group_users_member_12.svg) When channel_301 is assigned as a child of group_301, then the administrators, editors, and viewers of group_301 get the same respective access to channel_301. The administrator, editor, and viewer of channel_301 get the same respective access to thing_301. So here user_8 becomes the administrator of both channel_301 and thing_301 user_5 can able to assign group_301 as a child of group_101 -![group_users_member_13](diagrams/group_users_member_13.svg) +![group_users_member_13](../diagrams/group_users_member_13.svg) When group_301 becomes a child of group_101, then the administrator, editor, and viewer of group_101 get the same respective access to group_301. The administrator, editor, and viewer of group_301 get the same respective access to channel_301. The administrator, editor, and viewer of channel_301 get the same respective access to thing_301. So here user_5 becomes the editor of group_301, channel_301, and thing_301, user_4 becomes administrator of group_301, channel_301, and thing_301. user_8 has administrator access only to group_301 and its child entities channel_301 and thing_301. -![group_users_member_14](diagrams/group_users_member_14.svg) +![group_users_member_14](../diagrams/group_users_member_14.svg) ## User Registration diff --git a/docs/benchmark.md b/docs/dev-guide/benchmark.md similarity index 100% rename from docs/benchmark.md rename to docs/dev-guide/benchmark.md diff --git a/docs/bootstrap.md b/docs/dev-guide/bootstrap.md similarity index 97% rename from docs/bootstrap.md rename to docs/dev-guide/bootstrap.md index 6e03728..7fadbe1 100644 --- a/docs/bootstrap.md +++ b/docs/dev-guide/bootstrap.md @@ -13,24 +13,24 @@ title: Bootstrap Bootstrapping procedure is the following: -![Configure device](img/bootstrap/1.png) +![Configure device](../img/bootstrap/1.png) _1) Configure device with Bootstrap service URL, an external key and external ID_ -> ![Provision Magistrala channels](img/bootstrap/2.png) +> ![Provision Magistrala channels](../img/bootstrap/2.png) > > _Optionally create Magistrala channels if they don't exist_ > -> ![Provision Magistrala things](img/bootstrap/3.png) +> ![Provision Magistrala things](../img/bootstrap/3.png) > > _Optionally create Magistrala thing if it doesn't exist_ -![Upload configuration](img/bootstrap/4.png) +![Upload configuration](../img/bootstrap/4.png) _2) Upload configuration for the Magistrala thing_ -![Bootstrap](img/bootstrap/5.png) +![Bootstrap](../img/bootstrap/5.png) _3) Bootstrap - send a request for the configuration_ -![Update, enable/disable, remove](img/bootstrap/6.png) +![Update, enable/disable, remove](../img/bootstrap/6.png) _4) Connect/disconnect thing from channels, update or remove configuration_ ## Configuration diff --git a/docs/certs.md b/docs/dev-guide/certs.md similarity index 100% rename from docs/certs.md rename to docs/dev-guide/certs.md diff --git a/docs/cli/bootstrap-cli.md b/docs/dev-guide/cli/bootstrap-cli.md similarity index 100% rename from docs/cli/bootstrap-cli.md rename to docs/dev-guide/cli/bootstrap-cli.md diff --git a/docs/cli/consumers-cli.md b/docs/dev-guide/cli/consumers-cli.md similarity index 100% rename from docs/cli/consumers-cli.md rename to docs/dev-guide/cli/consumers-cli.md diff --git a/docs/cli/groups-cli.md b/docs/dev-guide/cli/groups-cli.md similarity index 54% rename from docs/cli/groups-cli.md rename to docs/dev-guide/cli/groups-cli.md index be5f108..7da0a39 100644 --- a/docs/cli/groups-cli.md +++ b/docs/dev-guide/cli/groups-cli.md @@ -19,8 +19,25 @@ This command registers a new group with the provided details. Example usage: +```bash +magistrala-cli groups create '{"name":"group 1"}' 9879f314-8b0a-4a11-b157-8523491ffa81 token +``` + Expected response: +```json +{ + "created_at": "2025-02-12T09:48:21.886997Z", + "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81", + "id": "a90eced3-daaa-4f51-a031-0103ff00e746", + "level": 1, + "name": "group 1", + "path": "a90eced3-daaa-4f51-a031-0103ff00e746", + "status": "enabled", + "updated_at": "0001-01-01T00:00:00Z" +} +``` + ### Retrieve a Specific Group To get the details of group: @@ -57,8 +74,24 @@ This command allows you to modify the group name, description, and metadata. Example usage: +```bash +magistrala-cli groups update '{"id":"497b188c-d439-43bb-bbd6-d728a736d4ce","name":"Group duo"}' 9879f314-8b0a-4a11-b157-8523491ffa81 token +``` + Expected response: +```json +{ + "created_at": "2025-02-12T09:57:57.05256Z", + "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81", + "id": "497b188c-d439-43bb-bbd6-d728a736d4ce", + "name": "Group duo", + "status": "enabled", + "updated_at": "2025-02-12T09:59:44.829208Z", + "updated_by": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b" +} +``` + ### Enable Group To change group status to enabled: @@ -69,8 +102,24 @@ magistrala-cli groups enable Example usage: +```bash +magistrala-cli groups enable a90eced3-daaa-4f51-a031-0103ff00e746 9879f314-8b0a-4a11-b157-8523491ffa81 token +``` + Expected response: +```json +{ + "created_at": "2025-02-12T09:48:21.886997Z", + "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81", + "id": "a90eced3-daaa-4f51-a031-0103ff00e746", + "name": "group 1", + "status": "enabled", + "updated_at": "2025-02-12T10:08:37.864362Z", + "updated_by": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b" +} +``` + ### Disable Group To change group status to disabled: @@ -81,8 +130,24 @@ magistrala-cli groups disable Example usage: +```bash +magistrala-cli groups disable a90eced3-daaa-4f51-a031-0103ff00e746 9879f314-8b0a-4a11-b157-8523491ffa81 token +``` + Expected response: +```json +{ + "created_at": "2025-02-12T09:48:21.886997Z", + "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81", + "id": "a90eced3-daaa-4f51-a031-0103ff00e746", + "name": "group 1", + "status": "disabled", + "updated_at": "2025-02-12T10:07:04.741721Z", + "updated_by": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b" +} +``` + ### Delete Group To delete a group from the system: @@ -91,46 +156,26 @@ To delete a group from the system: magistrala-cli groups delete ``` -Example usage: - -Expected response: - ### Get Group Members ```bash magistrala-cli groups members ``` -Example usage: - -Expected response: - ### Get Memberships ```bash magistrala-cli groups membership ``` -Example usage: - -Expected response: - ### Assign Members to Group ```bash magistrala-cli groups assign ``` -Example usage: - -Expected response: - ### Unassign Members to Group ```bash magistrala-cli groups unassign ``` - -Example usage: - -Expected response: diff --git a/docs/cli/introduction-to-cli.md b/docs/dev-guide/cli/introduction-to-cli.md similarity index 90% rename from docs/cli/introduction-to-cli.md rename to docs/dev-guide/cli/introduction-to-cli.md index e9c4049..296725f 100644 --- a/docs/cli/introduction-to-cli.md +++ b/docs/dev-guide/cli/introduction-to-cli.md @@ -87,9 +87,8 @@ For example: docker run -it --rm magistrala/cli -u http://192.168.160.1 users token admin@example.com 12345678 { - "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODA2MjEzMDcsImlhdCI6MTY4MDYyMDQwNywiaWRlbnRpdHkiOiJhZG1pbkBleGFtcGxlLmNvbSIsImlzcyI6ImNsaWVudHMuYXV0aCIsInN1YiI6ImYxZTA5Y2YxLTgzY2UtNDE4ZS1iZDBmLWU3M2I3M2MxNDM2NSIsInR5cGUiOiJhY2Nlc3MifQ.iKdBv3Ko7PKuhjTC6Xs-DvqfKScjKted3ZMorTwpXCd4QrRSsz6NK_lARG6LjpE0JkymaCMVMZlzykyQ6ZgwpA", - "access_type": "Bearer", - "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODA3MDY4MDcsImlhdCI6MTY4MDYyMDQwNywiaWRlbnRpdHkiOiJhZG1pbkBleGFtcGxlLmNvbSIsImlzcyI6ImNsaWVudHMuYXV0aCIsInN1YiI6ImYxZTA5Y2YxLTgzY2UtNDE4ZS1iZDBmLWU3M2I3M2MxNDM2NSIsInR5cGUiOiJyZWZyZXNoIn0.-0tOtXFZi48VS-FxkCnVxnW2RUkJvqUmzRz3_EYSSKFyKealoFrv7sZIUvrdvKomnUFzXshP0EygL8vjWP1SFw" + "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkyOTQxMjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MCwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.Qot3ZoqC1enhAS3YEJY3WJioMAJnr98laBGsJzSgF2Zege5pVqILVLcPZzRBmHdIPys4diAGbqRQQzfW_k_Huw", + "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkzNzY5MjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MSwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.EcRH3DUZcplHz-9Ry_90kSQKLwAWXPww9XfMZ9beoEJItpY39g5-n7vnTyLkRhOp6Pw6aZbfuhOL3TWIE-Q13A" } ``` diff --git a/docs/cli/messages-cli.md b/docs/dev-guide/cli/messages-cli.md similarity index 100% rename from docs/cli/messages-cli.md rename to docs/dev-guide/cli/messages-cli.md diff --git a/docs/cli/provision-cli.md b/docs/dev-guide/cli/provision-cli.md similarity index 100% rename from docs/cli/provision-cli.md rename to docs/dev-guide/cli/provision-cli.md diff --git a/docs/dev-guide/cli/users-cli.md b/docs/dev-guide/cli/users-cli.md new file mode 100644 index 0000000..e8fc21d --- /dev/null +++ b/docs/dev-guide/cli/users-cli.md @@ -0,0 +1,570 @@ +--- +title: Users +--- + + +Magistrala CLI provides a simple and efficient way to manage users. Below are the key commands to create, authenticate, and manage users within your system. + +### Create User + +To create a user using `Magistrala-CLI`, run the following command: + +```bash + +magistrala-cli users create + +``` + +This command registers a new user with the provided details. + +Example usage: + +```bash + magistrala-cli users create jane doe janedoe@example.com janedoe 12345678 +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "janedoe" + }, + "email": "janedoe@example.com", + "first_name": "jane", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "doe", + "role": "user", + "status": "enabled", + "updated_at": "0001-01-01T00:00:00Z" +} +``` + +> ⚠️ **Note:** Ensure that usernames are unique to prevent conflicts. + +### Login User + +To log in and obtain an access token: + +```bash +magistrala-cli users token [|] +``` + +Since v0.14.0, Magistrala supports domains. **Domains** are used to separate different tenants, and almost all the activities in Magistrala happen under a particular domain. +Only three major types of actions do not happen within a domain: login where you get to list domains and log in to them, and invitations management to accept domain membership sent by other users as well the creation of new users. +An access token with a domain is required for all the other actions on Clients, Channels, and Groups. +To authenticate within a specific domain, use: + +```bash +magistrala-cli users token +``` + +Example usage: + +```bash +magistrala-cli users token admin 12345678 +``` + +Expected response: + +```json +{ + "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkyOTQxMjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MCwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.Qot3ZoqC1enhAS3YEJY3WJioMAJnr98laBGsJzSgF2Zege5pVqILVLcPZzRBmHdIPys4diAGbqRQQzfW_k_Huw", + "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkzNzY5MjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MSwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.EcRH3DUZcplHz-9Ry_90kSQKLwAWXPww9XfMZ9beoEJItpY39g5-n7vnTyLkRhOp6Pw6aZbfuhOL3TWIE-Q13A" +} +``` + +### Refresh User Token + +If the access token has expired, you can obtain a new one using the refresh token: + +```bash +magistrala-cli users refreshtoken +``` + +Example usage: + +```bash +magistrala-cli users refreshtoken eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkzNzY5MjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MSwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.EcRH3DUZcplHz-9Ry_90kSQKLwAWXPww9XfMZ9beoEJItpY39g5-n7vnTyLkRhOp6Pw6aZbfuhOL3TWIE-Q13A +``` + +Expected response: + +```json +{ + "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkyOTQ2MTQsImlhdCI6MTczOTI5MTAxNCwiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MCwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.MlAUDZYNg2D5Bj9m6IAaXe6wo-U1-q4OpLjrB9TMfg30W1J0ybp2KE_cMfAzMyLUY-Kk_d1e0WYGgIUg7Rgm-Q", + "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkzNzc0MTQsImlhdCI6MTczOTI5MTAxNCwiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MSwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.FQNUwTQPVxas9l1p6ywy7UYO4Dc4rpgbkyMhzPSY20A9JMXFWYh43bxQugu4CsE3eAnp5Zxk9QXxKjmrKIMGiA" +} +``` + +### Retrieve a Specific User + +To get details of a specific user: + +```bash +magistrala-cli users get +``` + +Example usage: + +```bash +26ae3198-6060-4308-824c-c846953b9898 token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "janedoe" + }, + "email": "janedoe@example.com", + "first_name": "jane", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "doe", + "role": "user", + "status": "enabled", + "updated_at": "0001-01-01T00:00:00Z" +} +``` + +### Retrieve All Users + +To list all users: + +```bash +magistrala-cli users get all +``` + +Example usage: + +```bash +magistrala-cli users get all token +``` + +Expected response: + +```json +{ + "limit": 10, + "offset": 0, + "total": 2, + "users": [ + { + "created_at": "2025-02-11T16:14:03.503217Z", + "credentials": { + "username": "admin" + }, + "email": "admin@example.com", + "first_name": "super", + "id": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b", + "last_name": "admin", + "metadata": { + "role": "admin" + }, + "role": "admin", + "status": "enabled", + "updated_at": "0001-01-01T00:00:00Z" + }, + { + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "janedoe" + }, + "email": "janedoe@example.com", + "first_name": "jane", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "doe", + "role": "user", + "status": "enabled", + "updated_at": "0001-01-01T00:00:00Z" + } + ] +} +``` + +### Update User Information + +Using the update flag can update the user's names, tags, metadata, email as well as username. + +#### **Update User Names** + +To update a user's names: + +```bash +magistrala-cli users update '{"first_name":"new first_name", "last_name":"new last_name"}' +``` + +Example usage: + +```bash +magistrala-cli users update 26ae3198-6060-4308-824c-c846953b9898 '{"first_name":"Beyonce", "last_name":"Knowles"}' token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "janedoe" + }, + "email": "janedoe@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "role": "user", + "status": "enabled", + "updated_at": "2025-02-11T16:34:52.377144Z" +} +``` + +#### **Update User Metadata** + +To update a user's metadata: + +```bash +magistrala-cli users update '{"metadata":{"value2": "value3"}}' +``` + +Example usage: + +```bash +magistrala-cli users update 26ae3198-6060-4308-824c-c846953b9898 '{"metadata":{"aoty": "1"}}' token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "janedoe" + }, + "email": "janedoe@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "enabled", + "updated_at": "2025-02-11T16:36:56.188559Z" +} +``` + +#### **Update User Tags** + +To update a user's tags: + +```bash +magistrala-cli users update tags '["tag1", "tag2"]' +``` + +Example usage: + +```bash +magistrala-cli users update tags 26ae3198-6060-4308-824c-c846953b9898 '["lemonade", "renaissance"]' token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "janedoe" + }, + "email": "janedoe@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "enabled", + "tags": [ + "lemonade", + "renaissance" + ], + "updated_at": "2025-02-11T16:44:11.670547Z" +} +``` + +#### **Update User Email** + +To update a user's email: + +```bash +magistrala-cli users update email +``` + +Example usage: + +```bash +magistrala-cli users update email 26ae3198-6060-4308-824c-c846953b9898 beyonce@example.com token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "janedoe" + }, + "email": "beyonce@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "enabled", + "tags": [ + "lemonade", + "renaissance" + ], + "updated_at": "2025-02-11T16:45:36.288667Z" +} +``` + +#### **Update Username** + +To update a user's username: + +```bash +magistrala-cli users update username +``` + +Example usage: + +```bash +magistrala-cli users update username 26ae3198-6060-4308-824c-c846953b9898 beyonce token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "beyonce" + }, + "email": "beyonce@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "enabled", + "tags": [ + "lemonade", + "renaissance" + ], + "updated_at": "2025-02-11T16:46:55.951208Z" +} +``` + +### Update User Password + +To update a user's password: + +```bash +magistrala-cli users password +``` + +Example usage: + +```bash +magistrala-cli users password 12345678 123456789 token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "beyonce" + }, + "email": "beyonce@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "enabled", + "tags": [ + "lemonade", + "renaissance" + ], + "updated_at": "2025-02-11T17:12:50.101988Z" +} +``` + +### Reset User Password Request + +To send a request to reset a user's password: + +```bash +magistrala-cli users resetpasswordrequest +``` + +### Reset User Password + +To reset a user's password: + +```bash +magistrala-cli users resetpassword +``` + +### Enable User + +To enable a user's status: + +```bash +magistrala-cli users enable +``` + +Example usage: + +```bash +magistrala-cli users enable 26ae3198-6060-4308-824c-c846953b9898 token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "beyonce" + }, + "email": "beyonce@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "enabled", + "tags": [ + "lemonade", + "renaissance" + ], + "updated_at": "2025-02-11T17:16:50.323734Z" +} +``` + +### Disable User + +To disable a user: + +```bash +magistrala-cli users disable +``` + +Example usage: + +```bash +magistrala-cli users disable 26ae3198-6060-4308-824c-c846953b9898 token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "beyonce" + }, + "email": "beyonce@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "disabled", + "tags": [ + "lemonade", + "renaissance" + ], + "updated_at": "2025-02-11T17:15:17.096604Z" +} +``` + +### Delete User + +To delete a user: + +```bash +magistrala-cli users delete +``` + +Example usage: + +```bash +magistrala-cli users delete 28a8be12-f3eb-4917-851b-30bf04ea04a0 token +``` + +This will return an `OK` response. + +### Get Profile of the User + +To get the profile details of the currently authenticated user: + +```bash +magistrala-cli users profile +``` + +Example usage: + +```bash +magistrala-cli users profile token +``` + +Expected response: + +```json +{ + "created_at": "2025-02-11T16:15:12.607701Z", + "credentials": { + "username": "beyonce" + }, + "email": "beyonce@example.com", + "first_name": "Beyonce", + "id": "26ae3198-6060-4308-824c-c846953b9898", + "last_name": "Knowles", + "metadata": { + "aoty": "1" + }, + "role": "user", + "status": "enabled", + "tags": [ + "lemonade", + "renaissance" + ], + "updated_at": "2025-02-11T17:16:50.323734Z" +} +``` + +### Search User + +To search for a specific user using queries: + +```bash +magistrala-cli users search +``` diff --git a/docs/dev-guide.md b/docs/dev-guide/dev-guide.md similarity index 100% rename from docs/dev-guide.md rename to docs/dev-guide/dev-guide.md diff --git a/docs/edge.md b/docs/dev-guide/edge.md similarity index 99% rename from docs/edge.md rename to docs/dev-guide/edge.md index 290dcb9..940f544 100644 --- a/docs/edge.md +++ b/docs/dev-guide/edge.md @@ -11,7 +11,7 @@ Services that can be used on gateway to enable data and control plane for edge: - [Export][export] - [Magistrala][magistrala] -| ![Edge1](img/edge/edge.png) | +| ![Edge1](../img/edge/edge.png) | | :---------------------------------: | | Figure 1 - Edge services deployment | @@ -563,7 +563,7 @@ magistrala-mqtt | {"level":"info","message":"Publish - client ID export-88529f [agent]: ./edge.md#agent [export]: ./edge.md#export -[magistrala]: ./architecture.md +[magistrala]: ../user-guide/architecture.md [bootstrap]: ./bootstrap.md [bootstraping]: ./bootstrap.md#bootstrapping [provision]: ./provision.md diff --git a/docs/entities.md b/docs/dev-guide/entities.md similarity index 100% rename from docs/entities.md rename to docs/dev-guide/entities.md diff --git a/docs/events.md b/docs/dev-guide/events.md similarity index 100% rename from docs/events.md rename to docs/dev-guide/events.md diff --git a/docs/getting-started.md b/docs/dev-guide/getting-started.md similarity index 100% rename from docs/getting-started.md rename to docs/dev-guide/getting-started.md diff --git a/docs/kubernetes.md b/docs/dev-guide/kubernetes.md similarity index 100% rename from docs/kubernetes.md rename to docs/dev-guide/kubernetes.md diff --git a/docs/lora.md b/docs/dev-guide/lora.md similarity index 100% rename from docs/lora.md rename to docs/dev-guide/lora.md diff --git a/docs/messaging.md b/docs/dev-guide/messaging.md similarity index 100% rename from docs/messaging.md rename to docs/dev-guide/messaging.md diff --git a/docs/opcua.md b/docs/dev-guide/opcua.md similarity index 99% rename from docs/opcua.md rename to docs/dev-guide/opcua.md index 2d33fa9..e2fe79c 100644 --- a/docs/opcua.md +++ b/docs/dev-guide/opcua.md @@ -25,7 +25,7 @@ The OPC-UA adapter can connect to multiple OPC-UA servers and subscribe to multi ### Architecture -| ![OPC-UA](./img/opcua/opcua.png) | +| ![OPC-UA](../img/opcua/opcua.png) | | :--------------------------------------: | | Figure 1 - OPC-UA Adapter Architecture | diff --git a/docs/provision.md b/docs/dev-guide/provision.md similarity index 100% rename from docs/provision.md rename to docs/dev-guide/provision.md diff --git a/docs/security.md b/docs/dev-guide/security.md similarity index 100% rename from docs/security.md rename to docs/dev-guide/security.md diff --git a/docs/storage.md b/docs/dev-guide/storage.md similarity index 100% rename from docs/storage.md rename to docs/dev-guide/storage.md diff --git a/docs/tracing.md b/docs/dev-guide/tracing.md similarity index 96% rename from docs/tracing.md rename to docs/dev-guide/tracing.md index 187a3f8..51d9750 100644 --- a/docs/tracing.md +++ b/docs/dev-guide/tracing.md @@ -35,7 +35,7 @@ Jaeger uses 5 ports within the Magistrala framework. These ports can be edited i ## Message Tracing -Magistrala provides for tracing of messages ingested into the Magistrala platform. The message metadata such as topic, sub-topic, subscriber and publisher is also included in traces. ![HTTP Message Publishing trace](img/tracing/messagePub.png) +Magistrala provides for tracing of messages ingested into the Magistrala platform. The message metadata such as topic, sub-topic, subscriber and publisher is also included in traces. ![HTTP Message Publishing trace](../img/tracing/messagePub.png) The messages are tracked from end to end from the point they are published to the consumers where they are stored. ![Influx DB consumer trace][consumer-trace] @@ -47,13 +47,13 @@ Before getting started with Jaeger, there are a few terms that are important to When first navigating to the Jaeger UI, it will present a search page with an empty results section. There are multiple fields to search from including service, operation, tags and time frames. Clicking `Find Traces` will fill the results section with traces containing the selected fields. -![Search page with results](img/tracing/search.png) +![Search page with results](../img/tracing/search.png) The top of the results page includes a scatter plot of the traces and their durations. This can be very useful for finding a trace with a prolonged runtime. Clicking on one of the points will open the trace page of that trace. Below the graph is a list of all the traces with a summary of its information. Each trace shows a unique identifier, the overall runtime, the spans it is composed of and when it was ran. Clicking on one of the traces will open the trace page of that trace. -![Trace page with expanded spans](img/tracing/trace.png) +![Trace page with expanded spans](../img/tracing/trace.png) The trace page provides a more detailed breakdown of the individual span calls. The top of the page shows a chart breaking down what spans the trace is spending its time in. Below the chart are the individual spans and their details. Expanding the spans shows any tags associated with that span and process information. This is also where any errors or logs seen while running the span will be reported. diff --git a/docs/twins.md b/docs/dev-guide/twins.md similarity index 99% rename from docs/twins.md rename to docs/dev-guide/twins.md index 04febce..ff150b8 100644 --- a/docs/twins.md +++ b/docs/dev-guide/twins.md @@ -31,7 +31,7 @@ To overcome these problems, Magistrala comes with a **digital twin service**. Th Magistrala Twins service depends on the Magistrala IoT platform. The following diagram shows the place of the twins service in the overall [Magistrala architecture][architecture]: -![Magistrala Twins service architecture](img/twins/architecture.png) +![Magistrala Twins service architecture](../img/twins/architecture.png) You use an HTTP client to communicate with the twins service. Every request sent to the twins service is authenticated by users service. Twins service handles CRUD requests and creates, retrieves, updates and deletes twins. The CRUD operations depend on the database to persist and fetch already saved twins. @@ -339,7 +339,7 @@ Normally, you can use the default message broker, NATS, wildcards. In order to l Since messages published on message broker are republished on any other protocol supported by Magistrala - HTTP, MQTT, CoAP and WS - you can use any supported protocol client to pick up notifications. -[architecture]: ./architecture.md +[architecture]: ../user-guide/architecture.md [provision]: ./provision.md [writer]: ./storage.md [senml]: https://tools.ietf.org/html/rfc8428#section-4.3 diff --git a/docs/architecture.md b/docs/user-guide/architecture.md similarity index 98% rename from docs/architecture.md rename to docs/user-guide/architecture.md index 2183eed..a7f5a42 100644 --- a/docs/architecture.md +++ b/docs/user-guide/architecture.md @@ -17,7 +17,7 @@ Magistrala IoT platform is comprised of the following services: | [rules-engine][rules-engine] | Create rules using LUA script that process incoming messages | | [readers][readers] | Implement message readers ie Postgres and Timescale | -![arch](img/architecture.jpg) +![arch](../img/architecture.jpg) ## Domain Model @@ -55,8 +55,8 @@ Running Magistrala on gateway moves computation from cloud towards the edge thus [vernemq]: https://vernemq.com/ [kafka]: https://kafka.apache.org/ [senml]: https://tools.ietf.org/html/draft-ietf-core-senml-08 -[agent]: ./edge.md#agent -[export]: ./edge.md#export +[agent]: ../dev-guide/edge.md +[export]: ../dev-guide/edge.md#export [bootstrap]: https://github.com/absmach/magistrala/tree/main/bootstrap [consumers]: https://github.com/absmach/magistrala/tree/main/consumers [email]: https://github.com/absmach/magistrala/tree/main/internal/email diff --git a/docs/clients/bootstraps.md b/docs/user-guide/clients/bootstraps.md similarity index 90% rename from docs/clients/bootstraps.md rename to docs/user-guide/clients/bootstraps.md index 9233956..17109f0 100644 --- a/docs/clients/bootstraps.md +++ b/docs/user-guide/clients/bootstraps.md @@ -34,7 +34,7 @@ To create a bootstrap configuration via the UI: - Navigate to the **Bootstraps** option in the **Clients Management** panel. - Click on the **+ Create** button to open the **Create Bootstrap Configuration** dialog. - ![Create Bootstrap Configuration](../img/bootstraps/create-bootstrap.png) + ![Create Bootstrap Configuration](../../img/bootstraps/create-bootstrap.png) 2. **Enter Configuration Details**: - **Name**: Enter a human-readable name for the bootstrap configuration. @@ -43,7 +43,7 @@ To create a bootstrap configuration via the UI: - **Channel(s)**: Select the channels to which the device will connect. These must be provisioned before setting up the configuration. - **Client**: Optionally, choose an existing client or leave this field empty. If left empty, a new client will be created with the configuration ID. - ![Bootstrap Configuration Details](../img/bootstraps/config-without-client.png) + ![Bootstrap Configuration Details](../../img/bootstraps/config-without-client.png) 3. **Encryption Settings**: - Expand the **Encryption Settings** section to enter optional encryption credentials. @@ -52,13 +52,13 @@ To create a bootstrap configuration via the UI: - **CA Cert**: Input the trusted CA certificate. - These fields are optional but may be necessary if the device needs to establish a TLS-encrypted connection during bootstrapping. - ![Encryption Settings](../img/bootstraps/encryption-settings.png) + ![Encryption Settings](../../img/bootstraps/encryption-settings.png) 4. **Submit the Configuration**: - Click the **Create** button to save the bootstrap configuration. - A newly created bootstrap configuration will appear in the list as **Disabled** by default. You must manually enable it to activate the bootstrap process. - ![Created Bootstrap Configuration](../img/bootstraps/new-bootstrap.png) + ![Created Bootstrap Configuration](../../img/bootstraps/new-bootstrap.png) ### View and Manage Bootstrap Configurations @@ -66,15 +66,15 @@ To create a bootstrap configuration via the UI: - Click on any configuration in the list to view its details. - The configuration will show all fields, including the name, client ID, channels, and state (enabled or disabled). It will also provide options to view and edit the custom content and encryption settings. - ![Bootstrap Configuration Details](../img/bootstraps/client-bootstrap-config.png) + ![Bootstrap Configuration Details](../../img/bootstraps/client-bootstrap-config.png) 2. **Automatically Generated Clients**: - If a bootstrap configuration is created without specifying a client, a new client will be automatically generated using the configuration ID. This can be seen in the **Clients** section. - The new client will appear in the clients list with its status set to **Enabled**. - ![Auto-Generated Client](../img/bootstraps/thing-less-config.png) + ![Auto-Generated Client](../../img/bootstraps/thing-less-config.png) - ![Auto-Generated Client Clients Page](../img/bootstraps/new-bootstrap-thing-config.png) + ![Auto-Generated Client Clients Page](../../img/bootstraps/new-bootstrap-thing-config.png) ### Fields Overview diff --git a/docs/clients/channels.md b/docs/user-guide/clients/channels.md similarity index 79% rename from docs/clients/channels.md rename to docs/user-guide/clients/channels.md index cb87837..162c713 100644 --- a/docs/clients/channels.md +++ b/docs/user-guide/clients/channels.md @@ -10,13 +10,13 @@ Clients are able to **publish** or **subscribe** to a channel depending on the c To create a channel, click on the `+ Create` button present on the top-left corner of the page. You can also create multiple channels by clicking on the `+ Create Channels` button and uploading a _.csv_ file with channel **names** and any other fields you would like to add. -![Create channel](../img/clients/channel-create-buttons.png) +![Create channel](../../img/clients/channel-create-buttons.png) ### Channel Information Add a channel **_name_** and optionally **_tags_** and **_metadata_**. -![Channel information](../img/clients/channel-create.png) +![Channel information](../../img/clients/channel-create.png) ### Bulk Creation @@ -28,17 +28,17 @@ You can be able to create channels in bulk by uploading a _.csv_ file with the f A sample of the _.csv_ file can be found [here](https://github.com/absmach/magistrala-ui/blob/main/samples/channels.csv). -![Bulk create channels](../img/clients/channels-bulk-ceate.png) +![Bulk create channels](../../img/clients/channels-bulk-ceate.png) ## View a Channel After creating a channel, you will be able to see the created channel on the channels table. To view that channel click on the **row** or the **view** button in the row actions -![View channel](../img/clients/channel-view.png) +![View channel](../../img/clients/channel-view.png) This will lead you to the channel settings page, where you can view all the channel settings. -![View channel settings](../img/clients/channel-view-settings.png) +![View channel settings](../../img/clients/channel-view-settings.png) ## Update a Channel @@ -50,13 +50,13 @@ In the channel settings page, you are able to update the following channel detai To update a field, click on the `pencil` icon on the far end of the field to edit. Once you have updated the value, click on the `tick` icon to update the changes or the `cross` icon to cancel the change. To update the channel status, toggle the switch on the far end of the status field. -![Edit channel](../img/clients/channel-update.png) +![Edit channel](../../img/clients/channel-update.png) ## Connect to a Client Navigate to the `Connections` section of the channel navigation. This will lead you to the connections page where you can view the clients connected to a channel. -![Connections page](../img/clients/channel-connections.png) +![Connections page](../../img/clients/channel-connections.png) In this page you are able to add a connection by clicking on the `Connect` button on the top right corner. @@ -66,15 +66,15 @@ There are two connection type options: 1. **Publish**: Allows the client to send messages in the channel 2. **Subscribe**: Allows the client to read messages in the channel -![Connect client](../img/clients/channel-connect-client.png) +![Connect client](../../img/clients/channel-connect-client.png) To disconnect the client, click on the `Disconnect` button at the end of the channel row. -![Disconnect client button](../img/clients/channel-disc-client.png) +![Disconnect client button](../../img/clients/channel-disc-client.png) This will open up a dialog that allows you to select which connection type you want to remove. You can remove one or both of the connection types if you have multiple. -![Disconnect client dialog](../img/clients/channel-disc-client-dialog.png) +![Disconnect client dialog](../../img/clients/channel-disc-client-dialog.png) ## Channel Members @@ -83,11 +83,11 @@ This will open up a dialog that allows you to select which connection type you w Roles allow you to group a specific set of actions and allocate them to users. To create a role, navigate to the roles section on the client navbar. Click on the `+ Create` button and provide a role name. The actions and members are optional fields. -![Create channel role](../img/clients/channel-create-role.png) +![Create channel role](../../img/clients/channel-create-role.png) -##### Role Information +#### Role Information -![Channel role information](../img/clients/channel-create-role-dialog.png) +![Channel role information](../../img/clients/channel-create-role-dialog.png) The role name is complusory. You can optionally provide the role actions by selecting from the available actions. You can also optionally provide the members by searching for a user with their **username**. @@ -109,20 +109,20 @@ The following is the list of available actions for a channel: To update a role name, click on the `pencil` icon on the far right end of the field, update the value then click on the `tick` icon to update the changes or the `cross` icon to cancel the changes. -![Update role name](../img/clients/channel-role-update.png) +![Update role name](../../img/clients/channel-role-update.png) To update the **actions** and **members** click on the `pencil` icon, it will pop up a dialog box allowing you to select the actions and users you want to add. -![Update role actions](../img/clients/channel-role-add-actions.png) +![Update role actions](../../img/clients/channel-role-add-actions.png) -![Update role members](../img/clients/channel-role-add-members.png) +![Update role members](../../img/clients/channel-role-add-members.png) #### Delete You can also delete actions and members by clicking on the `trash` icon. It pops up a dialog that allows you to select which action or member you want to remove. Optionally you can delete all of the actions or members by clicking on the `Delete All Actions` or `Delete All Members` buttons. -![Delete role actions](../img/clients/channel-role-delete-actions.png) -![Delete role members](../img/clients/channel-role-delete-members.png) +![Delete role actions](../../img/clients/channel-role-delete-actions.png) +![Delete role members](../../img/clients/channel-role-delete-members.png) ### Users @@ -139,13 +139,13 @@ Audit logs track all **group events**, from **creation** to **updates** and **di To create a channel, navigate to the fourth tab under the groups and click on `+ Create`. This will open a dialog box which will take in a unique Channel name. Much like the Clients, clicking on `+ Create Channels` will allow a user to upload a _.CSV_ file with multiple channels. -![Create Group Channel](../img/users-guide/group-channel-create.png) +![Create Group Channel](../../img/users-guide/group-channel-create.png) ## View a Channel After the Channel is created, clicking on it while it is on the Channel's table leads to the **Channel View** Page. -![View Group Channel](../img/users-guide/group-channel-view.png) +![View Group Channel](../../img/users-guide/group-channel-view.png) ## Connect a Channel @@ -156,7 +156,7 @@ Clients can be connected to channels in groups. This is done in the **Connection These Channels can then be connected to a Client with either `subscribe` or `publish` connection types or both. -![Connect Group Channel Clients](../img/users-guide/group-channel-connections.png) +![Connect Group Channel Clients](../../img/users-guide/group-channel-connections.png) This is required to send messages via the channels and has been discussed in [QuickStart Guide][users-quick-start] @@ -164,7 +164,7 @@ This is required to send messages via the channels and has been discussed in [Qu **User Management** in group-channels is pretty much the same as in the group-clients. A user can add roles and role actions to the channel. -![Group Channel Roles Create](../img/users-guide/group-channel-roles-create.png) +![Group Channel Roles Create](../../img/users-guide/group-channel-roles-create.png) Role Actions present include but are not limited to: @@ -186,11 +186,11 @@ Role Actions present include but are not limited to: Once a Channel and Client are connected, a user can send messages with the channel as a topic and the client unique key. Messages sent are typically in SeNML format. -![View Messages Page](../img/users-guide/group-messages-view.png) +![View Messages Page](../../img/users-guide/group-messages-view.png) fields bear an asterisk. Messages are sent via _HTTP_ protocol in the UI. -![Send Message](../img/users-guide/group-send-message.png) +![Send Message](../../img/users-guide/group-send-message.png) The messages table will then update to include the message sent with the latest message appearing first. Using the filter options, you can filter through a wide range of messages based on the protocol, publisher or even value. diff --git a/docs/clients/clients.md b/docs/user-guide/clients/clients.md similarity index 79% rename from docs/clients/clients.md rename to docs/user-guide/clients/clients.md index fb7ae84..c1635f4 100644 --- a/docs/clients/clients.md +++ b/docs/user-guide/clients/clients.md @@ -8,13 +8,13 @@ title: Clients To create a client, click on the `+ Create` button present on the top-left corner of the page. You can also create multiple clients by clicking on the `+ Create Clients` button and uploading a _.csv_ file with client **names** and any other fields you would like to add. -![Create client](../img/clients/client-create-buttons.png) +![Create client](../../img/clients/client-create-buttons.png) ### Client Information Add a client **_name_** and optionally a **_key_** (has to be unique), **_tags_** and **_metadata_**. -![Client information](../img/clients/client-create.png) +![Client information](../../img/clients/client-create.png) The client **key** will be used to authorize the device to send messages. @@ -29,17 +29,17 @@ You can be able to create clients in bulk by uploading a _.csv_ file with the fo A sample of the _.csv_ file can be found [here](https://github.com/absmach/magistrala-ui/blob/main/samples/clients.csv). -![Bulk create clients](../img/clients/clients-bulk-create.png) +![Bulk create clients](../../img/clients/clients-bulk-create.png) ## View a Client After creating a client, you will be able to see the created client on the clients table. To view that client click on the **row** or the **view** button in the row actions -![View client](../img/clients/client-view.png) +![View client](../../img/clients/client-view.png) This will lead you to the client configuration page, where you can view all the client configurations. -![View client configurations](../img/clients/client-view-config.png) +![View client configurations](../../img/clients/client-view-config.png) ## Configurations @@ -57,15 +57,15 @@ This section enables a user to update the following client details: To update a field, click on the `pencil` icon on the far end of the field to edit. Once you have updated the value, click on the `tick` icon to update the changes or the `cross` icon to cancel the change. To update the client status, toggle the switch on the far end of the status field. -![Edit client](../img/clients/client-update.png) +![Edit client](../../img/clients/client-update.png) ### Bootstrap Configuration -Bootstrap configuration of a client allows bootstrapping of the device (self-starting process that proceeds without external input). Further details of bootstrapping are discussed in the [Bootstrap section](/docs/clients/bootstraps.md). +Bootstrap configuration of a client allows bootstrapping of the device (self-starting process that proceeds without external input). Further details of bootstrapping are discussed in the [Bootstrap section](bootstraps.md). To add a bootstrap configuration, click on the `Add Configuration` button. -![Add bootstrap configuration](../img/clients/client-bootstrap-button.png) +![Add bootstrap configuration](../../img/clients/client-bootstrap-button.png) A dialog box will appear allowing you to enter the following fields @@ -79,13 +79,13 @@ A dialog box will appear allowing you to enter the following fields - Client Key - CA Cert -![Bootstrap configuration dialog](../img/clients/client-bootstrap-dialog.png) +![Bootstrap configuration dialog](../../img/clients/client-bootstrap-dialog.png) ## Connect to a Channel Navigate to the `Connections` section of the client navigation. This will lead you to the connections page where you can view the channels a client is connected to. -![Connections page](../img/clients/client-connections.png) +![Connections page](../../img/clients/client-connections.png) In this page you are able to add a connection by clicking on the `Connect` button on the top right corner. @@ -95,15 +95,15 @@ There are two connection type options: 1. **Publish**: Allows the client to send messages in the channel 2. **Subscribe**: Allows the client to read messages in the channel -![Connect channel](../img/clients/client-connect-channel.png) +![Connect channel](../../img/clients/client-connect-channel.png) To disconnect from the channel, click on the `Disconnect` button at the end of the channel row. -![Disconnect channel button](../img/clients/client-disc-channel.png) +![Disconnect channel button](../../img/clients/client-disc-channel.png) This will open up a dialog that allows you to select which connection type you want to remove. You can remove one or both of the connection types if you have multiple. -![Disconnect channel dialog](../img/clients/client-disc-channel-dialog.png) +![Disconnect channel dialog](../../img/clients/client-disc-channel-dialog.png) ## Client Members @@ -112,11 +112,11 @@ This will open up a dialog that allows you to select which connection type you w Roles allow you to group a specific set of actions and allocate them to users. To create a role, navigate to the roles section on the client navbar. Click on the `+ Create` button and provide a role name. The actions and members are optional fields. -![Create client role](../img/clients/client-create-role.png) +![Create client role](../../img/clients/client-create-role.png) -##### Role Information +#### Role Information -![Client role information](../img/clients/client-create-role-dialog.png) +![Client role information](../../img/clients/client-create-role-dialog.png) The role name is complusory. You can optionally provide the role actions by selecting from the available actions. You can also optionally provide the members by searching for a user with their **username**. @@ -136,20 +136,20 @@ The following is the list of available actions for a client: To update a role name, click on the `pencil` icon on the far right end of the field, update the value then click on the `tick` icon to update the changes or the `cross` icon to cancel the changes. -![Update role name](../img/clients/client-role-update.png) +![Update role name](../../img/clients/client-role-update.png) To update the **actions** and **members** click on the `pencil` icon, it will pop up a dialog box allowing you to select the actions and users you want to add. -![Update role actions](../img/clients/client-role-add-actions.png) +![Update role actions](../../img/clients/client-role-add-actions.png) -![Update role members](../img/clients/client-role-add-members.png) +![Update role members](../../img/clients/client-role-add-members.png) #### Delete You can also delete actions and members by clicking on the `trash` icon. It pops up a dialog that allows you to select which action or member you want to remove. Optionally you can delete all of the actions or members by clicking on the `Delete All Actions` or `Delete All Members` buttons. -![Delete role actions](../img/clients/client-role-delete-actions.png) -![Delete role members](../img/clients/client-role-delete-members.png) +![Delete role actions](../../img/clients/client-role-delete-actions.png) +![Delete role members](../../img/clients/client-role-delete-members.png) ### Users diff --git a/docs/clients/groups.md b/docs/user-guide/clients/groups.md similarity index 82% rename from docs/clients/groups.md rename to docs/user-guide/clients/groups.md index a1344d1..caf9af6 100644 --- a/docs/clients/groups.md +++ b/docs/user-guide/clients/groups.md @@ -8,13 +8,13 @@ title: Groups To create a group, click on the `+ Create` button present on the top-left corner of the page. You can also create multiple groups by uploading a _.csv_ file with group **names** and any other fields you would like to add. -![Create group](../img/clients/group-create-button.png) +![Create group](../../img/clients/group-create-button.png) ### Group Information Add a group _name_ and optionally a _description_, _metadata_ and a _parent group_. -![Group information](../img/clients/group-information.png) +![Group information](../../img/clients/group-information.png) The parent group would add hierarchy to the group making it a child of the parent group you have selected. Actions within a role in the parent group trickle down to the children groups. @@ -22,7 +22,7 @@ The parent group would add hierarchy to the group making it a child of the paren After creating a group, it will show up on the page as the first group created. -![View Group](../img/clients/group-view.png) +![View Group](../../img/clients/group-view.png) > The family tree section shows a group's parent-child relationship (This feature is still under development :hammer: ) @@ -31,11 +31,11 @@ After creating a group, it will show up on the page as the first group created. While on the View Group Page, you are allowed to update the group details such as the name, description, metadata and the status. To update a field, click on the `pencil` icon on the far end of the field to edit. Once you have updated the value, click on the `tick` icon to update the changes or the `cross` icon to cancel the change. -![Edit Group](../img/clients/group-edit.png) +![Edit Group](../../img/clients/group-edit.png) A group can also be disabled or enabled by toggling the switch on the far end of the status field. -![Disabled Group](../img/clients/group-disabled.png) +![Disabled Group](../../img/clients/group-disabled.png) ## Group Members @@ -46,11 +46,11 @@ A group can also be disabled or enabled by toggling the switch on the far end of Roles allow you to group a specific set of actions and allocate them to users. To create a role, navigate to the roles section on the group navbar. Click on the `+ Create` button and provide a role name. The actions and members are optional fields. -![Create Group Role](../img/clients/group-role-create.png) +![Create Group Role](../../img/clients/group-role-create.png) ##### Role Information -![Group Role Information](../img/clients/group-role-information.png) +![Group Role Information](../../img/clients/group-role-information.png) The role name is complusory. You can optionally provide the role actions by selecting from the available actions. You can also optionally provide the members by searching for a user with their **username**. The following is the list of available actions for a group: @@ -126,20 +126,20 @@ The following is the list of available actions for a group: To update a role name, click on the `pencil` icon on the far right end of the field, update the value then click on the `tick` icon to update the changes or the `cross` icon to cancel the changes. -![Update role name](../img/clients/group-role-name.png) +![Update role name](../../img/clients/group-role-name.png) To update the **actions** and **members** click on the `pencil` icon, it will pop up a dialog box allowing you to select the actions and users you want to add. -![Update role actions](../img/clients/group-role-actions.png) +![Update role actions](../../img/clients/group-role-actions.png) -![Update role members](../img/clients/group-role-member.png) +![Update role members](../../img/clients/group-role-member.png) #### Delete You can also delete actions and members by clicking on the `trash` icon. It pops up a dialog that allows you to select which action or member you want to remove. Optionally you can delete all of the actions or members by clicking on the `Delete All Actions` or `Delete All Members` buttons. -![Delete role actions](../img/clients/group-role-delete-actions.png) -![Delete role members](../img/clients/group-role-delete-members.png) +![Delete role actions](../../img/clients/group-role-delete-actions.png) +![Delete role members](../../img/clients/group-role-delete-members.png) ### Users @@ -147,27 +147,27 @@ We can assign a user to a group by adding them as role members. This allows a us To add role members, one can add them when creating a role or in the specific role page. To add a user while in the role page, click on the pencil icon on the far end of the `Role Members` field, search for a user based on their username, and click on the user. Then click on `Add` to add them to the role. -![Add Group Member](../img/clients/group-role-member.png) +![Add Group Member](../../img/clients/group-role-member.png) Optionally, we have the capacity to add users by assigning them to a group in the users section of the group. This will allow you to assign a user to a group by adding them to a specific role. -![View Group Users](../img/clients/group-users.png) +![View Group Users](../../img/clients/group-users.png) > This feature is currently under development :hammer: ## Group Clients Magistrala provides the capacity to create clients directly in the group level. -A user is able to **create**, **update**, **disable**, **enable**, **delete**, and **connect** clients on the group level. These functionalities are described better in the [clients](/docs/clients/clients.md) section +A user is able to **create**, **update**, **disable**, **enable**, **delete**, and **connect** clients on the group level. These functionalities are described better in the [clients](clients.md) section -![Group clients](../img/clients/group-clients.png) +![Group clients](../../img/clients/group-clients.png) ## Group Channels Magistrala provides the capacity to create channels directly in the group level. -A user is able to **create**, **update**, **disable**, **enable**, **delete**, and **connect** channels on the group level. These functionalities are described better in the [channels](/docs/clients/channels.md) section +A user is able to **create**, **update**, **disable**, **enable**, **delete**, and **connect** channels on the group level. These functionalities are described better in the [channels](channels.md) section -![Group channels](../img/clients/group-channels.png) +![Group channels](../../img/clients/group-channels.png) ## Audit Logs diff --git a/docs/clients/image.png b/docs/user-guide/clients/image.png similarity index 100% rename from docs/clients/image.png rename to docs/user-guide/clients/image.png diff --git a/docs/clients/introduction.md b/docs/user-guide/clients/introduction.md similarity index 100% rename from docs/clients/introduction.md rename to docs/user-guide/clients/introduction.md diff --git a/docs/dashboards/areachart.md b/docs/user-guide/dashboards/areachart.md similarity index 88% rename from docs/dashboards/areachart.md rename to docs/user-guide/dashboards/areachart.md index 3b66dac..ab6c284 100644 --- a/docs/dashboards/areachart.md +++ b/docs/user-guide/dashboards/areachart.md @@ -11,7 +11,9 @@ Click the `Add Widget` button, then select the **Area Chart** option from the wi This will open the **Create Area Chart** dialog, where the settings and data sources can be configured. #### Configuring the Area Chart + Start by setting up a single data source. + - **Value Name**: Enter the name of the value you wish to visualize, such as voltage or temperature. - **Channel**: Select the channel that provides the data you want to plot. - **Client**: Choose the entity or device connected to the channel. @@ -20,13 +22,13 @@ Start by setting up a single data source. Multiple data sources can be added by clicking the `Add Source` button. -![Create Area Chart](../img/dashboards/create-areachart.png) +![Create Area Chart](../../img/dashboards/create-areachart.png) Once the data sources are configured, you can define a **Time Window** by specifying the "From" and "To" dates, which will constrain the data shown to the specified time period. In the **Settings** tab, you can adjust the **Update Interval** (how often the chart refreshes) and other chart appearance options. After configuring everything, click the `Create` button to add the Area Chart to your dashboard. -![Created Area Chart](../img/dashboards/new-areachart1.png) +![Created Area Chart](../../img/dashboards/new-areachart1.png) ### Edit the Area Chart @@ -38,20 +40,21 @@ The Area Chart can be edited at any time by clicking the `pencil` icon in the to For example, the chart can be switched to live data. -![Edit Area Chart](../img/dashboards/edit-areachart.png) +![Edit Area Chart](../../img/dashboards/edit-areachart.png) Once the changes have been made, click the `Update` button to save and apply the new settings. The chart will automatically refresh with the updated data or appearance. -![Updated Area Chart](../img/dashboards/area-chart-created.png) +![Updated Area Chart](../../img/dashboards/area-chart-created.png) In many cases, data is aggregated over time intervals. For instance, setting the **Aggregation Interval** to 10 minutes (600 seconds) and selecting the **Average** aggregation type will display the mean values over each 10-minute period for a 2-hour time window. -![Set Aggregation](../img/dashboards/aggregation-areachart-setting.png) +![Set Aggregation](../../img/dashboards/aggregation-areachart-setting.png) The result will be an Area Chart that shows the average value in each time interval, providing an insightful view of the data trends. -![Average Aggregated Area Chart](../img/dashboards/avg-areachart.png) +![Average Aggregated Area Chart](../../img/dashboards/avg-areachart.png) #### **Conclusion** + Area Charts are a powerful way to visualize changes in data over time. They allow trends and patterns to be easily tracked with a clean, filled-in graphical representation. This chart is especially useful for comparing cumulative values and emphasizing the overall volume of data. diff --git a/docs/dashboards/barchart.md b/docs/user-guide/dashboards/barchart.md similarity index 89% rename from docs/dashboards/barchart.md rename to docs/user-guide/dashboards/barchart.md index dd1c815..8ddf6bc 100644 --- a/docs/dashboards/barchart.md +++ b/docs/user-guide/dashboards/barchart.md @@ -17,29 +17,28 @@ This will open the **Create Bar Chart** dialog, where the chart’s settings and Just like with the line chart, the fields marked with an asterisk are required and must be filled in before clicking `Create` button. -![Create Bar Chart](../img/dashboards/create-barchart.png) +![Create Bar Chart](../../img/dashboards/create-barchart.png) Once the data sources are set, define a **Time Window** by specifying the "From" and "To" dates, which will limit the displayed data to the chosen time interval. In the **Settings** tab, further customize the chart by adjusting its appearance, including the update interval and other relevant properties. After configuring everything, click the `Create` button to save the Bar Chart widget. The dialog will close, and the Bar Chart will be added to the dashboard. -![Created Bar Chart](../img/dashboards/new-barchart.png) +![Created Bar Chart](../../img/dashboards/new-barchart.png) ### Edit the Bar Chart An existing bar chart can be edited at any time by clicking the `pencil` icon in the top-right corner of the chart. This will open an edit sheet on the right, where data sources, labels, time window, and other settings can be modified. - 1. **Add Data Sources**: You can add more data sources by clicking the `Add Source` button and providing additional channels, clients, and labels. 2. **Delete Data Sources**: Remove a data source by clicking the `trash` icon next to the specific source to be deleted. -![Edit Bar Chart](../img/dashboards/edit-barchart.png) +![Edit Bar Chart](../../img/dashboards/edit-barchart.png) In this section, the chart title, labels, and intervals can also be modified as needed. Once all changes are made, click the `Update` button to save the modifications. -![Edited Bar Chart](../img/dashboards/edited-barchart.png) +![Edited Bar Chart](../../img/dashboards/edited-barchart.png) The **Time Window** settings can further filter the data shown in the chart by specifying a specific time range. For example, selecting a time window from 17:30 to 19:30 will constrain the data to that two-hour period. @@ -50,7 +49,7 @@ For instance, applying aggregation with an interval of 10 minutes and selecting After applying these settings, the resulting chart will show aggregated values based on the specified criteria. -![Aggregated Bar Chart](../img/dashboards/min-barchart.png) +![Aggregated Bar Chart](../../img/dashboards/min-barchart.png) #### **Conclusion** diff --git a/docs/dashboards/controls.md b/docs/user-guide/dashboards/controls.md similarity index 91% rename from docs/dashboards/controls.md rename to docs/user-guide/dashboards/controls.md index 53136d7..4e08452 100644 --- a/docs/dashboards/controls.md +++ b/docs/user-guide/dashboards/controls.md @@ -23,7 +23,7 @@ To create a **Switch Card**, follow these steps: 2. Click on **"Add Widget"** and select **"Switch"** from the list. 3. A **Create Switch** dialog box will appear, as shown below. -![Create Switch Dialog](../img/dashboards/create-switch.png) +![Create Switch Dialog](../../img/dashboards/create-switch.png) #### Configure the Switch Card @@ -47,7 +47,7 @@ Once created, the switch card appears on the dashboard with the configured **tit - The **default state** of the switch is **OFF** (`false`). - Clicking on the **toggle button** will change its state to **ON** (`true`), sending a message to the client. -![Switch Card OFF](../img/dashboards/updated-switch.png) +![Switch Card OFF](../../img/dashboards/updated-switch.png) --- @@ -62,7 +62,7 @@ To edit a **Switch Card**, click the `pencil` icon in the top-right corner of th - **Value Name** - Modify the controlled value. - **Title** - Update the displayed title. -![Edit Switch Dialog](../img/dashboards/edit-switch.png) +![Edit Switch Dialog](../../img/dashboards/edit-switch.png) After making the necessary changes, click `Update` to save them. @@ -72,7 +72,7 @@ After making the necessary changes, click `Update` to save them. After editing, the switch can be toggled to the **ON** (`true`) state, sending a command to the connected device. -![Switch Card ON](../img/dashboards/created-switch.png) +![Switch Card ON](../../img/dashboards/created-switch.png) --- @@ -81,6 +81,7 @@ After editing, the switch can be toggled to the **ON** (`true`) state, sending a Switch Cards are essential for IoT control, allowing users to interact with devices directly from the dashboard. They offer an intuitive interface for toggling **boolean values** and sending real-time commands. Key benefits of **Switch Cards** include: + - Simple **ON/OFF** functionality for **boolean-based control**. - Real-time interaction with connected **IoT devices**. - Customizable settings for **channels, clients, and value names**. @@ -90,13 +91,14 @@ Key benefits of **Switch Cards** include: A **Slider Card** sends **numeric values** to a connected **client** through a **channel**. It allows for adjustable input, making it useful for controlling settings like **temperature, voltage, or airflow**. ### Create a Slider Card + To create a **Slider Card**, follow these steps: 1. **Enable Edit Mode** on the dashboard. 2. Click on **"Add Widget"** and select **"Slider"** from the list. 3. A **Create Slider** dialog box will appear. -![Create Slider Dialog](../img/dashboards/create-slider.png) +![Create Slider Dialog](../../img/dashboards/create-slider.png) #### Configure the Slider Card @@ -123,7 +125,7 @@ Once created, the slider card appears on the dashboard with the configured **tit - The **default value** of the slider is at the minimum value. - Dragging the **slider handle** changes the value, which is then sent to the client. -![Slider Card](../img/dashboards/created-slider.png) +![Slider Card](../../img/dashboards/created-slider.png) --- @@ -131,7 +133,7 @@ Once created, the slider card appears on the dashboard with the configured **tit To edit a Slider Card, click the **Pencil Icon** in the top-right corner of the widget. This will open the **Update Slider** dialog. -##### **Editable Slider Fields** +#### **Editable Slider Fields** - **Channel** - Change the assigned communication channel. - **Client** - Select a different connected device. @@ -140,7 +142,7 @@ To edit a Slider Card, click the **Pencil Icon** in the top-right corner of the - **Minimum & Maximum Values** - Adjust the slider range. - **Steps** - Define the increment between values. -![Edit Slider Dialog](../img/dashboards/edit-slider.png) +![Edit Slider Dialog](../../img/dashboards/edit-slider.png) After making the necessary changes, click `Update` to save them. @@ -150,11 +152,11 @@ After making the necessary changes, click `Update` to save them. After editing, the slider values can be adjusted in defined **steps** (e.g., increments of `10`). -![Slider with Steps](../img/dashboards/slider-updated.png) +![Slider with Steps](../../img/dashboards/slider-updated.png) --- -#### **Conclusion** +#### **Slider Conclusion** Control Cards offer a user-friendly way to **interact with IoT devices** directly from the dashboard. diff --git a/docs/dashboards/countcard.md b/docs/user-guide/dashboards/countcard.md similarity index 90% rename from docs/dashboards/countcard.md rename to docs/user-guide/dashboards/countcard.md index b67f701..90de8e5 100644 --- a/docs/dashboards/countcard.md +++ b/docs/user-guide/dashboards/countcard.md @@ -10,7 +10,7 @@ A **Count Card** provides a quick overview of the total number of entities such To create a Count Card, ensure your dashboard is in **Edit Mode**. Click the `Add Widget` button and select **Count Card** from the list of available widgets. This will open the **Create Count Card** dialog, where the data source and appearance of the card can be configured. -![Count Card Dialog](../img/dashboards/generic-countcard-dialog.png) +![Count Card Dialog](../../img/dashboards/generic-countcard-dialog.png) #### Configuring the Count Card @@ -33,28 +33,27 @@ The card will immediately display the total count of entities based on the selec - **Status**: The status of the counted entities (enabled or disabled). - **Tag**: The tag value, if a tag filter was applied. - ![New Count Card](../img/dashboards/new-countcard.png) - - + ![New Count Card](../../img/dashboards/new-countcard.png) ### Edit the Count Card + The `pencil` icon in the top-right corner of the widget allows for editing. Clicking this icon will open a settings panel where the data source, entity status, tag, and other settings can be adjusted. 1. **Data Source**: Modify the **Entity Type**, **Status**, or **Tag** to change the entities being counted. 2. **Update Interval**: Adjust the frequency with which the card refreshes. 3. **Title**: Update the title to reflect any new data or focus. - ![Editing Count Card](../img/dashboards/edit-countcard.png) + ![Editing Count Card](../../img/dashboards/edit-countcard.png) Once the updates are made, click `Update` to save the changes. The count card will refresh with the new data and settings. - ![Updated Count Card](../img/dashboards/edited-countcard.png) + ![Updated Count Card](../../img/dashboards/edited-countcard.png) #### Customizing Count Cards Count Cards are versatile and can be customized to meet specific needs. Customizable features include the title, status, tags, and icons displayed on the card. Below is an image that highlights these key features: - ![Features of Count Cards](../img/dashboards/countcard-features.png) + ![Features of Count Cards](../../img/dashboards/countcard-features.png) 1. **Changing Icons**: Each entity type can have a unique icon, visually representing the type of entity being counted (e.g., a device icon for "Clients"). 2. **Entity Status**: The status of the entities (Enabled/Disabled) is displayed. diff --git a/docs/dashboards/dashboards.md b/docs/user-guide/dashboards/dashboards.md similarity index 82% rename from docs/dashboards/dashboards.md rename to docs/user-guide/dashboards/dashboards.md index 331cbf5..effe6a3 100644 --- a/docs/dashboards/dashboards.md +++ b/docs/user-guide/dashboards/dashboards.md @@ -6,32 +6,31 @@ title: Dashboard Guide After loging into a **Domain**, navigate to **Dashboards** tab and click on the `+ Create` button. The dialog box prompts you to enter a dashboard name, and optionally a description and tags. -![Dasboard Creation](../img/dashboards/create-dash.png) +![Dasboard Creation](../../img/dashboards/create-dash.png) ### View Dashboards + Dashboards are initially displayed as cards after creation. To switch to a table view, click the `Show Table` button at the top right. This displays the same dashboards in a table format. -![Show Table](../img/dashboards/show-table.png) +![Show Table](../../img/dashboards/show-table.png) To switch back to card view, click the `Show Cards` button. -![Dashboard Table](../img/dashboards/table-view.png) - +![Dashboard Table](../../img/dashboards/table-view.png) ### Edit Dashboard -A user can edit the dashboard either by using the `edit` icon on the cards which will open a sheet on the right side navigation bar. +A user can edit the dashboard either by using the `edit` icon on the cards which will open a sheet on the right side navigation bar. -![Dasboard Editting](../img/dashboards/edit-dash.png) +![Dasboard Editting](../../img/dashboards/edit-dash.png) In the editing panel, a user can modify the dashboard's **name**, **description**, and **tags**. - ### Delete Dashboard A user can delete a dashboard by clicking the `trash` icon on the card or clicking **delete** in the options on the dropdown menu in table view. An alert will pop up to confirm if you'd like to have the dashboard deleted. -![Dasboard Action Buttons](../img/dashboards/dash-actions.png) +![Dasboard Action Buttons](../../img/dashboards/dash-actions.png) ### Upload Dashboard @@ -40,9 +39,9 @@ Magistrala allows dashboards to be uploaded in .JSON format. By clicking the `Upload` button at the top of the dashboard table, a dialog box will open, allowing users to select and upload a _.JSON_ file containing the required fields for a complete dashboard. > Ensure the file contains dashboard **name**, **layout**, and **metadata**. -The uploaded dashboard will then appear in the list with the uploaded data. +The uploaded dashboard will then appear in the list with the uploaded data. -![Upload Dashboard](../img/dashboards/dash-upload.png) +![Upload Dashboard](../../img/dashboards/dash-upload.png) Sample templates to support real-life use cases can be found [here](https://github.com/absmach/magistrala-ui/tree/main/samples/dashboard-templates). @@ -51,26 +50,31 @@ Sample templates to support real-life use cases can be found [here](https://gith Dashboards can be accessed by clicking on the respective card or corresponding row in the table view. ### Customize a Dashboard + #### Edit a Dashboard + Toggling **Edit Mode** enables dashboard editing features. In this mode, users can **add**, **modify**, or **remove** charts and widgets, as well as update the dashboard's **name**, **tags**, and **description** using the `Edit Dashboard` button. #### Choose a Layout + Layouts allow a user to select the layout type suitable for your needs. There are **desktop**, **laptop**, **tablet**, **phone** or **small phone** layouts. This adjust the width of the dashboard grid for better responsiveness. -![Dashboard Layouts](../img/dashboards/layouts.png) +![Dashboard Layouts](../../img/dashboards/layouts.png) #### Add a Widget + To add widgets, users can click `Add Widget` at the top of the page, opening a dialog box with available charts and widgets for selection. -![Dashboard Layouts](../img/dashboards/add-widget.png) +![Dashboard Layouts](../../img/dashboards/add-widget.png) When edit mode switch is toggled off a user has access to: ### Full-Screen Mode For an expanded view, clicking the `Full Screen` button allows the dashboard and its charts to occupy the entire screen. -![Dashboard Icons](../img/dashboards/content-buttons.png) +![Dashboard Icons](../../img/dashboards/content-buttons.png) ### Download a Dashboard + #### Download a Dashboard as pdf The `PDF icon` allows downloading the dashboard as a PDF file. @@ -79,5 +83,4 @@ The `PDF icon` allows downloading the dashboard as a PDF file. The `Download icon` enables downloading it as a JSON file. -![Edit dashboard](../img/dashboards/view-dashboard.png) - +![Edit dashboard](../../img/dashboards/view-dashboard.png) diff --git a/docs/dashboards/gauges.md b/docs/user-guide/dashboards/gauges.md similarity index 86% rename from docs/dashboards/gauges.md rename to docs/user-guide/dashboards/gauges.md index 22e0645..b5c09d2 100644 --- a/docs/dashboards/gauges.md +++ b/docs/user-guide/dashboards/gauges.md @@ -5,7 +5,7 @@ title: Gauges **Gauges** are essential widgets for visualizing the latest values from a connected **Client** or **Channel**. They provide an intuitive way to track metrics such as voltage, speed, or temperature. - + Magistrala offers different types of gauges, including: @@ -26,13 +26,13 @@ The **Simple Gauge** widget displays the latest value from a selected data sourc 1. Ensure the dashboard is in **Edit Mode**. 2. Click the `Add Widget` button and select **Simple Gauge** from the widget list. This will open the **Create Gauge Chart** dialog. - ![Simple Gauge Selection](../img/dashboards/gauge-type-filter.png) + ![Simple Gauge Selection](../../img/dashboards/gauge-type-filter.png) 3. **Gauge Type**: Select **Simple Gauge** from the dropdown. 4. **Channel**: Choose the **Channel** that will provide the data for the gauge. 5. **Client**: Select the **Client** (device/entity) that is connected to the Channel whose data will be visualized. 6. **Value Name**: Specify the name of the value to fetch messages (e.g., `demovoltage`). - ![Simple Gauge Configuration](../img/dashboards/create-simplegauge.png) + ![Simple Gauge Configuration](../../img/dashboards/create-simplegauge.png) **Settings Section** 7. **Minimum Value**: Set the minimum value for the gauge, which could represent the lower limit of the metric you're tracking (e.g., `50000` for voltage). 8. **Maximum Value**: Set the maximum value for the gauge (e.g., `100000` for voltage). @@ -40,12 +40,12 @@ The **Simple Gauge** widget displays the latest value from a selected data sourc 10. **Title**: Enter a descriptive title for the gauge (e.g., "Monical Voltage"). 11. **Unit**: Select the unit needed for the Simple Gauge. Available units can be chosen from the list: - ![Gauge Settings](../img/dashboards/settings-gaugechart.png) + ![Gauge Settings](../../img/dashboards/settings-gaugechart.png) 12. After configuring the gauge, click `Create` to save and add the widget to the dashboard. Once the widget is added, the gauge will immediately begin displaying the latest value based on the applied settings. - ![Simple Gauge Created](../img/dashboards/new-simplegauge.png) + ![Simple Gauge Created](../../img/dashboards/new-simplegauge.png) ### Temperature Gauge @@ -60,7 +60,7 @@ The **Temperature Gauge** widget operates similarly to the Simple Gauge but is s 5. **Client**: Select the **Client** (device) connected to the channel. 6. **Value Name**: Enter the value name for the temperature data that will be used to fetch messages(e.g., `tempValue`). - ![Temperature Gauge Configuration](../img/dashboards/create-temperature-gauge.png) + ![Temperature Gauge Configuration](../../img/dashboards/create-temperature-gauge.png) **Settings Section** 7. **Minimum Value**: Set the minimum value for the gauge (e.g., `0` for temperatures in degrees Celsius). 8. **Maximum Value**: Set the maximum value for the gauge (e.g., `200` for temperatures in degrees Celsius). @@ -68,10 +68,10 @@ The **Temperature Gauge** widget operates similarly to the Simple Gauge but is s 10. **Title**: Provide a title for the temperature gauge (e.g., "Monical Temperature Gauge"). 11. **Unit**: Select the unit needed for the temperature gauge. It will show up on the gauge chart. The options available are Degrees Celcius, Kelvin and Farenheight as shown below: - ![Temperature Gauge Settings](../img/dashboards/temperature-gauge-units.png) + ![Temperature Gauge Settings](../../img/dashboards/temperature-gauge-units.png) 12. Click **Create** to add the Temperature Gauge to your dashboard. The gauge will immediately start reflecting the latest temperature readings. - ![Temperature Gauge Created](../img/dashboards/new-temperaturegauge.png) + ![Temperature Gauge Created](../../img/dashboards/new-temperaturegauge.png) --- @@ -88,7 +88,7 @@ The **Speed Gauge** widget tracks speed or velocity values from connected device 5. **Client**: Choose the connected **Client** (device). 6. **Value Name**: Enter the name of the value that corresponds to speed (e.g., `speedValue`). - ![Speed Gauge Configuration](../img/dashboards/create-speedgauge.png) + ![Speed Gauge Configuration](../../img/dashboards/create-speedgauge.png) **Settings Section** 7. **Minimum Value**: Set the minimum speed value (e.g., `0`). 8. **Maximum Value**: Set the maximum speed value (e.g., `1000` for kilometers per hour). @@ -96,10 +96,10 @@ The **Speed Gauge** widget tracks speed or velocity values from connected device 10. **Title**: Provide a title for the speed gauge (e.g., "Monical Speed Gauge"). 11. **Unit**: Select the unit needed for the simple gauge. It will show up on the gauge chart. There is a list of Units you can choose from for speed gauge. - ![Speed Gauge Settings](../img/dashboards/create-speedgauge-unit.png) + ![Speed Gauge Settings](../../img/dashboards/create-speedgauge-unit.png) 11. Click **Create** to save the Speed Gauge widget. The gauge will then start showing the latest speed data. - ![Speed Gauge Created](../img/dashboards/new-speedgauge.png) + ![Speed Gauge Created](../../img/dashboards/new-speedgauge.png) --- @@ -107,13 +107,10 @@ The **Speed Gauge** widget tracks speed or velocity values from connected device The gauge can be edited later by clicking the `pencil` icon on the widget. This allows for adjustments to data sources, value names, titles or other settings. - ![Simple Gauge Editing](../img/dashboards/edit-gauge-settings.png) - - + ![Simple Gauge Editing](../../img/dashboards/edit-gauge-settings.png) #### **Conclusion** **Gauges** provide an effective and visual way to track live data for various metrics. Whether monitoring voltage, temperature, or speed, these widgets offer flexibility in displaying the most important data from connected IoT devices. Each gauge can be customized with specific value ranges, update intervals, and labels, making them adaptable to any use case. Existing gauges can also be edited to adjust settings as monitoring needs evolve. - diff --git a/docs/dashboards/introduction.md b/docs/user-guide/dashboards/introduction.md similarity index 91% rename from docs/dashboards/introduction.md rename to docs/user-guide/dashboards/introduction.md index aa42d94..fe6674e 100644 --- a/docs/dashboards/introduction.md +++ b/docs/user-guide/dashboards/introduction.md @@ -6,4 +6,4 @@ Dashboards are a powerful feature in Magistrala, and this section will cover how Each dashboard can be populated with multiple widgets, which are not limited to a single dataSource. Data can be displayed from devices and entities such as clients, providing a comprehensive view of system performance. -![Dashboard charts](../img/dashboards/card-view.png) \ No newline at end of file +![Dashboard charts](../../img/dashboards/card-view.png) diff --git a/docs/dashboards/linechart.md b/docs/user-guide/dashboards/linechart.md similarity index 84% rename from docs/dashboards/linechart.md rename to docs/user-guide/dashboards/linechart.md index 96ecb6a..3d29281 100644 --- a/docs/dashboards/linechart.md +++ b/docs/user-guide/dashboards/linechart.md @@ -8,9 +8,10 @@ To create a Line Chart, first ensure that the dashboard is in **Edit Mode**. Click on the `Add Widget` button, which will open a dialog box displaying all the available widgets. Select the **Line Chart** option from the list. -This will open the **Create Line Chart** dialog, where the chart's settings and data sources can be configured. +This will open the **Create Line Chart** dialog, where the chart's settings and data sources can be configured. #### Configuring the Line Chart + Start by setting up a single data source. - **Value Name**: Enter the name of the value used to fetch the messages. @@ -19,7 +20,7 @@ Start by setting up a single data source. - **Label**: Provide a label to track each data source clearly on the chart. - **Line Color**: Use the color picker to choose a color for the line. -![Line Chart data Source](../img/dashboards/single-data-linechart.png) +![Line Chart data Source](../../img/dashboards/single-data-linechart.png) Once the data sources are configured, define a **Time Window** by specifying the "From" and "To" dates to restrict the data to a specific time interval. @@ -27,35 +28,34 @@ In the **Settings** tab, the **Line Width** can also be adjusted to set the thic Once satisfied with the settings, click the `Create` button to save the Line Chart widget. This will close the dialog and add the new Line Chart to the dashboard. -![LineChart Created](../img/dashboards/created-linechart.png) +![LineChart Created](../../img/dashboards/created-linechart.png) ### Edit the Line Chart The Line Chart can be edited at any time by clicking the `pencil` icon on the widget. This will open a settings sheet on the right, where the chart’s data sources, labels, intervals, and title can be modified. -![Adjusting Line Chart dataSources](../img/dashboards/edit-linechart-sheet.png) +![Adjusting Line Chart dataSources](../../img/dashboards/edit-linechart-sheet.png) At this point, the labels, intervals, and chart title can also be edited. Clicking the `Update` button will save the changes and adjust the chart according to the new settings. A confirmation message (toast notification) will appear to confirm that the update has been applied. -![Edited Line Chart](../img/dashboards/new-linechart.png) +![Edited Line Chart](../../img/dashboards/new-linechart.png) The data can be further manipulated using the **Time Window** settings. For example, the data can be restricted to a specific interval, such as one hour, as shown in the following settings: -![Edit time window](../img/dashboards/to-from-linechart.png) +![Edit time window](../../img/dashboards/to-from-linechart.png) This adjustment will ensure the chart displays data within the defined time frame, ensuring that the final data point is at or before the specified _To_ date. Additionally, **Aggregation** can be applied to the data points. Aggregation requires a "From" value, a "To" value, and an interval. These settings help structure the query to the database for aggregated data. -![Aggregation Line Chart](../img/dashboards/aggregation-linechart-settings.png) +![Aggregation Line Chart](../../img/dashboards/aggregation-linechart-settings.png) In the example above, the chart is set to show the **Maximum** value over 10-minute intervals within a 100-minute time window. The resulting chart will look like this: -![Maximum Aggregates Line Charts](../img/dashboards/max-linechart.png) - +![Maximum Aggregates Line Charts](../../img/dashboards/max-linechart.png) #### **Conclusion** diff --git a/docs/dashboards/maps.md b/docs/user-guide/dashboards/maps.md similarity index 86% rename from docs/dashboards/maps.md rename to docs/user-guide/dashboards/maps.md index 502f78b..9dab63a 100644 --- a/docs/dashboards/maps.md +++ b/docs/user-guide/dashboards/maps.md @@ -25,7 +25,7 @@ To create a Marker Map, ensure that the dashboard is in **Edit Mode**. Then, cli This will open the **Create Marker Map** dialog, where users can configure the data sources and appearance of the map. -![Create Marker Map Dialog](../img/dashboards/markermap-dialog.png) +![Create Marker Map Dialog](../../img/dashboards/markermap-dialog.png) #### Configure the Marker Map @@ -34,24 +34,24 @@ This will open the **Create Marker Map** dialog, where users can configure the d - **Channel** - **Group** - ![Entity Type Selection](../img/dashboards/markermap-entities.png) + ![Entity Type Selection](../../img/dashboards/markermap-entities.png) 2. **Channel**: Select the specific entity whose location data will be displayed. For this example, a channel with pre-configured metadata will be plotted. 3. **Label**: Provide a label for the marker, which will help identify it on the map. -4. **Color**: Choose a color for the marker to distinguish it from others. -5. **Add Source**: Multiple data sources (entities) can be added to the map by clicking `Add Source`. -6. **Delete Source**: A data source can be removed by clicking the `trash` icon next to it. +3. **Color**: Choose a color for the marker to distinguish it from others. +4. **Add Source**: Multiple data sources (entities) can be added to the map by clicking `Add Source`. +5. **Delete Source**: A data source can be removed by clicking the `trash` icon next to it. - ![Create Channel Marker Map](../img/dashboards/datasosurce-markermap.png) + ![Create Channel Marker Map](../../img/dashboards/datasosurce-markermap.png) **Settings Section** 7. **Title**: Set a title for the map (e.g., "Marker Map"). This title will appear at the top of the map. 8. **Latitude Key**: Specify the metadata key that contains the latitude value. By default, it is set to `latitude`, but it can be modified if a different key is used. 9. **Longitude Key**: Similarly, set the metadata key for the longitude. The default is `longitude`. - ![Marker Map Settings](../img/dashboards/create-marker-dialog.png) + ![Marker Map Settings](../../img/dashboards/create-marker-dialog.png) Once all the required fields are completed, click the `Create` button to add the Marker Map to the dashboard. The map will automatically center on the specified locations based on the metadata. -![Channel Marker Map](../img/dashboards/new-markermap2.png) +![Channel Marker Map](../../img/dashboards/new-markermap2.png) Each marker on the map has an interactive popup that provides more information about the entity. Clicking on a marker will open a popup with the entity details, as shown below: @@ -60,7 +60,7 @@ Each marker on the map has an interactive popup that provides more information a - **Entity ID**: This is the unique identifier for the entity. It can be copied to the clipboard by clicking on the copy icon next to it. - **Latitude and Longitude**: The exact coordinates of the entity’s location, which can also be copied to the clipboard. - ![Marker Popup](../img/dashboards/popup-markermap-features.png) + ![Marker Popup](../../img/dashboards/popup-markermap-features.png) ### Edit the Marker Map @@ -69,11 +69,11 @@ To edit a Marker Map, click the `pencil` icon at the top-right corner of the map 1. **Add or Delete Data Sources**: Add additional entities to the map or remove existing ones by clicking the `Add Source` or `trash` icon, respectively. 2. **Modify Settings**: Update the **Latitude Key**, **Longitude Key**, and **Title** to better reflect the data being displayed. - ![Edit Marker Map](../img/dashboards/edit-channel-markermap2.png) + ![Edit Marker Map](../../img/dashboards/edit-channel-markermap2.png) Once changes have been made, click `Update` to apply the modifications. The updated map will display the new locations or modified settings. - ![Updated Marker Map](../img/dashboards/edited-markermap.png) + ![Updated Marker Map](../../img/dashboards/edited-markermap.png) #### Conclusion @@ -85,12 +85,12 @@ Marker Maps offer an intuitive way to visualize the physical locations of IoT de ### How Route Maps Work -Route Maps visualize location data by retrieving it from messages sent through a channel. The process for sending messages is covered in [getting-started](getting-started.md). +Route Maps visualize location data by retrieving it from messages sent through a channel. The process for sending messages is covered in [getting-started](../../dev-guide/getting-started.md). To use Route Maps, navigate to the messages tab of a channel that has connected clients. For Route Maps, it is crucial to use `location` as the value name, and the value type must be string. The message should contain the location data in the following format (as a string): `{"latitude":-1.206367, "longitude":36.905012}` - ![Sending Route Location Messagae](../img/dashboards/send-location-message.png) + ![Sending Route Location Messagae](../../img/dashboards/send-location-message.png) These location values are used to plot the device's movement on the map. The latest message will indicate the current location, while previous messages will form the route path. @@ -100,7 +100,7 @@ To create a Route Map, ensure that the dashboard is in **Edit Mode**. Click the This will open the **Create Route Map** dialog, where users can configure the data sources and appearance of the map. - ![Create Route Map Dialog](../img/dashboards/generic-routemap-dialog.png) + ![Create Route Map Dialog](../../img/dashboards/generic-routemap-dialog.png) #### Configure the Route Map @@ -112,7 +112,7 @@ This will open the **Create Route Map** dialog, where users can configure the da 6. **Add Source**: You can add multiple data sources (clients or channels) by clicking **Add Source**. 7. **Remove Source**: To remove a data source, click the `Trash Icon` next to the specific entry. - ![Route Map Data Source](../img/dashboards/routemap-datasources.png) + ![Route Map Data Source](../../img/dashboards/routemap-datasources.png) #### Settings Section @@ -123,7 +123,7 @@ This will open the **Create Route Map** dialog, where users can configure the da 5. **Longitude Key**: Specify the key in the message that contains the longitude value. The default is `longitude`, but this can be changed as needed. 6. **Route Line Width**: Adjust the thickness of the route line on the map. This allows users to highlight routes or distinguish between different paths visually. - ![Route Map Settings](../img/dashboards/routemap-advancedsettings.png) + ![Route Map Settings](../../img/dashboards/routemap-advancedsettings.png) Once all required fields are completed, click the `Create` button to add the Route Map to the dashboard. @@ -133,7 +133,7 @@ After creating the Route Map, the path will be displayed based on the messages t - **Single Message Route**: If only one message has been sent, the map will show a single marker for the location. - ![Created Route Map](../img/dashboards/new-routemap.png) + ![Created Route Map](../../img/dashboards/new-routemap.png) - **Multiple Messages Route**: As more messages are received, the route will appear longer, showing the movement or changes in location over time. @@ -146,15 +146,15 @@ To edit the Route Map, click the `pencil` icon at the top-right corner of the ma Changes to the map can be made by updating the data or settings and clicking Update to apply them. - ![Edit Route Map](../img/dashboards/edit-routemap-newthing.png) + ![Edit Route Map](../../img/dashboards/edit-routemap-newthing.png) The updated route map will refresh with the new data or settings. - ![Updated Route Map](../img/dashboards/edited-routemap.png) + ![Updated Route Map](../../img/dashboards/edited-routemap.png) Multiple data sources can also be added, as shown below: - ![Updated Route Map with 2 Devices](../img/dashboards/edited-routemap-2.png) + ![Updated Route Map with 2 Devices](../../img/dashboards/edited-routemap-2.png) #### Route Map Popups @@ -165,9 +165,8 @@ Each point on the map representing a message has an interactive popup with more - **Latitude and Longitude**: The exact coordinates of the location, which can be copied to the clipboard. - **View Client Details**: A link to the specific entity's details page. - ![Route Map Popup](../img/dashboards/popup-routemap-features.png) + ![Route Map Popup](../../img/dashboards/popup-routemap-features.png) -#### Conclusion +#### Route Map Conclusion Route Maps provide a dynamic way to visualize the movement or changes in location of devices over time. By retrieving location data from messages, these maps enable real-time tracking and historical path analysis. With customizable settings such as update intervals and time windows, Route Maps offer flexibility in monitoring IoT devices' geographical movements. Users can track multiple devices. - diff --git a/docs/dashboards/piechart.md b/docs/user-guide/dashboards/piechart.md similarity index 90% rename from docs/dashboards/piechart.md rename to docs/user-guide/dashboards/piechart.md index 6364bd5..1fb6f23 100644 --- a/docs/dashboards/piechart.md +++ b/docs/user-guide/dashboards/piechart.md @@ -5,7 +5,6 @@ title: Pie Chart **Pie Charts** provide a simple yet effective way to compare different data points by visualizing them as proportions of a whole. Unlike other timeseries charts, pie charts only display the latest value from each data source, making them ideal for showing the most recent data from multiple sources in a comparative manner. - ### Create a Pie Chart To create a Pie Chart, ensure that your dashboard is in **Edit Mode**. @@ -25,7 +24,7 @@ These are the required fields to configure the Pie Chart; 4. **Label**: Provide a label for each data source, which helps distinguish the different segments of the pie chart. 5. **Color**: Choose a color for each data source slice in the pie chart. -![Create Pie Chart](../img/dashboards/create-piechart.png) +![Create Pie Chart](../../img/dashboards/create-piechart.png) Once the data sources are configured, a Time Window can be defined by specifying the "From" and "To" dates to use historical data. The Pie Chart will display the latest message received within this time window, focusing on the most recent message during the specified period. @@ -33,8 +32,7 @@ In the Settings tab, the Update Interval can be adjusted to determine how often Once all settings are complete, click the `Create` button to add the Pie Chart widget to the dashboard. - -![New Pie Chart](../img/dashboards/new-piechart.png) +![New Pie Chart](../../img/dashboards/new-piechart.png) ### Edit the Pie Chart @@ -45,22 +43,22 @@ This will open the edit sheet on the right, where adjustments can be made to the 2. **Modifying Time Window**: Adjust the "From" and "To" dates to define the desired time period for the latest values. 3. **Delete a Data Source**: Click the `trash` icon to delete any data source. -![Edit Pie Chart](../img/dashboards/edit-piechart-times.png) +![Edit Pie Chart](../../img/dashboards/edit-piechart-times.png) Once the necessary changes are made, click `Update` to apply the modifications. The chart will refresh to display the updated data and settings. This is an edited chart showing live data. -![Edited Pie Chart](../img/dashboards/edited-piechart.png) +![Edited Pie Chart](../../img/dashboards/edited-piechart.png) Pie Charts support Aggregation, which allows displaying a summary value (such as **maximum**, **minimum**, **sum**, **count**, or **average**) from the data in each time window. Unlike other timeseries charts, there is no need to specify an interval—the time window itself defines the aggregation range, and the chart will only display the aggregated value for each data source. -![Aggregation Pie Chart](../img/dashboards/aggregation-piechart-setting.png) +![Aggregation Pie Chart](../../img/dashboards/aggregation-piechart-setting.png) For example, setting the aggregation to **Maximum** will display the highest value of each data source within the specified time window, helping users understand the overall distribution of data across different sources. -![Maximum Pie Chart](../img/dashboards/max-piechart.png) +![Maximum Pie Chart](../../img/dashboards/max-piechart.png) #### Customize Pie Charts @@ -68,4 +66,5 @@ For example, setting the aggregation to **Maximum** will display the highest val - **Color Customization**: Each slice in the pie chart represents a different data source, and the color picker allows for easy differentiation between them. #### **Conclusion** + With the ability to lock onto the latest message within a time window and aggregate data over specific periods, Pie Charts are a powerful tool for comparing real-time or recent data from multiple devices or channels in a visually appealing format. diff --git a/docs/dashboards/tablecard.md b/docs/user-guide/dashboards/tablecard.md similarity index 92% rename from docs/dashboards/tablecard.md rename to docs/user-guide/dashboards/tablecard.md index 3c7b5ac..6fccf87 100644 --- a/docs/dashboards/tablecard.md +++ b/docs/user-guide/dashboards/tablecard.md @@ -4,7 +4,6 @@ title: Table Card A **Table Card** displays a list of entities (such as devices, members, or groups) within a domain, showing both enabled and disabled entities. It also includes pagination to help manage large lists effectively. - ### Create a Table Card To create a Table Card, ensure the dashboard is in **Edit Mode**. @@ -23,7 +22,7 @@ Click the `Add Widget` button and select **Table Card** from the list of availab 4. **Update Interval**: Set the refresh interval for how often the table should update with the latest data. For example, an interval of `60` seconds will refresh the table every minute. 5. **Title**: Enter a title for the table card, which will appear at the top of the widget. - ![Table Card Configuration](../img/dashboards/tablecard-dialog.png) + ![Table Card Configuration](../../img/dashboards/tablecard-dialog.png) Once all necessary fields are completed, click the `Create` button to add the Table Card to the dashboard. @@ -33,22 +32,23 @@ The table card will immediately display the list of entities based on the select - **Status**: The status of the entity (enabled or disabled). - **Created At**: The timestamp of when the entity was created. - ![Table Card Created](../img/dashboards/new-tablecard.png) + ![Table Card Created](../../img/dashboards/new-tablecard.png) The card also includes pagination at the bottom, allowing navigation through multiple pages of entities. ### Edit the Table Card + To edit a Table Card, click the `pencil` icon in the top-right corner of the widget. This will open a settings sheet on the right, where the data source, entity status, tag, and other settings can be adjusted. 1. **Data Source**: Modify the **Entity Type**, **Status**, or **Tag** to change the entities displayed in the table. 2. **Update Interval**: Adjust the refresh interval for the table. 3. **Title**: Update the title of the table card to reflect any new data or focus. - ![Editing Table Card](../img/dashboards/edit-tablecard2.png) + ![Editing Table Card](../../img/dashboards/edit-tablecard2.png) Once the updates are made, click `Update` to save the changes. The table card will refresh with the new data and settings. - ![Updated Table Card](../img/dashboards/edited-tablecard.png) + ![Updated Table Card](../../img/dashboards/edited-tablecard.png) #### Customizing Table Cards diff --git a/docs/dashboards/valuecard.md b/docs/user-guide/dashboards/valuecard.md similarity index 90% rename from docs/dashboards/valuecard.md rename to docs/user-guide/dashboards/valuecard.md index b86cb0a..c2e9bdf 100644 --- a/docs/dashboards/valuecard.md +++ b/docs/user-guide/dashboards/valuecard.md @@ -9,7 +9,6 @@ A **Value Card** provides a snapshot of real-time data by displaying the latest To create a Value Card, ensure the dashboard is in **Edit Mode**. Click the `Add Widget` button, then select **Value Card** from the list of available widgets. This will open the **Create Value Card** dialog, where the data source and appearance of the card can be configured. - #### Configuring the Value Card 1. **Channel**: Select the channel from which the card will pull data. @@ -19,15 +18,15 @@ Click the `Add Widget` button, then select **Value Card** from the list of avail 5. **Title**: Provide a title for the Value Card, which will be displayed at the top of the widget. 6. **Unit**: Provide a title for the Value Card, which will be displayed at the top of the widget. -![Value Card Configuration](../img/dashboards/create-valuecard.png) +![Value Card Configuration](../../img/dashboards/create-valuecard.png) 7. **Icon**: Select an icon to visually represent the data displayed. A range of icons is available to match the context of the value. -![Icon Selection](../img/dashboards/valuecard-icons.png) +![Icon Selection](../../img/dashboards/valuecard-icons.png) Once all the necessary fields are completed, click the `Create` button to add the Value Card to the dashboard. The card will immediately display the latest value from the channel, along with the associated unit and icon. -![Value Card Created](../img/dashboards/new-valuecard.png) +![Value Card Created](../../img/dashboards/new-valuecard.png) ### Edit the Value Card @@ -39,12 +38,12 @@ To edit a Value Card, click the **Pencil Icon** in the top-right corner of the w 4. **Unit**: Update the unit if the data type changes (e.g., from volts to amps). 5. **Icon**: Select a new icon that matches the updated data context. -![Editing Value Card](../img/dashboards/edit-valuecard.png) +![Editing Value Card](../../img/dashboards/edit-valuecard.png) Once the updates are made, click **Update** to save the changes. The card will refresh to show the updated data and icon. -![Updated Value Card](../img/dashboards/edited-valuecard.png) +![Updated Value Card](../../img/dashboards/edited-valuecard.png) #### Customizing Value Cards @@ -52,4 +51,5 @@ The card will refresh to show the updated data and icon. - **Display**: The Value Card shows the value, unit, and the last update time, allowing users to quickly understand the current status of the connected device or channel. #### **Conclusion** + With Value Cards, users can effectively monitor the latest value of specific metrics, making them ideal for real-time overviews of critical data from connected devices. diff --git a/docs/dashboards/widgets.md b/docs/user-guide/dashboards/widgets.md similarity index 90% rename from docs/dashboards/widgets.md rename to docs/user-guide/dashboards/widgets.md index cbc8931..0163f88 100644 --- a/docs/dashboards/widgets.md +++ b/docs/user-guide/dashboards/widgets.md @@ -3,6 +3,7 @@ title: Widget Guide --- #### Introduction to Widgets + Widgets are interactive components designed to display data visually. They enable real-time monitoring and historical data analysis, providing valuable insights through customizable dashboards. Widgets can be tailored to meet specific requirements, making them essential tools for data-driven decision-making. Magistrala offers a variety of widgets, including charts, data cards, gauges, maps and control elements: @@ -51,8 +52,7 @@ Charts are perfect for time-series data and comparisons, while cards are designe Dashboards are built using **Widgets** that visualize data and facilitate control over other devices. These widgets can host a variety of charts and controls. To ensure that timeseries charts function correctly, you need to have connected channels and clients that actively send messages. - -![Edit Dashboard](../img/dashboards/editmode-checked.png) +![Edit Dashboard](../../img/dashboards/editmode-checked.png) ### Widget Chart Features @@ -66,24 +66,23 @@ These features include: - Filters - Data Aggregation - #### 1. Time Window The time window represents the interval used to fetch time-series data for charts. It is especially useful for time-series charts like Area, Line, Bar, Pie charts, and Route Maps. -![Calender Option](../img/dashboards/date-picker.png) +![Calender Option](../../img/dashboards/date-picker.png) The selected "from" and "to" times are included in the query sent to the database. Users can choose between **Realtime** and **History** modes: - - **History**: Displays data within a specific time range set using the calendar. +- **History**: Displays data within a specific time range set using the calendar. - - **Realtime**: Shows data as it is updated in real-time. +- **Realtime**: Shows data as it is updated in real-time. The date-time calendar also includes time slots. Clicking on the first box allows you to enter the time using a 24-hour clock format. When live data is selected, a red blinking button appears on the widget. Here is an example of a time-series Area chart using live data: -![Time series area chart](../img/dashboards/area-chart-created.png) +![Time series area chart](../../img/dashboards/area-chart-created.png) If no time window is set, **history** is set as default. @@ -98,8 +97,7 @@ For **time-series charts**, settings are generally consistent except for pie cha A user can only modify the **title** and **update interval**. The update interval determines how often the API requests new data from the database, with a default of **60 seconds**. Additionally, a user can modify the **x and y-axis** labels as needed. -![Settings](../img/dashboards/settings-xyaxes.png) - +![Settings](../../img/dashboards/settings-xyaxes.png) **Gauge charts** offer additional options, such as setting **minimum** and **maximum** values to control the scale. These default to *0* and *100*. Users can also select a unit from a provided list, including: @@ -150,28 +148,28 @@ The update interval determines how often the API requests new data from the data Here is an example of a chart with the unit set to *km* : -![Gauge-chart example](../img/dashboards/gauge-chartexample.png) +![Gauge-chart example](../../img/dashboards/gauge-chartexample.png) For **control sliders**, similar to gauge charts, you'll need to define minimum and maximum values to set the scale. The step value, which determines the increment or decrement per move, defaults to *10*. -![Slider chart settings](../img/dashboards/settings-slider.png) +![Slider chart settings](../../img/dashboards/settings-slider.png) For maps, the **Latitude Key** and **Longitude Key** tags are essential for retrieving geospatial data. These tags define the latitude and longitude attributes required to pinpoint entity positions. By default, these are set to *latitude* and *longitude*. **Route maps** allow you to adjust the **line width**, making it easy to modify the thickness of route lines. -![Route Map settings](../img/dashboards/settings-routemap.png) +![Route Map settings](../../img/dashboards/settings-routemap.png) **Value cards** provide options to configure the **update interval**, **unit**, and **title**, allowing for quick adjustments to how data is displayed. -![Value Card Settings](../img/dashboards/settings-valuecard.png) +![Value Card Settings](../../img/dashboards/settings-valuecard.png) #### 3. Icons The icons section provides a variety of icons that can enhance the value card's visualization. Simply type the name of the desired icon and it will appear on the card -![Icons select](../img/dashboards/icons-select.png) +![Icons select](../../img/dashboards/icons-select.png) #### 4. Filters @@ -195,12 +193,11 @@ The **ValueName** parameter functions as an additional filter by restricting req The status of an entity also serves as a key filter, especially in charts like the entity table and count card. This filter limits displayed entities based on their status: enabled, disabled, or all statuses. -![Status check](../img/dashboards/status-filter-charts.png) - +![Status check](../../img/dashboards/status-filter-charts.png) #### 5. Data Aggregation -Data aggregation is a powerful feature that enables the summarization of data over specific time periods. This is particularly useful for time-series charts where you want to visualize trends or patterns over a defined period. Magistrala currently supports the following aggregation methods: +Data aggregation is a powerful feature that enables the summarization of data over specific time periods. This is particularly useful for time-series charts where you want to visualize trends or patterns over a defined period. Magistrala currently supports the following aggregation methods: - **Maximum**: Retrieves the highest value within the specified time window. - **Minimum**: Retrieves the lowest value within the specified time window. @@ -216,10 +213,9 @@ For aggregation to work correctly: - In Realtime mode, users must select a From Date, specify the Last duration, and set the Aggregation Interval. - The **Aggregation Interval** indicates the frequency at which the data points are aggregated (e.g. every 10 seconds). -![Aggregation Settings](../img/dashboards/aggregation-setting.png) +![Aggregation Settings](../../img/dashboards/aggregation-setting.png) For example, to view the average temperature readings of a sensor every 10 minutes over the past 24 hours: @@ -229,7 +225,6 @@ For example, to view the average temperature readings of a sensor every 10 minut - Set the Aggregation Interval to 10 minutes. - This setup provides a clear visual representation of temperature trends. By using data aggregation, a user gains deeper insights into your data, making it easier to monitor and analyze the performance and behavior of your IoT devices. @@ -238,7 +233,7 @@ By using data aggregation, a user gains deeper insights into your data, making i Once you've created a widget, you can easily modify it to suit changing requirements. While in **Edit Mode**, click the `pencil` icon located at the top right corner of the widget you want to edit. This action opens a settings panel from the right side of the screen, as shown below: -![Chart showing edit icon](../img/dashboards/edit-icon-chart.png) +![Chart showing edit icon](../../img/dashboards/edit-icon-chart.png) In this panel, you'll find all the previously configured settings and data sources. You can: @@ -248,7 +243,7 @@ In this panel, you'll find all the previously configured settings and data sourc - Add additional data sources by clicking on the `Add Source` button, allowing the widget to visualize multiple data streams simultaneously. - Adjust the **Time Window** and other **Settings** such as chart appearance, filters and aggregation intervals as needed. -![Edit Chart Sheet ](../img/dashboards/edit-chartsheet.png) +![Edit Chart Sheet ](../../img/dashboards/edit-chartsheet.png) After making your changes, click the `Update` button to apply them. The widget will automatically refresh to display the new configuration, providing a real-time view of the updated data. @@ -256,19 +251,18 @@ For example, if you want to add two more data sources to an existing bar chart, This flexibility allows you to keep your dashboard stays up-to-date with the latest data allowing you to make adjustments on the fly to meet your monitoring and management needs. - ### Add Dummy Data From the widget menu, you can select `Dummy Data` to populate the chart with sample data. This feature provides a quick and easy way to create dummy charts, helping you understand the data structure needed for your visualizations. -![Widget Menu](../img/dashboards/widget-menu.png) +![Widget Menu](../../img/dashboards/widget-menu.png) ### Delete a Widget To delete a widget, click the `Delete` button in the widget menu on the widget card. Confirm the deletion when prompted to permanently remove the widget. -![Widget Menu](../img/dashboards/widget-menu.png) +![Widget Menu](../../img/dashboards/widget-menu.png) -![Deleting a Widget](../img/dashboards/delete-widget.png) +![Deleting a Widget](../../img/dashboards/delete-widget.png) -[users-quick-start]: users-quick-start.md +[users-quick-start]: ../users-quick-start.md diff --git a/docs/domain-management/billing.md b/docs/user-guide/domain-management/billing.md similarity index 87% rename from docs/domain-management/billing.md rename to docs/user-guide/domain-management/billing.md index b22eddc..8a1125e 100644 --- a/docs/domain-management/billing.md +++ b/docs/user-guide/domain-management/billing.md @@ -11,55 +11,59 @@ This means that Magistrala will not have the user's card payment credentials at Navigate to the Billing tab on the sidenav bar. This tab will only be visible to admin members of a domain. ## Overview + The billing page has multiple sections present each important to the billing process. -![Billing Page](../img/billing/billing-page.png) +![Billing Page](../../img/billing/billing-page.png) In a newly created domain without any data on billing, all the sections will be empty. - ## Add Billing Information + This section includes the user's contact details such as addresses, emails, and the name of the user to whom the subscription will be charged. -![Billing](../img/billing/billing-information.png) +![Billing](../../img/billing/billing-information.png) To fill this section, click on `Add` to trigger a dialogbox. On the form, you are required to fill in the Name, Email, Phone, Country and City of the billed customer. State and Province or Addresses are optional but help in the creation of invoices. After filling in the required data, click `Add` and the information will be fed into the system. -![Billing Information](../img/billing/add-bill-info.png) +![Billing Information](../../img/billing/add-bill-info.png) ## Subscribe to a Billing Plan + The subscription section handles the domain's subscription plan and shows the status of the subscription. To add a billing plan to the domain, click `Choose`, which will display a list of available subscription plans. -![Billing-plan-addition](../img/billing/choose.png) +![Billing-plan-addition](../../img/billing/choose.png) The subscription status can be either **completed**, where the user has already been charged, or **incomplete**, where the process is not yet finished and the subscription is inactive. The **plan details** generally show the user the limits of their subscribed plan. This ensures they are aware of their restrictions at all times. These limits define what can be accessed in terms of domains, users, groups, and devices. ## Add a Payment Method + Click on the `Add` button to gain access to the page where you will fill in your card information. A succesful update will lead you back to the Magistrala billing page with an active payment method. -![Adding the Card](../img/billing/add-card.png) +![Adding the Card](../../img/billing/add-card.png) You can add as many payment cards as needed. Each card will be verified to prevent any fraudulent cards from being accepted. Ensure that the card has sufficient funds to cover the subscription cost. You can also edit payment methods, set a default card and delete any payment method. -![Add multiple cards](../img/billing/pm-table.png) +![Add multiple cards](../../img/billing/pm-table.png) To set a payment method as default simply select `Set as default` in the dropdown. Once payment method has been set as default, a badge showing default appears. To delete a payment method simply select `Delete` on the dropdown and the payment method will be deleted. ## Generate an Invoice -Once the plan is selected, an invoice will be generated that can be downloaded by clicking the invoice icon downloads a pdf with all the required data. -![Invoice section](../img/billing/invoice.png) +Once the plan is selected, an invoice will be generated that can be downloaded by clicking the invoice icon downloads a pdf with all the required data. +![Invoice section](../../img/billing/invoice.png) ## Generate a Receipt + Once payment is received, there will be an receipt generated that a user can download by clicking on the receipt icon. -![Invoice section](../img/billing/receipt.png) \ No newline at end of file +![Invoice section](../../img/billing/receipt.png) diff --git a/docs/domain-management/domain.md b/docs/user-guide/domain-management/domain.md similarity index 87% rename from docs/domain-management/domain.md rename to docs/user-guide/domain-management/domain.md index ade1d32..a0eb5d3 100644 --- a/docs/domain-management/domain.md +++ b/docs/user-guide/domain-management/domain.md @@ -10,15 +10,15 @@ Here a user can edit the Domain Name, Alias, Tags and Metadata as well as copy t The Domain status can be disabled by clicking the `Disable` button or enabled by the `Enable` button. Disabling the domain will revoke the access for users who are not domain admins. -![Domain Info](../img/domain/domain-info.png) +![Domain Info](../../img/domain/domain-info.png) ## Domain Roles From the roles section of the domain, the user can create new roles with varying role actions. -By default, an admin role with complete control over the domain is always present and granted to the Domain creator. +By default, an admin role with complete control over the domain is always present and granted to the Domain creator. -![Domain Roles](../img/domain/roles.png) +![Domain Roles](../../img/domain/roles.png) This is a domain role actions comprehensive list: @@ -81,15 +81,15 @@ This is a domain role actions comprehensive list: To create a new role, click on the `+ Create` button, provide a descriptive name for the role, and optionally add users and actions -![Create Domain Role](../img/domain/create-role.png) +![Create Domain Role](../../img/domain/create-role.png) Once created, domain roles can be edited in their respective pages. -A user can edit the domain role name, role actions and role members. +A user can edit the domain role name, role actions and role members. -![Domain Role Page](../img/domain/domain-role-id.png) +![Domain Role Page](../../img/domain/domain-role-id.png) These fields can be updated directly on the page or via the dropdown menu options. -![Domain Action Buttons](../img/domain/role-actions.png) +![Domain Action Buttons](../../img/domain/role-actions.png) ## Domain Members diff --git a/docs/domain-management/introduction.md b/docs/user-guide/domain-management/introduction.md similarity index 100% rename from docs/domain-management/introduction.md rename to docs/user-guide/domain-management/introduction.md diff --git a/docs/domain-management/invitations.md b/docs/user-guide/domain-management/invitations.md similarity index 100% rename from docs/domain-management/invitations.md rename to docs/user-guide/domain-management/invitations.md diff --git a/docs/index.md b/docs/user-guide/index.md similarity index 98% rename from docs/index.md rename to docs/user-guide/index.md index 816e5d5..4ec263f 100644 --- a/docs/index.md +++ b/docs/user-guide/index.md @@ -12,7 +12,7 @@ Magistrala is a cutting-edge, open-source IoT cloud platform built on top of [Su It accepts user and client connections over various network protocols (i.e. HTTP, MQTT, WebSocket, CoAP), thus making a seamless bridge between them. It is used as the IoT middleware for building complex IoT solutions as one of its capabilities in modern software as a service functionalities. -![banner](img/gopherBanner.jpg) +![banner](../img/gopherBanner.jpg) ### Features @@ -35,7 +35,6 @@ It accepts user and client connections over various network protocols (i.e. HTTP - Developer Tools with comprehensive SDK and CLI. - Domain-Driven Design. - ## Contributing to Magistrala Thank you for your interest in Magistrala and the desire to contribute! diff --git a/docs/profile-management/users.md b/docs/user-guide/profile-management/users.md similarity index 78% rename from docs/profile-management/users.md rename to docs/user-guide/profile-management/users.md index 53f816d..52cf059 100644 --- a/docs/profile-management/users.md +++ b/docs/user-guide/profile-management/users.md @@ -8,44 +8,43 @@ Each user has access to a **Profile Page**, where personal information, security Clicking on the `user profile picture` or `avatar` at the top right opens a popover. - -#### Standard User Menu +### Standard User Menu - **Profile** - **Domains** - **Logout** -![User Popover](../img/profile-management/jdoe-popover.png) +![User Popover](../../img/profile-management/jdoe-popover.png) Selecting the Profile option reveals three main tabs: ### Account + The **Account** tab allows users to update their names, email and upload a profile picture. -![Profile Tab 1](../img/profile-management/jdoe-profile.png) +![Profile Tab 1](../../img/profile-management/jdoe-profile.png) ### Password + The **Password** tab focuses on security. Users can change their password by entering their current password, followed by the new password (which MUST pass verification) and its confirmation. > **Note:** After updating the password, the current session will be terminated, requiring the user to log in again with the new credentials. -![Profile Tab 2](../img/profile-management/jdoe-password-tab.png) +![Profile Tab 2](../../img/profile-management/jdoe-password-tab.png) ### Preferences + The **Preferences** tab enables users to customize language and theme settings. -![Profile Tab 3](../img/profile-management/jdoe-preferences-tab.png) +![Profile Tab 3](../../img/profile-management/jdoe-preferences-tab.png) Magistrala currently supports **English**, **German**, and **Serbian** languages and offers four different themes to choose from. -![Themes](../img/profile-management/jdoe-themes-tab.png) - - +![Themes](../../img/profile-management/jdoe-themes-tab.png) ## Password Recovery If a user forgets their password, they can click the `Forgot Password` link on the login page. This directs them to a page where they enter their email address to receive a password reset link. -![Forgot Password](../img/profile-management/forgot-password2.png) - +![Forgot Password](../../img/profile-management/forgot-password2.png) The reset password link contains a unique token. Clicking the link redirects the user to the **Reset Password** page, where a new password can be created and confirmed. After resetting the password, the user can log into the system with the new credentials. diff --git a/docs/rules-engine.md b/docs/user-guide/rules-engine.md similarity index 83% rename from docs/rules-engine.md rename to docs/user-guide/rules-engine.md index 112a598..a43d753 100644 --- a/docs/rules-engine.md +++ b/docs/user-guide/rules-engine.md @@ -19,7 +19,7 @@ Users can create rules by attaching input, logic, and output nodes. To create a **Rule** navigate to the Rules section and click on the `+ Create` button to open the rule creation dialog. Provide a **name** for the rule and click Create. -![Create a new Rule](../docs/img/rules/create-rule.png) +![Create a new Rule](../img/rules/create-rule.png) Users can view all created rules in a structured list, displaying: @@ -27,13 +27,13 @@ Users can view all created rules in a structured list, displaying: - Status (Enabled/Disabled) - Creation date -![Create a Rule Dialog](../docs/img/rules/create-rule-dialog.png) +![Create a Rule Dialog](../img/rules/create-rule-dialog.png) ## **View a Rule** Click on the rule name present at the rules table to be redirected to the Rule's ID page. -![View a Rule](../docs/img/rules/view-rule.png) +![View a Rule](../img/rules/view-rule.png) From here users can view the Rule's input and output nodes as well as the logic. @@ -41,7 +41,7 @@ From here users can view the Rule's input and output nodes as well as the logic. Users can enable or diable a Rule by clicking on the Toggle at the top right of the Rule page. -![Update Rule Status](../docs/img/rules/disabled-rule.png) +![Update Rule Status](../img/rules/disabled-rule.png) ## **Adding Comparison Block** @@ -54,7 +54,7 @@ A **Comparison Block** allows users to define conditions based on message payloa - Users can combine multiple conditions using **AND/OR** operators. -![Add multiple conditions](../docs/img/rules/add-multiple-conditions.png) +![Add multiple conditions](../img/rules/add-multiple-conditions.png) ## **Switching Between Logic Types** @@ -65,6 +65,6 @@ Users can switch between a **Comparison Block** and **Lua Script** editor: 3. Enter the custom script for message processing. 4. Save the changes. -![Switch to Editor](../docs/img/rules/switch-to-editor.png) +![Switch to Editor](../img/rules/switch-to-editor.png) -![Switched to Editor](../docs/img/rules/switched-to-editor.png) +![Switched to Editor](../img/rules/switched-to-editor.png) diff --git a/docs/users-quick-start.md b/docs/user-guide/users-quick-start.md similarity index 85% rename from docs/users-quick-start.md rename to docs/user-guide/users-quick-start.md index b3ec711..5c3a9f8 100644 --- a/docs/users-quick-start.md +++ b/docs/user-guide/users-quick-start.md @@ -15,17 +15,17 @@ To get started, create an account by providing the following details in the sign - **An email address** - **A username** -![Sign Up](../docs/img/users-guide/registeruser2.png) +![Sign Up](../img/users-guide/registeruser2.png) Once registered, the user will be redirected to the **Domains Homepage**, where they can create and manage multiple domains. -![Domain Homepage](../docs/img/users-guide/janedoe-domainshome.png) +![Domain Homepage](../img/users-guide/janedoe-domainshome.png) ## **Log In** Incase you already have an account, you can log in with your email/username and password. -![Login](../docs/img/users-guide/main-login.png) +![Login](../img/users-guide/main-login.png) ## **Log into a Domain** @@ -35,7 +35,7 @@ A **Domain** is a workspace that allows you to manage **Clients**, **Channels**, Click on the `+ Create` button on the top right to create a new domain. Since multiple domains can have the same name, you must add an **alias** which will be a unique descriptor for the domain. -![Domain Create](../docs/img/users-guide/jdoe-create-domain.png) +![Domain Create](../img/users-guide/jdoe-create-domain.png) Once you create a domain, you are given **admin** role over the domain by default. You are able to perform all actions available over the domain and all the entities provisioned inside the domain. You can also assign or invite members to the domain with various levels of permissions. Click on the respective card to log into a domain of your choice. @@ -47,12 +47,11 @@ Once logged in, you will be directed to the **Homepage** where you can view all On the sidebar navigation, click on **Groups** under the _Client Management_ section to be redirected to the groups page. -![Groups Page](../docs/img/users-guide/jdoe-groups-page.png) +![Groups Page](../img/users-guide/jdoe-groups-page.png) To create a group, click on the `+ Create` button present on the top-left corner of the page. This will open a popover with all the required fields for a new group. -![Create Group](../docs/img/clients/group-information.png) - +![Create Group](../img/clients/group-information.png) ## **Create a Client** @@ -67,11 +66,11 @@ A dialog box will open, requiring fields such as **Name**. You can add a unique key for the thing, although one is automatically generated. Additionally, **tags** can be assigned to Clients for better organization and filtering. -![Create Client](../docs/img/users-guide/group-client-create.png) +![Create Client](../img/users-guide/group-client-create.png) A user can also create bulk clients by clicking on the `+ Create Clients` button. This will lead to a dialogbox that takes in a _.CSV_ file with the clients' details filled in correctly as seen in these [samples](https://github.com/absmach/magistrala-ui/tree/main/samples). -![Create Clients](../docs/img/users-guide/group-clients-create.png) +![Create Clients](../img/users-guide/group-clients-create.png) ### View a Client @@ -80,7 +79,7 @@ To access the page, click on the Client in the Clients' table. The client's data can be updated in this page and its ID copied as well. -![View Client](../docs/img/users-guide/group-client-view2.png) +![View Client](../img/users-guide/group-client-view2.png) There **Connections** tab in the **group-client page** is where a User can connect a Client to a Channel. @@ -94,35 +93,35 @@ Each Client can **publish or subscribe** to a Channel, facilitating seamless dev To create a channel, navigate to the fourth tab under the groups and click on `+ Create`. This will open a dialog box which will take in a unique Channel name. Much like the Clients, clicking on `+ Create Channels` will allow a user to upload a _.CSV_ file with multiple channels. -![Create Group Channel](../docs/img/users-guide/group-channel-create.png) +![Create Group Channel](../img/users-guide/group-channel-create.png) ### View a Channel After the Channel is created, clicking on it while it is on the Channel's table leads to the Channel View Page. -![View Group Channel](../docs/img/users-guide/group-channel-view.png) +![View Group Channel](../img/users-guide/group-channel-view.png) Clients can be connected to channels in groups. This is done in the **Connections** tab. There are two connection types: - **Subscribe** - **Publish** -![Connect Group Channel Clients](../docs/img/users-guide/group-channel-connections.png) +![Connect Group Channel Clients](../img/users-guide/group-channel-connections.png) ## **Send a Message** Once a Channel and Client are connected, a user is able to send messages. Navigate to the `Messages` tab of the Group-Channel and click on `**Send Messages**`. -![View Messages Page](../docs/img/users-guide/group-messages-view.png) +![View Messages Page](../img/users-guide/group-messages-view.png) This will open a dialog box where all the required fields bear an asterisk. Messages are sent via _HTTP_ protocol in the UI. -![Send Message](../docs/img/users-guide/group-send-message.png) +![Send Message](../img/users-guide/group-send-message.png) The messages table will then update to include the message sent with the latest message appearing first. Using the filter options, you can filter through a wide range of messages based on the protocol, publisher or even value. -![Messages Table](../docs/img/users-guide/group-sent-messages-page.png) +![Messages Table](../img/users-guide/group-sent-messages-page.png) > The download message feature is currently not active but will be with future iterations of Magistrala. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 1b6c32c..adc6694 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -68,13 +68,13 @@ const config: Config = { type: 'docSidebar', sidebarId: 'userSidebar', position: 'left', - label: 'User Documentation', + label: 'User Docs', }, { type: 'docSidebar', sidebarId: 'devSidebar', - position: 'right', - label: 'Developer Documentation', + position: 'left', + label: 'Dev Docs', }, { to: '/blog', label: 'Blog', position: 'right' }, { diff --git a/sidebars.ts b/sidebars.ts index d8b2faf..f8fc9f2 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -4,17 +4,17 @@ const sidebars: SidebarsConfig = { userSidebar: [ { type: "doc", - id: "index", + id: "user-guide/index", label: "Overview", }, { type: "doc", - id: "architecture", + id: "user-guide/architecture", label: "Architecture", }, { type: "doc", - id: "users-quick-start", + id: "user-guide/users-quick-start", label: "Getting Started", }, { @@ -22,13 +22,13 @@ const sidebars: SidebarsConfig = { label: 'Domain Management', link: { type: "doc", - id: "domain-management/introduction", + id: "user-guide/domain-management/introduction", }, collapsible: true, items: [ - { type: "doc", id: "domain-management/domain", label: "Domain" }, - { type: "doc", id: "domain-management/billing", label: "Billing" }, - { type: "doc", id: "domain-management/invitations", label: "Invitations" }, + { type: "doc", id: "user-guide/domain-management/domain", label: "Domain" }, + { type: "doc", id: "user-guide/domain-management/billing", label: "Billing" }, + { type: "doc", id: "user-guide/domain-management/invitations", label: "Invitations" }, ], }, { @@ -37,13 +37,13 @@ const sidebars: SidebarsConfig = { collapsible: true, link: { type: "doc", - id: "clients/introduction", + id: "user-guide/clients/introduction", }, items: [ - { type: "doc", id: "clients/groups", label: "Groups" }, - { type: "doc", id: "clients/clients", label: "Clients" }, - { type: "doc", id: "clients/channels", label: "Channels" }, - { type: "doc", id: "clients/bootstraps", label: "Bootstraps" }, + { type: "doc", id: "user-guide/clients/groups", label: "Groups" }, + { type: "doc", id: "user-guide/clients/clients", label: "Clients" }, + { type: "doc", id: "user-guide/clients/channels", label: "Channels" }, + { type: "doc", id: "user-guide/clients/bootstraps", label: "Bootstraps" }, ], }, { @@ -51,108 +51,108 @@ const sidebars: SidebarsConfig = { label: "Dashboards", link: { type: "doc", - id: "dashboards/introduction", + id: "user-guide/dashboards/introduction", }, collapsible: true, items: [ - { type: "doc", id: "dashboards/dashboards", label: "Dashboard" }, - { type: "doc", id: "dashboards/widgets", label: "Widgets" }, - { type: "doc", id: "dashboards/linechart", label: "Line Chart" }, - { type: "doc", id: "dashboards/areachart", label: "Area Chart" }, - { type: "doc", id: "dashboards/barchart", label: "Bar Chart" }, - { type: "doc", id: "dashboards/gauges", label: "Gauges" }, - { type: "doc", id: "dashboards/piechart", label: "Pie Chart" }, - { type: "doc", id: "dashboards/countcard", label: "Count Card" }, - { type: "doc", id: "dashboards/tablecard", label: "Table Card" }, - { type: "doc", id: "dashboards/valuecard", label: "Value Card" }, - { type: "doc", id: "dashboards/maps", label: "Maps" }, - { type: "doc", id: "dashboards/controls", label: "Controls" }, + { type: "doc", id: "user-guide/dashboards/dashboards", label: "Dashboard" }, + { type: "doc", id: "user-guide/dashboards/widgets", label: "Widgets" }, + { type: "doc", id: "user-guide/dashboards/linechart", label: "Line Chart" }, + { type: "doc", id: "user-guide/dashboards/areachart", label: "Area Chart" }, + { type: "doc", id: "user-guide/dashboards/barchart", label: "Bar Chart" }, + { type: "doc", id: "user-guide/dashboards/gauges", label: "Gauges" }, + { type: "doc", id: "user-guide/dashboards/piechart", label: "Pie Chart" }, + { type: "doc", id: "user-guide/dashboards/countcard", label: "Count Card" }, + { type: "doc", id: "user-guide/dashboards/tablecard", label: "Table Card" }, + { type: "doc", id: "user-guide/dashboards/valuecard", label: "Value Card" }, + { type: "doc", id: "user-guide/dashboards/maps", label: "Maps" }, + { type: "doc", id: "user-guide/dashboards/controls", label: "Controls" }, ], }, { type: "doc", - id: "rules-engine", + id: "user-guide/rules-engine", label: "Rules Engine", }, { type: "doc", - id: "profile-management/users", + id: "user-guide/profile-management/users", label: "Profile Management", }, ], devSidebar: [ - { type: 'doc', id: 'getting-started', label: 'Getting Started' }, + { type: 'doc', id: 'dev-guide/getting-started', label: 'Getting Started' }, { type: "category", label: "CLI", link: { type: "doc", - id: "cli/introduction-to-cli", + id: "dev-guide/cli/introduction-to-cli", }, collapsible: true, items: [ - { type: "doc", id: "cli/users-cli", label: "Users Management" }, - { type: "doc", id: "cli/groups-cli", label: "Groups Management" }, - { type: "doc", id: "cli/bootstrap-cli", label: "Bootstrap Management" }, - { type: "doc", id: "cli/consumers-cli", label: "Consumers Management" }, - { type: "doc", id: "cli/provision-cli", label: "Provisioning Management" }, + { type: "doc", id: "dev-guide/cli/users-cli", label: "Users Management" }, + { type: "doc", id: "dev-guide/cli/groups-cli", label: "Groups Management" }, + { type: "doc", id: "dev-guide/cli/bootstrap-cli", label: "Bootstrap Management" }, + { type: "doc", id: "dev-guide/cli/consumers-cli", label: "Consumers Management" }, + { type: "doc", id: "dev-guide/cli/provision-cli", label: "Provisioning Management" }, ], }, - { type: 'doc', id: 'entities', label: 'Entities' }, - { type: 'doc', id: 'api', label: 'API' }, + { type: 'doc', id: 'dev-guide/entities', label: 'Entities' }, + { type: 'doc', id: 'dev-guide/api', label: 'API' }, { type: "category", label: "Concepts", items: [ - { type: 'doc', id: 'authentication', label: 'Authentication' }, - { type: 'doc', id: 'authorization', label: 'Authorization' }, - { type: 'doc', id: 'security', label: 'Security' }, - { type: 'doc', id: 'messaging', label: 'Messaging' }, + { type: 'doc', id: 'dev-guide/authentication', label: 'Authentication' }, + { type: 'doc', id: 'dev-guide/authorization', label: 'Authorization' }, + { type: 'doc', id: 'dev-guide/security', label: 'Security' }, + { type: 'doc', id: 'dev-guide/messaging', label: 'Messaging' }, ], }, { type: "category", label: "Development Tools", items: [ - { type: "doc", id: "dev-guide", label: "Developers Guide" }, - { type: "doc", id: "events", label: "Events" }, - { type: "doc", id: "tracing", label: "Tracing" }, + { type: "doc", id: "dev-guide/dev-guide", label: "Developers Guide" }, + { type: "doc", id: "dev-guide/events", label: "Events" }, + { type: "doc", id: "dev-guide/tracing", label: "Tracing" }, ], }, { type: "doc", - id: "storage", + id: "dev-guide/storage", label: "Storage", }, { type: "doc", - id: "edge", + id: "dev-guide/edge", label: "Edge", }, { type: "doc", - id: "certs", + id: "dev-guide/certs", label: "Certs", }, { type: "doc", - id: "kubernetes", + id: "dev-guide/kubernetes", label: "Kubernetes", }, { type: "category", label: "Extensions", items: [ - { type: "doc", id: "lora", label: "LoRa" }, - { type: "doc", id: "opcua", label: "OPC-UA" }, - { type: "doc", id: "provision", label: "Provisioning" }, - { type: "doc", id: "twins", label: "Twins Service" }, - { type: "doc", id: "bootstrap", label: "Bootstrap" }, + { type: "doc", id: "dev-guide/lora", label: "LoRa" }, + { type: "doc", id: "dev-guide/opcua", label: "OPC-UA" }, + { type: "doc", id: "dev-guide/provision", label: "Provisioning" }, + { type: "doc", id: "dev-guide/twins", label: "Twins Service" }, + { type: "doc", id: "dev-guide/bootstrap", label: "Bootstrap" }, ], }, { type: "doc", - id: "benchmark", + id: "dev-guide/benchmark", label: "Test Spec", }, ],