Login

Try consentmanager
Book a call

Allmän API: Åtgärdstyper

preauth

För att autentisera en användare, vänligen fråga efter åtgärdstyp preauth . Skicka användarnamnet tillsammans med din begäran så får du information om huruvida användaren behöver logga in med lösenord och/eller tvåfaktorsautentisering eller om en omdirigering till en tredjepartsserver (SAML/OAuth) är nödvändig.

Exempel på indata:

{
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username  
  "api_key":    ""         //API-Key
}

Exempel på översättning:

{
  ...
  "data":
  {
    "sso_type":          0/1/2/3,
    "sso_redirect":      "https://...",
    "twofactor_type":     0/1/2/3,
    "twofactor_required": true|false
  }
}

Svaret innehåller följande information:

Fält Beskrivning
sso_type

Typ av Single-Sign-On:

0: Ingen 2FA

1: LDAP

2: SAML

3: OAuth
sso_redirect URL för omdirigering av användaren (används med SAML + OAuth)
twofactor_type

Typ av tvåfaktorautentisering

0: Ingen 2FA

1: OTP

2: E-post

3: SMS
twofactor_required Om en andra faktor krävs eller inte (alla tvåfaktortyper, utom 0)

Obs: När en sso_redirect URL finns måste du vidarebefordra användaren till SSO-slutpunkten för autentisering. När användaren återvänder kan du fortsätta med nästa autentiseringssteg.

Obs: I de fall då e-post eller SMS används som tvåfaktorsautentisering skickar systemet automatiskt e-postmeddelandet/SMS:et med förhandsautentiseringsbegäran.

auth

För att autentisera användaren, använd åtgärdstypen auth. Skicka användarnamn och lösenord (samt 2FA-kod om nödvändigt) tillsammans med din begäran, så får du ett autentiseringstoken som svar. Token kan sedan användas för att behandla efterföljande begäranden.

Exempel på indata:

{
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username
  "kpass":      "...",     //Password
  "2fa":        "...",     //optional
  "longlife":   0|1 ,      //optional
  "api_key":    ""         //optional
}

Exempel på översättning:

{
  ...
  "data":
  {
    "kmd":"token"
  }
}

Spara värdet som finns under kmd och skicka det i alla efterföljande anrop till API:et som ingångsvärde kmd.

Observera: Vid tvåfaktorsautentisering kommer anropet till auth returneras en felkod beroende på autentiseringsmetoden om 2fa inte har skickats. I så fall måste du visa en sida för tvåfaktorsautentisering för användaren som matchar felkoden (t.ex. för att ange e-postkoden eller engångskoden). Använd den token (kmd) som du har fått och använd åtgärden verifyauth för att (åter)skicka 2fa-koden.

verifyauth

Åtgärden verifyauth kan användas för att antingen verifiera om en token (kmd) fortfarande är giltigt och/eller för att skicka in en 2fa-kod för tvåfaktorsautentisering.

Exempel på indata:

{
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
  "2fa":        "...",     //2fa code    
}

Exempel på översättning:

{
  ...
  "data":
  {
    "kmd":"token"
  }
}

Spara värdet som finns under kmd och skicka det i alla efterföljande anrop till API:et som ingångsvärde kmd.

logga ut

Åtgärden logout åtgärden avslutar en befintlig session (utloggning).

Exempel på indata:

{
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
}

rättigheter

Åtgärdstyp rights kan användas för att få en översikt över modeller och åtgärder som användaren har rätt att få tillgång till.

Exempel på indata:

{
  "accessType": 0|1|2|...,
  "token":      "..."
}

Exempel på översättning:

{
  ...
  "data":
  [
    {
      "model":   "User",
      "actions": ["get","list","update"]
    },
    {
      "model":   "Subaccount",
      "actions": ["get","list","update","create","delete","deleteinfo"]
    }
  ]
}

lista

Åtgärdstypen list kan användas för att begära en lista över poster av en specifik modell från databasen. Denna åtgärdstyp är avsedd att användas för att ge en användare en översikt över objekt (snarare än att visa specifika detaljer).

Exempel på förväntat indata:

{
  ... 
 "filters": [...],      // Filters to apply, see description (optional)
 "limit":   100,        // Limit of output rows (optional)
 "offset":  0,          // Start index of first row (optional)
 "order":   "...",      // Column to sort (optional)
 "sort":    "asc|desc", // Sorting direction of output (optional) 
 "cols":    [...]       // If set, will output the named fields, otherwise a default set of fields will be shown
 //optional: "assoc": true // If set, returns and associative array instead of a data list
 //optional: "dataonly": true // If set, returns the data list only (no header information)
}

Exempel på svar:

{
  "status":     "Success",
  "statuscode": 0,
  "msg":        "Erfolgreich",
  "model":      "Subaccount",
  "action":     "list",
  "data":       
  {
    "data":    
    [
      {
        "id":  "542",
        "row": 
        [
          "542",
          "aaa",
          "Aktiv"
        ]
      },
      {
        "id":  "543",
        "row": 
        [
          "543",
          "bbb",
          "Aktiv"
        ]
      }
    ],
    "head":    
    [
      {        
        "headline":     "ID",
        "colsort":      false,
        "colorder":     "intID",
        "colname":      "intID"
      },
      {
        "headlineType": "string",
        "headline":     "Nutzername",
        "colsort":      false,
        "colorder":     "strLogin",
        "colname":      "strLogin"
      },
      {
        "headlineType": "string",
        "headline":     "Status",
        "colsort":      false,
        "colorder":     "intStatus",
        "colname":      "intStatus"
      }
    ],
    "caption": "User",
    "count":   2,
    "total":   2
  }
}

Utdata består av en data matris och en motsvarande rubrikmatris. Datamatrisen innehåller de rader som ska visas för användaren. Rubrikmatrisen kommer att innehålla den specifika rubrikinformationen (t.ex. sortering, rubriktext och så vidare) för varje kolumn i tabellen.

Ovanstående exempeldata skulle resultera i att följande tabell visas:

Konverterade värden

För fält av typen lista (fältundertyperna 1, 2 och 12) kan du använda suffixet :convert i cols egenskapen i begäran för att få det läsbara värdet av innehållet istället för det råa värdet (t.ex. namnet på en kolumn istället för ID:t). Om en kolumn med detta suffix hittas kommer utdata att innehålla kolumnen två gånger, en gång som råvärde och en gång som konverterat värde.

Exempel på förväntat indata:

{
  ... 
 "model":   "Design",  
 "action":  "list",
 "cols":    ['strName', 'intPosition:convert']  
}

Exempel på svar:

{
 ...
  "data":       
  {
    "data":    
    [
      {
        "id":  "542",
        "row": 
        [
          "myDesign",
          "3",
          "Center middle"
        ]
      },
      ...
    ],
    "head":    
    [
      {        
        "headline":     "name",
        "colsort":      false,
        "colorder":     "strName",
        "colname":      "strName"
      },
      {        
        "headline":     "Position",
        "colsort":      false,
        "colorder":     "intPosition",
        "colname":      "intPosition"
      },
      {        
        "headline":     "Position",
        "colsort":      false,
        "colorder":     "intPosition",
        "colname":      "intPosition:convert"
      }
    ],
   ...
  }
}

Filter

Den

filters

Egenskapen i begäran JSON kan användas för att söka efter specifika objekt eller minska utdatalistan.

filters

egenskapen består av en matris med filterobjekt. Varje objekt har följande struktur:

{
  "fieldname":  "...", // Field the filter should apply to
  "comparison": "...", // (optional) Comparison type, see description
  "value"    :  "..."  // Value to compare the field to
}

För att söka i alla fält kan fältnamnet query användas.

Möjliga comparison värden är:

Jämförelsetyp Beskrivning
eql Likvärdigt. Hitta rader där innehållet i fieldname är exakt detsamma som value. (Denna typ är standard om comparison inte används i objektet.)
lt Mindre än. Hitta rader där innehållet i fieldname är mindre än value.
gt Större än. Hitta rader där innehållet i fieldname är större än value.
lte Mindre än/Lika med. Hitta rader där innehållet i fieldname är mindre än value eller lika med value.
gte Större än/Lika med. Hitta rader där innehållet i fieldname är större än value eller lika med value.
like Innehåller. Hitta rader där value ingår i innehållet i fieldname (delvis eller helt).
in Finns i listan. Hitta rader där innehållet i fieldname är exakt detsamma som en av value. I detta fall value bör vara en matris.
is Är NULL. Hitta rader där innehållet i fieldname är NULL.
isnot är inte NULL. Hitta rader där innehållet i fieldname inte är NULL.

Exempel:

{
  ...
  "filters":
  [
    {
      "fieldname": "age",
      "comparison": "gte",
      "value" : 27
    },
    {
      "fieldname": "lastname",
      "comparison": "like",
      "value" : "man"
    }
  ]
}

… kommer att hitta rader där age är lika med eller större än 27 och lastname innehåller man (t.ex. Hofmann eller Superman eller Mandy)

få

Åtgärdstypen get kan användas för att begära en eller flera poster av en specifik modell från databasen när ID:n för posterna redan är kända. Den avsedda användningen av denna åtgärdstyp är att visa data i ett formulär för redigering. Därför kommer svaret också att innehålla detaljerad information om varje fält.

Exempel på förväntat indata:

{
  ... 
 "ids":     [...]  // Array of IDs
 }

Skicka en tom array av ids för att endast få fältdefinitionen. Detta kan hjälpa dig att skapa en ny post baserad på fältdefinitionen.

Exempel på svar:

{
  "status":     "Success",
  "statuscode": 0,
  "msg":        "Erfolgreich",
  "model":      "Subaccount",
  "action":     "get",
  "data":       
  {
    "fields":     
    [
      {
        "fieldname":    "intID",
        "displayname":  "ID",
        "type":         2,
        "subtype":      8,
        "required":     true,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "542",
        "displayvalue": "",
        "listkeys":     [],
        "listvalues":   []
      },
      {
        "fieldname":    "strLogin",
        "displayname":  "Nutzername",
        "type":         1,
        "subtype":      0,
        "required":     true,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "aaa",
        "displayvalue": "aaa",
        "listkeys":     [],
        "listvalues":   []
      },
      {
        "fieldname":    "strPass",
        "displayname":  "Passwort",
        "type":         1,
        "subtype":      5,
        "required":     true,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "%%unchanged%%",
        "displayvalue": "********",
        "listkeys":     [],
        "listvalues":   []
      },
      {
        "fieldname":    "intStatus",
        "displayname":  "Status",
        "type":         2,
        "subtype":      1,
        "required":     false,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "1",
        "displayvalue": "Aktiv",
        "listkeys":     [ 0, 1 ],
        "listvalues":   [ "Inaktiv", "Aktiv" ]
      }
    ],
    "caption":    "User: aaa",
    "groups":     [],
    "ids":        [ 542 ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

Ovanstående exempel skulle kunna resultera i ett formulär som ser ut så här:

skapa

För att skapa nya poster kan du använda åtgärdstypen create.

Exempel på förväntat ingångstext:

{
  "ids":        [],
  "data":       {
    "intID":     "0",    
    "strLogin":  "new User",
    "strPass":   "ABCabc123!",
    "intStatus": "1"
  }
}

Resultatet av en lyckad uppdatering motsvarar exemplet som ges för get åtgärdstypen. Exempel på resultat:

{
  "status":         "Success",
  "statuscode":     0,
  "msg":            "Erfolgreich",
  "model":          "Subaccount",
  "action":         "get",
  "previousAction": "create",
  "data":           
  {
    "fields":     [...],
    "caption":    "User: new User",
    "groups":     [],
    "subgroups":  [],
    "ids":        [ 544 ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

Observera att create kommer att misslyckas om modellen med samma ID redan finns. Om du vill åsidosätta befintliga inställningar kan du skicka de två fälten insertIgnore (value=1) och/eller onDuplicateUpdate (värde=1). Att skicka insertIgnore till systemet att inte returnera ett fel om infogningen misslyckas. onDuplicateUpdate talar om för systemet att uppdatera alla värden om det finns ett befintligt objekt med samma ID.

uppdatera

För att ändra en eller flera befintliga poster kan du använda åtgärdstypen update.

Exempel på förväntat indata:

{
  "ids":        [ 542 ],
  "data":       
  {
    "intID":     "542",
    "strLogin":  "aaa",
    "strPass":   "abcabc",
    "intStatus": "1"
  }  
}

Resultatet av en lyckad uppdatering motsvarar exemplet som ges för get åtgärdstypen. Exempel på resultat:

{
  "status":         "Success",
  "statuscode":     0,
  "msg":            "Erfolgreich",
  "model":          "Subaccount",
  "action":         "get",
  "previousAction": "update",
  "data":           
  {
    "fields":     [...],
    "caption":    "User: aaa",
    "groups":     [],
    "subgroups":  [],
    "ids":        [ 542 ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

Om ett uppdateringsfel uppstår kommer systemet att svara med ett felmeddelande som detta:

{
  "status": "Error",
  "statuscode": 113,
  "msg": "Update error, see error message. Field specific messages see response.data",
  "model": "Subaccount",
  "action": "update",
  "data": 
  {
    "strLogin": "Wert muss mindestens 6 Zeichen lang sein",
    "strPass":  "Wert muss Sonderzeichen beinhalten"
  }
}

ta bort

Åtgärdstypen delete kan användas för att radera en eller flera poster av en specifik modell från databasen när postens ID redan är kända.

Exempel på förväntat indata:

{
  ... 
 "ids":     [...]  // Array of IDs
 }

Exempel på svar:

{
  "status":         "Success",
  "statuscode":     0,
  "msg":            "Erfolgreich",
  "model":          "Subaccount",
  "action":         "create",
  "previousAction": "delete",
  "data":           
  {
    "fields":     [...],
    "caption":    "User: new User",
    "groups":     [],
    "subgroups":  [],
    "ids":        [  ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

 

We do our best to keep this purely informative documentation up to date. However, if you notice that any of these guides need a little touch-up, let us know!