Standard entitások adatmodellje

A visszatérési érték a következő alap mezőket tartalmazza:

{
   "result": "ok",
   "type": "ENTITYTYPE",
   "data": [],
   "errors": [],
   "missingRoles": [],
   "operations": {}
}

Ezekből a következő mezők megléte opcionális:

• data
• errors
• missingRoles
• operations

Amennyiben a művelet sikeres volt:

• a result mező értéke “ok”
• az errors és missingRoles listák üresek
• nem listázó művelet esetén a data.entity-ben lévő mező szintű errors listák üresek

Amennyiben valamilyen probléma történt:

• a result mező értéke “error”
• az errors lista tartalmazza a felmerült entitás szintű problémákat
• nem listázó művelet esetén a data.entity-ben lévő mező szintű errors listák tartalmazzák a felmerült problémákat mezőkre bontva
• amennyiben jogosultság probléma volt, a missingErrors listában találhatók a hiányzó jogosultságok

type

A típus a visszaadott adat típusát (a “data” mező) határozza meg. Egy konkrét API hívás esetén ez az érték nem változik, azaz már az API hívásakor tudni lehet, hogy milyen típusú adat fog szerepelni a data mezőben.

Ez az ENTITY entitás esetén lehet:

• ENTITY
  • egy ENTITY entitás található a data mezőben
• ENTITY[]
  • egy ENTITY entitás lista található a data mezőben
• ENTITYMilestone
  • egy ENTITY entitás egy mérföldköve található a data mezőben
• ENTITYMilestone[]
  • egy ENTITY entitás mérföldköveinek listája található a data mezőben
• ENTITYChangeLog
  • egy ENTITY entitás naplója található a data mezőben
• ENTITYChangeLog[]
  • egy ENTITY entitás módosítás naplóinak listája található a data mezőben

data

Ez a search műveletek esetén egy entitás lista, minden más esetén egy konkrét entitás.

Egy entitás alap struktúrája:

   "data": {
       "entityLoaded": "fully",
       "entity": {
           "id": {
               "value": "scr_6197958773047296"
           },
           "idEnd": {
               "value": "6197958773047296"
           },
           "field1": {
               "value": "2021-02-22T13:59:07+00:00",
               "errors": [],
               "warnings": []
           },
           "field2": {
               "value": "",
               "errors": [],
               "warnings": [],
               "editable": 1,
               "validation": []
           },
           "field3": {
               "value": 10,
               "errors": [],
               "warnings": [],
               "editable": 1,
               "validation": [
                   {
                       "validator": "number",
                       "level": "error"
                   }
               ]
           }
           ...
       },
       "entityOperations": {
           "access": 1,
           "select": 0,
           "edit": 1,
           "activate": 0,
           "archive": 1,
           "trash": 1,
           "lock": 1,
           "unlock": 0,
           "delete": 0,
           "restore": 1,
           "viewChangeLogs": 1,
           "viewMilestones": 1,
           "addMilestone": 1,
           "editMilestone": 1
       }
   },

entityLoaded

Megmondja, hogy be lett-e töltve az adatbázisból az entitás, illetve ha igen, akkor azt, hogy minden adat be lett-e töltve.

• fully
  • minden adat be lett töltve
• partially
  • csak részben lett betöltve, tipikusan a search műveletek esetén fordul elő, amikor nem kell minden adatot visszaadnia az API-nak
• none
  • nem lett betöltve, általában unaccessible vagy missingRoles hiba esetén fordul elő

entity

Magának az entitásnak az adatai. A következő mező szerepel minden esetben:

• id
  • az azonosító, amit az API-nak kell küldeni

Emellett megjelenhetnek opcionálisan a következő mezők, az adott API hívástól és a user konkrét jogaitól függően:

• createdAt
  • datetime, statikus
  • mikor lett létrehozva
• createdBy
  • string, statikus
  • ki hozta létre
• lastModAt
  • datetime, statikus
  • mikor lett utoljára szerkesztve
• lastModBy
  • string, statikus
  • ki szerkesztette utoljára
• shortDescription
  • string
  • rövid leírás
• techComment
  • string
  • technikai megjegyzés
• weight
  • number
  • súly, amit a rendezésnél, illetve néhány esetben a tartalom generáláskor kell felhasználni
• status
  • number, statikus
  • az elem státusza
    • 0: aktív
    • 3: archív
    • 9: trashed
  • közvetlenül nem szerkeszthető, csak a megfelelő művelet elindításával
• warningCount
  • number, statikus
  • hány warning van összesen
• usageCount
  • number, statikus
  • összesen hány tartalom használja az adott entitást
• locked
  • number, statikus
  • zárolva van-e az entitás
    • 0: fel van oldva
    • 1: zárolt
  • közvetlenül nem szerkeszthető, csak a megfelelő művelet elindításával
• visible
  • number
  • látható-e az entitás
    • 0: rejtett
    • 1: látható
• editable
  • number
  • szerkeszthető-e az entitás
    • 0: nem szerkeszthető
    • 1: szerkeszthető

Minden más mező az entitástól és az adott user jogaitól függ.

A fenti mezőket a konkrét entitások dokumentációi már nem fogják külön tartalmazni, azonban azt jelezni fogják, ha ezek a mezők is hozzátartoznak az adatmodellhez!

Egy mező tipikus formátuma

            "field": {
               "value": 10,
               "warnings": [],
               "editable": 1,
               "validation": [
                   {
                       "validator": "number",
                       "level": "error"
                   }
               ]
           }

• value
  • a mező adata, string vagy number lehet
• warnings
  • opcionális
  • azoknak a validátoroknak a listája, ami warning szintű hibát generáltak az utolsó módosításkor az adott mezőn
  • formátumban azonos a válasz errors mezejében található adatokkal (lásd lentebb)
  • warning esetén megtörténik a módosítás, de megjelöli a rendszer, hogy valamit még csinálni kellene az adott mezővel
• errors
  • opcionális
  • azoknak a validátoroknak a listája, ami error szintű hibát generáltak az utolsó módosításkor az adott mezőn
  • formátumban azonos a válasz errors mezejében található adatokkal (lásd lentebb)
  • error esetén nem történik meg a módosítás, de a visszaadott mező value-jában az az érték található, ami a mentéskor az adatbázisba kerülne
• editable
  • opcionális
  • megadja, hogy az adott user tudja-e az adott mezőt szerkeszteni
  • ha nem adja vissza az API a mezőt, akkor 0 az érték, ez tipikusan azoknál a mezőknél van, amiket soha nem lehet szerkeszteni, például az id
• validation
  • opcionális
  • az adott mezőre érvényes validátorok listája
  • ezek fognak minden módosításkor lefutni
  • a validátorban található “level” mondja meg, hogy milyen szintű hibát fog generálni a validátor

Példák entitás adatokra a fenti nagy json objektumban:

• field1
  • egy statikus adat mező, amit nem lehet szerkeszteni
• field2
  • egy szerkeszthető mező, amire nincsenek validátorok meghatározva
• field3
  • egy szerkeszthető mező, amire meg vannak validátorok határozva

egyszerű lista típusú mezők formátuma

Az egyszerű listák esetén ugyanaz a formátuma, mint a normál mezők esetén, csak a value mező értéke egy string tömb lesz.

Tipikus használata olyan esetekben, amikor például string-ek listáját kell eltárolni (például tag-ek vagy azonosítók, mint például a UserRole entitás esetén).

struktúrált lista típusú mezők formátuma

Ebben az esetben is hasonló a struktúra, mint a normál mezőknél, de a value mező egy belső struktúrát tartalmaz:

    "fieldName": {
        "value": {
            "items": [
                {
                    "key": {
                        "value": "k1",
                        "warnings": [],
                        "errors": [],
                        "editable": 1,
                        "validation": [
                            {
                                "validator": "required",
                                "level": "error",
                                "param1": null
                            }
                        ]
                    },
                    "value": {
                        "value": "v1",
                        "warnings": [],
                        "errors": [],
                        "editable": 1,
                        "validation": [
                            {
                                "validator": "required",
                                "level": "warning",
                                "param1": null
                            }
                        ]
                    }
                },
                {
                    "key": {
                        "value": "k2",
                        "warnings": [],
                        "errors": [],
                        "editable": 1,
                        "validation": [
                            {
                                "validator": "required",
                                "level": "error",
                                "param1": null
                            }
                        ]
                    },
                    "value": {
                        "value": "",
                        "warnings": [
                            {
                                "validator": "required",
                                "param1": null,
                                "actual": ""
                            }
                        ],
                        "errors": [],
                        "editable": 1,
                        "validation": [
                            {
                                "validator": "required",
                                "level": "warning",
                                "param1": null
                            }
                        ]
                    }
                }
            ],
            "new": {
                "key": {
                    "validation": [
                        {
                            "validator": "required",
                            "level": "error",
                            "param1": null
                        }
                    ]
                },
                "value": {
                    "validation": [
                        {
                            "validator": "required",
                            "level": "warning",
                            "param1": null
                        }
                    ]
                }
            }
        }
    }

A belső struktúrának két mezeje van:

• items
  • egy tömb, amiben a konkrét elemek találhatók. Az egyes elemek egy beágyazott entitásként vannak kezelve, emiatt ugyanúgy néz ki a struktúrájuk, mint az alap entitásoknak, azaz minden mezőhöz megvannak a megfelelő értékek, például a validálási szabályok.
• new
  • ebben egy, az items tömbben szereplő entitásokkkal azonos struktúrájú entitás található, aminek kizárólag a validálási szabályai jelennek meg.
  • gyakorlatilag ebből le lehet kérni, hogy egy új elem hozzáadásakor milyen validálási szabályok fognak lefutni

entityOperations

Megadja, hogy az adott user az adott entitáson milyen műveleteket tud végrehajtani.

Ezek figyelembe veszik az entitás aktuális állapotát, például:

• zárolt entitást csak feloldani lehet
• aktív entitást nem lehet aktiválni
• csak kukázott entitást lehet véglegesen törölni

• ...

• access
  • eléri-e az entitás funkcióit
• select
  • listázhatja-e az entitást más entitások miatt
• edit
  • tudja-e szerkeszteni
• activate
  • tudja-e aktiválni
• archive
  • tudja-e archiválni
• trash
  • tudja-e kukázni
• lock
  • tudja-e zárolni
• unlock
  • fel tudja-e oldani
• delete
  • tudja-e törölni
• restore
  • visszaállíthatja-e az entitást egy korábbi mérföldkőre
• viewChangeLogs
  • láthatja-e egy entitás módosítási naplóit
• viewMilestones
  • láthatja-e egy entitás mérföldköveit
• addMilestone
  • létrehozhat-e egy új mérföldkövet
• editMilestone
  • módosíthat-e egy mérföldkövet

errors

Az errors listában validátorok vannak felsorolva, amik hibát találtak a művelet során.

Az alap formátum:

   "errors": {
       "FIELD": [
           {
               "validator": "VALIDATORNAME",
               "actual": "ACTUALVALUE"
           }
       ]
   }

A validátor “actual” mezeje nem minden esetben szerepel az adatok között.

A mező, amihez egy hiba tartozhat:

• entity
• milestoneentity

Egy mezőhöz több error is tartozhat, amennyiben több validátor is error szintű hibát generált.

Az “entity” szintű hibák a következők lehetnek:

• unaccessible
  • nem létezik az entitás, amin a műveletet akarja az API végrehajtani
• missingRole
  • jogosultság hibába futott a rendszer, ebben az esetben a hiányzó jogok a válasz missingRoles listájában lehetnek
• unknownOperation
  • ismeretlen műveletet próbál végrehajtani az API

A restore művelet esetén szerepelhet a “milestoneentity” mező is, amennyiben a megadott milestone nem létezik, és emiatt azon egy unaccessibble error generálódik.

A normál mezőkön a validátorok lehetnek például (nem teljes lista):

• required
• unique
• integer
• minLength
• maxLength
• ...

missingRoles

Ez egy egyszerű string lista, amiben a hiányzó jogok nevei szerepelnek.

Erre jelenleg debug miatt van szükség, amennyiben nyomozni kell, hogy egy adott műveletet miért nem enged az API végrehajtani.

operations

Az operation mező definiálja, hogy milyen műveleteket tud az adott user általában az adott entitás típuson végrehajtani.

   "operations": {
       "access": 1,
       "select": 1,
       "listIfActive": 1,
       "listIfArchived": 1,
       "listIfTrashed": 1,
       "listIfVisible": 1,
       "listIfInvisible": 1,
       "listIfLocked": 1,
       "listIfUnlocked": 1,
       "editIfEditable": 1,
       "editIfReadonly": 1,
       "activate": 1,
       "archive": 1,
       "trash": 1,
       "lock": 1,
       "unlock": 1,
       "delete": 1,
       "restore": 1,
       "add": 1,
       "viewChangeLogs": 1,
       "viewMilestones": 1,
       "addMilestone": 1,
       "editMilestone": 1,
       "viewWeight": 1,
       "viewVersionMeta": 1
   }

Mivel ezek általános jogokat határoznak meg, így nincs egyetlen entitás állapota sem figyelembe véve.

• access
  • eléri-e az entitás funkcióit
• select
  • listázhatja-e az entitást más entitások miatt
• listIfActive
  • tudja-e listázni az aktív entitásokat
• listIfArchived
  • tudja-e listázni az archív entitásokat
• listIfTrashed
  • tudja-e listázni a kukázott entitásokat
• listIfVisible
  • tudja-e listázni a látható entitásokat
• listIfInvisible
  • tudja-e listázni a rejtett entitásokat
• listIfLocked
  • tudja-e listázni a zárolt entitásokat
• listIfUnlocked
  • tudja-e listázni a feloldott entitásokat
• editIfEditable
  • tudja-e szerkeszteni a szerkeszthető entitásokat
• editIfReadonly
  • tudja-e szerkeszteni a nem szerkeszthető entitásokat
• activate
  • tud-e aktiválni egy entitást
• archive
  • tud-e archiválni egy entitást
• trash
  • tud-e kukázni egy entitást
• lock
  • tud-e zárolni egy entitást
• unlock
  • fel tud-e oldani egy entitást
• delete
  • tud-e törni egy entitást
• restore
  • visszaállíthatja-e az entitást egy korábbi mérföldkőre
• add
  • létrehozhat-e egy új bejegyzést
• viewChangeLogs
  • láthatja-e egy entitás módosítási naplóit
• viewMilestones
  • láthatja-e egy entitás mérföldköveit
• addMilestone
  • létrehozhat-e egy új mérföldkövet
• editMilestone
  • módosíthat-e egy mérföldkövet
• viewWeight
  • láthatja-e a weight mezőt
• viewVersionMeta
  • láthatja-e a version meta mezőket
  • createdAt
  • createdBy
  • lastModAt
  • lastModBy