La procedura PEOPLELINK, soluzione Sistemi per gestire la rilevazione/gestione presenze e i processi HR, è integrata con la procedura JOB.

L'integrazione permette uno scambio di dati fra le due procedure, sia in avviamento sia per gli allineamenti successivi.

I flussi di integrazione fra le due procedure sono:

·         il trasferimento dei dati riferiti a ditte, lavoratori, rapporti di lavoro da JOB a PEOPLELINK, attività utile sia in fase di avviamento sia a regime per allineare costantemente i dati.
I dati comuni fra le due procedure sono quindi inseriti in JOB e trasferiti automaticamente in PEOPLELINK.
Prima di avviare l'integrazione è necessario impostare il codice rilevazione presenze sui Rapporto di lavoro imputando un codice numerico univoco per dipendente/ditta

·         l'invio da PEOPLELINK a JOB dei calendari presenze per consentire l'acquisizione delle presenze, utili all'elaborazione automatica cedolini.

Per realizzare il collegamento fra PEOPLELINK e JOB definite:

·         in PEOPLELINK:

o   il collegamento attraverso la funzione Configurazione integrazione con Sistemi, che invia automaticamente una mail con i dati di registrazione dell'installazione

o   i parametri di configurazione

·         in JOB, il collegamento con l'installazione PEOPLELINK.

Collegamento con JOB

Le informazioni da PEOPLELINK a JOB sono contenute in file .CSV e il loro trasferimento avviene tramite servizi REST, procedete come da flusso di seguito riportato.

Parametri di integrazione

Sono proposti dei parametri standard che si possono personalizzare:

·         categorie dipendenti da importare

·         esclusione dipendenti cessati

·         esclusione dipendenti con codice rilevazione presenze non valorizzato

 disattivate il campo in caso di riassunzione e in JOB è stato riportato nel nuovo rapporto di lavoro lo stesso codice rilevazione presenze del vecchio rapporto di lavoro. Se è attivo il calcolo automatico della matricola presenze è possibile importare tutti i rapporti di lavoro compresi quelli senza codice rilevazione presenze

·         disattivazione della sincronizzazione codice ATECO 2025

·         chiusura ruolo collaboratore quando il rapporto di lavoro viene chiuso

·         calcolo automatico delle matricole presenze
 deve essere utilizzata in caso di riassunzione se nel nuovo rapporto di lavoro viene riportato lo stesso codice rilevazione presenze. Non può essere utilizzata se l'impianto PEOPLELINK contiene delle anagrafiche non sincronizzate con JOB o JOB4. Dovete controllare che la gestione "Procedure" di PEOPLELINK sia configurata per utilizzare il campo matricola paghe per  generare il file del calendario presenze

·         configurazione e sincronizzazione dei residui
 disponibile nei prossimi rilasci

Collegamento con PEOPLELINK

Menu: Integrazioni gestionali > Integrazione con HR e Presenze > Integrazione con PEOPLELINK

Il destinatario della e-mail di registrazione deve inserire il codice collegamento ricevuto, in modo da realizzare il collegamento con PEOPLELINK; procedete come da flusso di seguito riportato.

 Per maggiori dettagli per attivare l'Accreditamento dell'installazione Accreditamento installazione.

 Per il corretto funzionamento dovete abilitare i seguenti link (Per le installazioni SIR non è necessario)

·         https://peoplelinkonlineacs.tuono.org (porta TCP/443)

·         https://webapi.peoplelinkonline.com (porta TCP/443)

Migrare il collegamento da JOBSQL a JOB4

Menu: Integrazioni con HR e Presenze > Integrazione con PEOPLELINK

In caso di un'installazione unificata JOB SQL-JOB4 potete migrare il collegamento da JOB SQL a JOB4; procedete come da flusso di seguito riportato.

Instaurare in JOB più collegamenti per la stessa ditta

Potete instaurare in JOB più collegamenti con diverse procedure (JOB RISORSE e PEOPLELINK) per la stessa ditta, in modo da facilitare la migrazione verso PEOPLELINK.

Menu: Integrazioni gestionali > Integrazione con HR e Presenze > Integrazione con PEOPLELINK

Per aggiungere delle ditte in un collegamento già instaurato con PEOPLELINK procedete come da flusso di seguito riportato.

L'acquisizione dei dati inviati da JOB in PEOPLELINK si compone delle seguenti fasi:

1.      invio dei dati: operazione da eseguire sull'installazione JOB solo se non avete schedulato l'invio dei dati, o se volete inviare i dati manualmente tra un invio schedulato e l'altro

2.      acquisizione dei dati: operazione eseguita automaticamente in PEOPLELINK e controllo esito importazione.
Per tutti i dettagli consultate la sezione "Configurare in PEOPLELINK i parametri oggetto di integrazione dati" della scheda Configurare l'integrazione.

Inviare i dati da JOB

Menu JOB: Integrazione con HR e Presenze > Integrazione con PEOPLELINK

I dati da inviare a PEOPLELINK sono:

·         l'anagrafica della ditta

·         l'anagrafica dei lavoratori e i dati dei rapporti di lavoro ("Soggetti e Dipendenti" in PEOPLELINK)

·         i contratti dei lavoratori somministrati e distaccati.

È necessario impostare il codice rilevazione presenze sui Rapporto di lavoro prima di avviare l'integrazione impostando un codice numerico univoco per Dipendente/Ditta.

L'invio può essere:

·         schedulato, per maggiori dettagli consultate la scheda Configurare l'integrazione

·         manuale, come di seguito descritto.

Acquisire i dati in PEOPLELINK

L'acquisizione dei dati predisposti da JOB avviene in modo automatico in PEOPLELINK e, al termine dell'acquisizione, visualizzate l'esito dell'importazione attraverso la funzione di menu: ADVANCED>Log servizi.

Selezionate la funzione "ImportAnagraficaJOB", impostate i filtri desiderati e avviate la ricerca.

Con il doppio clic su una riga, viene aperto il dettaglio del LOG:

In alternativa potete consultare i LOG seguendo il seguente flusso:

I LOG saranno visualizzati nel seguente elenco:

Configurare l'invio calendari

Per eseguire la configurazione necessaria all'invio delle presenze a JOB, procedete come da flusso di seguito riportato.

Preparare i dati per export e generazione file da inviare a JOB

Per eseguire la preparazione dei dati all'esportazione, procedete come da flusso di seguito riportato.

Configurare l'elaborazione automatica cedolini in JOB

Per configurare l'acquisizione dei file predisposti da PEOPLELINK ed eseguire l'elaborazione automatica cedolini, consultate la scheda Definire i parametri per l'elaborazione automatica cedolini.

Acquisire le presenze in JOB4

Per acquisire in JOB4 i dati inviati da PEOPLELINK procedete come segue:

Per eseguire la configurazione necessaria all'invio del codice PUC a JOB, procedete come da flusso di seguito riportato.

I dati oggetto dell'integrazione tra JOB a PEOPLELINK sono elencati nella seguente tabella:

I dati sono esportati con logiche diverse a seconda che si tratti del primo invio o di un invio successivo:

·         se si tratta del primo invio dei dati, i dati comprendono tutto lo storico, in base alle opzioni di invio dati indicate in configurazione

·         se sono invii periodici successivi al primo, i dati sono quelli validi alla data di sistema riferite ai rapporti di lavoro attivi o cessati da meno di 6 mesi.

È necessario impostare il codice rilevazione presenze sui Rapporto di lavoro prima di avviare l'integrazione impostando un codice numerico univoco per Dipendente/Ditta.

In casi particolari, se dovete rinviare tutto lo storico dei dati presenti in JOB (come avviene con il primo invio), utilizzare l'opzione Rinvia ditta.

Se i dati inviati da JOB sono diversi da quelli presenti in PEOPLELINK, l'acquisizione viene effettuata con le seguenti modalità:

·         in PEOPLELINK non è presente la data di storicizzazione del dato inviata da JOB: viene creata in PEOPLELINK la nuova data di storicizzazione

·         in PEOPLELINK è presente la stessa di storicizzazione del dato inviata da JOB: il contenuto della storicizzazione presente in PEOPLELINK viene sovrascritta con i dati inviati da JOB.

Classificazioni gestionali

Le classificazioni gestionali devono essere configurate come riportato nel seguente flusso:

Se dovete eliminare un collegamento attivato tra PEOPLELINK e JOB, seguite il flusso di seguito illustrato.

Autenticazione

L'accesso alle API avviene tramite autenticazione basata su Bearer Token.

Il token viene generato a partire da uno user e una password specifica per singola installazione. Una volta creata la credenziale, lo user non è più modificabile. Inoltre, la password è autogenerata e rimane visibile solo in fase di creazione; è comunque possibile richiedere un cambio password in qualunque momento, ma non sarà mai possibile, per l'assistenza Sistemi / Peoplelink recuperarla o visualizzarla in un secondo momento.

È possibile richiedere più utenze, per finalità diverse e con limitazioni differenti. Il token, di default, ha una validità di dieci minuti.

Il token deve essere inviato in ogni richiesta HTTP tramite header Authorization. Le richieste prive di token, con token non valido o con token scaduto verranno rifiutate dal sistema con un errore di autenticazione.

A corredo dell'header Authorization sarà obbligatorio indicare anche l'header X-PL-ApiToken, fornito anch'esso in fase di approvazione della richiesta di accesso.

Al contrario del Bearer Token, quest'ultimo header non ha scadenza.

Il sistema prevede l'utilizzo di due chiavi API distinte:

·         chiave per endpoint in lettura, denominata UniversaRead

·         chiave per endpoint in scrittura, denominata UniversaWrite.

Questa separazione permette di applicare un livello aggiuntivo di sicurezza e controllo sugli accessi. Gli endpoint in lettura sono generalmente utilizzati per recuperare dati dal sistema. Gli endpoint in scrittura sono utilizzati per creare, modificare o, in determinati casi, eliminare dati.

IP whitelist

Per ottimizzare il livello di sicurezza, l'accesso alle API può essere protetto anche tramite IP whitelist. Questo significa che le chiamate API sono consentite solo se provenienti da indirizzi IP preventivamente autorizzati.

Durante la richiesta di attivazione delle credenziali, il cliente o partner può comunicare gli indirizzi IP pubblici, sia essi singoli IP o range di indirizzi, sia IPv4 sia IPv6, dai quali verranno effettuate le chiamate. Se non verranno indicate limitazioni agli IP, le API saleranno questo layer di controllo. In caso contrario, le richieste provenienti da IP non presenti in whitelist verranno bloccate.

In caso di modifica dell'infrastruttura del cliente o partner, ad esempio cambio IP, nuova sede, nuovo server o nuovo ambiente cloud, sarà necessario richiedere l'aggiornamento della whitelist, senza l'obbligatorietà di cambiare o creare una nuova utenza di accesso.

Abilitazione degli endpoint

Ogni utenza API può essere configurata per accedere solo a determinati endpoint. Questo consente di limitare l'utilizzo delle API alle sole funzionalità necessarie per l'integrazione del cliente o partner.

La lista degli endpoint è recuperabile direttamente dallo swagger all'indirizzo https://webapi.peoplelinkonline.com/Swagger.

Di default, salvo indicazioni specifiche, tutti gli endpoint disponibili saranno abilitati. Nel caso in cui il cliente o partner abbia necessità di accedere solo a un sottoinsieme di API, tale informazione deve essere comunicata in fase di richiesta credenziali o successivamente tramite richiesta di ri-configurazione. L'aggiornamento della lista degli endpoint non comporta la necessità di cambiare o creare una nuova utenza di accesso.

Rate limit

Le API sono soggette a rate limit.

Il rate limit è un meccanismo che limita il numero massimo di richieste che un client può effettuare in un determinato intervallo di tempo. Questo sistema serve a:

·         garantire la stabilità del servizio

·         prevenire utilizzi anomali o eccessivi

·         proteggere l'infrastruttura da sovraccarichi

·         assicurare un utilizzo equo delle risorse tra tutti i clienti e partner.

Quando il limite viene superato, il sistema può restituire un errore HTTP 429 - Too Many Requests. A corredo, la response includerà alcuni header HTTP utili a conoscere lo stato corrente del rate limit, ovvero:

·         X-RateLimit-Limit: numero massimo di richieste consentite nella finestra temporale corrente

·         X-RateLimit-Remaining: numero di richieste ancora disponibili nella finestra temporale corrente

·         Retry-After: tempo, in secondi, da attendere prima di effettuare una nuova richiesta, normalmente presente in caso di errore 429.

Il client che utilizza le API deve gestire correttamente il rate limit, evitando di continuare a inviare richieste quando il limite è stato raggiunto.

In particolare, è consigliato:

·         leggere gli header di rate limit restituiti dal server

·         rallentare automaticamente l'invio delle richieste quando X-RateLimit-Remaining è basso

·         sospendere temporaneamente le chiamate in caso di risposta 429

·         rispettare il valore indicato da Retry-After, se presente

·         implementare meccanismi di retry controllato

·         evitare retry immediati e continui

·         utilizzare una strategia di backoff progressivo in caso di errori ripetuti.

Il rate limit impostato di default sulle API è di 20 chiamate al minuto per ogni end-point. È possibile richiedere una modifica di tale valore tramite lo stesso caso AOL o con un caso ad-hoc, indicando il tipo di esigenza, l'end-point coinvolto e il volume previsto di chiamate.

Sicurezza e gestione delle credenziali

Le credenziali API devono essere conservate in modo sicuro.

È responsabilità del cliente o partner evitare la condivisione non autorizzata di:

·         Bearer Token

·         X-PL-ApiToken

·         eventuali credenziali o informazioni tecniche/riservate associate all'utenza.

Le chiavi non devono essere inserite direttamente nel codice sorgente, soprattutto se versionato in repository condivisi.

È consigliato utilizzare sistemi sicuri di gestione dei segreti, come:

·         variabili d'ambiente

·         secret manager

·         vault aziendali

·         configurazioni cifrate.

In caso di sospetta compromissione delle credenziali, è necessario richiederne immediatamente la revoca e la rigenerazione. Inoltre, l'accesso alle API può essere revocato o limitato in caso di:

·         utilizzo non conforme

·         superamento ripetuto dei limiti consentiti

·         tentativi di accesso non autorizzati

·         utilizzo da IP non autorizzati

·         compromissione delle credenziali

·         violazione degli accordi contrattuali o tecnici.

Eventuali modifiche alla configurazione dell'utenza API, come aggiornamento IP, rigenerazione chiavi o abilitazione/disabilitazione endpoint, devono essere richieste tramite i canali di supporto previsti.

Scadenza delle credenziali

Le credenziali di accesso alle API possono essere soggette ad una data di scadenza.

La scadenza dell'utenza è definita manualmente, con indicazione di una data assoluta (es.: il 31/12/2027), e definisce il termine entro il quale le credenziali API risultano valide e utilizzabili per l'accesso agli endpoint autorizzati.

Quando un'utenza API si avvicina alla data di scadenza, il sistema segnala tale informazione tramite l'header HTTP di risposta Sunset. L'header Sunset viene valorizzato solo quando il tempo residuo alla scadenza effettiva è compreso nei 90 giorni precedenti la data di scadenza.

Fino alla data indicata nell'header, l'utenza può continuare a utilizzare le API, salvo eventuali revoche, limitazioni o sospensioni. Successivamente alla scadenza, le chiamate effettuate con tale utenza saranno considerate non valide e verranno rifiutate dal sistema.

La presenza dell'header Sunset non indica un errore nella chiamata, ma rappresenta un'informazione preventiva sulla futura scadenza dell'utenza API. L'assenza dell'header Sunset indica che, al momento della chiamata, l'utenza non si trova nella finestra di preavviso dei 90 giorni precedenti la scadenza oppure che non è prevista una scadenza configurata.

Logging delle chiamate API

Tutte le chiamate effettuate verso le API possono essere registrate dal sistema a fini di sicurezza, monitoraggio, audit e supporto tecnico. Il logging delle chiamate consente di tracciare l'utilizzo delle API e di verificare eventuali anomalie, errori applicativi, superamenti dei limiti di utilizzo o tentativi di accesso non autorizzati.

Le informazioni registrate possono includere, a titolo esemplificativo:

·         Data e ora della richiesta

·         Endpoint invocato

·         Metodo http

·         Indirizzo IP sorgente

·         Esito della chiamata

·         Codice HTTP restituito

·         Headers

·         Tempo di esecuzione

·         Eventuali indicazioni tecniche in caso di errori o eccezioni verificatesi in fase di chiamata agli endpoint.

Le API, acronimo di Application Programming Interface, sono interfacce software che permettono a sistemi diversi di comunicare tra loro in modo standardizzato.

Attraverso le API, clienti, Partner o sistemi esterni possono integrare le funzionalità del software PEOPLELINK all'interno delle proprie applicazioni, automatizzare processi, leggere dati, inviare informazioni o sincronizzare contenuti tra piattaforme differenti.

Le API esposte dal sistema sono progettate per consentire un'integrazione sicura, controllata e tracciabile, nel rispetto delle policy di autenticazione, autorizzazione, sicurezza e limiti di utilizzo definiti dal servizio.

La specifica tecnica completa degli endpoint disponibili è consultabile pubblicamente all'indirizzo https://webapi.peoplelinkonline.com/Swagger tramite documentazione Swagger / OpenAPI, che descrive nel dettaglio:

·         endpoint disponibili

·         metodi HTTP supportati

·         parametri richiesti e opzionali

·         struttura delle request

·         struttura delle response

·         codici di errore

·         snippet di esempio, per l'implementazione delle chiamate in vari linguaggi di programmazione.

La documentazione Swagger rappresenta il riferimento tecnico ufficiale per l'utilizzo delle API. Non saranno forniti PDF o materiale cartaceo/digitale differente dall'URL dello swagger, anche se richiesta del cliente o del Partner.

Nel linguaggio comune, il termine Swagger indica la pagina di documentazione tecnica attraverso cui consultare le API. Più precisamente, OpenAPI è il formato che descrive le API, mentre Swagger UI è l'interfaccia che rende quella descrizione navigabile. Swagger UI è predisposto anche per effettuare chiamate di prova agli endpoint, ma quest'ultima opzione non è attiva su PEOPLELINK.

Swagger permette quindi di capire come costruire una richiesta, quali informazioni inviare e quale risposta aspettarsi.

Orientarsi nell'interfaccia

L'interfaccia dello Swagger PEOPLELINK mette a disposizione due definizioni, selezionabili dal menu Select a definition posto in testata:

·         quella del servizio token ACS, dedicata all'autenticazione e all'ottenimento del token di accesso temporaneo

·         quella delle API applicative, che documenta le funzionalità disponibili per l'integrazione, con i relativi parametri, formati delle richieste e risposte previste.

Il primo passo è quindi scegliere la definizione corrispondente all'attività da svolgere: ottenere il token oppure consultare e utilizzare le API vere e proprie.

Nella sezione Servers sono indicati gli indirizzi dei due ambienti disponibili: produzione, destinato all'utilizzo operativo, e sviluppo, da utilizzare per le attività di sviluppo e test se si dispone di un ambiente di sviluppo dedicato.

È importante distinguere queste due selezioni: la definizione determina quale documentazione viene visualizzata, mentre il server mostra la destinazione che le chiamate dovranno avere. Prima di procedere, occorre verificare di aver scelto l'ambiente corretto e di utilizzare indirizzi e credenziali coerenti per il servizio ACS e per le API applicative, tenendo presente che i rispettivi URL sono distinti.

Scoprire come sono organizzate le API

Gli endpoint delle API sono categorizzati sulla base del modulo PEOPLELINK oppure, nel caso siano generali, ovvero validi per tutti i moduli, indicate come ALL. Sono anche categorizzati in base al fatto che siano in lettura o in scrittura (evidenziazione in rosso). Questa organizzazione permette di individuare l'area interessata senza dover esaminare subito tutti i percorsi disponibili. In sequenza, in ogni categoria, sono elencati tutti gli endpoint a quest'ultima associati (evidenziati in blu).

Nello Swagger PEOPLELINK, i metodi HTTP, indicati alla sinistra di ogni endpoint, non indicano che un determinato endpoint sia in scrittura (POST) o in lettura (GET). Non devono, quindi, essere interpretati secondo una corrispondenza RESTful/CRUD.

La regola pratica è: il metodo indica come inviare la richiesta; la documentazione indica che cosa farà il servizio.

Ogni riga di ogni endpoint ha una struttura così composta:

1.      metodo HTTP (GET o POST)

2.      path dell'endpoint, da concatenare con l'URL del server

3.      argomento e dati trattati dall'endpoint

4.      icona per copiare l'endpoint (a comparsa quando il mouse viene posizionato sopra uno specifico endpoint)

5.      icona per aprire tutti i dettagli dell'endpoint

Inoltre, dopo ogni nuovo rilascio in produzione, verrà aggiunto un badge grafico per indicare gli endpoint nuovi (NEW) o quelli che hanno subito una modifica (UPDATED). Sono previsti anche due badge speciali il cui scopo è indicare se l'endpoint è in beta (BETA) o in anteprima (PREVIEW).

Comprendere una scheda di dettaglio di un endpoint

Quando apri il dettaglio di un endpoint (clic sulla rispettiva riga), vengono mostrate tutte le informazioni necessarie al suo utilizzo, come spiegazione estesa, URL di destinazione, dati della request, formati, dati della response, snippet di codice, ecc.

Parametri e corpo della richiesta

I Parameters, presenti sia negli endpoint in GET che in POST, possono essere collocati nel path dell'URL, nella query string o negli header. La posizione è significativa: un valore documentato come parametro di header non va spostato arbitrariamente nel corpo della richiesta o in query string. Per ciascun parametro sono indicati il nome, il tipo, l'eventuale formato, l'indicazione di obbligatorietà, la posizione, una descrizione funzionale, eventuali valori di esempio, di default o consigliati.

Tutti gli endpoint PEOPLELINK richiedono sempre 4 parametri:

·         X-PL-ApiToken: APIKey per gli endpoint in lettura o in scrittura, generato su PEOPLELINK nella funzionalità Chiavi di accesso per le API

·         User-Agent: nome identificativo della procedura che sta eseguendo la chiamata; altamente consigliato utilizzare una nomenclatura del tipo NomeAzienda/NomeApplicativo 1.0 dove:

o   NomeAzienda indica la ragione sociale del cliente (senza spazi e senza caratteri diversi da A-Z e 0.9)

o   NomeApplicativo indica un nome di riferimento dell'applicativo o della procedura che sta utilizzando le API

o   1.0 indica la versione dell'applicativo

·         Accept-Language: Culture, tra quelle supportate da PEOPLELINK, da utilizzare per nelle response. Il default è it-IT

·         Accept-Encoding: indica l'encoding da utilizzare nella risposta; altamente consigliato impostarlo su gzip per ridurre la dimensione dei dati scambiati.

Altri parametri possono essere richiesti in base alle necessità dell'endpoint, principalmente per gli endpoint in GET.

Il Request body, presente negli endpoint di tipo POST, descrive invece il contenuto da inviare nel corpo della richiesta. Il tipo di contenuto, come application/json oppure application/x-www-form-urlencoded, fa parte del contratto dell'API: non è una preferenza liberamente sostituibile dal client. Il body può essere composto da uno o più elementi e nello schema vengono indicati, per ognuno, il nome, il tipo l'eventuale formato, l'indicazione di obbligatorietà, una descrizione funzionale, eventuali valori di esempio, di default o consigliati.

La sezione Example value, disposta alla sinistra dello Schema, aiuta a capire la forma dei dati, ma non va copiato senza sostituire i valori dimostrativi e verificare i requisiti. Per distinguere campi obbligatori, valori ammessi e formati, usa lo schema e le descrizioni, non soltanto l'esempio visualizzato.

Risposte e interpretazione degli errori e dei warning

La sezione Responses documenta le risposte previste per l'operazione selezionata, indicando gli stati HTTP, le relative descrizioni, la struttura del corpo della risposta ed eventuali header. Queste informazioni descrivono il comportamento atteso dell'API e non rappresentano la risposta effettivamente ricevuta durante un test.

La colonna Code elenca gli stati HTTP documentati. Per le API PEOPLELINK, tali stati devono essere interpretati come segue:

·         200: restituito sia se la risposta è valida sia se vengono riscontrati errori; Lo stato HTTP 200, da solo, non garantisce quindi il successo dell'operazione. In questo caso, il campo statusCode presente nel corpo della risposta indica l'esito applicativo:

o   200: Esito positivo

o   400: Con errori

·         401: token mancante o non valido. Il corpo della risposta è da ignorare

·         429: troppe richieste inviate in un breve lasso di tempo. Limite di frequenza superato

·         500: errore interno del server. Il corpo della risposta è da ignorare

·         Eventuali altri stati HTTP non documentati vanno sempre trattati come errori generali.

La colonna Description riporta la spiegazione dello stato HTTP e la documentazione del contenuto associato. Comprende lo schema della risposta, con la struttura delle proprietà, i nomi dei campi, i tipi di dato, i formati e le descrizioni funzionali. Quando previsti, oltre al corpo della risposta, alcune operazioni delle API PEOPLELINK possono restituire specifici header HTTP contenenti informazioni utili per la gestione dell'integrazione. Gli header non devono essere interpretati come parte del JSON restituito dall'API: appartengono alla risposta HTTP e devono quindi essere letti separatamente dal client. La loro presenza dipende dallo stato HTTP restituito e dalla condizione che si è verificata. Le API PEOPLELINK possono restituire i seguenti Header in response:

·         Warning: segnala la deprecazione del token e informa di pianificarne la sostituzione

·         Sunset: indica che sull'utenza è stata indicata una scadenza e che è necessario pianificare il rinnovo delle credenziali prima della data indicata

·         X-RateLimit-Limit: indica il limite massimo di chiamate consentite alle API in un determinato lasso di tempo

·         X-RateLimit-Remaining: indica il numero di richieste alle API ancora disponibili prima di raggiungerne il massimo in un determinato lasso di tempo

·         Retry-After: indica il numero di secondi da attendere prima che il rate limit si azzeri.

La colonna Links non è rilevante ai fini dell'integrazione e può essere ignorata.

Gli snippet di codice

Gli snippet sono frammenti di codice che mostrano come costruire una chiamata. Servono a passare dalla descrizione dell'API a una possibile implementazione nel proprio ambiente di sviluppo.

Lo Swagger PEOPLELINK mette a disposizione, su ogni endpoint, una sezione denominata Code snippets, con una serie di opzioni standard tra applicativi e linguaggi di programmazione. Al clic sul pulsante specifico, viene mostrato il rispettivo codice di esempio, con destinazione e metodo compilati sulla base del server selezionato, segnaposti e dei dati di esempio per gli Header, le QueryString, il Path e/o il Body. Gli snippet gestiti dallo swagger PEOPLELINK sono:

·         Postman

·         cURL

·         C# (HttpClient)

·         Python

·         Kotlin

·         Javascript (fetch)

·         Javascript (jQuery)

Considera lo snippet come un punto di partenza, non come un'integrazione pronta per la produzione. Nel codice applicativo prevedi anche la corretta gestione delle rate limit, timeout, controllo degli errori e protezione dei segreti. Verifica, quindi, che quella rappresentazione contenga i valori desiderati.

L'utilizzo delle API è riservato a clienti, partner o soggetti autorizzati. Per poter utilizzare le API PEOPLELINK è necessario creare una o più chiavi di accesso, ognuna composta da una serie di informazioni e configurazioni tecniche necessarie sia a tracciare gli utilizzatori e il motivo della creazione, sia per applicare configurazioni e/o limitazioni di accesso.

Tramite la funzionalità Chiavi di accesso per le API, presente nel modulo ADVANCED, puoi creare e gestire tutte le chiavi di accesso di cui necessiti.

Esempio: potresti voler creare una chiave di accesso da utilizzare su un software terzo per la sincronizzazione dei soli dati del timesheet, e un'altra chiave di accesso per integrare unicamente le unità organizzative con un differente servizio aziendale.

L'accesso a questa funzionalità è gestita, al pari di tutte le altre funzionalità di PEOPLELINK, ovvero tramite i Ruoli autorizzativi.

 Ti consigliamo di prestate la massima attenzione agli operatori a cui fornisci l'accesso, sia in lettura sia in scrittura.

Creare una nuova chiave di accesso alle API

Utilizza il pulsante Gestisci - Crea per avviare la procedura di creazione di una nuova chiave di accesso. La procedura di creazione è composta da due fasi distinte.

La prima fase prevede la compilazione delle informazioni fondamentali, ovvero lo username e la password da utilizzare per la richiesta del Token ACS oltre ai riferimenti tecnici.

Lo Userame ha una lunghezza minima di 10 caratteri, fino ad un massimo di 20 e deve essere univoco a livello globale.

La Password è sempre e obbligatoriamente generata da PEOPLELINK, ma può essere rigenerata più volte prima di essere salvata.

 La password viene criptata e protetta al momento del salvataggio e non potrà essere recuperata in nessun modo. Va quindi copiata con l'apposito tasto alla destra della casella di testo e memorizzarla in un luogo sicuro prima di salvare l'utenza.

La descrizione, ovvero il motivo per cui viene creata la chiave di accesso, e i dati del referente sono obbligatori.

Il rate limit è fisso e i campi sono sempre disabilitati. I valori vengono ereditati dalle policy globali di PEOPLELINK. Per approfondimenti su cosa è e come funziona un rate limit fare riferimento ai Concetti di base.

Una volta che tutti i campi sono compilati si può procedere al salvataggio utilizzando il pulsante Salva. A seguire, utilizzando il pulsante Gestisci - Modifica, potrai avviare la modifica della chiave di accesso appena creata al fine procedere con la fase 2, ovvero l'inizializzazione delle ApiKey di lettura e/o scrittura, insieme ad eventuali limitazioni specifiche.

Le API di PEOPLELINK prevedono una differenziazione tra gli endpoint che consentono l'accesso in lettura rispetto agli endpoint di scrittura. Per generare la rispettiva ApiKey è necessario cliccare sul pulsante Genera Key in corrispondenza della rispettiva casella di testo. L'ApiKey può essere rigenerata più volte, ma tutte le eventuali versioni precedenti vengono annullate e sostituite sempre da quella nuova.

Di default, tutti gli endpoint sono abilitati per essere utilizzati. E' possibile applicare delle restrizioni agli endpoint abilitati sulla specifica chiave di accesso che si sta modificando utilizzando i dropdown Endpoint abilitati in lettura ed Endpoint abilitati in scrittura per selezionare cosa può essere utilizzato. Per indentificare cosa fa ogni endpoint e quali sono le sue caratteristiche, fare riferimento allo swagger.

Nel caso in cui siano abilitati, in lettura, uno o più endpoint che operano sugli eventi anagrafici, sarà obbligatorio anche indicare un Profilo amministrativo degli eventi anagrafici, il cui scopo è quello di applicare delle limitazioni ai dati anagrafici che possono essere letti nelle API (es. dati retributivi, indirizzi, formazione, visite mediche, etc.). Nel caso non vuoi applicare nessuna limitazione, dovrai obbligatoriamente selezionare la voce Non applicare nessun Profilo amministrativo degli eventi anagrafici.

Un ulteriore limitazione che puoi applicare alle chiavi di accesso alle API è relativa agli indirizzi IP del chiamante. Il campo IP Whitelist ti consente di indicare gli indirizzi IP abilitati a chiamare gli endpoint associati a questa chiave di accesso. Puoi indicare singoli indirizzi o range di IP, sia in formato IPV4 che IPV6.

Una volta che tutti i campi sono compilati si può procedere al salvataggio utilizzando il pulsante Salva.

Modificare le limitazioni e rigenerare le ApiKey di una chiave di accesso

Per modificare le limitazioni oppure per rigenerare le ApiKey di una chiave di accesso alle API premi sul pulsante Gestisci - Modifica.

Lo Username e la descrizione non sono mai modificabili, mentre la password non è mai visibile dopo che la chiave di accesso è stata creata e salvata.

Tutte le altre configurazioni, ad eccezione del rate limit, sono modificabili e rigenerabili in qualsiasi momento. Le regole e le logiche di funzionamento sono le stesse indicate nella fase della creazione di un nuova chiave di accesso.

Modificare la password di una chiave di accesso

Puoi modificare la password di una chiave di accesso alle API rigenerandola.

Così come avviene in fase di creazione di una nuova chiave di accesso, la Password è sempre e obbligatoriamente generata da PEOPLELINK, ma può essere rigenerata più volte prima di essere salvata.

 La password viene criptata e protetta al momento del salvataggio e non potrà essere recuperata in nessun modo. Va quindi copiata con l'apposito tasto alla destra della casella di testo e memorizzarla in un luogo sicuro prima di salvare il cambio password.

Il sistema distingue gli accessi API in base alla tipologia di operazione da eseguire, prevedendo due chiavi distinte:

·         UniversaRead, dedicata agli endpoint in lettura

·         UniversaWrite, dedicata agli endpoint in scrittura.

Gli endpoint associati alla chiave UniversaRead permettono esclusivamente il recupero di dati già presenti nel sistema PEOPLELINK. Si tratta quindi di API pensate per consultare informazioni, esportare dati o alimentare sistemi esterni, senza apportare modifiche ai dati presenti nell'impianto.

Gli endpoint associati alla chiave UniversaWrite, invece, permettono l'invio di dati verso PEOPLELINK con finalità di creazione, aggiornamento o, dove previsto, eliminazione. Le API di scrittura non operano come semplici chiamate dirette di salvataggio, ma sfruttano lo stesso sistema interno di import avanzato disponibile nel modulo DOCKS, già utilizzato per gli import da file.

Questo significa che i tracciati disponibili per la scrittura via API sono gli stessi previsti dagli import avanzati del portale, con la differenza che:

·         tramite interfaccia DOCKS i dati vengono forniti mediante file Excel

·         tramite API i dati vengono forniti in formato JSON.

La logica di validazione, elaborazione e controllo rimane coerente con quella dell'import avanzato. Ogni richiesta di scrittura viene analizzata e validata formalmente; se i dati risultano corretti, l'elaborazione viene inserita in una coda dedicata ed eseguita in modalità asincrona. Sarà poi possibile consultare lo stato dell'elaborazione tramite un apposito endpoint.

Le API di scrittura seguono una logica all-or-nothing: se durante la validazione o l'elaborazione viene rilevato anche un solo errore, l'intero import viene annullato e nessun dato viene scritto su PEOPLELINK. Gli import eseguiti tramite API, sia conclusi correttamente sia terminati con errori, possono essere consultati anche dal modulo DOCKS per un periodo determinato, con la possibilità di verificarne l'esito e i dati elaborati.

In conclusione, la chiave UniversaRead abilita l'accesso ai dati in sola consultazione, con model in response specifici per ogni endpoint, mentre la chiave UniversaWrite abilita operazioni di scrittura controllate, validate e tracciate attraverso il motore di import avanzato di PEOPLELINK, condiviso con quello in interfaccia di DOCKS.

Il set di API indicate come Import avanzato e raccolte, nello swagger, sotto il tag ALL (Scrittura) rappresentano il canale ufficiale attraverso cui software esterni possono scrivere dati all'interno di PEOPLELINK. Si tratta di tre endpoint che lavorano in sequenza e in modo asincrono, formando un flusso completo: scoperta della struttura dati, invio dei dati, monitoraggio dell'elaborazione.

Il principio architetturale di fondo è la generalità: anziché esporre un endpoint per ogni entità, viene offerto un unico punto di ingresso capace di gestire tipologie di import diverse, differenziate dal codice implementativo impl passato nella chiamata. Questo riduce la superficie dell'API pubblica e uniforma il comportamento per tutti i moduli.

Flusso operativo

Il flusso inizia con GetJsonExample, un endpoint di supporto che restituisce un template JSON completo per la tipologia di import desiderata. Il template include i nomi di tutti i fogli previsti, le colonne necessarie e dati mock di esempio. Può essere ottenuto in formato grezzo con commenti esplicativi oppure come JSON valido e immediatamente utilizzabile. Questo endpoint elimina la necessità di consultare documentazione esterna: il contratto dati è autodocumentato e sempre aggiornato.

Una volta costruito il JSON con i dati reali, si procede con SendJson, il cuore del sistema. L'endpoint riceve un body strutturato a fogli, dove ogni foglio rappresenta una categoria di dati e contiene una lista di righe, ognuna a sua volta composta da celle chiave-valore. Prima di qualunque elaborazione, il sistema esegue una pre-validazione sincrona: se il JSON è malformato o contiene errori strutturali, la risposta lo segnala immediatamente senza accodare nulla. Se invece la validazione ha esito positivo, l'import viene messo in coda per l'elaborazione asincrona e viene restituito un identificativo univoco. Il comportamento in caso di sovrapposizione con dati già presenti è controllabile tramite due parametri: l'algoritmo di upsert aggiorna i record esistenti identificandoli univocamente, mentre il flag di upsert parziale permette di scegliere se sovrascrivere il record per intero o aggiornare soltanto i campi effettivamente presenti nel JSON. Per alcuni import, è possibile indicare anche un algoritmo di post-elaborazione specifico, da eseguire al termine dell'import. La gestione è ALL-OR-NOTHING: se anche un solo record presenta un errore in fase di elaborazione, l'intero import viene annullato e nulla viene scritto sul database.

Una volta ottenuto l'identificativo dell'import, il chiamante deve interrogare CheckState per sapere come procede l'elaborazione. L'endpoint riceve l'ID e il codice di tipologia, e restituisce uno stato che può essere: completato con successo, in errore, ancora in coda, oppure sconosciuto. In caso di errore, viene fornita la lista dei messaggi di dettaglio generati durante l'elaborazione, utili per diagnosticare il problema e correggere i dati prima di un nuovo invio.

Parametri in Request da utilizzare con l'import

impl è il parametro che identifica la tipologia di import da eseguire. Ogni valore numerico corrisponde a una specifica entità del sistema e determina quale struttura dati viene attesa nel body, quali validazioni vengono applicate e su quali tabelle di PEOPLELINK verranno scritti i dati. È obbligatorio sia in SendJson che in CheckState, perché il sistema non ha modo di inferire autonomamente di quale entità si tratti. In sostanza, è la chiave che disambigua il comportamento dell'endpoint unico: lo stesso SendJson si comporta in modo completamente diverso a seconda del valore di impl passato.

alg definisce la strategia con cui il sistema gestisce i dati in ingresso rispetto a quelli già presenti sul database. Il valore 1, detto algoritmo di startup, esegue un inserimento diretto senza verificare se esistono già record equivalenti: va usato esclusivamente in fase di prima installazione o in scenari in cui si è certi dell'assenza di duplicati, perché non offre alcuna protezione contro la creazione di record sovrapposti. Il valore 2, detto algoritmo di upsert, è quello pensato per l'uso ordinario: il sistema cerca di identificare univocamente ogni record in ingresso e, se lo trova già presente, lo aggiorna; se non lo trova, lo inserisce come nuovo. Questo approccio è però applicabile solo alle entità che dispongono di un identificativo univoco stabile, poiché senza di esso il sistema non è in grado di stabilire se un record esista già o meno.

partialupsert entra in gioco esclusivamente quando si utilizza l'algoritmo di upsert (alg=2) e controlla la profondità dell'aggiornamento in caso di sovrapposizione. Con il valore false, che è il comportamento predefinito, l'aggiornamento è totale: il record esistente viene completamente riscritto con i dati del JSON, e i campi non presenti nella chiamata vengono azzerati o riportati al valore di default. Con il valore true, l'aggiornamento è invece parziale: vengono toccati soltanto i campi esplicitamente presenti nel JSON, lasciando invariati tutti gli altri. La scelta tra i due comportamenti dipende dall'intenzione del chiamante: se si vuole sincronizzare completamente un record lo si imposta a false, se si vuole aggiornare solo alcuni attributi senza rischiare di perdere dati già presenti lo si imposta a true.

postelab è un parametro opzionale che permette di agganciare, al termine dell'import, un algoritmo di post-elaborazione specifico, cablato all'interno del software PEOPLELINK. Se non viene valorizzato, l'import si conclude con la sola scrittura dei dati. Se invece viene indicato un valore riconosciuto dal sistema, al completamento dell'import viene eseguita automaticamente una logica aggiuntiva configurata lato server, tipicamente utile per aggiornare strutture derivate, ricalcolare aggregati o innescare processi consequenziali all'inserimento dei dati. I valori ammessi non sono liberi ma predefiniti: dipendono dalla tipologia di import (impl) e dalla configurazione dell'installazione.

Conseguentemente a quanto sopra riportato si ricorda che:

·         la lista di tutte le tipologie di import disponibili è consultabile direttamente nello swagger e viene aggiornata ad ogni rilascio

·         l'algoritmo di startup è sempre disponibile per tutti gli import. La disponibilità o meno dell'algoritmo di upsert è indicata nel template JSON di esempio.

Correlazione tra import multipli con l'header X-PL-SyncId

X-PL-SyncId è un header HTTP opzionale, ma fortemente consigliato, che il client genera autonomamente e passa nella chiamata a SendJson. Il valore atteso è un GUID, ma non ci sono specifiche stringenti.

La sua funzione è di correlazione: quando un import logicamente unitario viene spezzato in più chiamate a SendJson - ad esempio, perché il client decide di inviare un'entità alla volta invece che in batch - passando lo stesso GUID in tutte le chiamate si comunica al sistema che quelle operazioni fanno parte di uno stesso contesto. Questo permette di tracciarle e riconciliarle insieme lato PEOPLELINK, anziché trattarle come import indipendenti e scollegati.

Non è quindi un meccanismo di idempotenza nel senso stretto del termine, ovvero non impedisce la doppia esecuzione di una stessa chiamata in caso di retry. Il suo scopo è semantico: fornire un filo conduttore tra operazioni distinte che il chiamante considera parte di uno stesso evento di import.

Potete utilizzare i seguenti schemi di import avanzati:

·         IDENTITIES: Anagrafica badge (avanzato)

·         TASK: Anagrafica clienti, commesse e attività (avanzato) - versione beta pubblica

·         VISTA: Anagrafica asset (avanzato)

·         VISTA: Anagrafica competenze (avanzato)

·         VISTA: Anagrafica posizioni lavorative (avanzato)

·         VISTA: Assegnazioni ai soggetti delle competenze (avanzato)

·         VISTA: Assegnazioni ai soggetti delle posizioni lavorative (avanzato)

·         VISTA: Assegnazione eventi anagrafici (avanzato).

·         VISTA: Gruppi di edizioni ed edizioni per corsi formativi (avanzato)

·         IDENTITIES: Anagrafica badge (avanzato)

·         TASK: Anagrafica clienti, commesse e attività (avanzato) - versione beta pubblica

I file da utilizzare, per i quali è possibile scaricare i relativi template Excel utilizzando il bottone <Download template per import>, avranno le seguenti caratteristiche:

·         IDENTITIES: Anagrafica badge (avanzato) - Utile per l'import dei badge e la relativa assegnazione ai soggetti
Per questo schema di import specifico, ogni foglio rappresenta la categoria a cui appartiene:

o   Badge - Foglio contenente la lista di badge da aggiungere in anagrafica. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Associazione a soggetti - Foglio contenente la lista di soggetti da associare ai badge. I badge ai quali vanno associati possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria "Badge". Per questa categoria sono previsti i seguenti algoritmi di import: Startup.

o   Badge con associazione (legacy) - Foglio contenente la lista di badge da aggiungere in anagrafica e da associare ad un determinato soggetto. Per questa categoria è previsto l'algoritmo di import di Startup.
 Questa categoria, derivante dal vecchio tracciato di import dei badge anagrafici, potrebbe venir rimossa in aggiornamenti futuri in quanto obsoleta.

·         TASK: Anagrafica clienti, commesse e attività (avanzato) - utile per l' import generico dei clienti, referenti clienti, commesse, classificazioni di commessa e attività di commessa in TASK.
Per questo schema di import specifico, ogni foglio rappresenta la categoria a cui appartiene:

o   Clienti - Foglio contenente la lista di clienti da aggiungere e/o modificare in anagrafica. Per questa categoria sono previsti i seguenti algoritmi di import: Startup, Upsert.

o   Referenti - Foglio contenente la lista di referenti relativi a determinati clienti da aggiungere e/o modificare. I clienti sui quali potranno venir salvati possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Clienti. Per questa categoria sono previsti i seguenti algoritmi di import: Startup, Upsert.

o   Commesse - Foglio contenente la lista di commesse da aggiungere in anagrafica. I clienti alle quali potranno essere associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Clienti. Per questa categoria sono previsti i seguenti algoritmi di import: Startup, Upsert.

o   Classificazioni - Foglio contenente la lista di associazioni delle classificazioni di commessa in anagrafica. Le commesse alle quali potranno venir associati possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Commesse. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Attività - Foglio contenente la lista di attività di commessa da aggiungere in anagrafica. Le commesse alle quali potranno venir associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Commesse. Per questa categoria sono previsti i seguenti algoritmi di import: Startup, Upsert.

·         VISTA: Anagrafica asset (avanzato) - utile per l'import generico degli asset e delle scadenze, dei documenti e/o allegati, degli storici rilevazioni, delle manutenzioni e delle commesse associate legate ad essi in VISTA.
Per questo schema di import specifico, ogni foglio rappresenta la categoria a cui appartiene:

o   Asset aziendali - Foglio contenente la lista di asset aziendali da aggiungere e/o modificare in anagrafica. Per questa categoria sono previsti i seguenti algoritmi di import: Startup, Upsert.

o   Scadenze - Foglio contenente la lista di scadenze da aggiungere in anagrafica. Gli asset aziendali ai quali potranno venir associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Asset aziendali. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Documenti e allegati - Foglio contenente la lista di documenti e allegati da aggiungere in anagrafica. Gli asset aziendali ai quali potranno venir associati possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Asset aziendali. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Storico rilevazioni - Foglio contenente la lista di storici rilevazioni da aggiungere in anagrafica. Gli asset aziendali ai quali potranno venir associati possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Asset aziendali. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Manutenzioni - Foglio contenente la lista di manutenzioni da aggiungere in anagrafica. Gli asset aziendali ai quali potranno venir associati possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Asset aziendali. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Commesse associate - Foglio contenente la lista di commesse associate da aggiungere in anagrafica. Gli asset aziendali ai quali potranno venir associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Asset aziendali. Per questa categoria è previsto l'algoritmo di import di Startup.

·         VISTA: Anagrafica competenze - utile per l'import generico delle competenze e/o delle associazioni delle posizioni lavorative ad esse in VISTA.
Per questo schema di import specifico, ogni foglio rappresenta la categoria a cui appartiene:

o   Competenze - Foglio contenente la lista di competenze da aggiungere in anagrafica. Per questa categoria è previsto l'algoritmo di import di Startup.

·         Posizioni lavorative associate - Foglio contenente la lista di posizioni lavorative da associare alle competenze. Le competenze alle quali vanno associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Competenze. Per questa categoria è previsto l'algoritmo di import di Startup.

·         VISTA: Anagrafica posizioni lavorative (avanzato) - utile per l' import generico delle posizioni lavorative e/o delle associazioni delle competenze e/o delle mappe retributive ad esse in VISTA.
Per questo schema di import specifico, ogni foglio rappresenta la categoria a cui appartiene:

o   Posizioni lavorative - Foglio contenente la lista di posizioni lavorative da aggiungere in anagrafica. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Competenze associate - Foglio contenente la lista di competenze da associare alle posizioni lavorative. Le posizioni lavorative alle quali vanno associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Posizioni lavorative. Per questa categoria è previsto l'algoritmo di import di Startup.

·         Mappe retributive associate - Foglio contenente la lista di mappe retributive da associare alle posizioni lavorative. Le posizioni lavorative alle quali vanno associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria Posizioni lavorative. Per questa categoria è previsto l'algoritmo di import di Startup.

·         VISTA: Assegnazioni ai soggetti delle competenze (avanzato) - utile per l'assegnazione delle competenze ai soggetti
Per questo schema di import specifico, il foglio Competenze sarà strutturato in base alle informazioni obbligatorie necessarie per il salvataggio di una competenza su un soggetto in anagrafica:

o   Codice fiscale (chiave)

o   Cognome (solo figurativo)

o   Nome (solo figurativo)

o   Competenza (da valorizzare sempre con il codice della competenza)

o   Data di riferimento

o   Importanza

o   Valutazione desiderata.

·         VISTA: Assegnazioni ai soggetti delle posizioni lavorative (avanzato) - utile per l'assegnazione delle posizioni lavorative ai soggetti
Per questo schema di import specifico, il foglio Posizioni lavorative sarà strutturato in base alle informazioni obbligatorie necessarie per il salvataggio di una competenza su un soggetto in anagrafica:

o   Codice fiscale (chiave)

o   Cognome (solo figurativo)

o   Nome (solo figurativo)

o   Data inizio

o   Data fine

o   Posizione lavorativa (da valorizzare sempre con il codice della posizione lavorativa)

o   Tipologia di assegnazione

o   Quota o peso

o   Azienda

o   Sede

o   Aggiungi competenze

o   Valutazione desiderata.

·         VISTA: Assegnazione eventi anagrafici (avanzato) - Utile per l'import delle categorie di eventi
Il file è composto da più fogli, tanti quanti le categorie di eventi configurate; ogni foglio ha come descrizione il codice della categoria di evento. Le colonne presenti variano di foglio in foglio in base ai campi previsti per ciascuna tipologia di categoria di evento.

·         VISTA: Gruppi di edizioni ed edizioni per corsi formativi (avanzato) - Utile per l'import generico dei gruppi di edizioni dei corsi formativi, delle edizioni dei corsi formativi e/o dei calendari sessione da associare ad esse in VISTA.
Per questo schema di import specifico, ogni foglio rappresenta la categoria a cui appartiene:

o   Gruppi corsi formativi - Foglio contenente la lista di gruppi di edizioni dei corsi formativi da aggiungere in anagrafica. Per questa categoria è previsto l'algoritmo di import di Startup.

o   Edizioni corsi formativi - Foglio contenente la lista di edizioni di corsi formativi da aggiungere in anagrafica. I gruppi di edizioni alle quali potranno venir associate possono essere già presenti in anagrafica oppure essere presenti nel foglio con categoria "Gruppi corsi formativi". Per questa categoria è previsto l'algoritmo di import di Startup.

o   Calendario sessioni - Foglio contenente la lista di calendari sessioni da aggiungere in anagrafica. Le edizioni di corsi formativi alle quali andranno associati potranno essere già presenti in anagrafica oppure essere presenti nel foglio con categoria "Edizioni corsi formativi". Per questa categoria è previsto l'algoritmo di import di Startup.

 È possibile in fase di import poter allegare dei documenti, utilizzando un file in formato .zip contenente oltre al file di Excel anche i file relativi agli allegati, dopo aver indicato, per ciascun allegato, il nome e l'estensione nell'apposita colonna del foglio Excel.

Se la lettura del file Excel andrà in errore, verrà inviata una notifica di errore e sarà necessario rieffettuare l'import del file Excel, in quanto impossibile da leggere dal sistema per un errore di struttura o generico, che verrà specificato nel log di import.

Caricare i file da importare

All'interno della scheda Import da file, nella funzionalità Gestione documenti, potete scaricare il file contenente il template per l'importazione che si necessita, in base allo schema e formato specificati.

Per l'import manuale, potete scaricare il file template in formato Excel cliccando sul bottone <Dowload template per import>.

Una volta compilato il template in Excel, caricate il file cliccando sul bottone <Carica file> e procedete al caricamento del file utilizzando uno degli schemi sottostanti alla categoria IMPORT AVANZATI.

Cliccate sul bottone <Continua> per confermare. A caricamento completato apparirà il link Valida import.

Configurare e modificare i fogli da importare

·         Cliccate sul link Valida import per visualizzare la struttura e i dati importati.

·         Selezionate i fogli da importare
 se un foglio non verrà selezionato prima della fase finale di import, sarà completamente ignorato. Inoltre, non sarà possibile importarne i dati in un secondo momento tramite lo stesso file caricato, in quanto una volta terminato il processo di import, tutti i fogli verranno impostati in modalità di sola-lettura, per verificare la veridicità dei dati importati rispetto a quelli presenti a interfaccia.

·         Selezionate l'algoritmo da utilizzare:

o   primo import (starup): viene utilizzato in fase di startup di un impianto per caricare nuovi elementi a prescindere da quelli già esistenti.
 In caso di rilevazione di elementi aventi un codice univoco già esistente la procedura si blocca in fase di validazione

o   import di upsert: viene utilizzato per caricare nuovi elementi o aggiornare quelli già esistenti.
 se un elemento viene individuato a sistema, e nel foglio sono presenti delle colonne contenenti celle vuote per esso, i campi relativi alle colonne in questione verranno svuotati (se non obbligatori). Se si desidera evitare questo comportamento, sarà necessario caricare il foglio contenente unicamente le colonne che si desidera modificare. In alternativa, è possibile indicare le colonne da non considerare in fase di mappatura, per esempio il nome e cognome dei soggetti che in fase di import non vanno considerati perché la chiave è il codice fiscale.

·         Verificate ed eventualmente modificate/correggete il contenuto della lista delle colonne, quindi cliccate su Valida e salva.

·         Cliccate sul pulsante Anteprima e gestione dati per visualizzare i dati, selezionare eventuali dati da non importare e risolvere eventuali errori salvandoli.

·         Una volta gestiti i dati da importare, selezionate Importa tutto per completare l'operazione.

Gestire i dati da importare

Potete visualizzare i dati letti dal sistema di import dopo aver cliccato sul pulsante Anteprima dati da importare; i campi con errori sono evidenziati e tramite un tooltip potete leggere dettagli dell'errore in questione.

Inoltre, sempre tramite un tooltip, sugli identificativi dei soggetti, se previsti, sarà possibile visualizzare nome e cognome del soggetto, se individuato in anagrafica.

 Per confermare la modifica di una cella dovete cliccare all'esterno di essa.

Potete decidere di non importare singole righe spuntando la checkbox presente nella prima colonna Non Importare.

Cliccate sul pulsante Valida e salva per confermare eventuali modifiche effettuate.

Importare i dati salvati

Se la validazione è andata a buon fine, potete effettuare l'import dei dati cliccando sul pulsante <Importa tutto> confermando l'esecuzione.

A import completato potete cliccare sul link Dati, nella colonna Stato dell'import, per visualizzare in sola lettura i fogli importati con i relativi dati importati.

 Il numero verde all'interno della colonna corrisponde al numero di fogli importati, non ai singoli elementi importati.