Lettura utenti

• Verifica esistenza utente
• Lettura di un singolo utente
• Elencare utenti
• Model

Verifica esistenza utente

Api per la verifica dell'esistenza di un utente dato il suo ID

[HEAD] ​/api​/v3​/users​/{userId}

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Path Parameters

• userId: identificativo univoco dell' utente

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.

HTTP 200

L' utente esiste.

Il body della risposta non è presente

HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare una connessione per il gestore specificato. 

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di connessione

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

• code: corrisponde al codice d'errore HTTP ritornato (es: 409)
• message: messaggio d'errore
• subErrors: eventuali errori innestati in quello ritornato
• timestamp: data ed ora di ritorno dell'errore

Lettura di un singolo utente

API per recuperare i dati di uno specifico utente dato il suo ID

[GET] ​/api​/v3​/users/{userId}

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Path Parameters

• userId: identificativo univoco dell' utente da leggere

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.

HTTP 200

L'utente è stato recuperata con successo.

Il body della risposta è un singolo User contenente i ruoli, le informazioni base e lo stato dell' utente:

{
  "roles": [
    {
      "appId": "string",
      "resourceId": "string",
      "actionKey": "string",
      "featureCode": "string",
      "resourceUuid": "string",
      "policyId": "string",
      "createdAt": "2020-09-11T10:01:15.512Z",
      "createdBy": "string"
    }
  ],
  "profile": {
    "id": "string",
    "type": "string",
    "description": "string",
    "firstName": "string",
    "lastName": "string",
    "language": "string",
    "tsid": "string",
    "ncsId": "string",
    "uuid": "string"
  },
  "status": {
    "active": true,
    "activatedAt": "2020-09-10T13:49:33.092Z",
    "activatedBy": "string",
    "createdAt": "2020-09-10T13:49:33.092Z",
    "createdBy": "string",
    "modifiedAt": "2020-09-10T13:49:33.092Z",
    "modifiedBy": "string",
    "deleted": true,
    "deletedAt": "2020-09-10T13:49:33.092Z",
    "deletedBy": "string"
  }
}

 

HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare una connessione per il gestore specificato. 

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di connessione

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

• code: corrisponde al codice d'errore HTTP ritornato (es: 409)
• message: messaggio d'errore
• subErrors: eventuali errori innestati in quello ritornato
• timestamp: data ed ora di ritorno dell'errore

Elencare utenti

API che per ottenere un elenco filtrato di utenti con i relativi ruoli e informazioni di stato.

[GET] /api/v3/users

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Query Parameters

Parametri obbligatori

• itemId: identificativo univoco dell' azienda per cui è richiesto l'elenco degli utenti

Parametri opzionali

• roles: elenco separato da virgole di ruoli da ricercare.
• appIds: elenco separato da virgole di appId da ricercare
• featureCodes: elenco separato da virgole di feature code da ricercare
• userTypes: elenco separato da virgole di userTypes da ricercare. I valori accettati sono T per le utenze tecniche, P per le utenze personali
• userId: identificativo univoco dell'utenza da cercare
• policyIds: elenco per la ricerca per policy id , ad esempio è possibile cercare gli utenti per una determinata connessione
• sortBy.field: indica il campo su cui va fatto l'ordinamento, come valori sono accettati EMAIL(default), LAST_NAME, FIRST_NAME, DESCRIPTION, CREATED_AT, ACTIVE
• sortBy.order: ASC (default) per un ordinamento crescente, DESC per un ordinamento decrescente
• unpaged:  false (default) per una lista paginata, true per una lista non paginata.

Se unpaged è false i seguenti parametri diventano obbligatori.

• pagination.pageNumber: numero della pagina da recuperare. La prima pagina è 0
• pagination.itemPerPage: numero di utenti da recuperare per pagina.

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.

HTTP 200

L'elenco di utenti è stato recuperato con successo.

{
  "totalItems": 0,
  "roleCount": {
    "OWNER": 0,
    "ADMIN": 0,
    ...
  },
  "users": [
    {
      "roles": [
        {
          "appId": "string",
          "resourceId": "string",
          "actionKey": "string",
          "featureCode": "string",
          "resourceUuid": "string",
          "policyId": "policyId",
          "createdAt": "2020-09-11T10:01:15.512Z",
          "createdBy": "string"
        }
      ],
      "profile": {
        "id": "string",
        "type": "string",
        "description": "string",
        "firstName": "string",
        "lastName": "string",
        "language": "string",
        "tsid": "string",
        "ncsId": "string",
        "uuid": "string"
      },
      "status": {
        "active": true,
        "activatedAt": "2020-09-11T10:01:15.512Z",
        "activatedBy": "string",
        "createdAt": "2020-09-11T10:01:15.512Z",
        "createdBy": "string",
        "modifiedAt": "2020-09-11T10:01:15.512Z",
        "modifiedBy": "string",
        "deleted": true,
        "deletedAt": "2020-09-11T10:01:15.512Z",
        "deletedBy": "string"
      }
    }
  ]
}

• totalItems: numero totale degli utenti che rispettano i filtri specificati
• roleCount: numero di utenti raggruppati per ruoli
• users: array di User che rispettano i filtri specificati.

HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare una connessione per il gestore specificato. 

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di connessione

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

• code: corrisponde al codice d'errore HTTP ritornato (es: 500)
• message: messaggio d'errore (es: Errore interno del server)
• subErrors: eventuali errori innestati in quello ritornato
• timestamp: data ed ora di ritorno dell'errore

Model

Elenco dei model ritornati dalle API di lettura

User

E' il model che definisce l'utente ts-digital, contiene tutte le info relative all'utente.

{
  "roles": {},
  "profile": {},
  "status": {}
}

• roles: array contente tutti i ruoli dell' utente
• profile: informazioni sul profilo dell'utente
• status: informazioni sullo stato dell'utente

Role

Entità che descrive un ruolo di uno specifico utente

{
  "appId": "string",
  "resourceId": "string",
  "actionKey": "string",
  "featureCode": "string",
  "resourceUuid": "string",
  "createdAt": "2020-09-11T10:01:15.512Z",
  "createdBy": "string"
}

• appId: identificativo dell'applicazione a cui fa riferimento il ruolo
• resourceId: identificativo(id) della risorsa a cui fa riferimento il ruolo
• actionKey: identificativo del ruolo
• featureCode: identificativo della feature dell'applicazione a cui fa riferimento il ruolo. Se il ruolo non ha feature multiple, il campo è null
• resourceUuid: identificativo(uuid) della risorsa a cui fa riferimento il ruolo
• createdAt: data di assegnazione ruolo espressa come stringa
• createdBy: utente che ha assegnato il ruolo

Profile

Entità che definisce le info di uno specifico utente

{
 "id": "string",
 "type": "string",
 "description": "string",
 "firstName": "string",
 "lastName": "string",
 "language": "string",
 "tsid": "string",
 "ncsId": "string"
}

• id: identificativo univoco dell' utente
• type: tipologia di utente. (PERSONALE, TECNICA)
• description: descrizione dell'utente, è valorizzata solo per le utenze tecniche.
• firstName: nome dell'utente, è valorizzato solo per le utenze personale
• lastName: cognome dell'utente, è valorizzato solo per le utenze personale
• language: iso language + country code dell'utente (es. it-IT)
• tsid: identificativo univoco Team System.
• ncsId: identificativo univoco Notification Center

Status

Entità che definisce lo stato di uno specifico utente

{
 "active": true,
 "activatedAt": "2021-04-20T12:51:15.058Z",
 "activatedBy": "string",
 "createdAt": "2021-04-20T12:51:15.058Z",
 "createdBy": "string",
 "modifiedAt": "2021-04-20T12:51:15.058Z",
 "modifiedBy": "string",
 "deleted": true,
 "deletedAt": "2021-04-20T12:51:15.058Z",
 "deletedBy": "string"
}

• active: se true, l' utente è attivo ed utilizzabile
• activatedAt: data ed ora di attivazione dell'utente espressa come stringa
• activatedBy: identificativo dell'utenza che ha attivato l'utente
• createdAt: data ed ora di creazione dell'utente espressa come stringa
• createdBy: identificativo dell'utenza che ha creato l'utente
• modifiedAt: data ed ora di ultima modifica dell'utente espressa come stringa
• modifiedBy: identificativo dell'utenza che ha modificato l'utente
• deleted: se true, la connessione è stata eliminata e non è più utilizzabile
• deletedAt: data di cancellazione dell'utente espressa come stringa
• deletedBy: identificativo dell'utenza che ha effettuato la cancellazione