La definizione della query di ricerca avanzata

La definizione della query di ricerca avanzata in formato JSON è composta da quattro sezioni principali che specificano:

• dove eseguire la ricerca (campodatasource )
• i cui dati devono essere ricercati (campopopulation )
• quali condizioni aggiuntive le voci di origine devono corrispondere per essere restituite dalla ricerca (campofilters )
• come formattare e presentare i risultati (campooutput )

La sezione datasource include i seguenti campi che sono tutti facoltativi:

• datatype (stringa) definisce il tipo di dati da richiamare: TASKS o INSTANCES. TASKS è il valore predefinito.
• systemTypes (array di stringhe) definisce il tipo di sistemi in cui devono essere richiamati i dati da: Process, BPEL, Case. Il valore predefinito dipende dal tipo di dati:
  • Process e BPEL per le attività
  • Process e Case per le istanze
• systemFilter (oggetto) definisce un elenco di sistemi da includere o meno durante la ricerca. Si tratta di un oggetto con due campi (array di stringhe), includes e excludes per elencare rispettivamente gli ID dei sistemi da includere o escludere per la ricerca.

Il seguente esempio mostra i dettagli di una sezione datasource per la ricerca di attività BPD (Process) e BPEL su tutti i sistemi tranne quella con ID sistema "4a8a5317-808e-48fe-964e-ff489ed356ce":

"datasource": {
    "datatype": "TASKS",
    "systemTypes": ["Process", "BPEL"],
    "systemFilter": {
        "excludes": ["4a8a5317-808e-48fe-964e-ff489ed356ce"]
    }
}

Questo esempio mostra i dettagli di una sezione datasource per ricercare le istanze del caso su tutti i sistemi:

"datasource": {
    "datatype": "INSTANCES",
    "systemTypes": ["Case"]
}

La sezione population attualmente supporta una singola destinazione e può essere omessa dalla query di ricerca:

• target (stringa): SELF (ricerca delle proprie attività e istanze)

Il seguente esempio mostra i dettagli della sezione population predefinita:

"population": {
    "target": "SELF"
}

Un filtro è una serie di condizioni sui campi dell'attività pubblica o dell'istanza. Solo le attività o le istanze che corrispondono alle condizioni aggiuntive definite nella sezione filters verranno restituite dalla ricerca. La sezione filters include i seguenti campi che sono tutti facoltativi:

• interaction (stringa) sfrutta i campi privati per consentire un facile filtraggio per stato. È l'equivalente del campo interaction di Ricerche salvate e supporta gli stessi valori:
  • claimed: attività che sono state richieste e che non sono state ancora completate (non valide per la ricerca delle istanze)
  • available: attività non ancora richieste e non ancora completate (non valide per la ricerca di istanze)
  • claimed_and_available: attività non ancora completate (non valide per la ricerca dell'istanza)
  • completed: attività o istanze completate
  • active: istanze che non sono ancora state completate (non valide per la ricerca di attività)
  • failed: istanze non riuscite (non valide per la ricerca di attività)
  • all: tutte le attività e le istanze indipendentemente dal loro stato corrente.
  Il valore predefinito è all.
• caseScope (stringa) è l'ambito della ricerca per le istanze del caso. I possibili valori sono:
  • Allowed: tutte le istanze del caso che la popolazione può visualizzare
  • Assigned: solo le istanze del caso assegnate alla popolazione
  Il valore predefinito è Assigned.
• v1_conditions : condizioni di ricerca salvate (array di condizioni che devono corrispondere tutte)
• v1_queryFilter (stringa): sintassi di tipo SQL, uguale al parametro queryFilter dell'API REST GET /v1/tasks e PUT /v1/instances .
• v1_searchFilter (string): sintassi di ricerca testo completo, uguale al parametro searchFilter dell'API REST GET /v1/tasks .
• json_query (oggetto): nuova sintassi JSON che supporta la combinazione AND, OR e NOT di condizioni. Il filtro json_query è un oggetto JSON (albero). I campi sono condizioni di ricerca salvata (field, operator, value) che possono essere combinate con and, ore not.
  Il seguente esempio illustra una query nella sintassi JSON:

  
  "json_query": {
      ”not": {
          ”or": [{
              "field": "taskPriority",
              "operator": "GreaterThan",
              "value": 100
          },
          {
              ”and": [{
                  "field": "customer",
                  "operator": "Equals",
                  "value": ”ACME corp."
              },
              {
                  "field": "product",
                  "operator": "Equals",
                  "value": "CP4BA"
              }]
          }]
      }
  }
  

Il seguente esempio mostra i dettagli di una sezione filters per richiamare le attività richieste che hanno una priorità superiore a 100 e che hanno almeno un campo che includa la parola "ACME" (ricerca testo completo in tutti i valori dei campi attività):

"filters": {
  "interaction": "claimed",
  "json_query": {
    "field": "taskPriority",
    "operator": "GreaterThan",
    "value": 100
  },
  "v1_searchFilter": "ACME"
}

La sezione output definisce come presentare i risultati, in base ai seguenti campi che sono tutti facoltativi:

• fields (array di stringhe): elenco di campi da restituire per ogni attività o istanza.
• includeAllBusinessData (booleano): restituisce tutti i campi di dati di business contemporaneamente.false è il valore predefinito.
• usersFullName (booleano): specifica come formattare le informazioni dell'utente nei risultati (nome completo o ID utente). true è il valore predefinito.
• aliases (array di oggetti): elenco di alias (uguale al campo Ricerca salvata aliases )
• sort (array di oggetti): specifica come ordinare i risultati. Ogni oggetto nell'array ha due campi, field (stringa) è il nome di un campo su cui ordinare i risultati e order (stringa), ASC o DESC (valore predefinito ASC) a seconda che i risultati debbano essere ordinati rispettivamente in base al valore del campo crescente o decrescente.
• alphabeticalSort (stringa): ordina per ordine alfabetico e lessicografico (per i campi stringa a cui si fa riferimento nel campo sort ).
• size (intero): numero massimo di risultati nella risposta (il valore predefinito è 25).
• stats (oggetto): statistiche da restituire con i risultati. Attualmente è possibile restituire un singolo tipo di statistiche (uguale a quando si esegue una ricerca salvata con il parametro calcStats impostato su true), specificato impostando il parametro type (stringa) dell'oggetto stats su Basic

Il seguente esempio mostra i dettagli di una sezione output per una ricerca di attività che richiede il resoconto dell'attività, l'ID attività, l'ID istanza, l'attività a rischio e tutti i dati di business per le attività corrispondenti, ordinati in base all'attività ascendente a rischio, con un massimo di 50 risultati e le statistiche di base insieme ai risultati:

"output": {
    "fields": ["taskNarrative", "taskId", "instanceId", "taskAtRiskTime"],
    "includeAllBusinessData": true,
    "sort": [{
        "field": "taskAtRiskTime",
        "order": "ASC"
    }],
    "size": 50,
    "stats": {
        "type": "Basic"
    }
}

Le query di ricerca riutilizzabili hanno un campo metadata (oggetto) aggiuntivo, che contiene i seguenti campi:

• name (string): un nome univoco obbligatorio per la ricerca riutilizzabile;
• description (stringa): una descrizione facoltativa per la query di ricerca riutilizzabile;
• sharing (oggetto): vengono condivise informazioni facoltative sulla query di ricerca riutilizzabile. Include i seguenti campi:
  • shared (booleano): true per condividere con altri utenti, false (valore predefinito) altrimenti
  • teams (array di oggetti): elenco di team di processi con cui condividere la query di ricerca. Se null, undefined o vuoto mentre shared è true, la query di ricerca viene condivisa con tutti. Per condividere con un team di processi specifico di cui si è membri o responsabili, definire questo team nell'array (notare che un singolo valore è attualmente supportato) utilizzando un oggetto con il campo teamId per l'identificativo del team di processi.
• owner (oggetto): informazioni sull'utente che possiede la query di ricerca riutilizzabile
• creator (oggetto): informazioni sull'utente che ha creato la query di ricerca riutilizzabile
• lastUpdater (oggetto): informazioni sull'utente che ha aggiornato per ultimo la query di ricerca riutilizzabile
• creationDate (stringa): ISO8601 data/ora in cui è stata creata la query di ricerca riutilizzabile
• lastUpdateDate (stringa): ISO8601 data / ora dell'ultimo aggiornamento della query di ricerca riutilizzabile

L'esempio riportato di seguito mostra i dettagli della sezione metadata per una query di ricerca riutilizzabile:

"metadata": {
    "name": "my tasks list",
    "description": "a search query that retrieves my task list",
    "sharing": {
        "shared": true,
        "teams": [{
            "teamId": "24.6615a4b0-fd38-4ea5-8bc0-69d2f107369e",
            "teamName": "Human Resources",
            "processAppName": "Hiring Sample"
        }],
    },
    "owner": {
        "id": "jane.doe@acme.com",
        "fullName": "Jane Doe"
    },
    "creator": {
        "id": "admin@acme.com",
        "fullName": "Administrator"
    },
    "lastUpdater": {
        "id": "user.name@ibm.com",
        "fullName": "User Name"
    },
    "creationDate": "2024-01-31T12:34:42.183Z",
    "lastUpdateDate": "2024-02-01T16:03:12.874Z"
}