admin/raven
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Browse Source
This commit is contained in:
John Cardinal
2018-06-28 23:41:48 +00:00
commit 515bd37952
256 changed files with 29890 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
docs/8.0/ayanova/docs/_placeholder.md Normal file
View File

@@ -0,0 +1,254 @@
# Placeholder
This is a placeholder page for sections that are not written yet
#STANDARDS FOR AYANOVA DOCS
All one or two # headings are all capse, three or more #'s are regular sentence case.
## Body copy
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras arcu libero,
mollis sed massa vel, *ornare viverra ex*. Mauris a ullamcorper lacus. Nullam
urna elit, malesuada eget finibus ut, ullamcorper ac tortor. Vestibulum sodales
pulvinar nisl, pharetra aliquet est. Quisque volutpat erat ac nisi accumsan
tempor.
**Sed suscipit**, orci non pretium pretium, quam mi gravida metus, vel
venenatis justo est condimentum diam. Maecenas non ornare justo. Nam a ipsum
eros. [Nulla aliquam](/) orci sit amet nisl posuere malesuada. Proin aliquet
nulla velit, quis ultricies orci feugiat et. `Ut tincidunt sollicitudin`
tincidunt. Aenean ullamcorper sit amet nulla at interdum.
## Headings
### The 3rd level
#### The 4th level
##### The 5th level
###### The 6th level
## Headings <small>with secondary text</small>
### The 3rd level <small>with secondary text</small>
#### The 4th level <small>with secondary text</small>
##### The 5th level <small>with secondary text</small>
###### The 6th level <small>with secondary text</small>
## Blockquotes
> Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum.
Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc
mauris, a ultricies libero efficitur sed. *Class aptent* taciti sociosqu ad
litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie
imperdiet consectetur.
### Blockquote nesting
> **Sed aliquet**, neque at rutrum mollis, neque nisi tincidunt nibh, vitae
faucibus lacus nunc at lacus. Nunc scelerisque, quam id cursus sodales, lorem
[libero fermentum](/) urna, ut efficitur elit ligula et nunc.
> > Mauris dictum mi lacus, sit amet pellentesque urna vehicula fringilla.
Ut sit amet placerat ante. Proin sed elementum nulla. Nunc vitae sem odio.
Suspendisse ac eros arcu. Vivamus orci erat, volutpat a tempor et, rutrum.
eu odio.
> > > `Suspendisse rutrum facilisis risus`, eu posuere neque commodo a.
Interdum et malesuada fames ac ante ipsum primis in faucibus. Sed nec leo
bibendum, sodales mauris ut, tincidunt massa.
### Other content blocks
> Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu
lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl,
sit amet laoreet nibh.
``` js hl_lines="8"
var _extends = function(target) {
for (var i = 1; i < arguments.length; i++) {
var source = arguments[i];
for (var key in source) {
target[key] = source[key];
}
}
return target;
};
```
> > Praesent at `:::js return target`, sodales nibh vel, tempor felis. Fusce
vel lacinia lacus. Suspendisse rhoncus nunc non nisi iaculis ultrices.
Donec consectetur mauris non neque imperdiet, eget volutpat libero.
## Lists
### Unordered lists
* Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus
non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci,
at elementum urna sodales vitae. In in vehicula nulla, quis ornare libero.
* Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
* Nam vulputate tincidunt fringilla.
* Nullam dignissim ultrices urna non auctor.
* Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut
eros sed sapien ullamcorper consequat. Nunc ligula ante, fringilla at aliquam
ac, aliquet sed mauris.
* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.
### Ordered lists
1. Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis
elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla
consectetur feugiat sodales.
2. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur
ridiculus mus. Aliquam ornare feugiat quam et egestas. Nunc id erat et quam
pellentesque lacinia eu vel odio.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed.
1. Mauris dictum mi lacus
2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Sed
aliquet, neque at rutrum mollis, neque nisi tincidunt nibh.
3. Pellentesque eget `:::js var _extends` ornare tellus, ut gravida mi.
``` js hl_lines="1"
var _extends = function(target) {
for (var i = 1; i < arguments.length; i++) {
var source = arguments[i];
for (var key in source) {
target[key] = source[key];
}
}
return target;
};
```
3. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo.
### Definition lists
Lorem ipsum dolor sit amet
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor
lobortis orci, at elementum urna sodales vitae. In in vehicula nulla.
Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.
Cras arcu libero
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante, fringilla at
aliquam ac, aliquet sed mauris.
## Code blocks
### Inline
Morbi eget `dapibus felis`. Vivamus *`venenatis porttitor`* tortor sit amet
rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
per inceptos himenaeos. [`Pellentesque aliquet quam enim`](/), eu volutpat urna
rutrum a.
Nam vehicula nunc `:::js return target` mauris, a ultricies libero efficitur
sed. Sed molestie imperdiet consectetur. Vivamus a pharetra leo. Pellentesque
eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus.
### Listing
#!js hl_lines="8"
var _extends = function(target) {
for (var i = 1; i < arguments.length; i++) {
var source = arguments[i];
for (var key in source) {
target[key] = source[key];
}
}
return target;
};
## Horizontal rules
Aenean in finibus diam. Duis mollis est eget nibh volutpat, fermentum aliquet
dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna
non auctor.
***
Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis
elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla
consectetur feugiat sodales.
## Data tables
| Sollicitudo / Pellentesi | consectetur | adipiscing | elit | arcu | sed |
| ------------------------ | ----------- | ---------- | ------- | ---- | --- |
| Vivamus a pharetra | yes | yes | yes | yes | yes |
| Ornare viverra ex | yes | yes | yes | yes | yes |
| Mauris a ullamcorper | yes | yes | partial | yes | yes |
| Nullam urna elit | yes | yes | yes | yes | yes |
| Malesuada eget finibus | yes | yes | yes | yes | yes |
| Ullamcorper | yes | yes | yes | yes | yes |
| Vestibulum sodales | yes | - | yes | - | yes |
| Pulvinar nisl | yes | yes | yes | - | - |
| Pharetra aliquet est | yes | yes | yes | yes | yes |
| Sed suscipit | yes | yes | yes | yes | yes |
| Orci non pretium | yes | partial | - | - | - |
Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus
non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci,
at elementum urna sodales vitae. In in vehicula nulla, quis ornare libero.
| Left | Center | Right |
| :--------- | :------: | ------: |
| Lorem | *dolor* | `amet` |
| [ipsum](/) | **sit** | |
Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu
lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl,
sit amet laoreet nibh.
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Table</th>
<th>with colgroups (Pandoc)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Lorem</td>
<td>ipsum dolor sit amet.</td>
</tr>
<tr>
<td>Sed sagittis</td>
<td>eleifend rutrum. Donec vitae suscipit est.</td>
</tr>
</tbody>
</table>

37
docs/8.0/ayanova/docs/api-console.md Normal file
View File

@@ -0,0 +1,37 @@
# 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.
You can access the api explorer console by navigating with your browser to this path on your AyaNova API server:
`/api-docs/`
For example if your AyaNova server were located on port 7575 of the local computer you would connect to it via this url:
`http://localhost:7575/api-docs/`
## Authentication
Most of the API endpoints in AyaNova require 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.
The "response body" section will contain the return value, something similar to this:
``` hl_lines="5"
{
"ok": 1,
"issued": 1518034370,
"expires": 1520626370,
"token": "xyGhbGciOiJIUzI1NiIsInR4cCI6IkpXVCJ9.utJpYXQ4OiIxNqE4MDM0MzcfIiwiZXhwjjoiMTUyMDYyNjM8MCIsImlocyI0IkF53U5vdmEiLCJpZCI6IjEifQ.z7QaHKt2VbcysunIvsfa-51X7owB1EYcyhpkdkfaqzy",
"id": 1
}
```
The highlighted line above contains the token 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 the word Bearer followed by a space and then your api token, for example using the above you would paste in:
`Bearer xyGhbGciOiJIUzI1NiIsInR4cCI6IkpXVCJ9.utJpYXQ4OiIxNqE4MDM0MzcfIiwiZXhwjjoiMTUyMDYyNjM8MCIsImlocyI0IkF53U5vdmEiLCJpZCI6IjEifQ.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.

25
docs/8.0/ayanova/docs/api-error-codes.md Normal file
View File

@@ -0,0 +1,25 @@
# API ERROR CODES
The AyaNova API will return an [error response](api-response-format.md#error-responses) when an error condition arises.
All API error codes are numbers between 2000 and 3000 and are intended to be consumed by software clients or for reference purposes for developers.
API error codes are different from [server error codes](ops-error-codes.md) which are intended for AyaNova system operators and related only to the running of the server itself.
Here are all the API level error codes that can be returned by the API server:
| CODE | MEANING |
| ----- | ------------------------------ |
| 2000 | API closed - Server is running but access to the API has been closed to all users |
| 2001 | API closed all non OPS routes - Server is running but access to the API has been restricted to only server maintenance operations related functionality |
| 2002 | Internal error from the API server, details in [server log](common-log.md) file |
| 2003 | Authentication failed, bad login or password, user not found |
| 2004 | Not authorized - current user is not authorized for operation attempted on the resource (insufficient rights) |
| 2005 | Object was changed by another user since retrieval (concurrency token mismatch) |
| 2010 | Object not found - API could not find the object requested |
| 2020 | PUT Id mismatch - object Id does not match route Id |
| 2030 | Invalid operation - operation could not be completed, not valid, details in message property |
| 2200 | Validation error - general top level indicating object was not valid, specifics in "details" property |
| 2201 | Validation error - Field is required but is empty or null |
| 2202 | Validation error - Field length exceeded |
| 2203 | Validation error - invalid value |

3
docs/8.0/ayanova/docs/api-intro.md Normal file
View File

@@ -0,0 +1,3 @@
# DEVELOPERS API
AyaNova REST API for developers

8
docs/8.0/ayanova/docs/api-request-format.md Normal file
View File

@@ -0,0 +1,8 @@
# API request format
AyaNova uses a RESTful API and supports the [JSON](https://www.json.org/) data interchange format exclusively.
No other data formats are supported, your code must supply and consume JSON formatted data.
All developer interaction with the AyaNova API is via the REST server interface only.
**TODO FILL THS OUT**

222
docs/8.0/ayanova/docs/api-response-format.md Normal file
View File

@@ -0,0 +1,222 @@
# API response format
AyaNova uses a RESTful API and supports the [JSON](https://www.json.org/) data interchange format exclusively.
No other data formats are supported, your code must supply and consume JSON formatted data.
All developer interaction with the AyaNova API is via the REST server interface only.
## Successful responses
### GET RESPONSE
All successful GET responses have a standard format:
```json
{
"Result": {
"id": 150,
"name": "Handmade Rubber Pizza",
...etc...
}
}
```
The results of the response are always contained in the `result` property and could be a single object, a collection or in some cases nothing at all.
HTTP Status Code is set in the header.
### GET COLLECTION RESPONSE
In the case of a collection most routes support paging, here is an example paged collection request and response:
Request (note the `offset` and `limit` parameters):
`http://localhost:3000/api/v8.0/Widget?Offset=2&Limit=3`
Limit must be a value between 1 and 100.
Response:
```json
{
"result": [
...collection...
],
"paging": {
"count": 2000,
"offset": 2,
"limit": 3,
"first": "http://localhost:3000/api/v8.0/Widget?pageNo=1&pageSize=3",
"previous": "http://localhost:3000/api/v8.0/Widget?pageNo=1&pageSize=3",
"next": "http://localhost:3000/api/v8.0/Widget?pageNo=3&pageSize=3",
"last": "http://localhost:3000/api/v8.0/Widget?pageNo=667&pageSize=3"
}
}
```
`Previous` or `next` properties will contain "null" instead of an url on boundaries where there is no record to link to.
### PUT RESPONSE
A successful PUT response does not return any data but returns HTTP status code 204 (no content) in the header.
**WARNING:** Be careful using PUT, you must provide **all** properties or any properties left out will be removed at the server. If you are updating a subset of properties use PATCH instead to save bandwidth.
### PATCH RESPONSE
Use PATCH to update specific properties only.
A successful PATCH response does not return any data but returns HTTP status code 204 (no content) in the header.
Patches must conform to the [JSONPATCH](http://jsonpatch.com/) standard.
### POST RESPONSE
A successful POST response contains the object posted with it's Id value set and the HTTP status code of 201 (created).
### DELETE RESPONSE
A successful DELETE response does not return any data but returns HTTP status code 204 (no content) in the header.
## Error responses
### Fundamental errors
Fundamental, basic errors return a header status code only and are generally self explanatory. For example if you attempt to use XML formatted data with the API you will receive an error response consisting only of the header 415 (unsuported media type).
401
In cases where authentication fails you will receive an empty body response with the header 401 (unauthorized) returned.
The details of what was wrong are contained in the header, here is an example of an invalid JWT authentication token:
```json
{
"content-length": "0",
"date": "Fri, 09 Mar 2018 16:46:07 GMT",
"server": "Kestrel",
"www-authenticate": "Bearer error=\"invalid_token\", error_description=\"The signature is invalid\"",
"content-type": null
}
```
### Error response object
All error responses that return data have an `Error` object property at top level. The error object varies in the properties it contains depending on the error.
Here is the most minimal error response that returns data:
```json
{
"Error": {
"Code": "2000",
"Message": "Developer readable error message"
}
}
```
An error object will always contain at minimum an [API error `Code`](api-error-codes.md) property for reference and a `message` property with descriptive text intended for developers.
### Validation error response object
Here is an example of a more detailed error response showing validation errors on a request:
```json hl_lines="4 "
{
"error": {
"code": "2200",
"details": [
{
"message": "255 max",
"target": "Name",
"error": "LengthExceeded"
},
{
"target": "EndDate",
"error": "RequiredPropertyEmpty"
},
{
"target": "Roles",
"error": "InvalidValue"
}
],
"message": "Object did not pass validation"
}
}
```
The above example shows multiple validation errors ([API error code](api-error-codes.md) 2200) in several properties when attempting to post an object.
`details` outer property contains the collection of all validation errors.
`target` property shows the location of the error. The value of `target` is either a property name corresponding to the property that failed business rule validation or blank if the validation rule applies to the entire object in general.
`error` property contains the exact [validation error](api-validation-error-codes.md).
`message` property optionally contains further information of use to the developer, in the example above you can see that the name property has more than the maximum limit of 255 characters.
### Concurrency error response object
AyaNova uses "optimistic concurrency" tracking. This means a concurrency token needs to accompany most change (PUT, PATCH) routes.
Objects that require concurrency tokens to update are the objects that return a `ConcurrencyToken` property on a GET request.
Every update to an object results in a new concurrency token for that object.
In a concurrency error response ([API error code](api-error-codes.md) 2005) and header HTTP code 409 (Conflict) is returned if a user attempts to update a record that was changed by another user since it was retrieved (outdated concurrency token provided).
Here is an example:
```json
{
"error": {
"code": "2005",
"message": "Object was changed by another user since retrieval (concurrency token mismatch)"
}
}
```
### Other errors response format
Errors not related to validation or concurrency may contain one or more nested `innerError` properties. Each nested `innererror` object represents a higher level of detail than its parent. When evaluating errors, clients MUST traverse through all of the nested `innererrors` and choose the deepest one that they understand.
Here is a sample error response with innererror set:
```json hl_lines="6 "
{
"error": {
"code": "1005",
"message": "Previous passwords may not be reused",
"target": "password",
"innererror": {
"code": "1006",
"innererror": {
"code": "1007",
"minLength": "6",
"maxLength": "64",
"characterTypes": ["lowerCase","upperCase","number","symbol"],
"minDistinctCharacterTypes": "2",
"innererror": {
"code": "1008"
}
}
}
}
}
```
Note that the contents of the `innererror` property may vary and contain distinct properties appropriate to the specific error condition.
### Server internal errors
Internal server errors are returned with an HTTP Status Code of 500 and an error object as follows:
```json
{
"error": {
"code": "2002",
"message": "See server log for details",
"target": "Server internal error"
}
}
```
For security reasons no details of an internal server exception are returned, you must examine the [server log](common-log.md) to see the details.
Generally this means the request triggered an unhandled exception which will be logged in detail to the log file.
Please report any internal server errors (preferrably with the log showing the exception details) to AyaNova support so we can look into it.

78
docs/8.0/ayanova/docs/api-upload-routes.md Normal file
View File

@@ -0,0 +1,78 @@
# API UPLOAD ROUTES
AyaNova has several API routes for uploading files.
These routes are all `POST` routes:
- `/api/v{version}/Attachment`
- `/api/v{version}/ImportAyaNova7`
- `/api/v{version}/Restore`
Upload routes are not testable from the API explorer.
Upload routes expect a form to be uploaded with file content disposition (multipart/form-data).
AyaNova will allow a maximum of 12gb per file upload for "Utility" routes such as restore and import routes.
User file routes such as attachments may have a smaller limit, see the User documentation section for those features for limit details.
Here is a sample minimal HTML form that works with AyaNova file routes:
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title></title>
<script src="https://code.jquery.com/jquery-3.2.1.min.js"
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
crossorigin="anonymous"></script>
<script type="text/javascript">
$(document).ready(function () {
$("#upload").click(function (evt) {
var fileUpload = $("#files").get(0);
var files = fileUpload.files;
var data = new FormData();
for (var i = 0; i < files.length; i++) {
data.append(files[i].name, files[i]);
}
//Attachment upload route requires further form data to designate
//the object being attached to by it's type and id:
//data.append('AttachToObjectType','2');
//data.append('AttachToObjectId','200');
$.ajax({
type: "POST",
url: "http://yourserver:7575/api/v8.0/Attachment",
headers: {
Authorization: "Bearer JWTTokenHere"
},
contentType: false,
processData: false,
data: data,
success: function (message) {
alert("upload successful!");
console.log(message);
},
error: function (error) {
console.log(error);
alert("There was an error uploading files!");
}
});
});
});
</script>
</head>
<body>
<form method="post" enctype="multipart/form-data">
<input type="file" id="files" name="files" multiple />
<input type="button" id="upload" value="Upload file(s)" />
</form>
</body>
</html>
```

14
docs/8.0/ayanova/docs/api-validation-error-codes.md Normal file
View File

@@ -0,0 +1,14 @@
# API VALIDATION ERROR CODES
All the validation error codes that can be [returned](api-response-format.md) by the API server.
In each case there may be more details in the `message` property where appropriate.
| CODE | MEANING |
| ----- | ------------------------------ |
| RequiredPropertyEmpty | Required property is missing or empty |
| LengthExceeded | A text property has more characters than are allowed. The limit will be returned in the `message` property of the validation error |
| NotUnique | A text property is required to be unique but an existing identical value was found in the database |
| StartDateMustComeBeforeEndDate | When an object requires a start and end date the start date must be earlier than the end date |
| InvalidValue | Generic error indicating an input object's property is not set correctly |
| ReferentialIntegrity | Indicates modifying the object (usually a delete) will break the link to other records in the database. The other records need to be modified before continuing |
| InvalidOperation | Indicates the operation is invalid, details provided in the `message` |

69
docs/8.0/ayanova/docs/common-log.md Normal file
View File

@@ -0,0 +1,69 @@
# LOGGING
AyaNova keeps a log of important events for troubleshooting purposes.
AyaNova logs to the file log-ayanova.txt.
Every Wednesday it archives the current log file to a numbered archive log file, for example log-ayanova-1.txt, log-ayanova-2.txt etc.
Any log older than 4 weeks is deleted permanently; 4 total logs are kept, which means a total of one month of logs are kept at any given time.
## INFORMATION SECURITY AND PRIVACY
By design and policy no personally identifiable information is intentionally gathered into log files.
User logins are logged in an anonymized way:
* AyaNova anonymizes IP addresses by masking the final segment of the address
* Passwords are not logged
* Users are logged as their internal id number not their name
Sometimes 3rd party tools may log to the log file and we may need to restrict them to conform to our privacy policy. If you find any personally identifiable information in a log file please advise us immediately at [support@ayanova.com](mailto:support@ayanova.com).
## Log path
By default AyaNova logs to a "logs" folder situated below the folder where AyaNova is started.
You can override this and set a custom log location by command line argument or by setting the "AYANOVA_LOG_PATH" environment variable.
Example command line log path parameter
`"dotnet run --AYANOVA_LOG_PATH=/home/gztw/Documents/temp/cmdlinelogs"`
If both a command line parameter and an environment variable are set the command line parameter takes precedence.
## Log level
AyaNova supports 6 levels of logging, the default level is "Info" which is a medium level and will log general operations and any errors or warnings that may arise.
**WARNING**
AyaNova server will run ***extremely slowly*** when setting a log level lower than Info. A very large amount of information is logged at Debug or lower levels and each item logged takes time away from the normal server operations. Unless directed to by technical support or attempting to diagnose a specific problem, you should avoid setting a log level lower than "Info".
You can set the log level via environment variable or command line parameter "AYANOVA_LOG_LEVEL".
For example from the command line
`"dotnet run --AYANOVA_LOG_LEVEL=Info"`
Below are listed the accepted values for log level from highest to lowest. A level logs everything at that level and above.
So, for example, "Trace" level will log the most and "Fatal" will log the least.
* `Fatal` - Critical errors that prevent AyaNova from running or force it to shut down. This setting results in the least amount of logging.
* `Error` - Logs all of the above plus errors that AyaNova can recover from and continue to operate.
* `Warn` - Logs all of the above plus issues that AyaNova can work around but should be looked into and are warnings to system operators.
* `Info` - Default level. Logs all the above levels plus normal behavior in low level of detail. Basic general operations are logged like startup and shutdown, configuration changes etc.
* `Debug` - Logs all the above plus every request to the server in detail and information about internal operations.
* `Trace` - Logs all the above plus highest level detail of internal program code operations. Useful primarily to AyaNova technical support to troubleshoot a specific issue, but too detailed for normal purposes.
## Troubleshooting logging
If you are having issues with logging you can enable a logger diagnostic log with a command line parameter or environment variable.
Enabling this setting will cause a log file named "log-ayanova-logger.txt" to be written to the folder AyaNova is started in.
Command line parameter
`-- AYANOVA_LOG_ENABLE_LOGGER_DIAGNOSTIC_LOG=true`
or set the environment variable
`AYANOVA_LOG_ENABLE_LOGGER_DIAGNOSTIC_LOG = true`
Warning: this diagnostic log should be disabled as soon as it's not required. Unlike the normal log, this log file is not automatically trimmed so it will grow in size forever.

BIN
docs/8.0/ayanova/docs/img/ayanovaicon48.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
docs/8.0/ayanova/docs/img/ayanovaicon60x60.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.0 KiB

BIN
docs/8.0/ayanova/docs/img/dbdump.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/8.0/ayanova/docs/img/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.3 KiB

BIN
docs/8.0/ayanova/docs/img/v8ServerMetricsDashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 675 KiB

BIN
docs/8.0/ayanova/docs/img/v8ServerMetricsSnapshotText.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

23
docs/8.0/ayanova/docs/index.md Normal file
View File

@@ -0,0 +1,23 @@
# WELCOME TO AYANOVA ![AyaNovaIcon](img/ayanovaicon60x60.png)
## About this documentation
This manual has the following sections:
- **User**
User manual and guide to AyaNova features
- **Operations**
Technical guide for installation and ongoing maintenance operations of AyaNova
- **Developer**
Guide for software developers to use the AyaNova REST interface
## Beyond this manual
If you have a question that is not answered in this manual contact AyaNova support directly: [support@ayanova.com](mailto:support@ayanova.com)
Or check out our support forum [https://forum.ayanova.com/](https://forum.ayanova.com/)

9
docs/8.0/ayanova/docs/intro.md Normal file
View File

@@ -0,0 +1,9 @@
# INTRODUCTION
How to use this help manual
## Searching
- one
- two
- three

33
docs/8.0/ayanova/docs/ops-config-db.md Normal file
View File

@@ -0,0 +1,33 @@
# DATABASE
AyaNova uses [PostgreSQL](https://www.postgresql.org/) as it's database server in all configurations, no other database is supported.
## Default connection string
If no connection string is specified AyaNova will use a default value: "Server=localhost;".
## Setting the connection string
AyaNova expects the connection string to be provided by an environment variable or command line parameter named:
`AYANOVA_DB_CONNECTION`
Example command line parameter:
`dotnet run --AYANOVA_DB_CONNECTION="Server=localhost;Database=MyAyaNovaDB;"`
Example environment variable:
Windows:
`set "AYANOVA_DB_CONNECTION=Server=localhost;Database=MyAyaNovaDB;"`
Linux:
`export AYANOVA_DB_CONNECTION="Server=localhost;Database=MyAyaNovaDB;"`
If both a command line parameter and an environment variable are set the command line parameter takes precedence.
## Default database
If no default database is specified AyaNova will use the default value: "AyaNova".

56
docs/8.0/ayanova/docs/ops-config-default-language.md Normal file
View File

@@ -0,0 +1,56 @@
# DEFAULT LANGUAGE / LOCALE SETTING
This setting controls the default language for text displayed to users in the AyaNova user interface.
Users can choose to override this setting in their user account by choosing an another language.
It will also be used for some messages that originate at the server and are not associated with a particular user where applicable.
## Default
If no language is specified or AyaNova can't find the language specified in the database then AyaNova defaults to English locale "en".
## Built in language values
In addition to user defined or customized languages, AyaNova comes with 4 "stock" languages built in and accepts a range of values for selecting the stock language.
You can use the ISO two letter country code or the English name of the language or that languages own name for the language.
Valid settings:
| LANGUAGE | VALID SETTINGS |
| ----- | ------------------------------ |
| English | "en", "English" |
| French | "fr", "French", "Français" |
| German | "de", "German", "Deutsch" |
| Spanish | "es", "Spanish", "Español" |
## Custom language values
AyaNova allows for customized languages and this setting should be the exact name of a custom locale that exists within AyaNova if not using a built in language.
## Setting
AyaNova expects the language setting to be provided by an environment variable or command line parameter named
`AYANOVA_DEFAULT_LANGUAGE`
The value specified should be a string containing one of the stock valid settings in the table above or the name of a custom locale, for example:
`French`
or
`AcmeWidgetsCustomLocale`
Example command line parameter
`dotnet run --AYANOVA_DEFAULT_LANGUAGE="ES"`
Example environment variable
Windows
`set "AYANOVA_DEFAULT_LANGUAGE=DE"`
Linux / MAC
`export AYANOVA_DEFAULT_LANGUAGE="MyCustomLocale"`
If both a command line parameter and an environment variable are set the command line parameter takes precedence.

41
docs/8.0/ayanova/docs/ops-config-environment-variables.md Normal file
View File

@@ -0,0 +1,41 @@
# ENVIRONMENT VARIABLES / COMMAND LINE ARGUMENTS LIST
Most of the AyaNova configuration is stored inside the database, however anything related to starting the server can not be stored in the database and so environment variables or command line parameters are used to control server start up settings.
These values can all be specified as an environment variable or as a command line parameter. In cases where both are specified, the command line parameter takes precedence.
## DATABASE
- [AYANOVA_DB_CONNECTION](ops-config-db.md)
## FILE STORAGE LOCATIONS
- [AYANOVA_FOLDER_BACKUP_FILES](ops-config-folder-backup-files.md)
- [AYANOVA_FOLDER_USER_FILES](ops-config-folder-user-files.md)
## LOGGING
- [AYANOVA_LOG_ENABLE_LOGGER_DIAGNOSTIC_LOG](common-log.md#troubleshooting-logging)
- [AYANOVA_LOG_LEVEL](common-log.md#log-level)
- [AYANOVA_LOG_PATH](common-log.md#log-path)
## LANGUAGE / LOCALE
- [AYANOVA_DEFAULT_LANGUAGE](ops-config-default-language.md)
## API
- [AYANOVA_USE_URLS](ops-config-use-urls.md)
- [AYANOVA_FOLDER_USER_FILES](ops-config-folder-user-files.md)
- [AYANOVA_FOLDER_BACKUP_FILES](ops-config-folder-backup-files.md)
## METRICS
- [AYANOVA_METRICS_USE_INFLUXDB](ops-metrics.md)
- [AYANOVA_METRICS_INFLUXDB_BASEURL](ops-metrics.md)
- [AYANOVA_METRICS_INFLUXDB_DBNAME](ops-metrics.md)
- [AYANOVA_METRICS_INFLUXDB_CONSISTENCY](ops-metrics.md)
- [AYANOVA_METRICS_INFLUXDB_USERNAME](ops-metrics.md)
- [AYANOVA_METRICS_INFLUXDB_PASSWORD](ops-metrics.md)
- [AYANOVA_METRICS_INFLUXDB_RETENSION_POLICY](ops-metrics.md)
- [AYANOVA_METRICS_INFLUXDB_CREATE_DATABASE_IF_NOT_EXISTS](ops-metrics.md)

35
docs/8.0/ayanova/docs/ops-config-folder-backup-files.md Normal file
View File

@@ -0,0 +1,35 @@
# BACKUP FILES FOLDER SETTING
This setting controls where AyaNova stores backup and restore files used by the backup and restore features built into AyaNova.
In addition this folder is used when importing from an AyaNova 7 export file.
Warning: this folder MUST NOT be the same location set for [AYANOVA_FOLDER_USER_FILES](ops-config-folder-user-files.md) or AyaNova will not start.
## Default
If no override is specified AyaNova will store backup files in a `backupfiles` folder in the AyaNova root folder where AyaNova is started from.
## Overriding
AyaNova expects the backup files folder path to be provided by an environment variable or command line parameter named
`AYANOVA_FOLDER_BACKUP_FILES`
The value specified should be a string containing a fully qualified file path for the platform, for example:
`c:\data\ayanova\backupfiles`
Example command line parameter
`dotnet run --AYANOVA_FOLDER_BACKUP_FILES="/var/lib/ayanova/backupfiles"`
Example environment variable
Windows
`set "AYANOVA_FOLDER_BACKUP_FILES=c:\data\ayanova\backupfiles"`
Linux / MAC
`export AYANOVA_FOLDER_BACKUP_FILES="/var/lib/ayanova/backupfiles"`
If both a command line parameter and an environment variable are set the command line parameter takes precedence.

35
docs/8.0/ayanova/docs/ops-config-folder-user-files.md Normal file
View File

@@ -0,0 +1,35 @@
# USER FILES FOLDER SETTING
This setting controls where AyaNova stores user uploaded files used by features that allow file attachment or uploads.
AyaNova stores these files with random names in the folder specified.
Warning: this folder MUST NOT be the same location set for [AYANOVA_FOLDER_BACKUP_FILES](ops-config-folder-backup-files.md) or AyaNova will not start.
## Default
If no override is specified AyaNova will store user files in a `userfiles` folder in the AyaNova root folder where AyaNova is started from.
## Overriding
AyaNova expects the user files folder path to be provided by an environment variable or command line parameter named
`AYANOVA_FOLDER_USER_FILES`
The value specified should be a string containing a fully qualified file path for the platform, for example:
`c:\data\ayanova\userfiles`
Example command line parameter
`dotnet run --AYANOVA_FOLDER_USER_FILES="/var/lib/ayanova/userfiles"`
Example environment variable
Windows
`set "AYANOVA_FOLDER_USER_FILES=c:\data\ayanova\userfiles"`
Linux / MAC
`export AYANOVA_FOLDER_USER_FILES="/var/lib/ayanova/userfiles"`
If both a command line parameter and an environment variable are set the command line parameter takes precedence.

36
docs/8.0/ayanova/docs/ops-config-use-urls.md Normal file
View File

@@ -0,0 +1,36 @@
# PORT / URL SETTING
You can control the port and URL that the AyaNova server will listen on via environment variable or command line parameter.
## Default
If no override is specified AyaNova will use the following default value:
`"http://*:7575"`
This means AyaNova will listen on port 7575
## Overriding
AyaNova expects the PORT and URL to be provided by an environment variable or command line parameter named
`AYANOVA_USE_URLS`
The value specified should be a string of one or more semicolon separated values, for example:
`http://*:5000;http://localhost:5001;https://hostname:5002`
Example command line parameter
`dotnet run --AYANOVA_USE_URLS="http://*:5000"`
Example environment variable
Windows
`set "AYANOVA_USE_URLS=http://*:5000"`
Linux / MAC
`export AYANOVA_USE_URLS="http://*:5000"`
If both a command line parameter and an environment variable are set the command line parameter takes precedence.

28
docs/8.0/ayanova/docs/ops-error-codes.md Normal file
View File

@@ -0,0 +1,28 @@
# SERVER ERROR CODES
AyaNova will provide a server error code when an error arises.
All AyaNova server error codes start with the letter E followed by a number in the range 1000-1999.
Server error codes are different from [API error codes](api-error-codes.md) which are intended for software and developers using the AyaNova developers API.
The purpose of these server error codes is to make it easier to look them up in this manual and easily communicate errors to technical support if necessary.
In most cases where an error occurs there will be more detailed information about the error in the [log file](common-log.md).
Here are all the error codes that can be returned by the AyaNova server:
| CODE | MEANING |
| ----- | ------------------------------ |
| E1000 | Could not connect to the database specified in the [connection string](ops-config-db.md). |
| E1010 | Could not find wwwRoot folder. AyaNova must be started from the folder immediately above wwwRoot. Generally the start folder should be the same folder as AyaNova.dll file. |
| E1012 | Missing resource folder. AyaNova was started from the wrong location or the resource folder was not installed properly. This is required to intialize a new AyaNova database |
| E1013 | Missing language resource file was deleted, renamed or not installed correctly. Resource language files are required to load into a new AyaNova database to display text in several languages for the user interface |
| E1015 | Missing language. One or more of the stock languages were not found in the database or a custom language specified in the config setting [AYANOVA_DEFAULT_LANGUAGE](ops-config-default-language.md) is missing from the database. Log will have details. |
| E1020 | Licensing related error. The message will contain the explanation |
| E1030 | AyaNova database failed an integrity check. Contact support immediately. |
| E1040 | File location [environment variables](ops-config-environment-variables.md) for backup files and user files were found to be the same location and must not be |
| E1050 | XXXXXXXX |
| E1060 | XXXXXXXX |
| E1070 | XXXXXXXX |
| E1080 | XXXXXXXX |
| E1090 | AyaNova failed to start due to an unexpected error during boot. |

64
docs/8.0/ayanova/docs/ops-import-v7.md Normal file
View File

@@ -0,0 +1,64 @@
# IMPORTING OLDER AYANOVA DATA
AyaNova 8+ can import data from AyaNova 7.5. For versions of AyaNova older than 7.5 you must first upgrade them to 7.5 before continuing.
## OVERVIEW
We have created a DBDump plugin for AyaNova 7.5 that will export the entire database into a universal format (JSON text files in a zip archive) that can be imported by AyaNova 8+.
Importing AyaNova 7.5 data is a two step process.
- Export data from AyaNova 7.5 using the DBDump plugin
- Import the export data into AyaNova 8 or above
## WARNINGS
### Do not rename the export file
AyaNova 8+ expects the export file to have a specific name format. For example: `ayanova.data.dump.2018-10-31--11-18-16.zip`.
If you rename the file AyaNova 8 may not recognize it as a valid DBDump file and will not offer it as an option for import.
The DBDump filename contains the date and time the export was started `ayanova.data.dump.YEAR-MONTH-DAY--HOUR-MINUTE-SECOND.zip`
### Repeated import not supported
Importing 7.5 data more than once to the same AyaNova 8+ database is not supported and could result in damage to data integrity.
Note that it's possible to import into a database more than once for test and evaluation purposes as long as you erase it before each import, however data should not be imported more than once into the same database without erasing it first to ensure data integrity.
In other words you cannot continue to work in both AyaNova 7.5 and AyaNova 8 at the same time and expect to export and import data repeatedly to keep them in "sync".
### Multi-user networked AyaNova 7.5
If other users are working in AyaNova when the DBDump plugin is run the resulting export file will not be valid as there could be records changed or missing that will be required to import. Be certain no other users are working in AyaNova before you run the DBDump.
Generator: Be sure to stop the AyaNova Generator *before* starting the DBDump plugin. Failing to do so could result in a corrupt export file as there could be records changed or missing that are required for import.
If you have a networked installation of AyaNova 7.5, when you are ready to transition to the newer version of AyaNova you will need to ensure that no other users are still working in AyaNova 7.5 after you do the final DBDump.
We recommend stopping the old database server immediately after the final DBDump in case there is a chance that there are still users inside or outside of your network that may access AyaNova 7.5.
### Before uninstalling AyaNova 7.5
Examine your imported data in AyaNova 8+; carefully ensure that the data you expect to see has been imported properly. You may still need to make another export in case of any issues that arise so it's not a good idea to immediately uninstall AyaNova 7.5 until you are sure the newer version of AyaNova has all your data in it and is ready for business.
We recommend keeping your AyaNova 7.5 installation for at least a month in case an issue comes up.
### Keep your last AyaNova 7.5 backup
We recommend you keep a backup copy of your AyaNova 7.5 database in a safe location for at least a year after transitioning to AyaNova 8+ in case any issues arise.
## EXPORT FROM AYANOVA 7.5
1. Avoid future problems: If you haven't already, go back and read the section titled "WARNINGS" above carefully.
2. [Download the DBDump plugin](https://ayanova.com/TODO) installer and run it on a computer with AyaNova 7.5 already installed and configured.
3. Pick an export location: Ensure you have enough free space in the location you are going to save the DBDump file to; you may require as much as double the space that your current AyaNova database is using.
4. Multi-user only: If exporting from a networked multi-user AyaNova 7.5 installation, now is the time to ensure all users are out and networked Generator service is stopped. **Do not proceed until this is verfied**.
5. Login to AyaNova 7.5 as the Manager account and select and run the "DBDump" plugin: ![DBDump](img/dbdump.png)
6. Select the location to save the dump file to from step 3 above.
7. A form will popup and show the progress of the DBDump operation and the name and location of the dump file. When completed a single .ZIP file will be created containing all the data that can be imported from AyaNova 7.5 in a format ready for import into AyaNova 8+. If this is your final export before moving to AyaNova 8+ you should keep a permanent copy of this file as a precaution.
## IMPORT TO AYANOVA 8+
TODO once we have UI

63
docs/8.0/ayanova/docs/ops-metrics.md Normal file
View File

@@ -0,0 +1,63 @@
# METRICS
AyaNova 8+ automatically tracks server metrics for ongoing server maintenance, monitoring and troubleshooting.
## OVERVIEW
Metrics are statistical and other information gathered automatically during server operation that can be used to assess the health of an AyaNova server.
This information is typically useful to the Operations staff who are responsible for maintaining the AyaNova server in good working condition.
When the AyaNova server is booted it starts gathering snapshots of statistical data during regular intervals that can be viewed to observe the current state of the server and some historical data from the point it was last rebooted.
Some examples of the metrics gathered include:
- Performance per API endpoint routes
- Error rates per HTTP error code and API endpoint route
- Transactions per endpoint
- Database records per table of significance
- Count and size of user files (attachments) stored at the server
- Count and size of operations files (backups, import/export etc) stored at the server
- Job operations data about background process jobs (notifications, backups, maintenance etc) running, succeeded and failed
- Memory usage of the server
- And more
## ROLES AND RIGHTS
Metrics are available to users with the `OPS - full` or `OPS - limited` roles.
## INFORMATION SECURITY AND PRIVACY
By design and policy no personally identifiable information is gathered for metrics. The data about API routes consists of consolidated information gathered over multiple users and does not track per IP address.
## VIEWING SNAPSHOT METRICS
View a current metrics snapshot directly on the server via the [API Explorer](api-console.md) tool:
![API Explorer](img/v8ServerMetricsSnapshotText.png)
TODO: VIEW METRICS IN AYANOVA CLIENT UI
## TAKING IT TO THE NEXT LEVEL - STORING METRICS AND VIEWING GRAPHICALLY
AyaNova has built in support to send metrics snapshots automatically to the open source time series database [InfluxDB](https://www.influxdata.com/) and can be viewed with the open source analytics and monitoring tool [Grafana](https://grafana.com/)
Example of a testing run of AyaNova during development visualized with Grafana and InfluxDB hosted in a Docker container:
![Grafana in Docker](img/v8ServerMetricsDashboard.png)
### Configuration settings for InfluxDB
Use of InfluxDB for metrics is controlled with [environment variables](ops-config-environment-variables.md) read during startup of the AyaNova server:
- `AYANOVA_METRICS_USE_INFLUXDB` true / false value, default is `false` set to `true` to turn on metrics reporting to InfluxDB
- `AYANOVA_METRICS_INFLUXDB_BASEURL` string value uri to your InfluxDB server default value is `http://127.0.0.1:8086`
- `AYANOVA_METRICS_INFLUXDB_DBNAME` string value name of database to use with InfluxDB server default value is `AyaNova`
- `AYANOVA_METRICS_INFLUXDB_CONSISTENCY` string value name of InfluxDB consistency policy to use with InfluxDB server default value is empty and not set
- `AYANOVA_METRICS_INFLUXDB_USERNAME` string value user name of account to connect to database default value is `root`
- `AYANOVA_METRICS_INFLUXDB_PASSWORD` string value password of account to connect to database default value is `root`
- `AYANOVA_METRICS_INFLUXDB_RETENSION_POLICY` string value name of InfluxDB retention policy to use with InfluxDB server default value is empty and not set
- `AYANOVA_METRICS_INFLUXDB_CREATE_DATABASE_IF_NOT_EXISTS` true / false value, default is `true` set to `true` to automatically create database in InfluxDB if it doesn't exist
### Setting up a Grafana dashboard
TODO: dashboard setup and mention of docker

40
docs/8.0/ayanova/mkdocs.yml Normal file
View File

@@ -0,0 +1,40 @@
theme:
name: 'material'
favicon: 'img/favicon.ico'
logo: 'img/ayanovaicon60x60.png'
palette:
primary: 'indigo'
accent: 'indigo'
site_name: AyaNova manual
site_dir: '../../../server/AyaNova/wwwroot/docs'
# Extensions
markdown_extensions:
- admonition
- codehilite:
guess_lang: false
- toc:
permalink: true
pages:
- Home: 'index.md'
- User guide:
- 'Introduction': 'intro.md'
- Operations guide:
- 'Installation': '_placeholder.md'
- 'Logging': 'common-log.md'
- 'Language / locale': 'ops-config-default-language.md'
- 'Backup files folder': 'ops-config-folder-backup-files.md'
- 'User files folder': 'ops-config-folder-user-files.md'
- 'Database configuration': 'ops-config-db.md'
- 'PORT and URL configuration': 'ops-config-use-urls.md'
- 'Environment variable reference': 'ops-config-environment-variables.md'
- 'Server error codes': 'ops-error-codes.md'
- 'Importing from older AyaNova': 'ops-import-v7.md'
- 'Metrics': 'ops-metrics.md'
- Developer guide:
- 'Introduction': 'api-intro.md'
- 'API developers console': 'api-console.md'
- 'API request format': 'api-request-format.md'
- 'API response format': 'api-response-format.md'
- 'API error codes': 'api-error-codes.md'
- 'API validation error codes': 'api-validation-error-codes.md'
- 'API upload routes': 'api-upload-routes.md'