Comparaison des versions

Légende

  • Ces lignes ont été ajoutées. Ce mot a été ajouté.
  • Ces lignes ont été supprimées. Ce mot a été supprimé.
  • La mise en forme a été modifiée.
Sommaire

Introduction

Les webhook webhooks Métier permettent de manipuler une entité (client, contact, ...) à partir de l'extérieur via un appel de type http.
Les webhook webhooks Métier implémente implémentent une structure commune de leur contrat JSON.

Entête

Structure

Le JSON lors de l'appel au webHook devra contenir les éléments suivants :

Bloc de code
languagejson
{
  "header": 
    {
       "caller": how called the webhook ie.: infinity
       "callerVersion": version of the caller ie. 1.2.3.4
       "languageCode": FR, EN, DE, PT, ES, IT, FR-CA, EN-CA
       "userCode": user how called the webhook
       "callDateTime": initial call date/time, usefull when retries or whatever network issue
       "markForExport": value for srvExport of the table, can be 0, 1, 2 (optional, default is 1)
       "webhookVersion": version of the webhook for top-down compatibility, can be 1 or 2 (optional, default is 2). Today is used for webhook intervention, equipment and contract.
    },
    "action":
    {
       "verb": "value", // GET, PUT, DELETE, LIST, DEFINITION
       "parameters": //depends on the verb 
        {
            // depends on the {verb
        }
   },
   "data":
   {
       // depends on the webhook (used for verb = PUT to insert/update the data)      
   }
}

Avec les possibilités suivantes selon le verb :

...

GET : lire un enregistrement

...

verb “PUT”

Permet d'écrire un enregistrement

...

DELETE : supprimer un enregistrement

...

LIST : lister plusieurs enregistrements

...

DEFINITION : obtenir les propriétés de l'objet métier ainsi que les listes de valeurs possibles associées

...

(Ajout/Mise à jour).

Bloc de code
languagejson
"verb": GETPUT
"parameters":

{
   "code": code of the record to get (mandatory)
   "resultType":
   // for webhook file
  "entity": "value",
  "simpleextension" : main info of the record (by default)
      "extended": all columns of the record"value"
}

Le bloc data contient les données à créer/mettre à jour. Ce bloc est différent pour chaque webhook. Consultez la fiche expert de chaque webhook pour le détail.

Bloc de code
languagejson
"data":
{
    "xxxxx":
    {
        "extendedRelatedcodexxxxx": all columns of the record + given context (one entity per foreign key)
   "settings": depends of the webhook (optional)"value", // optional
        "field1": "value",
     {     }
}

"verb"field2": PUT
"parametersvalue":,
{   // for webhook file   "entity": "value",....
   "extension": "value"
}

"verb": DELETE (V1: delete only record at a time)
"parameters": 
{ }
}

La possibilité est donné de faire des PUT par LOT en passant un tableau de data.
La variable Webhook.PUT.MaxElementAtOnce défini le nombre maximum d'éléments qui peuvent être passés à la fois (par défaut : 10). Ceci permet de tenir compte du timeout réseau.

Bloc de code
languagejson
"data":   
[{
    "xxxxx":
    {
        "codecodexxxxx": code of the record to delete (mandatory) "value", // optional
        "deleteTypefield1": "value",
        "logicalfield2": no"value",
real delete in db (by default)   ....
   "physical": real}
delete},
possible{
if record is not referred"xxxxx":
to elsewhere   {
   "simulation": simulate the delete (can be used to know in advance if a record can be deleted)
}

"verb": LIST 
"parameters": 
{ "codexxxxx": "value", // optional
        "field1": "value",
        "listTypefield2": "value",
       "simple": main info of the record (by default), the columns are determined by each webhook
      "extended": all columns of the record 
      "extendedRelated": not used for verb=LIST   
   "pageNumber": "xx" // used to read the page of the records list, 1 page = 10 records (optional, default pageNumber is 1)
     ....
    }
},
{
    ....
}]

L'initialisation du code d'un enregistrement se fera par ordre de priorité de la manière suivante lors de la création :

  1. Code fourni dans le json (et s'il n'existe pas encore, sinon on sera en modification)

  2. Utilisation du numbering si existant sur le code de l'entité.

  3. Code = ID de l'enregistrement (codexxxxx = xxxxx_ID)

verb “DELETE”

Permet de supprimer un enregistrement.

Bloc de code
languagejson
"verb": DELETE
"parameters": 
{
   "code": code of the record to delete (mandatory)
   "deleteType": 
      "logical": no real delete in db (by default - not implemented at time)
      "physical": real delete, possible if record is not referred to elsewhere
    You can read "simulation": simulate the delete (can listbe pageused perto pageknow untilin maxPageNumberadvance (resultif ofa maxPageNumberrecord givencan inbe the "response")   deleted)
}

verb “GET”

Permet de lire un enregistrement.

Bloc de code
languagejson
"verb": GET
"parameters": 
{
   "settingscode": dependscode of the webhookrecord (optional)to get (mandatory)
 {  "resultType":
  }    "filterssimple" : dependsmain info of the webhookrecord called here, not mandatory, each filter added will result is an AND in the query (for example intervention)
              For a filter operator "equal" it is possible to give more values separated by "|" (ie "email": "email1|email2|email3")
   {
     "codeIntervention": "value", filter is equal
     "codeCustomer": "value", filter is equal
     "codeContract": "value", filter is equal
     "startDate": "value", filter is greater or equal to
     "endDate": "value", filter is lesser or equal to(by default)
      "extended": all columns of the record 
      "extendedRelated": all columns of the record + given context (one entity per foreign key)
   "settings": 
   {
       // depends of the webhook (optional)
   }
}

verb “LIST”

Permet de lister plusieurs enregistrements.

Bloc de code
languagejson
"verb": LIST 
"parameters": 
{
   "listType": 
      "simple": main info of the record (by default), the columns are determined by each webhook
      "extended": all columns of the record 
      "interventionTypeextendedRelated": "value", filter is equal
   }not used for verb="LIST"  
   "orderBypageNumber" : "valuexx" // depends used to read the page of the webhookrecords (optional)list, 1 orderpage the= returned10 records (foroptional, exampledefault webhookpageNumber event,is the1)
value can be "eventDateDesc" to order the records by event date descending)    "topRows": "xx" // limit the returned records (optional)
}

"verb": DEFINITION
"parameters":
{
  "baseculture_id": "value" // (optional) Culture to use to return labels. If not given, the LanguageCode of the header will be used by default.
}

Pour le verb PUT il faut alimenter le bloc data qui contiendra les données à créer/mettre à jour. Ce bloc est différent pour chaque webhook. Consultez la fiche expert de chaque webhook pour le détail.

Bloc de code
languagejson
"data":
{
    "xxxxx           You can read the list page per page until maxPageNumber (result of maxPageNumber given in the "response")   
   "settings": 
   {
       // depends of the webhook (optional)
   }
   "filters":     {         
   {
     "codexxxxx": "value", // optionaldepends of the webhook (optional), each filter added will "field1": "value",
    result is an AND in the query
   "field2": "value",   // For a filter operator  ....
    }
}

La possibilité est donné de faire des PUT par LOT en passant un tableau de data.
La variable Webhook.PUT.MaxElementAtOnce défini le nombre maximum d'éléments qui peuvent être passés à la fois (par défaut : 10). Ceci permet de tenir compte du timeout réseau.

Bloc de code
languagejson
"data":   
[{
    "xxxxx":
    {"equal" it is possible to give more values separated by "|" (ie "email": "email1|email2|email3")
   }
   "orderBy" : "value" // depends of the webhook (optional), order the returned records (for example webhook event, the value can be "eventDateDesc" to order the records by event date descending)
   "topRows": "xx" // limit the returned records (optional)
}

verb “DEFINITION”

Permet d’obtenir les propriétés de l'objet métier ainsi que les listes de valeurs possibles associées.

Bloc de code
languagejson
"verb": DEFINITION
"parameters":
{
  "baseculture_id": "value" // (optional) Culture to use to return labels. If not given, the LanguageCode of the header will be used by default.
}

Réponse

Structure

Bloc de code
languagejson
{
    "label": "Webhook xxx", //name of the called webhook
    "codeScript": "Webhookxxx", //script called by the webhook
    "resultType": "JSON",
    "result":
    {
        "common":
        {
            "resultCode": "0", // 0 if ok otherwise specific error of the webhook
            "errorMessage": "" // if resultCode <> 0, text of the error in english
        },
        "response":
        {
            // depends of the webhook
        }
    },
    "statistics": 
    {
        "durationMs": xx, // duration of execution time
        "consumedTimeOnDatabaseMs": xx, // DB time used
        "selectQueryCount": xx, // number of select query done
        "insertQueryCount": xx, // number of insert query done
        "updateQueryCount": xx, // number of update query done
        "deleteQueryCount": xx, // number of delete query done
        "codexxxxxreadTokenCount": "value"xx, 
        "executedFunctionCount": xx, // optionalnumber of function called
        "field1translatorHitCount": "value",xx, // number of translations done
        "field2languageHitCount": "value", xx 
    }    
....
 }

verb “PUT”

La réponse aura 1 section.

Bloc de code
languagejson
  "response": 
 } },
{
    "xxxxxdata": 
    [{

       "codexxxxxaction": "value", // optionalinserted or updated
      "field1xxxxx_ID": "value", // with xxxxx = table and value is ID created/updated
      "field2codexxxxx": "value", // with xxxx = table and value is ....
code created/updated
   } },
{]
    .... }]

L'initialisation du code S'il s'agit d'un enregistrement se fera par ordre de priorité de la manière suivante lors de la création :

  1. Code fourni dans le json (et qu'il n'existe pas encore sinon on sera en modification)

  2. Utilisation du numbering si existant sur le code de l'entité.

  3. Code = ID de l'enregistrement (codexxxxx = xxxxx_ID)

Réponse

Standard response of a webhook:

PUT par lot, le détail du résultat sera un tableau dimensionné selon la section "data" passée en entrée.

Bloc de code
languagejson
"result": 
{
    "labelresults": 
    [{
       "Webhook Intervention", //name of the called webhook "common": 
        {
            "codeScriptresultCode": "WebhookIntervention0", //script called by 0 if ok otherwise specific error of the webhook
    "resultType": "JSON",        "resulterrorMessage": "see below", // if resultCode  "statistics": {
    <> 0, text of the error in english
   "durationMs": 1360, //duration of execution time},
        "consumedTimeOnDatabaseMsresponse": 990,
//DB time used      {
  "selectQueryCount": 3, //number of select query done
        "insertQueryCountdata": 0,
 //number of insert query done       [{
 "updateQueryCount": 0, //number of update query done         "deleteQueryCountaction": 0"value", //number ofinserted deleteor queryupdated
done         "readTokenCount": 1842,            "executedFunctionCountxxxxx_ID": 258"value", //number ofwith functionxxxxx called= table and value is ID created/updated
  "translatorHitCount": 552, //number of translations done         "languageHitCountcodexxxxx": 0 
    }
}

Détail du résultat :

Bloc de code
languagejson
"result":
{
  "common":
    {
"value" // with xxxx = table and value is code created/updated
     "resultCode": "0", //0 if ok otherwise specific error}]
of the webhook      }
"errorMessage": "" //if resultCode <>0},
text of the error in{
english (V1)     },   "responsecommon":
 
{     depends on the webhook{
  }
}

Pour le verb PUT, la réponse aura 1 section :

Bloc de code
languagejson
          "responseresultCode": "0",
       {     "maxElementAtOnceerrorMessage": "10"
// max elements that can be passed at once        },
        "dataresponse": 
    [{    {
            "actiondata": "value", // inserted or updated
           "xxxxx_ID": "value", // with xxxxx = table and value is ID created/updated [{
                "codexxxxxaction": "value",
// with xxxx = table and value is code created/updated     }]
  }

S'il s'agit d'un PUT par lot, le détail du résultat sera un tableau dimensionné selon la section "data" passée en entrée :

Bloc de code
languagejson
"result": 
{"xxxxx_ID": "value",
                "resultscodexxxxx": "value"
     [{       }]
        "common":}
    },
    {
        ...
   "resultCode": "0", //0 if ok otherwise specific error of the webhook  }]
}

verb “DELETE”

La réponse aura 1 section.

Bloc de code
languagejson
  "response": 
  {
    "data": 
    [{
      "errorMessageaction": "deleted"
//if resultCode <>0, text of}]
the error in english (V1)
        },
        }

verb “GET”

La réponse aura 2 sections.

Bloc de code
languagejson
"response":
  {
    "data":
 {     [{ 
      "maxElementAtOnce": "10" // maxdepends elementsof thatthe canwebhook
be passed at once }],
           "data"fieldList": 
  
         [{
      "entityName": "value", // name of the entity (ie   "action": "value", // inserted or updated
intervention)
      "fields":
      [{
        "xxxxx_IDfieldName": "value", // withname xxxxxof =the tablefield and(ie value is ID created/updated
   codeintervention, customer_ID, …)
            "codexxxxxfieldType": "value", // withtype xxxxof =the tablefield and: valuevarchar, istext, code created/updated
    int, double, bool, datetime, timestamp, foreignkey
       }] "fieldLength": "value", // length of the field : }informed for varchar, text
 },     {  "fieldLabel": "value" // label of the field "common": depends on the value of the languageCode from the {header (default : FR)
      },
  "resultCode": "0",    {
        "errorMessagefieldName": "value",
         }"fieldType": "value",
        "responsefieldLength": "value",
        {"fieldLabel": "value"
      },
     "maxElementAtOnce": "10" // max elements that can be passed at once {
        ...
      }],
      "datarelated": // for listType = "extendedRelated"
      [{
 [{       "entityName": "value",
        "actionfields":
"value",        [{
          "xxxxx_ID": "value",...
        }]
      },
 "codexxxxx": "value"    {
        }]
"entityName": "value",
       } "fields":
   },     [{
          ...
  
 }]
}

Pour le verb DELETE, la réponse aura 1 section :

Bloc de code
languagejson
  "response":        }]
  {    },
"data":      [{
      "action": "deleted"  ...  
      }]
    }]    

...

verb “LIST”

La réponse aura 2 sections :.

Bloc de code
languagejson
  "response":
  {
    "maxPageNumber": xx, // verb=LIST : number of pages of records
    "pageSize": 10, // verb=LIST : number of records per page
    "data":":
    [{ 
        [{// depends of the webhook
    }],
     "fieldList": 
    [{
      "entityName": "value", // name of the tableentity (ie intervention)
      "fields":
      [{
        "fieldName": "value", // name of the field (ie codeintervention, customer_ID, …)
        "fieldType": "value", // type of the field : varchar, text, int, double, bool, datetime, timestamp, foreignkey
        "fieldLength": "value", // length of the field : informed for varchar, text
        "fieldLabel": "value" // label of the field : depends on the value of the languageCode from the header (default : FR)
      },
      {
        "fieldName": "value",
        "fieldType": "value",
        "fieldLength": "value",
        "fieldLabel": "value"
      },
      {
        ...
      }],
    }]  "related":
      [{
        "entityName": "value",
        "fields":
        [   

verb “DEFINITION”

La réponse aura 2 sections.

Bloc de code
languagejson
  "response":
  {
    "data":
    [{ ...
        }]"fieldName1":
      },  [{
    {         "entityNamecode": "value",
          "fieldslabel": "value"
       [{ },
        {
...         }]       }"code": "value",
      {         ..."label": "value"
        }],
    }]     

Pour le verb DEFINITION, la réponse aura 2 sections :

Bloc de code
languagejson
  "response":{
     {     "data":...
      [{ depends of}
the webhook}],      As an}],
example for contact      "generictype_ID_civilityfieldName2":
        [{
          "code": "CIVILITY-MRvalue",
          "label": "Mister"value"
        },
        {
          "code": "CIVILITY-MMEvalue",
          "label": "Madamevalue"
        },
        {
            "code": "CIVILITY-MRS"...
        }
        }],
       "label": "Miss" ...
     }],
     "fieldList": 
    [{
      "entityName": "value", // name of the tableentity (ie intervention)
      "fields":
      [{
        "fieldName": "value", // name of the field (ie codeintervention, customer_ID, …)
        "fieldType": "value", // type of the field : varchar, text, int, double, bool, datetime, timestamp, foreignkey
        "fieldLength": "value", // length of the field : informed for varchar, text
        "fieldLabel": "value", // label of the field : depends on the value of the languageCode from the header (default : FR)
        "fieldNameToShow": "value", // field alias for GET and LIST
        "alias": "value", // field alias for PUT
        "canGet": "value", // field can be read (0, 1)
        "canInsert": "value", // field can be updated for a new record (0, 1)
        "canUpdate": "value", // field can be updated for a existing record (0, 1)
        "mandatory": "value", // field is mandatory in sent json (0, 1)
        "canotBeNullcannotBeNull": "value", // field cannot be null or empty in sent json (0, 1)
        "dataType": "value" // data type for generictype foreignkey field
      },
      {
        "fieldName": "value",
        "fieldType": "value",
        "fieldLength": "value",
        "fieldLabel": "value",
        "fieldNameToShow": "value",
        "alias": "value",
        "canGet": "value",
        "canInsert": "value",
        "canUpdate": "value",
        "mandatory": "value",
        "canotBeNullcannotBeNull": "value",
        "dataType": "value"
      },
      {
        ...
      }],
      "related":
      [{
        "entityName": "value",
        "fields":
        [{
          ...
        }]
      },
      {
        "entityName": "value",
        "fields":
        [{
          ...
        }]
      },
      {
        ...  
      }]
    }]