diff --git a/docs/8.0/ayanova/docs/adm-users.md b/docs/8.0/ayanova/docs/adm-users.md index 5a6eda78..49e461de 100644 --- a/docs/8.0/ayanova/docs/adm-users.md +++ b/docs/8.0/ayanova/docs/adm-users.md @@ -4,23 +4,23 @@ The Users [form](ay-start-form-overview.md) is used to create and edit Users and ## Authorization Roles required -Many roles can *select* this object on other records where approriate. Editing or viewing this object in detail is only available to Users with the following [roles](ay-biz-admin-roles.md): +Many roles can _select_ this object on other records where approriate. Editing or viewing this object in detail is only available to Users with the following [roles](ay-biz-admin-roles.md): Full access -- Business administration +- Business administration Read only access -- Business administration - restricted +- Business administration - restricted ## How to access Users Users are accessed in the following ways: -- From the `Administration` [navigation drawer](ay-start-form-overview.md#navigation-drawer) `Users` item -- By clicking on the [open record icon](ay-start-form-autocomplete.md#opening-selected-record) in any User autocomplete list on any other form where users can be selected -- From any [data table](ay-start-form-data-tables.md) column showing a Users column +- From the `Administration` [navigation drawer](ay-start-form-overview.md#navigation-drawer) `Users` item +- By clicking on the [open record icon](ay-start-form-autocomplete.md#opening-selected-record) in any User autocomplete list on any other form where users can be selected +- From any [data table](ay-start-form-data-tables.md) column showing a Users column ## How Users work @@ -50,12 +50,16 @@ Also, for security purposes it is important that each User have their own accoun ## Users data table +![table](img/adm-users.png) + The Users [data table](ay-start-form-data-tables.md) lists all the Users in AyaNova and provides data table [common menu options](ay-start-form-data-tables.md#common-menu-options). In addition there is a `Direct notification` menu option that is the multiple user version of the single user [direct notification](#direct-notification) feature provided to notify multiple users at once. ## User edit form +![edit form](img/adm-users-edit-user-tab.png) + The User edit form contains all the [standard edit form](ay-start-edit-forms.md) functionality plus the following: ### Fields @@ -110,28 +114,6 @@ This read only field shows the most recent date and time this User logged in. The active field controls whether a User is enabled in AyaNova. Inactive Users can not log in and their name is not offered in selection lists for new records by default. -### Menu options - -#### Direct notification - -Send a direct Notification message to this User. This differs from a Memo in that it will trigger an alert for them (the bell icon at the top of the AyaNova user interface) and is useful when you have an urgent message to send. - -#### Send password reset email - -Initiate a password reset process for this User. - -When a user forgets their password or a new User has just been created and you want them to set their own password to get started, use this link to send the User a temporary access link to AyaNova so they can set their password and login name themselves. - -Note that it requires the User to have a valid email address set in the settings tab. - -#### Scheduled Users - -If this User is a scheduleable type, this menu option is a shortcut to the work order item scheduled users data table filtered to show only _this_ User's records. - -#### Labors - -If this User is a scheduleable type, this menu option is a shortcut to the work order item labor data table filtered to show only _this_ User's records. - ##### Revoking access and locking out Users Only active Users can login. If a User is set to inactive their authentication token is immediately revoked and even if they are currently logged in they will be logged out the moment they attempt any operation in AyaNova that needs to connect with the server or when the web application attempts to connect behind the scenes to check for notifications as it periodically does. @@ -152,4 +134,32 @@ In addition some notifications can be filtered by tag as required. ### User settings tab -This section is a duplicate of the [User settings](home-user-settings.md) form available to all logged in users. This tab is provided for and Administrator to edit or set up Users in advance. +![edit form settings tab](img/adm-users-edit-user-settings-tab.png) + +This section is a duplicate of the [User settings](home-user-settings.md) form available to all logged in users. + +This tab is provided as a convenience for an Administrator when first creating a new User or to help a User with their settings. + +### Menu options + +![edit form menu](img/adm-users-edit-menu.png) + +#### Direct notification + +Send a direct Notification message to this User. This differs from a Memo in that it will trigger an alert for them (the bell icon at the top of the AyaNova user interface) and is useful when you have an urgent message to send. + +#### Send password reset email + +Initiate a password reset process for this User. + +When a user forgets their password or a new User has just been created and you want them to set their own password to get started, use this link to send the User a temporary access link to AyaNova so they can set their password and login name themselves. + +Note that it requires the User to have a valid email address set in the settings tab. + +#### Scheduled Users + +If this User is a scheduleable type, this menu option is a shortcut to the work order item scheduled users data table filtered to show only _this_ User's records. + +#### Labors + +If this User is a scheduleable type, this menu option is a shortcut to the work order item labor data table filtered to show only _this_ User's records. diff --git a/docs/8.0/ayanova/docs/api-console.md b/docs/8.0/ayanova/docs/api-console.md index efcce48a..c86ae783 100644 --- a/docs/8.0/ayanova/docs/api-console.md +++ b/docs/8.0/ayanova/docs/api-console.md @@ -1,6 +1,24 @@ # API explorer console -The AyaNova server uses [Swagger-ui](https://www.swagger.io) to provide an interactive live api explorer and documentation console for developers to learn about and experiment with the AyaNova REST API. +![api console](img/api-console.png) + +The AyaNova server uses [Swagger-ui](https://www.swagger.io) to provide an interactive live API explorer and documentation console for developers to learn about and experiment with the AyaNova REST API. + +## WARNING + +**BEWARE** This console operates on the **live** data on your server! If you are experimenting, particularly with routes that modify data, we highly recommend installing a separate [trial version](ay-evaluate.md) of AyaNova just for experimentation purposes. + +## How to access the API explorer console + +There are two ways to access your AyaNova server's API explorer console: + +### From the server api 'meta' page + +![server home](img/api-server-meta-page-console.png) + +You can select the option to open the console from the servers api meta page pictured above, append `/api/v8/` to your server url to access this page. + +### Directly by address You can access the api explorer console by navigating with your browser to this path on your AyaNova API server: `/api-docs/` @@ -12,7 +30,7 @@ Using this console you can see real working examples of exactly what is required ## Authentication -Most of the API endpoints in AyaNova require a [JSON web token](https://jwt.io/introduction/) authentication to use them. The API console supports the ability to set a authorization token so you can fully test all routes. +Most of the API endpoints in AyaNova require a [JSON web token](https://jwt.io/introduction/) authentication to use them. The API console supports the ability to set a authorization token so you can fully test all routes. To obtain a token expand the "Auth" route in the main console and enter a value for login and password and click on the "Try it out" button to obtain an API token. @@ -20,20 +38,30 @@ The "response body" section will contain the return value, something similar to ```json hl_lines="5" { - "ok": 1, - "issued": 1518034370, - "expires": 1520626370, - "token": "xyGhbGciOiJIUzI1NiIsInR4cCI6IkpXVCJ9.utJpqE4MDM0............fQ.z7QaHKt2VbcysunIvsfa-51X7owB1EYcyhpkdkfaqzy", - "id": 1 + "ok": 1, + "issued": 1518034370, + "expires": 1520626370, + "token": "xyGhbGciOiJIUzI1NiIsInR4cCI6IkpXVCJ9.utJpqE4MDM0............fQ.z7QaHKt2VbcysunIvsfa-51X7owB1EYcyhpkdkfaqzy", + "id": 1 } ``` -The highlighted line above contains the token (shortened for illustration) you require, copy the token *value* not including the quotation marks. This is your access token. +The highlighted line above contains the token (shortened for illustration) you require, copy the token _value_ not including the quotation marks. This is your access token. -Click on the "Authorize" button at the top of the API console and a popup dialog box will open. In the "Value" box the dialog enter your api token, for example using the above you would paste in: +Click on the "Authorize" button at the top of the API console and a popup dialog box will open. In the "Value" box the dialog enter your api token, for example using the above you would paste in: `xyGhbGciOiJIUzI1NiIsInR4cCI6IkpXVCJ9.utJpqE4MDM0............fQ.z7QaHKt2VbcysunIvsfa-51X7owB1EYcyhpkdkfaqzy` then click on the "Authorize" button inside the popup dialog box. You have now saved your credentials (until you close or reload this browser window) and can access any of the API endpoints in this test console you have permission to access with the credentials you supplied earlier. + +### Use web app JWT + +It can sometimes be useful as a developer to be able to simultaneously use the AyaNova UI and the developers console with the same account logged in. + +To do this login with the web app as normal but with the web browser developer console open and in the browser's developer console "Network" tab copy the JWT token being sent in the Request Header and paste that into the AyaNova API explorer Authorization dialog. + +This avoids the issue with a login invalidating prior JWT issued to the same User account. + +![web app JWT](img/api-console-jwt-web-app.png) diff --git a/docs/8.0/ayanova/docs/img/adm-users-edit-menu.png b/docs/8.0/ayanova/docs/img/adm-users-edit-menu.png new file mode 100644 index 00000000..632ab9bf Binary files /dev/null and b/docs/8.0/ayanova/docs/img/adm-users-edit-menu.png differ diff --git a/docs/8.0/ayanova/docs/img/adm-users-edit-user-settings-tab.png b/docs/8.0/ayanova/docs/img/adm-users-edit-user-settings-tab.png new file mode 100644 index 00000000..4eed9a73 Binary files /dev/null and b/docs/8.0/ayanova/docs/img/adm-users-edit-user-settings-tab.png differ diff --git a/docs/8.0/ayanova/docs/img/adm-users-edit-user-tab.png b/docs/8.0/ayanova/docs/img/adm-users-edit-user-tab.png new file mode 100644 index 00000000..ed2bc1cf Binary files /dev/null and b/docs/8.0/ayanova/docs/img/adm-users-edit-user-tab.png differ diff --git a/docs/8.0/ayanova/docs/img/adm-users.png b/docs/8.0/ayanova/docs/img/adm-users.png new file mode 100644 index 00000000..9899d343 Binary files /dev/null and b/docs/8.0/ayanova/docs/img/adm-users.png differ diff --git a/docs/8.0/ayanova/docs/img/api-console-jwt-web-app.png b/docs/8.0/ayanova/docs/img/api-console-jwt-web-app.png new file mode 100644 index 00000000..a00f4a03 Binary files /dev/null and b/docs/8.0/ayanova/docs/img/api-console-jwt-web-app.png differ diff --git a/docs/8.0/ayanova/docs/img/api-console.png b/docs/8.0/ayanova/docs/img/api-console.png new file mode 100644 index 00000000..7ede4d91 Binary files /dev/null and b/docs/8.0/ayanova/docs/img/api-console.png differ diff --git a/docs/8.0/ayanova/docs/img/api-server-meta-page-console.png b/docs/8.0/ayanova/docs/img/api-server-meta-page-console.png new file mode 100644 index 00000000..4a65b6e3 Binary files /dev/null and b/docs/8.0/ayanova/docs/img/api-server-meta-page-console.png differ