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
2022-03-25 23:41:07 +00:00
parent f1a47293a7
commit 5d81b2ea92
3 changed files with 101 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/8.0/ayanova/docs/adm-import-customer.md
View File

@@ -133,7 +133,6 @@ The first Customer record here illustrates importing a Customer with a link to e
"Active": true,
"Notes": "Devolved asynchronous info-mediaries",
"Wiki": null,
"CustomFields": null,
"Tags": [
"zone7"
],

141
docs/8.0/ayanova/docs/adm-import.md
View File

@@ -1,7 +1,8 @@
# Import
The Import form is used to import new records *or* update existing records in AyaNova.
The Import form is used to import new records _or_ update existing records in AyaNova from a local import file.
For more advanced import or synchronization requirements use the [AyaNova developers API](api-intro.md).
## Authorization Roles required
@@ -15,58 +16,119 @@ Read only access
- Business administration - restricted
## How to access Import
From the `Administration` navigation pane select `Import` navigation item.
## Import file requirements
### File types supported
You can import / update from either JSON or CSV files.
Internally AyaNova only imports .json data so a .csv file is converted to json by the web app before sending it to the server for import.
### Import file format
Each supported object type that can be imported has it's format documented individually, click through the objects listed below to see the import file requirements.
Field names in .json or header row names in .csv files *must* match exactly in case and spelling the field names in each object type's specification document. Any other fields included will be removed by AyaNova before sending to the server for import.
CSV files must have a header row as the first row containing the specified field names. It's ok to omit any non-required fields.
#### Header row
CSV files must have the specified field names in the header row.
## Object types supported
Currently these types of AyaNova objects can be imported. Each item below links to the specific format and special notes about importing that specific object:
- [Customer specifications](adm-import-customer.md)
## How import works
Checkmarking "Import new records" indicates you want to **import** unmatched records into AyaNova.
AyaNova will attempt to match the import records to existing records in the AyaNova database by comparing the "key" field (identified in each objects import specifications). Usually the key field will be the `Name` field but in some casea may be another field that is the primary unique identifier for that record type.
The key field much match exactly, case and spelling matter.
If no existing record matches the key field then that record will be submitted to the business object `create` handler for validation and saving. This is the exact same process used when you manually edit and save a form in AyaNova which ensures all business and validation rules are checked.
If no errors are found then the record is saved into the database and a success message is added to the results list displayed in the Import form once import has completed.
If errors are found during validation no save is made and the error message is added to the results list displayed in the Import form once import has completed.
Non matching by key field specified, if not found (any difference in spelling or case) will attempt to import.
Uses same code as entering in form so any errors will be returned and are same as ones displayedin form for validation.
## How update works
Checkmarking "Update existing records" indicates you want to **update** matched records in AyaNova.
AyaNova will attempt to match the records in the import file to existing records in the AyaNova database by comparing the "key" field (identified in each objects import specifications). Usually the key field will be the `Name` field or whichever field is the primary unique identifier for that record type.
The key field much match exactly, case and spelling matter.
If an existing record matches the key field then that record will be submitted to the business object `update` handler for updating then validation and saving. This is the exact same process used when you manually edit and save a form in AyaNova which ensures all business and validation rules are checked.
All the fields provided in the import file will be used to replace the matching fields in the current business object in the database.
The key (usually `Name`) field can not be updated as it's used to match records.
### Partial updates
You may want to only partially update existing records in specific fields. AyaNova supports this by convention: only include fields you want updated.
Any fields that should remain untouched must **not** be included in the import file.
For example if you wanted to only update email addresses in Customers you would provide only the key field for matching (`Name`) and the `EmailAddress` fields in the import file.
All included fields are overwritten, so an empty or null field value in the import file will overwrite (remove) any data in the matching field in the existing record.
## Import files
### File types supported
You can import / update from either JSON or CSV files.
Internally AyaNova only imports .json data; a .csv file is converted to json format first by the web app before sending it to the AyaNova server for import.
### Import file format
Each supported object type that can be imported has it's import specification and examples documented individually, click through the objects listed below to see the import file specifications for each type.
Field names in .json or header row names in .csv files _must_ match exactly in case and spelling the field names in each object type's specification document. Any other fields included will be removed by AyaNova before sending to the server for import.
CSV files must have a header row as the first row containing the specified field names. It's ok to omit any non-required fields.
The order of the fields in JSON or CSV is not important.
#### Dates and times
Dates and times in the input files are assumed to be in UTC / GMT time zone.
#### Tags in CSV files
Tags in a CSV file must be a quoted comma separated string of tags like this: "blue,red,white".
A single tag doesn't require the comma, for example: "blue".
Tags in the import file that do not conform to the AyaNova [Tag format specification](ay-start-form-tags.md#tag-format) will be modified to fit within the specification.
#### CSV Header row
CSV files must have the specified field names in the header row.
#### CSV Parsing errors
When you select a .csv file to import the AyaNova web app will first attempt to convert it JSON format understood by the AyaNova server. If there are any errors when parsing in the CSV document they will be displayed in the results area of the import form indicating the line number in the csv file, and the error with that line.
To ensure the integrity of the data, import will _not_ be attempted if ther are _any_ csv parsing errors.
CSV parsing errors come form a utility and are not translated so they will be displayed in the English language only.
### Maximum file size
The actual limit on how many records can be imported / updated at once depends on many different things from individual browser limits, memory available, intermediate networking device and server configuration etc making it impossible to specify a limit.
As a rough guideline we recommend keeping the import file under 300kb in size to be safe.
## Can I import an AyaNova export file?
JSON export files created with the [Export extension](ay-ex-export.md) can be imported into AyaNova however not all fields exported are importable, any fields not found in the import specification will be ignored.
The export extension exports many more object types and includes more fields than the import process supports.
## Import specifications
The following listed types of AyaNova objects can currently be imported / updated in AyaNova.
Types not listed may be added in future; for needs beyond what is provided with the import feature, you can always import **any** data now into AyaNova via software written using the [AyaNova developers API](api-intro.md).
Each item below links to a page showing the specific format required for the import file and special notes about importing that specific object:
- [Customer specifications](adm-import-customer.md)
## Import form
### Menu options
00000000000000000000000000000000000000000000
Notes for docs:
Import new records - if checked will import any records that are not found to match by name
@@ -76,14 +138,11 @@ csv and json supported
csv must have first row headers which must match expected field names in order to map
Records are matched by primary identifier, usually "Name" field and must be unique
Field names must be the expected ones this means csv column headers as well as json property names, unrecognized fields will be thrown out and ignored
Each type of supported importable object's allowed fields and types is documented below
CSV will be converted to JSON before importing, if there are any errors in the CSV the import will not proceed and the results of the CSV parser's errors found will be displayed on the import page
CSV will be converted to JSON before importing, if there are any errors in the CSV the import will not proceed and the results of the CSV parser's errors found will be displayed on the import page
Errors from the parser are in English language only
Tags in CSV must be quotation delimited comma separated list of items like this: "blue,red,white", if it's only one tag then simply "blue" is fine

2
docs/8.0/ayanova/docs/api-intro.md
View File

@@ -2,7 +2,7 @@
AyaNova features a RESTful API that can be used by developers to integrate their applications with AyaNova.
The AyaNova user interface web application uses this same API for all access to AyaNova.
The AyaNova user interface web application uses this same API for all access to AyaNova so anything you can do in AyaNova you can do in code.
AyaNova comes with a [API explorer console](api-console.md) that can be used by developers to test and experiment with each API route without writing code and view the shape of the data.