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


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

Nome opzioneStili supportatiApplicato a
AnagraphicCompanyTypeIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
AnagraphicIndustryIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
AnagraphicSourceIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
BusinessRolesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • Csv
  • CsvOfIds
  • CsvOfNames
  • Id
CommercialZoneStyle
  • AdaptiveCode
  • AdaptiveDescription
  • AdaptiveExternalReference
  • AdaptiveStringOnlyCode
  • AdaptiveStringOnlyDescription
  • Id
CompanyCategoriesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • CsvOfIds
  • CsvOfNames
  • Id
CompanyIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
ContactCategoriesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • CsvOfIds
  • CsvOfNames
  • Id
ContactIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
EmailStyle
  • Compact
  • Csv
  • FlattenedExpansion
  • Full
  • Tiny
  • ValueOnly
FreeFieldsStyle
  • AsValueOnlyParentProperties
  • Full
GeoLocalizationStyle
  • Full
  • GeoJSON
ImplicitConsentStyle
  • Compact
  • Full
LeadCategoriesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • CsvOfIds
  • CsvOfNames
  • Id
LeadIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadPriorityIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadProductInterestIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadRatingIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadStatusIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
OpportunityCategoryStyle
  • AdaptiveDescription
  • AdaptiveExternalReference
  • AdaptiveStringOnlyDescription
  • FlattenedExpansion
  • Id
OpportunityIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
OpportunityPhaseStyle
  • AdaptiveDescription
  • AdaptiveExternalReference
  • AdaptiveStringOnlyDescription
  • FlattenedExpansion
  • Id
OwnerIdStyle
  • AdaptiveExternalReference
  • AdaptiveStringOnlyUserAccount
  • AdaptiveUserAccount
  • FlattenedExpansion
  • Id
  • StrictEmail
PhoneStyle
  • Compact
  • Csv
  • FlattenedExpansion
  • Full
  • Tiny
  • ValueOnly
PrivacySettingsStyle
  • Compact
  • Full
PrivacyTypeManagementIdStyle
  • AdaptiveCode
  • AdaptiveDescription
  • AdaptiveStringOnlyCode
  • AdaptiveStringOnlyDescription
  • AdaptiveStringOnlyTitle
  • AdaptiveTitle
  • Id
SalesPersonsStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveStringOnlyUserAccount
  • AdaptiveUserAccount
  • Csv
  • CsvOfIds
  • CsvOfNames
  • Id
TagsStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • Csv
  • CsvOfIds
  • CsvOfNames
  • Id


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".

NameValue
...
Is Searchable YES
...

Esempi:

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.


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"