Introduction
Les webhooks Métier permettent de manipuler une entité (client, contact, ...) à partir de l'extérieur via un appel de type http.
Les 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 |
---|
|
{
"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
PUT : é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
...
verb “PUT”
Permet d'écrire un enregistrement (Ajout/Mise à jour).
Bloc de code |
---|
|
"verb": GETPUT
"parameters":
{
"code": code of the record to get (mandatory)
"resultType":
"simple" : main info of the record (by default)
"extended": all columns of the record// for webhook file
"entity": "value",
"extension": "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 |
---|
|
"data":
{
"xxxxx":
{
"extendedRelatedcodexxxxx": all columns of the record + given context (one entity per foreign key)"value", // optional
"settingsfield1": depends"value",
of the webhook (optional) {
}
}
"verb"field2": PUT
"parametersvalue":,
{ // for webhook file "entity": "value",....
"extension": "value"
}
"verb": DELETE (V1: delete only record at a time)
"parameters":
{
"code": code of the record to delete (mandatory)
"deleteType": }
} |
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 |
---|
|
"data":
[{
"xxxxx":
{
"codexxxxx": "value", // optional
"field1": "value",
"field2": "value",
....
}
},
{
"xxxxx":
{
"codexxxxx": "value", // optional
"field1": "value",
"field2": "value",
....
}
},
{
....
}] |
L'initialisation du code d'un enregistrement se fera par ordre de priorité de la manière suivante lors de la création :
Code fourni dans le json (et s'il n'existe pas encore, sinon on sera en modification)
Utilisation du numbering si existant sur le code de l'entité.
Code = ID de l'enregistrement (codexxxxx = xxxxx_ID)
verb “DELETE”
Permet de supprimer un enregistrement.
Bloc de code |
---|
|
"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
"simulation": simulate the delete (can be used to know in advance if a record can be deleted)
} |
verb “GET”
Permet de lire un enregistrement.
Bloc de code |
---|
|
"verb": GET
"parameters":
{
"code": code of the record to get (mandatory)
"resultType":
"simple" : main info of the record (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 |
---|
|
"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
"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)
"logical": no real delete in db (by default) "physical": realYou delete,can possibleread ifthe recordlist ispage notper referredpage tountil elsewheremaxPageNumber (result of maxPageNumber given in the "simulation": simulate the delete (can be used to know in advance if a record can be deleted)
}
"verb": LIST
"parameters":
{
"listType":
response")
"settings":
{
// depends of the webhook (optional)
}
"simplefilters": main info of the record (by default), the columns are
determined by each webhook{
"extended": all columns // depends of the recordwebhook (optional), each filter added will result "extendedRelated": not used for verb=LIST is an AND in the query
"pageNumber": "xx" // usedFor a tofilter readoperator the"equal" pageit ofis thepossible recordsto list,give 1more pagevalues =separated 10by records"|" (optional, default pageNumber is 1)
ie "email": "email1|email2|email3")
}
"orderBy" : "value" // depends of the webhook (optional), order the returned records (for example Youwebhook canevent, read the listvalue pagecan perbe page"eventDateDesc" untilto maxPageNumberorder (resultthe ofrecords maxPageNumberby givenevent in the "response"date descending)
"topRows": "settingsxx": depends// oflimit the returned webhookrecords (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 |
---|
|
"verb": DEFINITION
"parameters":
{
}
"filters"baseculture_id": depends of the webhook called here, not mandatory, each filter added will result is an AND in the query (for example intervention)
"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 |
---|
|
{
"label": "Webhook xxx", //name of the called webhook
For a filter operator"codeScript": "equalWebhookxxx", //script itcalled isby possiblethe towebhook
give more values separated by"resultType": "|JSON",
(ie "emailresult":
"email1|email2|email3") {
"codeInterventioncommon":
"value", filter is equal {
"codeCustomer": "value", filter is equal "codeContractresultCode": "value0", filter is equal
"startDate": "value", filter is greater or equal to// 0 if ok otherwise specific error of the webhook
"endDateerrorMessage": "value"" // if resultCode <> 0, filtertext isof lesserthe orerror equalin toenglish
"interventionType": "value", filter is},
equal } "orderByresponse" :
"value" // depends of the webhook (optional), order the{
returned records (for example webhook event, the value can be "eventDateDesc" to order// thedepends recordsof bythe eventwebhook
date descending) "topRows": "xx" // limit}
the returned records (optional) },
"verb": DEFINITION "parametersstatistics": {
"baseculture_id": "value" //{
(optional) Culture to use to return labels. If not given"durationMs": xx, the// LanguageCodeduration of execution thetime
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 |
---|
|
"data":
{"consumedTimeOnDatabaseMs": xx, // DB time used
"xxxxxselectQueryCount": xx, // number of select query {done
"codexxxxxinsertQueryCount": "value"xx, // optional number of insert query done
"field1updateQueryCount": "value",
xx, // number of update query done
"field2deleteQueryCount": "value"xx, // number of delete query done
.... } } |
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 |
---|
|
"data":"readTokenCount": xx,
[{ "xxxxxexecutedFunctionCount": xx, // number of function {called
"codexxxxxtranslatorHitCount": "value"xx, // optionalnumber of translations done
"field1languageHitCount": "value",xx
}
"field2} |
verb “PUT”
La réponse aura 1 section.
Bloc de code |
---|
|
"response": "value",
{
"maxElementAtOnce": "10" // max ....elements that can be passed }
},
{at once
"xxxxxdata":
[{
"codexxxxxaction": "value", // optionalinserted or updated
"field1xxxxx_ID": "value", // with xxxxx = table and value is ID created/updated
"field2 "codexxxxx": "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 :
Code fourni dans le json (et qu'il n'existe pas encore sinon on sera en modification)
Utilisation du numbering si existant sur le code de l'entité.
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 |
---|
|
{
"label"result": "Webhook
Intervention", //name of the called webhook{
"results":
"codeScript": "WebhookIntervention", //script called by the webhook [{
"resultTypecommon": "JSON",
"result": "see below", {
"statistics": { "durationMsresultCode": 1360"0", //duration 0 if ok otherwise specific error of the webhook
execution time "consumedTimeOnDatabaseMserrorMessage": 990,"" //DB timeif usedresultCode <> 0, text of the error in english
"selectQueryCount": 3, //number of select query done},
"insertQueryCountresponse": 0, //number of insert query done
{
"updateQueryCountmaxElementAtOnce": 0,"10" //number ofmax updateelements querythat donecan be passed at once
"deleteQueryCount": 0, //number of delete query done "data":
"readTokenCount": 1842, [{
"executedFunctionCount": 258, //number of function called "translatorHitCountaction": 552"value", //number ofinserted translationsor doneupdated
"languageHitCount": 0 } } |
Détail du résultat :
Bloc de code |
---|
|
"result"xxxxx_ID": {
"commonvalue":, // with xxxxx = {table and value "resultCode": "0", //0 if ok otherwise specific error of the webhookis ID created/updated
"errorMessagecodexxxxx": "value" //if resultCodewith <>0,xxxx text= oftable theand errorvalue inis english (V1)code created/updated
}, "response": { }]
depends on the webhook }
} |
Pour le verb PUT, la réponse aura 1 section :
Bloc de code |
---|
|
"response":
},
{
"datacommon":
[ {
"action "resultCode": "value0",
// inserted or updated "xxxxx_IDerrorMessage": "value",
// with xxxxx = table and value is},
ID created/updated "codexxxxxresponse": "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 |
---|
|
"result":
{
"results":
[{"maxElementAtOnce": "10" // max elements that can be passed at once
"commondata":
[{
{ "resultCodeaction": "0value", //0 if
ok otherwise specific error of the webhook "errorMessagexxxxx_ID": "" //if resultCode <>0value",
text of the error in english (V1) }, "response"codexxxxx": "value"
{ }]
"data":}
},
{
[{ ...
}]
} |
verb “DELETE”
La réponse aura 1 section.
Bloc de code |
---|
|
"actionresponse": "value",
// inserted or{
updated "data":
[{
"xxxxx_IDaction": "valuedeleted",
// with}]
xxxxx = table and value is ID created/updated
} |
verb “GET”
La réponse aura 2 sections.
Bloc de code |
---|
|
"response":
{
"data":
[{
"codexxxxx": "value" // withdepends xxxxof =the tablewebhook
and value is code created/updated }],
"fieldList":
[{
}] }
},
{
"entityName": "value", // name of the entity (ie intervention)
"commonfields":
{
[{
"resultCodefieldName": "0value", // name of the field (ie codeintervention, customer_ID, …)
"errorMessagefieldType": "value", // type of the field : varchar, text, }int, double, bool, "response":
datetime, timestamp, foreignkey
{ "fieldLength": "value", // length of the field "data": informed for varchar, text
[{
"action": "value","fieldLabel": "value" // label of the field : depends on the value of the languageCode from the header (default : FR)
},
{
"xxxxx_ID": "value", "fieldName": "value",
"codexxxxxfieldType": "value",
"fieldLength": "value",
}] "fieldLabel": "value"
} },
{
...
}]
} |
...
...
Bloc de code |
---|
|
"response":
{ "datarelated":
[{
"action": "deleted// for listType = "extendedRelated"
}] } |
Pour le verb LIST ou GET, la réponse aura 2 sections :
Bloc de code |
---|
|
"response":[{
{ "maxPageNumberentityName": xx"value",
// verb=LIST : number of pages of records "fields":
"pageSize": 10, // verb=LIST : number[{
of records per page "data": ...
[{ depends of the webhook}],
},
"fieldList": [{
"entityName": "value",
// name of the table (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
}]
}] |
verb “LIST”
La réponse aura 2 sections.
Bloc de code |
---|
|
"response":
{
"fieldLengthmaxPageNumber": "value"xx, // number of lengthpages of records
the field : informed for varchar"pageSize": 10, text// number of records per page
"fieldLabeldata":
"value" // label[{ of
the field : depends on the value of the// languageCodedepends fromof the headerwebhook
(default : FR) }],
},"fieldList":
[{
"fieldNameentityName": "value", // name of the entity (ie intervention)
"fieldType": "value", "fields":
"fieldLength": "value", [{
"fieldLabelfieldName": "value", // name of the field (ie }codeintervention, customer_ID, …)
{ ...
}],
"related":
[{"fieldType": "value", // type of the field : varchar, text, int, double, bool, datetime, timestamp, foreignkey
"entityNamefieldLength": "value", // length of the field : informed for "fields":varchar, text
[{
...
}]"fieldLabel": "value" // label of the field : depends on the value of the languageCode from the header (default : FR)
},
{
"entityNamefieldName": "value",
"fieldsfieldType": "value",
[{ "fieldLength": "value",
...
"fieldLabel": "value"
}]
},
{
...
}],
}] |
...
verb “DEFINITION”
La réponse aura 2 sections :.
Bloc de code |
---|
|
"response":
{
"responsedata":
{ [{
"data": [{// depends of the webhook
}],
As an example for contact
"generictype_ID_civility":
[{
"code": "CIVILITY-MR",
"label": "MisterMonsieur"
},
{
"code": "CIVILITY-MME",
"label": "Madame"
},
{
"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)
"canotBeNull": "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",
"canotBeNull": "value",
"dataType": "value"
},
{
...
}],
"related":
[{
"entityName": "value",
"fields":
[{
...
}]
},
{
"entityName": "value",
"fields":
[{
...
}]
},
{
...
}]
}] |
...