Interfaccia API di testo di CA SDM

Questo articolo contiene i seguenti argomenti:
casm173
Questo articolo contiene i seguenti argomenti:
Panoramica delle API di testo
L'
API di testo
è un'interfaccia che consente di utilizzare input basato su testo per creare e aggiornare gli oggetti nel database di CA SDM, come Issue, Richieste, contatti e asset. Utilizzando l'API testo è possibile assegnare dei valori alla maggior parte dei campi accessibili agli utenti.
CA SDM> richiede che tutti i dati siano immessi in formato UTF-8, altrimenti possono essere danneggiati. L'utilità pdm_unconv consente di convertire i dati di un set di caratteri da locale a UTF-8 e da UTF-8 a locale.
È possibile accedere all'API testo utilizzando le interfacce seguenti:
  • Riga di comando
  • Posta elettronica
È possibile utilizzare i servizi Web in alternativa all'interfaccia API testo per l'integrazione tra più applicazioni.
Interfaccia della riga di comando
Utilizzare il comando
pdm_text_cmd
per attivare l'interfaccia della riga di comando API di testo. Dopodiché è possibile immettere informazioni specifiche, ad esempio la tabella da elaborare e l'operazione da eseguire, utilizzando i parametri del comando pdm_text_cmd.
L'input dell'API testo viene passato al comando pdm_text_cmd nel formato file di input o direttamente da STDIN.
Per l'immissione dei parametri dal prompt dei comandi, utilizzare Ctrl+Z in Windows e Ctrl+D in POSIX.
Non è possibile utilizzare le virgolette singole o doppie come parametri per i comandi bop_cmd e pdm_text_nxd.
Formato input
L'input dell'API testo è specificato nei seguenti modi:
  • Nell'interfaccia riga di comando, l'input è normalmente specificato in un file di testo trasmesso al comando
    pdm_text_cmd
    .
  • Nell'interfaccia di posta elettronica, l'input è specificato nel testo del messaggio. Si specifica un'espressione regolare per individuare gli identificatori dell'oggetto di destinazione.
L'input di API testo si formatta allo stesso modo indipendentemente dall'interfaccia che si usa.
Il formato base dell'input è il seguente:
%keyword=value
oppure
%PROPERTY={{property_label}}value
Il normale comportamento dei comandi API testo ha le seguenti eccezioni, in cui tra due o più comandi in conflitto tra loro, l'ultimo visualizzato ha precedenza:
  • Quando un messaggio contiene più elementi di ID ticket corrispondenti alla stringa di filtro della regola di casella di posta, o più comandi ID ticket di API testo, viene utilizzato il primo riscontrato. Inoltre, un elemento di ID ticket, identificato mediante la stringa di filtro della casella di posta, sovrascrive qualsiasi comando ID ticket di API testo, indipendentemente da quale compare per primo.
  • Quando un messaggio contiene più comandi API testo di commento del registro, tutti i commenti vengono pubblicati, anche se il loro ordine di apparizione nel registro delle attività di ticket può variare.
A tutti gli elementi di ID ticket corrispondenti al filtro, validi o meno, e i comandi ID ticket di API testo all'interno del messaggio, applicabili/applicati o meno, viene aggiunto un commento prima della pubblicazione del comando. Gli elementi di ID ticket identificati attraverso i filtri della regola della casella di posta vengono visualizzati come -((...))-. I segni di percentuale (%) nei comandi ID ticket di API testo vengono convertiti in due parentesi di apertura "((", e il comando è seguito da due parentesi di chiusura "))". Se un comando ID ticket di API testo compare dopo un altro comando API testo con un commento di registro (%LOG=…), il comando ID ticket di API testo viene trasformato in commento di registro separato.
Il commento di registro è il solo comando API testo che può comparire più volte in un unico messaggio ed essere applicato a ogni occorrenza. Per tutti gli altri comandi, l'API testo utilizza solo l'ultima occorrenza, poiché le occorrenze multiple di altri comandi entrano in conflitto tra loro. I comandi di commento di registro multipli pubblicano messaggi di commento di registro separati e non necessariamente in un ordine definito.
Inoltre, se compare nel messaggio, all'inizio o tra altri due comandi API testo, un comando ID ticket di API testo viene convertito in commento di registro. Se il comando precedente è un commento di registro (%LOG=…) o una descrizione di aggiornamento (%DESCRIPTION=…), viene aggiunto a tale comando invece di essere trasformato in un commento di registro separato.
Modalità di utilizzo delle parole chiave da parte dell'API di testo
È possibile utilizzare due tipi di parole chiave come input per l'interfaccia API testo.
  • Definizioni nella sezione [KEYWORDS] del file
    text_api.cfg
    : questo tipo è un gruppo di parole chiave correlate direttamente ai campi di varie tabelle che è possibile aggiornare. Ad esempio, la maggior parte dei campi del modulo Dettagli Issue sono definiti nella sezione [KEYWORDS]. Utilizzando queste parole chiave, è possibile impostare i valori per i campi nel record in fase di aggiornamento o creazione. Ad esempio, la riga seguente imposta la priorità della Issue su 5:
    %PRIORITY=5
    La sezione [KEYWORDS] del file
    text_api.cfg
    elenca tutte le parole chiave. È possibile definire parole chiave aggiuntive (ad esempio per consentire l'accesso dell'API testo ai campi aggiunti durante la personalizzazione dello schema del database).
  • Le seguenti parole chiave speciali vengono sempre definite come riportato di seguito, indipendentemente dai contenuti del file
    text_api.cfg
    :
Parola chiave
Descrizione
ASSET
Utilizzata per associare un elemento a un ticket. Questa parola chiave è valida per le Richieste, per le Issue e per gli Ordini di cambiamento. Il valore specificato è il nome dell'elemento, che deve essere già presente. È possibile specificare questa parola chiave più volte, poiché un ticket può essere associato più elementi.
ATTACHMENT
Utilizzata internamente dall'interfaccia di posta elettronica per aggiungere gli allegati di posta elettronica a un ticket.
DESCRIZIONE
Specifica il valore da utilizzare per il campo della descrizione del ticket. Questa parola chiave viene utilizzata se l'input viene inviato all'interfaccia API testo senza una parola chiave esplicita. Questa parola chiave viene applicata automaticamente da Mail Eater quando il messaggio non inizia con una parola chiave ma contiene un elemento ID ticket o parola chiave.
È possibile cambiare la modalità di gestione della parola chiave DESCRIPTION per gli aggiornamenti, utilizzando nella sezione [OPTIONS] del file text_api.cfg la voce seguente:
UPDATE_DESC_IS_LOG
Se questa opzione è impostata su YES, il valore viene utilizzato per creare un commento del registro. Se il valore è impostato su NO, il valore sovrascrive il valore esistente del campo della descrizione.
FROM_EMAILFROM_EMAIL_OVERRIDE
Utilizzate dall'interfaccia di posta elettronica per eseguire l'associazione con il campo Indirizzo di posta elettronica nel record ca_contact. Viene utilizzato anche come log_agent per il ticket. Se entrambi sono forniti, FROM_EMAIL viene ignorato.
FROM_EMAIL è impostato automaticamente da Mail Eater con l'indirizzo del mittente del messaggio.
FROM_PERSID
Utilizzata dall'interfaccia della riga di comando per definire log_agent per un'operazione. Ad esempio, quando un record ca_contact non dispone di ID utente. Questa parola chiave viene trasmessa automaticamente da pdm_text_cmd se è specificato il parametro -p
.
Il valore viene associato a un persistent_id del record ca_contact.
FROM_USERID
Utilizzata solo nell'interfaccia della riga di comando per definire il comando log_agent per un'operazione. Questa parola chiave viene trasmessa automaticamente da
pdm_text_cmd
se è specificato il parametro -u. Il valore viene associato a un ID utente di un contatto.
LOG
Utilizzata per creare una voce di registro. Questa parola chiave è valida per le Richieste, per gli Ordini di cambiamento, per le Issue e per i contatti. Questa parola chiave viene applicata automaticamente da Mail Eater quando il messaggio non inizia con una parola chiave ma contiene un elemento ID ticket o parola chiave, o una parola chiave DESCRIPTION.
PROPERTY
Utilizzata per impostare il valore di una proprietà. Questa parola chiave è valida solo per le Richieste, per gli Ordini di cambiamento e per le Issue. Contrariamente alle altre parole chiave, che sono seguite dal segno di uguale (=), la sintassi della parola chiave PROPERTY deve includere l'etichetta della proprietà, ad esempio:
PROPERTY={{etichetta_proprietà}}valore
È necessario specificare
etichetta_proprietà
esattamente come è riportata nel database.
SEARCH
Utilizzata solo nell'interfaccia riga di comando per fornire un elenco di parole chiave da utilizzare in una query per aggiornare più ticket di un asset. Il valore è un elenco di parole chiave da utilizzare nella ricerca.
Convenzioni di immissione delle parole chiave
Al formato delle parole chiave immesse si applicano le seguenti convenzioni:
  • Far precedere ogni parola chiave (inclusa PROPERTY) da un segno di percentuale (%). Il segno di percentuale deve essere in posizione colonna uno. Se la prima riga non vuota dell'input non contiene un segno di percentuale all'inizio della riga, viene utilizzato %
    DESCRIPTION= oppure %LOG=
    come prefisso per i dati in arrivo, a seconda che sia stato trovato un elemento ID ticket o una parola chiave. Se viene impostato
    %DESCRIPTION
    , il contenuto del messaggio fino alla prima parola chiave viene registrato come descrizione del ticket. Se viene impostato
    %LOG
    , il contenuto del messaggio fino alla prima parola chiave viene registrato come commento registro.
  • Non utilizzare spazi nella parola chiave, tra il segno di percentuale (%) e la parola chiave o tra la parola chiave e il segno di uguale (=).
  • Non utilizzare le virgolette per i valori; tutti i dati dopo il segno = rappresentano il valore.
  • La parole chiave non fanno distinzione tra maiuscole e minuscole.
  • Se l'input include parole chiave duplicate, viene utilizzata l'ultima paraola chiave; altrimenti, l'ordine in cui vengono specificate le coppie parola chiave/valore è ininfluente.
  • Specificare i valori della parola chiave come si farebbe per il campo corrispondente nell'interfaccia Web. Ad esempio, per specificare un tipo di contatto Analista, utilizzare
    %CONTACT_TYPE=Analista
    , anche se nel database questo valore viene memorizzato come valore intero. La parola chiave
    CONTACT_TYPE
    è definita nel file
    text_api.cfg
    , il quale converte il valore specificato in modo che corrisponda al valore memorizzato.
    Il rispetto delle maiuscole/minuscole nel valore dipende dal DBMS utilizzato.
  • I dati di tipo stringa possono occupare più righe.
Formattazione di un messaggio di posta elettronica per aggiornare un ticket
Un utente può formattare un messaggio di posta elettronica per creare o aggiornare un ticket.
Per formattare un messaggio di posta elettronica per creare o aggiornare un ticket, utilizzare i seguenti campi:
  • A
    Specifica il nome della casella di posta assegnato al contatto di CA SDM impostato per l'utente con privilegi.
  • Da
    Specifica la persona che invia il messaggio di posta elettronica. La persona deve essere definita nella tabella
    ca_contact
    , a meno che nella regola della casella di posta applicabile non sia specificata l'opzione
    Consenti anonimo
    .
    L'indirizzo Da fa tipicamente parte della configurazione del programma di posta elettronica in uso e non viene generalmente impostato a livello di messaggio.
  • Allegati
    Consente di allegare documenti e altri file al messaggio di posta elettronica per inviare allegati all'interfaccia API testo.
  • Oggetto
    Corrisponde a parole chiave di una stringa di filtro della regola della casella di posta, in particolare quando si crea un ticket.
  • Testo
    Specifica il corpo del messaggio di posta elettronica utilizzando l'interfaccia API testo. Per creare o aggiornare un ticket, è possibile specificare la parola chiave
    ISSUE_ID
    ,
    REQUEST_ID
    o
    CHANGE_ID
    in base al tipo di ticket.
Delimitatori di inizio e fine dei messaggi di posta elettronica
Alcune interfacce di posta elettronica aggiungono informazioni all'inizio o alla fine dei messaggi di posta elettronica (ad esempio la codifica MIME) che possono causare malfunzionamenti dell'interfaccia stessa.
Se l'interfaccia di posta elettronica aggiunge informazioni, è possibile utilizzare i seguenti delimitatori:
start-request ed end-request. L'interfaccia di posta elettronica ignora le informazioni specificate prima del delimitatore start-request e dopo il delimitatore end-request.
CA SDM Maileater ora supporta i formati HTML e RTF (Rich-Text Format) per i messaggi di posta in arrivo.
Esempio: utilizzare i delimitatori start-request e end-request
"start-request" message_body "end-request"
Modalità di utilizzo degli elementi da parte dell'interfaccia API testo
L'interfaccia API testo elabora l'oggetto o il corpo del testo di notifiche di posta elettronica. Le regole della casella di posta consentono di identificare elementi e valori utilizzati dall'interfaccia API testo. Ad esempio, è possibile definire la regola per Incidenti Incident:{{object_id}}, in modo che Incident:1234 venga tradotto in %INCIDENT_ID=1234 per l'interfaccia API testo, dove 1234 è il ref_num dell'Incidente. Poiché nel messaggio di posta elettronica l'elemento deve essere univoco e facile da trovare, è possibile renderlo più distintivo, ad esempio %Incident:{{object_id}}%.
A questo scopo, apporre alla parola chiave {{object_id}} un carattere che non sia una lettera, un numero, una virgola, una barra (/) oppure un segno più (+) o uguale (=), poiché questi caratteri possono comparire all'interno di un elemento. In caso contrario, è possibile che i caratteri che seguono l'elemento vengano interpretati per una parte del valore dell'elemento oppure che un carattere all'interno del valore dell'elemento venga interpretato per un carattere che segue tale valore.
Il daemon Mail Eater esegue le operazioni riportate di seguito:
  1. Trova l'elemento in un messaggio di posta elettronica (ad esempio, Incident:1234) che è associato al ticket appropriato o ad altro oggetto supportato dall'interfaccia API testo.
  2. Traduce l'elemento in un token dell'interfaccia API testo (ad esempio, %INCIDENT_ID=1234).
  3. Il daemon Mail Eater invia il messaggio con tag all'interfaccia API testo. L'interfaccia API testo elabora il messaggio di posta elettronica, applica il testo, i comandi o entrambi, che contiene nel ticket appropriato e genera una risposta automatica indicando se il messaggio di posta elettronica ricevuto è stato applicato correttamente. A seconda delle azioni eseguite, viene inoltre inviato un messaggio di posta elettronica separato per segnalare determinati eventi specifici, quali la creazione di un ticket.
Modalità di impostazione di risposte a notifiche di posta per l'aggiornamento di ticket
Il daemon API testo (pdm_text_nxd) crea e aggiorna ticket con informazioni provenienti da interfacce esterne, ad esempio la riga di comando e la posta elettronica. È possibile impostare la posta elettronica in modo che utilizzi l'interfaccia API testo per consentire agli utenti (contatti) di aggiornare ticket rispondendo a notifiche di posta elettronica. Il testo della risposta viene aggiunta al ticket come attività commento registro.
Per impostare risposte a notifiche per aggiornare ticket, procedere come segue:
  1. Impostare il metodo di notifica utilizzato dal contatto su pdm_mail - T
    reply_email_address
    o su pdm_mail - F
    reply_email_address.
    L'
    indirizzo_postal_risposta
    specifica l'indirizzo della posta elettronica in entrata della casella di posta. Quando il contatto fa clic su Rispondi nel messaggio di posta elettronica, l'indirizzo viene compilato dall'indirizzo Da o Rispondi a del messaggi al quale sta rispondendo.
    -T imposta l'indirizzo Rispondi a. -F imposta l'indirizzo Da, che è utilizzato come indirizzo di risposta se non ne viene specificato un altro.
    Alcuni programmi di posta elettronica non usano o non possano utilizzare l'indirizzo Rispondi a.
  2. Creare o aggiornare una regola della casella posta utilizzando una password dell'interfaccia API testo.
    Gli elementi definiti dall'utente nei filtri della regola della casella di posta sostituiscono le seguenti parole chiave dell'interfaccia API testo:
Oggetto
Parola chiave API testo
Identificativo
Incidente
%INCIDENT_ID
Ref_num
Problema
%PROBLEM_ID
Ref_num
Richiesta
%REQUEST_ID
Ref_num
Chg_ref_num
%CHANGE_ID
Chg_ref_num
Issue
%ISSUE_ID
Ref_num
  1. Creare o aggiornare una frase di notifica che corrisponde alla regola.
  2. Creare o aggiornare un modello di messaggio che utilizza la frase di notifica.
  3. Aggiornare la regola della casella di posta creata nel passaggio 2 per specificare il modello di messaggio che è stato creato o aggiornato nel passaggio 4.
Dopo che l'utente riceve la notifica e risponde, si verificano le seguenti azioni:
  1. Quando viene trovata la stringa di filtro, l'eventuale parola chiave e il valore dell'ID ticket denotati dal segnaposto vengono aggiunti al messaggio.
  2. Se viene trovato un elemento ID ticket corrispondente, il ticket corrispondente viene aggiornato con un commento registro o una nuova descrizione o altri valori in base al testo, alle parole chiave e ai comandi nel messaggio.
  3. Se non viene trovato un elemento ID ticket corrispondente, viene creato un ticket con una descrizione e altri parametri in base al testo, alle parole chiave e ai comandi nel messaggio.
Esempio di impostazione di una risposta a una notifica di Incidente
L'esempio riportato di seguito illustra come impostare una risposta a una notifica di Incidente.
Per impostare una risposta a una notifica di Incidente, procedere come segue:
  1. Creare una regola della casella di posta utilizzando i seguenti campi e valori:
    • Filtro: Body contains
    • Stringa filtro: %Incident:{{object_id}}%
    • Ignora maiuscole/minuscole: YES
    • Azione: Update Object
    • Oggetto azione: Incident
  2. Creare un frase di notifica che includa la regola, come illustrato di seguito:
    • Simbolo: Incident Reply
    • Codice: IncidentReply
    • Attivo: Active
    • Descrizione: commento che incorpora la risposta a un Incidente/Problema/Richiesta.
    • Frase: per aggiungere un commento a @{call_req_id.type.sym}, è sufficiente rispondere a questo messaggio di posta elettronica o includere la riga seguente (in una riga autonoma):
      %Incident:{call_req_id.ref_num}%
      Nel regola del testo di risposta automatica della casella di posta, omettere il prefisso call_req_id. Questo prefisso applica un contesto in cui il testo della regola della casella di posta si trova già e tale modifica di contesto non è valida quando si opera già da tale contesto.
  3. Creare o aggiornare un modello di messaggio che utilizza la frase di notifica come indicato di seguito:
    • Testo del messaggio di notifica
      This is a simple notification. @{notification_phrase[IncidentURL1].phrase}
  4. Aggiornare la regola della casella di posta creata nel passaggio 1 per specificare il modello di messaggio che è stato creato nel passaggio 3, come indicato di seguito:
    Modello messaggio:
    nome della regola della casella di posta
Modalità di aggiornamento di un esempio di ticket da parte di un utente finale
L'esempio riportato di seguito dimostra come un utente finale (John Smith) risponde a una notifica di posta elettronica per aggiornare un ticket Incidente.
Il corpo o l'oggetto del messaggio include l'identificativo dell'oggetto. Il segnaposto {{object_id}} all'interno della stringa di filtro denota l'identificativo dell'oggetto.
  1. Viene inviata una notifica a John Smith che include le seguenti istruzioni:
    In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %Incident:1234%
  2. John Smith risponde alla notifica come segue:
    This is my response...
  3. Il daemon Mail Eater riceve la seguente versione di testo del messaggio di John Smith:
    This is my response... From: Service Desk Sent: Wednesday, September 18, 2009 10:22 AM To: Smith, John Subject: Simple Notification This is a simple notification. In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %Incident:1234%
  4. Il daemon Mail Eater elabora le regole nell'ordine e trova l'elemento %Incident:1234%:
    This is my response... From: Service Desk Sent: Wednesday, September 18, 2009 10:22 AM To: Smith, John Subject: Simple Notification This is a simple notification. In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %INCIDENT_ID=1234
  5. Il daemon Mail Eater aggiunge le parole chiave dell'interfaccia API testo e il valore {{object_id}} a un'istruzione %INCIDENT_ID= e lascia un marcatore dove è stato trovato il valore {{object_id}}. Il testo seguente mostra i dai inviati all'interfaccia API testo. Il testo in grassetto indica i valori aggiunti dal daemon Mail Eater.
    %LOG=This is my response...
    From: Service Desk
    Sent: Wednesday, September 18, 2009 10:22 AM
    To: Smith, John
    Subject: Simple Notification
    This is a simple notification.
    In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself).
    %Incident:-((...))-%
    %INCIDENT_ID=1234
  6. L'interfaccia API testo aggiunge un commento registro per l'Incidente 1234.
Metodi di conversione delle parole chiave
A molte delle parole chiave definite nel file text_api.cfg è associato un metodo per convertire il valore specificato in un valore appropriato per la memorizzazione nel database. Questa funzione consente agli utenti di specificare i valori come nell'interfaccia Web, senza dover conoscere il tipo di implementazione di base.
Il file di configurazione include diversi esempi di questo tipo di definizione delle parole chiave tra cui ISSUE.PRIORITY e CONTACT.CONTACT_TYPE. Se è necessario definire parole chiave aggiuntive, ad esempio per consentire l'accesso dell'API testo ai campi aggiunti durante la personalizzazione dello schema del database, è possibile utilizzare uno dei seguenti metodi predefiniti:
Metodo
Tipo di output
lookup_actbool
INTEGER
lookup_asset_by_name
UUID
lookup_asset_by_persid
UUID
lookup_chg_category
STRING
lookup_chg_status
STRING
lookup_cnt_by_email
UUID
lookup_cnt_by_last_first_middle
UUID
lookup_cnt_by_logonid
UUID
lookup_cnt_by_persid
UUID
lookup_cnt_meth
INTEGER
lookup_cnt_type
INTEGER
lookup_company
UUID
lookup_cr_status
STRING
lookup_cr_template
STRING
lookup_domain
INTEGER
lookup_grc
INTEGER
lookup_group
UUID
lookup_impact
INTEGER
lookup_iss_category
STRING
lookup_iss_status
STRING
lookup_loc
UUID
lookup_mfr_model
UUID
lookup_nr_family
INTEGER
lookup_org
UUID
lookup_person_contacting
INTEGER
lookup_position
INTEGER
lookup_priority
INTEGER
lookup_prob_category
STRING
lookup_product
INTEGER
lookup_resource_status
INTEGER
lookup_service_lvl
STRING
lookup_severity
INTEGER
lookup_state
INTEGER
lookup_timezone
STRING
lookup_type_of_contact
INTEGER
lookup_urgency
INTEGER
lookup_workshift
STRING
Se il valore da convertire non è supportato da nessuno dei metodi predefiniti, è necessario creare un metodo personalizzato. Il metodo dovrebbe utilizzare un valore STRING come input e restituire come output un valore INTEGER, STRING o UUID. La restituzione di un valore -1 (o “-1”) indica che il valore non può essere determinato e quindi non impostato. Per UUID, il valore restituito deve essere “(uuid) NULL”.
Ad esempio, è possibile sviluppare un metodo per convertire un ID utente in un riferimento di tabella ca_contact. Il valore di input, ad esempio Amministratore, verrebbe passato al metodo e il metodo dovrebbe restituire l'ID della tabella ca_contact per l'ID utente dell'amministratore.
Il modo con cui si definiscono le parole chiave nel file di configurazione consente di definire più associazioni di parole chiave nello stesso campo, inclusi diversi metodi di conversione, in base al valore specificato. Ad esempio, è possibile che per l'assegnatario vi siano differenti associazioni di parole chiave per definire in che modo impostare il valore in base a differenti valori di input. Un input potrebbe essere l'ID utente e un altro potrebbe essere il cognome, il nome, il secondo nome e un altro ancora potrebbe essere l'ID ca_contact effettivo, ad esempio 793ED69B4E87A545BD8E911834D829FC). Ogni parola chiave viene associata a un metodo di conversione differente, tranne l'ultima che non deve essere convertita.