Introduzione
Premessa e concetti di base
La seguente documentazione ha lo scopo di illustrare le funzionalità relative alle API REST esposte dal sistema.
Al fine di utilizzare agevolmente le API REST, è necessario possedere alcune nozioni di base circa i concetti e gli oggetti fondamentali.
Qualora si posseggano già tali competenze, è possibile saltare questo capitolo e procedere oltre.
Web API Controllers
Le funzionalità di interfacciamento e comunicazione API REST sono implementate tramite appositi Web API Controllers.
Ogni Controller contiene un set di funzionalità dette Actions.
Ogni Action costituisce un end-point del sistema, ed è invocabile via HTTP tramite un URL univoco ed uno specifico set di verbi HTTP
La sezione relativa al Routing illustra le modalità tramite le quali è possibile invocare le Actions dei Controller
Business Objects
Gli oggetti che rappresentano le entità del sistema (aziende, contatti, leads, opportunità, attività, etc) sono detti "Business Objects" (indicati per brevità con l'acronimo "BO")
La lista completa dei Business Objects è formalizzata nell'apposito enum "BusinessObjectType"
Ad ogni elemento dell'enum BusinessObjectType corrisponde uno specifico Business Object
Controllers dei Business Objects
I Business Objects costituiscono il cuore delle business logic del sistema, ed espongono le proprie funzioni tramite appositi end-points API REST detti "Web API controllers"
Al fine di interagire con un Business Object è necessario quindi individuare il corrispondente end-point. La sezione Controllers contiene la lista di tutti i controllers disponibili, indicandone per ognuno la tipologia. I controllers deputati all'interfacciamento con uno specifico Business Object sono marchiati tramite l'icona
La sezione relativa al Routing illustra le modalità tramite le quali è possibile invocare le Actions dei Controller
DTO (Data Transfer Objects)
I Business Objects sono entità molto complesse, ricche di informazioni e funzioni.
Risulterebbe poco pratico manipolarli direttamente tramite le Actions dei Controller (per l'ovvio motivo che oggetti e servizi sono entità programmatiche con semantiche d'uso molto differenti)
Per facilitarne l'utilizzo (ed in particolare, per semplificarne la rappresentazione JSON, per ogni Business Object esiste un corrispondente DTO, un "Data Transfer Object".
Lo scopo dei DTO è appunto quello di rappresentare, serializzare e trasportare i dati di un Business Object.
Le Actions dei Controller dei Business Objects ricevono in input e ritornano in output i DTO
Come precedentemente indicato, la lista completa dei Business Objects è formalizzata nell'apposito enum "BusinessObjectType"
Ad ogni elemento dell'enum BusinessObjectType corrisponde il DTO di uno specifico Business Object
La JSON⇄DTO⇄BO "transformation chain"
Come precedentemente detto, i BO vengono manipolati via JSON tramite la mediazione dei DTO.
I diagrammi a seguire rappresentano (in modo estremamente semplice e sintetico) la pipeline che "collega" il client (sulla sinistra) al database del backend (sulla destra) attraverso la JSON⇄DTO⇄BO "transformation chain"
Serialization (JSON←DTO←BO)
Deserialization (JSON→DTO→BO)
Autenticazione
Token JWT
Al fine di potere invocare le API REST, è necessario ottenere un token di autenticazione tramite l’apposito servizio /Auth/Login, al quale dovrà essere inviato un pacchetto JSON nella seguente forma:
{
"grant_type": "password",
"username": "admin@admin.com",
"password": "admin"
}
Il servizio ritornerà un token JWT (proprietà access_token) che dovrà essere utilizzato in tutte le chiamate successive tramite Bearer Authentication
{
"access_token": "my_jwt_token",
"expires_in": 1200,
"refresh_token": "5fc87399-413d-44de-8976-dc3d15e4b0bc",
"result": 0,
"token_type": "bearer"
}
Il flusso instaurato è il seguente:
Bearer Authentication
La "Bearer Authentication" (tradotta "autenticazione al portatore", detta anche "autenticazione token") è uno schema di autenticazione HTTP che coinvolge un token di sicurezza denominato bearer token.
Il nome "Autenticazione al portatore" può essere inteso come "concedere l'accesso al portatore di questo token".
Il bearer token è una stringa criptica o un hash, generalmente creata dal server in risposta a una richiesta di accesso.
Il client deve inviare questo token nel HTTP header Authorization quando si effettuano richieste a endpoint/risorse protette:
Lo schema "Bearer Authentication" è stato originariamente creato come parte di OAuth 2.0 nel RFC 6750, ma è spesso usato anche da solo. Analogamente alla Autenticazione di base (Basic authentication), la "Bearer Authentication" deve essere utilizzata solo su HTTPS (SSL).
Una tipica invocazione GET HTTP di un endpoint/risorsa API REST protetta è simile a questa:
GET https://myhost.com/api/latest/Company/Get/1 HTTP/1.1
Host: myhost.com
Connection: keep-alive
Accept: application/json, text/plain, */*
Origin: null
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Authorization: Bearer my_jwt_token
Accept-Encoding: gzip, deflate, br
Accept-Language: en,en-US;q=0.9,it-IT;q=0.8,it;q=0.7
API Key
L'API key è una stringa criptata che può essere utilizzata per invocare delle API che richiedono autenticazione.
Per creare un token di accesso, andare in SETUP => UTENTI => UTENTE.
Aprire il TAB "Web API Keys" e cliccare il bottone Aggiungi Web API Key per generare un token.
Per ogni token si può impostare la sicurezza che permette di limitare il tipo di azioni sugli oggetti principali.
Ad esempio, se si vuole esclusivamente inserire lead, si consigla di disabilitare tutte le funzionalità tranne il flag crea sulla riga lead.
Passare l'API key in una chiamata REST API come header o parametro di querystring con il seguente formato:
Sostituisci API_KEY con la tua API key,
apikey=API_KEY
Ad esempio, per passare l'API key ad una richiesta di nuova istanza per un lead:
GET http://api.crmincloud.it/api/latest/lead/GetNewInstance?apikey=API_KEY
Identificazione dell’applicazione chiamante
Alcune delle funzioni delle API REST possono essere utilizzate solamente se (oltre ad una corretta autenticazione dell’utente) si esegue anche una dichiarazione dell’applicazione chiamante.
Il nome dell’applicazione chiamante viene inviato al server tramite un apposito header HTTP:
Crm-ApplicationName
Qualora si sia in possesso di tale “Application Name”, è bene utilizzarla in tutte le chiamate verso il server.
GET https://myhost.com/api/latest/Company/Get/1 HTTP/1.1
Host: myhost.com
Connection: keep-alive
Accept: application/json, text/plain, */*
Origin: null
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Authorization: Bearer my_jwt_token
Accept-Encoding: gzip, deflate, br
Accept-Language: en,en-US;q=0.9,it-IT;q=0.8,it;q=0.7
Crm-ApplicationName: MyApplication
Controllers
La seguente lista contiene tutti i controllers Web API disponibili
- Account
- Activity
- Activity Sub Type
- Address
- Anagraphic Company Type
- Anagraphic Industry
- Anagraphic Interest
- Anagraphic Priority
- Anagraphic Rating
- Anagraphic Source
- Anagraphic Status
- Appointment
- Auth
- Calendar Configuration
- Calendar Event
- Catalog
- Catalog Categories
- Catalog Product Price
- Company
- Contact
- Contact Category
- Currency
- EMail Type
- Flow
- Flow Template
- Flow Trigger
- Groups
- Hook
- Lead
- List
- Mail Category
- Mailing
- Mailing Delivery
- Mailing Domain
- Mail Template
- Message
- Message Channel
- Opportunity
- Opportunity Category
- Opportunity Lost Reason
- Opportunity Phase
- Order
- Payment
- Payment Mode
- Phone Type
- Price List Description
- Privacy Activity Motivation Implicit Consent
- Privacy Management
- Privacy Motivations Implicit Consent
- Privacy Type Management
- Progressive Code
- Quote
- Referrer Category
- Relation Type
- Sales Performance Target
- Signature
- Storage
- Storage Categories
- Tag
- Tax Value
- Web Mail Account
- Work Plan
- Work Plan Status
- Zone
Errori
Le actions dei controllers possono generare errori per i seguenti casi:
- Stato 400: query mal strutturate (es. parametri codificati non correttamente)
- Stato 401: errori di autenticazione (es. chiavi o credenziali non riconosciute)
- Stato 403: Proibito. La richiesta era valida, ma il server rifiuta l'azione. L'utente potrebbe non disporre delle autorizzazioni necessarie per una risorsa o potrebbe aver bisogno di un account di qualche tipo.
- Stato 404: Non trovato, o risorsa sconosciuta
- Stato 409: Conflitto. Indica che la richiesta non può essere elaborata a causa di conflitti nello stato corrente della risorsa, ad esempio un conflitto di modifica tra più aggiornamenti simultanei.
- Stato 500: Errore interno del del server
Gli errori sono formattati in JSON
Versioning
E’ possibile selezionare la versione dei web services tramite il token {version}
/api/{version}/{controller}/{details}/{action}/{id}?{querystring}
Il token {version} può contenere sia valori “esatti”, sia l’alias speciale “latest”, che identifica la versione più recente tra quelle esistenti nel sistema.
In linea generale si raccomanda vivamente l’utilizzo dell’alias speciale “latest”.
Qualora si desideri essere particolarmente “conservativi” ed aderenti ad una specifica versione, specificarne il nome in modo esplicito (es. “v1”).
Routing
Il sistema utilizza la seguente sintassi di routing, costituita da una sequenza di "path-tokens" (i parametri della request):
{schema}://{host}/api/{version}/{controller}/{details}/{action}/{id}?{querystring}
I tokens identificano rispettivamente:
- {host} -> HOST dell’URL
- {version} -> versione dei web services
- {controller} -> nome del servizio (controller) che si desidera invocare
- {details} -> livello opzionale di dettaglio del JSON ritornato (se pertinente)
- {action} -> azione opzionale (metodo) invocata nel controller
- {id} -> singolo argomento opzionale (parametro) del metodo nel controller, qualora esso lo preveda
- {querystring} -> parametri aggiuntivi ed eventuali "modificatori" del processo di elaborazione e serializzazione
Opzioni
Le funzioni delle API REST implementate in CRM in Cloud includono un vasto set di opzioni che consentono di adattare struttura e forma dei pacchetti JSON in base alle proprie esigenze e preferenze.
Al contrario dei parametri, che vengono specificati nella route dell’URL (attraverso i tokens e la querystring), le opzioni devono invece essere passate tramite gli headers HTTP della request.
Come da RFC6648 tutte le opzioni passate tramite headers HTTP hanno nel proprio nome il prefisso custom “Crm-”.
Qualora una certa opzione non venga specificata, il sistema utilizzerà il valore di default specifico alla {version} indicata nell’URL.
Di seguito vengono elencate le opzioni disponibili, e sinteticamente descritti i relativi valori accettati.
Opzioni di formattazione globale
Le opzioni di formattazione globale consentono un controllo di alto livello sul comportamento del serializzatore/deserializzatore, determinando le caratteristiche generali del JSON restituito/accettato.
Crm-TypeNameHandling
- None: il JSON non contiene alcun type name per gli oggetti rappresentati
- Objects: il JSON contiene i type names per gli oggetti rappresentati
- RootOnly: il JSON contiene il type name dell'oggetto al livello della root
Crm-NullValueHandling
- Ignore: non serializzare le properties aventi valore NULL
- Include: serializzare anche le properties aventi valore NULL
Crm-NamingStrategy
- AsIs: le properties vengono serializzate con nome uguale a quello del codice sorgente
- UpperCamelCase: viene applicata la naming convention “Pascal Case”
- LowerCamelCase: viene applicata la naming convention “Camel Case”
- SnakeCase: viene applicata la naming convention “Snake Case”
- KebabCase: viene applicata la naming convention “Kebab Case”
Crm-Formatting
- None: il JSON non viene indentato, e risulta su un’unica riga di testo
- Indented: Il JSON viene indentato (tabbing=1)
Crm-WebApiRules è una lista CSV di regole (separate da virgola) da attivare per processare la richiesta. I valori correntemente supportati sono:
- LeadMustBeUniqueByEmail=VALUE: Quando VALUE è true, il lead creato deve avere un indirizzo email univoco all'interno del database. Quando VALUE è false (o la regola non è specificata nella lista CSV) la regola è ignorata
Serializzazione polimorfica
Come già indicato nella sezione delle Opzioni, le funzioni delle API REST implementate in CRM in Cloud includono un vasto set di funzioni che consentono di adattare struttura e forma dei pacchetti JSON in base alle proprie esigenze e preferenze.
Consultare la sezione delle Opzioni per ottenere tutti i dettagli relativi al loro uso
Opzioni di serializzazione polimorfica supportate
Le opzioni di serializzazione polimorfica agiscono ad un livello altamente granulare, consentendo una customizzazione più “chirurgica” di quanto sia possibile fare con le opzioni di formattazione.
Clicca su un'opzione tra quelle indicate di seguito per visualizzare una breve guida circa il suo utilizzo (il prefisso "Crm-" delle opzioni è omesso per brevità).
Nota sugli enums: le proprietà di tipo enum sono trattate in una sezione specifica
Enums polimorfici
Numerose proprietà degli oggetti di sistema sono di tipo enum.
Al fine di semplificarne la serializzazione polimorfica, è disponibile un set unificato di stili (opzionali) per ognuna di esse:
- AdaptiveString: serializza l'enum come stringa.
- AdaptiveInteger: serializza l'enum come valore numerico equivalente
Per maggiori dettagli circa la serializzazione polimorfica degli enum, fare riferimento all'apposita documentazione
External References
Molti Business Object (e relativi DTO) di CRM in Cloud possono essere associati ad una "external reference", cioè l'entità corrispondente di un altro sistema di terze parti.
Le "external references" sono quindi relazioni logiche tra una entità nativa di CRM in Cloud e la corrispondente entità di un sistema esterno.
Esse vanno viste come meta-dati puramente descrittivi, ed esistono a solo beneficio dei mappings effettuati dai sistemi di sincronizzazione.
Tipicamente le "external references" non sono coinvolte in nessun processo interno di CRM in Cloud.
Esempio: companies ed accounts
A titolo di esempio, si assuma che CRM in Cloud venga sincronizzato (tramite plugins o altri meccanismi basati sulle API REST) con altri N sistemi.
Ognuno di questi N sistemi sarà discriminato da CRM in Cloud tramite un identificativo specificato nel parametro Crm-ApplicationName.
Ogni account (o qualsiasi altro Business Object) di CRM in Cloud potrà avere quindi una "controparte" di tale entità per ognuno degli N sistemi esterni.
La property CompanyDTO.ownerId rappresenta l'owner (un account di CRM in Cloud) della company.
Il seguente diagramma illustra le relazioni descritte:
Serializzazione polimorfica delle properties che rappresentano external references
La property CompanyDTO.ownerId può essere serializzata tramite svariati stili (vedi sezione apposita sulla serializzazione polimorfica del campo "ownerId").
Uno di questi stili di serializzazione è AdaptiveExternalReference.
Usando lo stile AdaptiveExternalReference, ogni “owner“ (account) è rappresentato da una stringa che contiene lo username dell’account corrispondente nel database del client chiamante.
Come precedentemente detto, il valore corretto da restituire viene determinato utilizzando quanto specificato in Crm-ApplicationName.
GET
Quando si esegue una richiesta in GET di un DTO, la property per la quale è specificata un'opzione di serializzazione polimorfica che supporta lo stile AdaptiveExternalReference, assume il seguente valore:
- la stringa presente nel campo "External Reference Value" (vedi diagramma precedente), se essa è non nulla e non vuota
- Il nome/codice del Business Object di CRM in Cloud in caso "External Reference Value" (vedi diagramma precedente) sia vuota o nulla (o nel caso non siano presenti associazioni)
PUT/POST
Quando si esegue una richiesta in PUT/POST di un DTO, la property per la quale è specificata un'opzione di serializzazione polimorfica che supporta lo stile AdaptiveExternalReference, tratta i valori ricevuti come segue:
- Se viene inviato un valore stringa, esso viene utilizzato per risolvere (nel campo "External Reference Value" del diagramma precedente) il relativo valore intero dell'ID/PK del record "External Reference Table" (associato alla tabella del Business Object corrispondente). Se non esiste un record avente la stringa data, viene ritornato un errore.
- Se viene inviato un intero, esso sarà considerato come l'id numerico precedentemente menzionato (ID/PK della tabella "External References Table" del diagramma precedente).
Emulazione
Come già indicato nella sezione delle Opzioni, le funzioni delle API REST implementate in CRM in Cloud includono un vasto set di funzioni che consentono di adattare struttura e forma dei pacchetti JSON in base alle proprie esigenze e preferenze.
Consultare la sezione delle Opzioni per ottenere tutti i dettagli relativi al loro uso
Opzioni di emulazione
Qualora fosse necessario emulare il comportamento della precedente versione delle API REST (Tustena 17), è possibile (per quanto sconsigliato) utilizzare la seguente opzione.
- Crm-EmulateWebApiVersion
- Non specificato: Nessuna emulazione viene attivata
- v9: emula il comportamento delle API REST di precedente generazione (Tustena 17)
OData
Le API REST sono internamente basate sulla tecnologia Microsoft WebAPI, e sono largamente compliant con le specifiche REST, OData v3 e OData v4.
OData compliancy
Esistono svariati metodi di ricerca basati su OData.
L’attuale implementazione supporta una significativa porzione delle URL conventions di OData v3 ed alcune URL conventions e funzioni di OData v4
Criteri OData
Negli URL di ricerca basati su OData è possibile specificare il seguente set di criteri:
- Top
- Skip
- OrderBy
- Filter
- Select
Ricerca di ID tramite OData
Il seguente URL ritorna gli ID dei BO trovati in base ai criteri specificati.
GET: /api/{version}/{controller}/SearchIds ?
- $filter = filter &
- $orderby = order criteria &
- $skip = items to skip &
- $top = max items to return
Se invocato tramite POST, questo URL consente di specificare i criteri OData per mezzo di un JSON invece che tramite parametri dell’URL (utile per evitare escaping dei dati).
Esempio:
"filter": "id eq 1 or (id gt 3 and id lt 10)",
"orderby": "id asc",
"top": "100",
"skip": "0",
"select": "id,companyName,billed"
Ricerca di BO/DTO tramite OData
Il seguente URL ritorna i DTO in formato JSON dei BO trovati.
GET: /api/{version}/{controller}/Search ?
- $filter = filter &
- $orderby = order criteria &
- $skip = items to skip &
- $top = max items to return
Se invocato tramite POST, questo URL consente di specificare i criteri OData per mezzo di un JSON invece che tramite parametri dell’URL (utile per evitare escaping dei dati).
Esempio:
"filter": "id eq 1 or (id gt 3 and id lt 10)",
"orderby": "id asc",
"top": "100",
"skip": "0",
"select": "id,companyName,billed"
Diagnostica criteri OData
Il seguente URL consente di testare il parser OData, ottenendo come risultato un JSON che rappresenta i valori dei parametri Odata passati nella querystring o nel POST.
GET: /api/{version}/{controller}/GetODataQueryParameters
$filter – operatori logici
Le espressioni del parametro $filter supportano i seguenti operatori logici:
- eq -> Equal
- ne -> Not Equal
- gt -> Greater Than
- ge -> Greater Than or Equal
- lt -> Less Than
- le -> Less Than or Equal
- and -> Logical And
- or -> Logical Or
Per maggiori dettagli fare riferimento alle relative specifiche OData v3
$filter – operatori aritmetici
Le espressioni del parametro $filter supportano i seguenti operatori aritmetici:
- add -> somma
- sub -> sottrazione
- mul -> moltiplicazione
- div -> divisione
- mod -> modulo
Per maggiori dettagli fare riferimento alle relative specifiche OData v3
Esempi
- add -> /api/latest/Company/Search?$filter=Billed+add+5+eq+15
- sub -> /api/latest/Company/Search?$filter=Billed+sub+5+eq+25
- mul -> /api/latest/Company/Search?$filter=Billed+mul+5+eq+100
- div -> /api/latest/Company/Search?$filter=Billed+div+5+eq+5
- mod -> /api/latest/Company/Search?$filter=Billed+mod+5+eq+0
$filter – funzioni canoniche
Le espressioni del parametro $filter supportano le seguenti funzioni canoniche:
- startswith
- endswith
- length
- indexof
- replace
- substring
- substringof
- tolower
- toupper
- trim
- concat
Per maggiori dettagli fare riferimento alle relative specifiche OData v3
Esempi
- startswith: /api/latest/Company/Search?$filter=startswith(companyName,'ACME')+eq+10
- endswith: /api/latest/Company/Search?$filter=endswith(companyName,'srl')+eq+10
- contains: /api/latest/Company/Search?$filter=contains(companyName,'srl')
- length: /api/latest/Company/Search?$filter=length(companyName)+eq+10
- indexof: /api/latest/Company/Search?$filter=indexof(companyName,'S')+eq+7
- replace: /api/latest/Company/Search?$filter= replace(companyName,'srl','s.r.l.')+eq+'acme+s.r.l.'&$top=10&$skip=0
- substring (1 argomento): /api/latest/Company/Search?$filter=substring(companyName,1)+eq+'do'
- substring (2 argomenti): /api/latest/Company/Search?$filter=substring(companyName,1,2)+eq+'do'
- substringof: /api/latest/Company/Search?$filter=substringof('srl',companyName)
- tolower: /api/latest/Company/Search?$filter=tolower(companyName)+eq+'my+company+name'
- toupper: /api/latest/Company/Search?$filter=toupper(companyName)+eq+'MY+COMPANY'
- trim: /api/latest/Company/Search?$filter=trim(companyName,1)+eq+'my+company'
- concat: /api/latest/Company/Search?$filter=concat(companyName,Code)+eq+'My+companyABC'
Elementi correlati
I {controller} WebApi sono in grado di rilevare parametri OData qualora essi siano specificati negli URL delle richieste degli elementi correlati/figli.
L’attuale implementazione supporta:
- Top
- Skip
- OrderBy
- Filter
- Select
Di seguito alcuni esempi relativi all’applicazione di OData ai webservice
Elementi correlati - top
Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$top=10
Esempio -> GET: /api/{version}/Company/1/Contacts?$top=10
Elementi correlati - skip
Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$skip=10
Esempio -> GET: /api/{version}/Company/1/Contacts?$skip=10
Elementi correlati - paginazione
Combinando $top e $skip è possibile eseguire la paginazione del resultset
Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$top=10&$skip=50
Esempio -> GET: /api/{version}/Company/1/Contacts?$top=10&$skip=50
Elementi correlati - orderby
Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$orderby=criteria
Esempio -> GET: /api/{version}/Company/1/Contacts?$orderby=Id%20desc
Elementi correlati - filter
Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$filter=criteria
Esempio -> GET: /api/{version}/Company/1/Contacts?$filter=CompanyId%20eq%201
Elementi correlati - select
Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$select=csv
Esempio -> GET: /api/{version}/Company/1/Contacts?$select=id,companyName
Elementi correlati - altri esempi
GET:
/api/{version}/Company/1/Activities?$filter=Subject%20eq'Appuntamento'&$top=10&$skip=5&$orderby=Description%20desc
GET:
/api/{version}/Company/1/Contacts?$filter=Name%20eq%20'Damiano'
Tipi dati primitivi supportati da OData
Il parser OData supporta i seguenti tipi dati primitivi:
- numeri interi
- numeri non interi
- stringhe
- bool
- data/ora (vedi paragrafo a seguire)
Nello specifico, i tipi MS.NET supportati sono:
- System.Byte
- System.SByte
- System.UInt16
- System.Int16
- System.UInt32
- System.Int32
- System.Int64
- System.UInt64
- System.Single
- System.Double
- System.Decimal
- System.String
- System.DateTime (vedi paragrafo a seguire)
OData ed i campi di tipo enum
Il parser OData supporta svariati tipi enum, ma è bene ricordare che essi vanno espressi tramite l'equivalente valore stringa, non tramite il valore numerico nativo.
Esempi:
GET:
/api/{version}/Company/1/Opportunities?$filter=status eq 'Suspended'
GET:
/api/{version}/Opportunity/SearchIds?$filter=status eq 'Suspended'
OData ed i campi di tipo data/ora
Il parser OData supporta i campi di tipo data/ora (System.DateTime).
E' possibile esprimere una data/ora in diversi modi (sia in formato OData v3 che OData v4).
Di seguito alcuni esempi corretti, ed alcuni esempi errati.
Esempi corretti in formato OData v3:
- $filter=myDateTimeField eq datetime'2015-07-28T10:23:00Z'
- $filter=myDateTimeField eq datetime'2015-07-28T10:23:00.1Z'
- $filter=myDateTimeField gt datetime'2015-07-28T10:23:00.12Z'
- $filter=myDateTimeField lt datetime'2015-07-28T10:23:00.123Z'
- $filter=myDateTimeField eq datetime'2015-07-28T10:23:00.1234Z'
- $filter=myDateTimeField gt datetime'2015-07-28T10:23:00.12345Z'
- $filter=myDateTimeField eq datetime'2015-07-28T10:23:00.123456Z'
- $filter=myDateTimeField lt datetime'2015-07-28T10:23:00.1234567Z'
Esempi corretti in formato OData v4:
- $filter=myDateTimeField eq 2015-07-28T10:23:00Z
- $filter=myDateTimeField eq 2015-07-28T10:23:00.1Z
- $filter=myDateTimeField gt 2015-07-28T10:23:00.12Z
- $filter=myDateTimeField lt 2015-07-28T10:23:00.123Z
- $filter=myDateTimeField eq 2015-07-28T10:23:00.1234Z
- $filter=myDateTimeField gt 2015-07-28T10:23:00.12345Z
- $filter=myDateTimeField eq 2015-07-28T10:23:00.123456Z
- $filter=myDateTimeField lt 2015-07-28T10:23:00.1234567Z
Esempi errati:
- $filter=myDateTimeField eq '2015-07-28T10:23:00.1Z'
- $filter=myDateTimeField eq cast(2015-07-28T10:23:00Z)
Properties ricercabili e non ricercabili
Non tutte le properties dei DTO sono ricercabili via OData.
Per verificare se una determinata property è ricercabile, visitare l'apposito riferimento documentale e verificare quanto indicato alla voce "Is Searchable".
| Name | Value |
|---|---|
| ... | |
| Is Searchable | YES |
| ... |
Esempi:
- Property ricercabile: CompanyDTO.address
- Property non ricercabile: CompanyDTO.boStatus
NOTA IMPORTANTE
LE COMPARAZIONI TRA STRINGHE SONO REGOLATE DALLE IMPOSTAZIONI DI COALESCE A LIVELLO DI DATABASE SQL SERVER.
NE CONSEGUE CHE, ANCHE SE ALCUNE FUNZIONALITA' DI ODATA RISULTANO IMPLEMENTATE, IL LORO COMPORTAMENTO E' INFLUENZATO DA TALI IMPOSTAZIONI E POTREBBE GENERARE RISULTATI INATTESI.
E' NECESSARIO QUINDI TENERE IN CONSIDERAZIONE QUESTO ASPETTO QUANDO SI ESEGUONO OPERAZIONI IN CUI LA CASE-SENSITIVITY E' RILEVANTE.
Free Fields
Molti Business Object (e relativi DTO) sono customizzabili, ed è quindi possibile definire per ognuno un diverso set di campi custom.
Tali campi custom sono detti Free Field.
I Free Field sono campi custom definibili dall'utente, e possono contenere dati di svariata natura.
Ogni Free Field ha un tipo dati specifico (selezionato in fase di configurazione), e sulla base di tale tipo, i dati del campo seguono determinate regole di validazione.
Free Field e polimorfismo
Come per molti altri campi, anche i Free Field godono delle proprietà di polimorfismo, ed è quindi possibile selezionare molteplici stili di serializzazione/deserializzazione.
Per maggiori dettagli, fare riferimento all'apposito paragrafo descrittivo sulla serializzazione dei Free Field
Free Field e OData
I Free Field sono utilizzabili nelle ricerche OData come selettori di campo (criterio $select).
Al fine di poterli discriminare dagli altri campi standard del Business Object, è necessario specificare il prefisso "FF_"
Esempio:
GET: /api/{version}/Company/Search?$select=id,companyName,FF_MyCustomFreeField1,FF_AnotherFreeField
Business Objects che supportano Free Field
La lista che segue contiene tutti i controllers relativi a Business Objects che supportano la definizione e l'uso dei Free Fields.
- Account
- Activity
- Address
- Catalog
- Catalog Product Price
- Company
- Contact
- Lead
- Opportunity
- Order
- Quote
- Storage
Glossario
Glossario dei termini
Di seguito una lista dei termini maggiormente utilizzati in queste documentazioni
Business Object -> Gli oggetti che rappresentano le entità del sistema (aziende, contatti, leads, opportunità, attività, etc) sono detti "Business Objects" (indicati per brevità con l'acronimo "BO"). Per maggiori dettagli fare riferimento alla sezione introduttiva
BO -> Acronimo usato per fare riferimento ai "Business Objects". Per maggiori dettagli fare riferimento alla sezione introduttiva
DTO -> Acronimo di Data Transfer Objects. Per ogni Business Object esiste un corrispondente DTO, un "Data Transfer Object". Lo scopo dei DTO è quello di rappresentare, serializzare e trasportare i dati di un Business Object. Per maggiori dettagli fare riferimento alla sezione introduttiva
Controller -> Porzione del URL di routing di un end-point API REST. Vedi anche "routing". Per maggiori dettagli fare riferimento alla sezione introduttiva
Action -> Funzionalità RPC di un controller, invocabile tramite l'URL di routing di un end-point API REST. Vedi anche "routing". Per maggiori dettagli fare riferimento alla sezione introduttiva
Polymorphic Serialization -> Serializzazione polimorfica. Le opzioni di serializzazione polimorfica agiscono ad un livello altamente granulare, consentendo una customizzazione più “chirurgica” di quanto sia possibile fare con le opzioni di formattazione. Alcune properties dei DTO sono marchiate come "polimorfiche". Per tali properties è possibile specificare uno stile di serializzazione, che ne modifica forma e struttura. Per maggiori dettagli, fare riferimento alla sezione delle opzioni
Logical Primitive -> Alcune properties dei DTO sono marchiate come "Logical Primitive". Per "tipo primitivo" si intendono:
- Stringhe
- Numeri (sia interi che decimali)
- Date (ed intervalli temporali)
- Boolean
- Enums (sia in formato intero che stringa)
BusinessObjectType -> la lista completa dei Business Objects è formalizzata nell'apposito enum "BusinessObjectType". Per maggiori dettagli fare riferimento alla sezione introduttiva
ForeignKey -> Foreign key, o "chiave esterna". Alcune properties dei DTO sono marchiate come "Foreign key". Tali properties sono deputate a contenere il valore di associazione (tipicamente un ID numerico) tra un oggetto/DTO/BO "master" ed un oggetto correlato "detail".
List -> Lista. Alcune properties dei DTO sono marchiate come "Foreign key". Tali properties sono deputate a contenere il valore di associazione (tipicamente un ID numerico) tra un oggetto/DTO/BO "master" ed un oggetto correlato "detail". Alcune "Foreign keys" possono contenere un legame con una lista di oggetti/DTO/BO
Virtual Property / Aliased Property -> si tratta di un alias di una property fisica di un DTO/BO. Ad esempio, la property "NormalizeEmail" di CompanyDTO è serializzata come "emails"