Interfaz de la API de texto de CA SDM

Este artículo contiene los siguientes temas:
casm173
Este artículo contiene los siguientes temas:
Descripción general de la API de texto
La
API de texto
es una interfaz que permite utilizar entradas de texto para crear y actualizar objetos de la base de datos de CA SDM como, por ejemplo, incidencias, solicitudes, contactos y activos. Utilizando la API de texto se pueden asignar valores a la mayor parte de los campos que son accesibles para los usuarios.
CA SDM exige que todas las entradas tengan el formato UTF-8. De lo contrario, pueden corromperse. La utilidad pdm_unconv le permite convertir los datos de un conjunto de caracteres local a UTF-8 y viceversa.
Puede accederse a la API de texto mediante las siguientes interfaces:
  • Línea de comandos
  • Email
Para la integración entre aplicaciones se pueden utilizar los servicios web en lugar de la API de texto
.
Interfaz de línea de comandos
El comando
pdm_text_cmd
se emplea para activar la interfaz de la línea de comandos de la API de texto. Puede especificar determinada información, por ejemplo, la tabla que debe procesarse y la operación que debe realizarse por medio de parámetros en el comando pdm_text_cmd.
La entrada de la API de texto se traslada al comando pdm_text_cmd con la forma de un archivo de entrada o directamente desde STDIN.
Al transferir los parámetros desde el símbolo del sistema, utilice Ctrl+Z en Windows y Ctrl+D en POSIX.
No se pueden utilizar las comillas simples o dobles como parámetros para los comandos bop_cmd y pdm_text_nxd.
Formato de entrada
La entrada a la API de texto se especifica de las siguientes maneras:
  • En la interfaz de línea de comandos, la entrada se especifica generalmente en un archivo de texto introducido en el comando
    pdm_text_cmd
    .
  • En la interfaz de correo electrónico, se especifica en el texto del correo electrónico. El usuario especifica una expresión regular para encontrar los identificadores de objeto de destino.
El usuario aplica formato a la entrada de la API de texto de la misma manera sin importar qué interfaz utiliza.
El formato básico para la entrada es el siguiente:
%keyword=value
o
%PROPERTY={{property_label}}value
El comportamiento normal de los comandos de la API de texto tiene las excepciones siguientes, donde el comando que aparece al último de dos o más comandos en conflicto tiene prioridad:
  • Cuando un mensaje contiene varios artefactos de ID de ticket válidos que coinciden con la cadena de filtro de regla de buzón de correo o varios comandos de ID de ticket de la API de texto, se utiliza el primero que se encuentra. También, un artefacto de ID de ticket, que se identifica utilizando la cadena de filtro de regla para el buzón de correo, anula cualquier comando de ID de ticket de la API de texto, sin tener en cuenta cuál aparece primero.
  • Cuando un mensaje contiene varios comandos de la API de texto de comentario del registro, todos los comentarios se envían, aunque el orden en el cual aparecen en el registro de actividades del ticket puede variar.
Todos los artefactos de ID de ticket que coinciden con el filtro, sean válidos o no, y los comandos de ID de ticket de la API de texto dentro del mensaje, sean aplicables o no, o se hayan aplicado o no, se comentan antes de que el mensaje se envíe. Los artefactos de ID de ticket identificados a través de los filtros de la regla para el buzón de correo aparecen como -((...))-. Los signos de porcentaje (%) adelante de los comandos de ID de la API de texto se convierten en dos paréntesis de apertura ((, y dos paréntesis de cierre)) siguen al comando. Si un comando de ID de ticket de la API de texto aparece después de otro comando de la API de texto con un comentario de registro (%LOG=…), el comando de ID de ticket de la API de texto comentado se convierte en un comentario de registro separado.
El comentario de registro es el único comando de la API de texto que puede aparecer repetidas veces en un mensaje y aún así tener cada resultado aplicado. Para algunos otros comandos, la API de texto utiliza solamente el último resultado porque los resultados múltiples de otros comandos se contradicen. Los comandos de comentario de registro múltiples envían mensajes de comentario de registro separados al ticket, y no necesariamente siguiendo algún orden en particular.
Además, si un comando de ID de ticket de la API de texto aparece en el mensaje, ya sea al inicio del mensaje o entre otros dos comandos de la API de texto, se convierte en un comentario de registro. Si el comando anterior es un comentario de registro (%LOG=…) o una descripción de actualización (%DESCRIPTION=…), se añade a ese comando en lugar de convertirse en un comentario de registro separado.
Cómo utiliza la API de texto las palabras clave
Hay dos tipos de palabras clave que se pueden utilizar en las entradas de la API de texto.
  • Las definiciones en la sección [KEYWORDS] del archivo
    text_api.cfg
    : Este tipo es un grupo de palabras clave relacionadas directamente con los campos de las diferentes tablas que se pueden actualizar. Por ejemplo, en esta sección se definen la mayoría de los campos del formulario Detalles de incidencia. Con estas palabras clave, es posible definir valores para los campos de los registros que se estén actualizando o creando. Por ejemplo, la línea siguiente define la prioridad de una incidencia en 5:
    %PRIORITY=5
    La sección [KEYWORDS] del archivo
    text_api.cfg
    enumera todas las palabras clave. Puede definir palabras clave adicionales (por ejemplo, para permitir el acceso de la API de texto a campos que ha agregado al personalizar su esquema de base de datos).
  • Las siguientes palabras clave especiales se definen siempre de la siguiente manera, sin tener en cuenta el contenido del archivo
    text_api.cfg
    :
Palabra clave
Descripción
ASSET
Se emplea para adjuntar elementos a los tickets; es válida para peticiones, incidencias y órdenes de cambio. El valor especificado es el nombre del elemento, que ya debe existir. Esta palabra clave se puede especificar varias veces ya que los tickets pueden tener adjuntos varios elementos.
ATTACHMENT
La interfaz de correo electrónico la usa de forma interna para agregar adjuntos a los partes.
DESCRIPTION
Especifica el valor que se debe usar para el campo de descripción del parte. Esta palabra clave se sobrentiende si se envía la entrada a Text API sin indicar ninguna palabra clave. Esta palabra clave es aplicada automáticamente por el receptor de correo cuando el mensaje no empieza con una palabra clave pero contiene un artefacto de ID de ticket o palabra clave.
Es posible cambiar la manera de tratar en las actualizaciones la palabra clave DESCRIPTION mediante la entrada siguiente de la sección [OPTIONS] del archivo text_api.cfg:
UPDATE_DESC_IS_LOG
Si se define esta opción en SÍ, se emplea el valor para crear un comentario de registro; en cambio, si se define en NO, el valor sobrescribe el campo de descripción existente.
FROM_EMAILFROM_EMAIL_OVERRIDE
La interfaz de correo electrónico la usa para realizar la comparación con el campo Dirección de correo electrónico del registro de la tabla ca_contact. También sirve como log_agent para el tíquet. Si se proporcionan los dos, se ignora FROM_EMAIL.
El receptor de correo establece FROM_EMAIL automáticamente con la dirección del remitente del mensaje.
FROM_PERSID
La interfaz de la línea de comandos la usa para definir el log_agent de las operaciones, por ejemplo, si el registro de ca_contact carece de ID de usuario. pdm_text_cmd traslada automáticamente esta palabra clave si se especifica el parámetro -p
.
El valor se compara con el valor de persistent_id del registro de ca_contact.
FROM_USERID
Sólo se usa en la interfaz de la línea de comandos para definir el log_agent de las operaciones.
pdm_text_cmd
traslada automáticamente esta palabra clave si se especifica el parámetro -u. El valor se compara con el ID de usuario de un contacto.
LOG
Sirve para crear entradas de registro; es válida para solicitudes, órdenes de cambios, incidencias y contactos. El receptor de correo aplica esta palabra clave automáticamente cuando el mensaje no empieza con una palabra clave pero contiene o un artefacto de ID de ticket o palabra clave, o una palabra clave DESCRIPTION.
PROPERTY
Sirve para definir el valor de las propiedades; es válida para solicitudes, órdenes de cambios e incidencias. A diferencia de otras palabras clave, que van seguidas tan sólo de un signo igual y un valor, la sintaxis de la palabra clave PROPERTY debe incluir la etiqueta de la propiedad como se ilustra a continuación:
PROPERTY={{etiqueta_propiedad}}valor
Debe especificar la
etiqueta_propiedad
exactamente como aparezca en la base de datos.
SEARCH
Solo se usa en la interfaz de la línea de comandos para suministrar una lista de palabras clave que se puede usar en una consulta para actualizar varios tickets para un activo. El valor se corresponde con la lista de palabras clave que se emplea en la búsqueda.
Convenciones de entrada de palabra clave
Se aplican las siguientes convenciones para aplicar formato a la entrada de palabras clave:
  • Coloque un prefijo en todas las palabras clave (incluso PROPERTY) con un signo de porcentaje (%). El signo de porcentaje debe estar en la posición de columna uno. Si la primera línea no vacía de la entrada no tiene un signo de porcentaje en el principio de la línea, se usa
    %DESCRIPTION= o %LOG=
    como prefijo para los datos entrantes, dependiendo de si se ha encontrado una palabra clave o un artefacto del ID del ticket. Si se establece
    %DESCRIPTION
    , el contenido del mensaje hasta la primera palabra clave se envía como descripción del ticket. Si se establece
    %LOG=
    , el contenido del mensaje hasta la primera palabra clave se envía como comentario del registro.
  • No introduzca ningún espacio entre la palabra clave y el símbolo %, ni tampoco entre la palabra clave y el signo igual (=).
  • No entrecomille los valores: se supone que todos los datos que siguen al signo igual son valores.
  • Las palabras clave no distinguen entre mayúsculas y minúsculas.
  • Si la entrada incluye palabras clave duplicadas, se utiliza la última palabra clave. De lo contrario, el orden en el cual especifica los pares de palabra clave/valor es insignificante.
  • Especifique los valores de las palabras clave del mismo modo que en los campos correspondientes en la interfaz Web. Por ejemplo, para indicar un tipo de contacto Analista, se debe usar
    %CONTACT_TYPE=Analyst
    aunque dicho valor se almacene como un entero en la base de datos. En
    text_api.cfg
    se define la palabra clave
    CONTACT_TYPE
    para que convierta el valor especificado de manera que coincida con el valor almacenado.
    Que el valor distinga mayúsculas de minúsculas depende del DBMS subyacente
    .
  • Los datos de cadena pueden abarcar varias líneas.
Cómo dar formato a un mensaje de correo electrónico para actualizar un ticket
Un usuario puede aplicar formato a un mensaje de correo electrónico para crear o actualizar un ticket.
Para aplicar formato a un mensaje de correo electrónico para crear o actualizar un ticket, utilice los campos siguientes:
  • A
    Especifica el nombre del buzón de correo asignado al contacto de CA SDM configurado para el usuario con privilegios.
  • Desde
    Especifica la persona que envía el correo electrónico. Se debe definir a la persona en la tabla
    ca_contact
    a menos que se haya especificado la opción
    Permitir anónimo
    en la regla de buzón de correo aplicable.
    La dirección de origen generalmente es parte de la configuración de su programa de correo electrónico y normalmente no se establece en forma individual para cada mensaje
    .
  • Archivos adjuntos
    Agrega documentos y otros archivos al correo electrónico para enviarle adjuntos a la API de texto.
  • Asunto
    Hace coincidir palabras clave en una cadena de filtro de la regla para el buzón de correo, especialmente cuando se crea un ticket.
  • Cuerpo
    Especifica el cuerpo del mensaje de un correo electrónico que usa la API de texto. Se puede especificar la palabra clave
    ISSUE_ID
    ,
    REQUEST_ID
    o
    CHANGE_ID
    según el tipo de ticket para crear o actualizar un ticket.
Inicio y finalización de delimitadores de mensaje de correo electrónico
Algunas interfaces de correo electrónico agregan información al principio o al final de los mensajes de correo, lo que puede provocar un funcionamiento incorrecto de la interfaz de correo electrónico (por ejemplo, la codificación MIME).
Si la interfaz de correo electrónico agrega información, se pueden utilizar los siguientes delimitadores:
start-request y end-request. La interfaz de correo electrónico ignora toda la información que se ha especificado antes de start-request y después de end-request.
CA SDM Maileater ahora es compatible con los correos electrónicos en formato HTML y de texto enriquecido (RTF) para los correos entrantes.
Ejemplo: Uso de los delimitadores start-request and end-request
"start-request" message_body "end-request"
Cómo utiliza artefactos la API del texto
La API de texto procesa el asunto o el cuerpo de las notificaciones por correo electrónico. Las reglas para el buzón de correo le permiten identificar artefactos y valores que la API de texto utiliza. Por ejemplo, puede definir la regla para incidentes como Incident:{{object_id}}, para que al encontrar Incident:1234 traduzca a %INCIDENT_ID=1234 para la API de texto. 1234 es el ref_num para el incidente. Porque el artefacto debe ser único en el correo electrónico y debe poder encontrarse fácilmente, puede hacer que se diferencie más como por ejemplo %Incident:{{object_id}}%.
Coloque detrás de la palabra clave {{object_id}} un carácter que no sea una letra, un número, una coma, una barra diagonal (/), el signo más (+) ni el signo igual (=), porque estos caracteres pueden aparecer dentro de un artefacto. De lo contrario, es posible que los caracteres que siguen al artefacto puedan ser malinterpretados como parte del valor del artefacto, o que un carácter dentro del valor del artefacto se pueda malinterpretar como el carácter que sigue al valor.
El receptor de correo realiza lo siguiente:
  1. Busca el artefacto dentro de un correo electrónico (como Incident:1234) que asigna al ticket apropiado u otro objeto compatible con la API de texto.
  2. Traduce el artefacto a un token de la API de texto (como %INCIDENT_ID=1234).
  3. Envía el mensaje etiquetado a la API de texto. La API de texto procesa el correo electrónico, aplica el texto, los comandos o ambos que contienen al ticket apropiado y genera un correo electrónico de respuesta automática que indica si el mensaje de correo electrónico que recibió se aplicó correctamente. Dependiendo de las acciones ejecutadas, también se envía un mensaje de correo electrónico de notificación por separado para indicar ciertos eventos específicos, como la creación de un ticket.
Cómo configurar respuestas de notificación para actualizar tickets.
El daemon de la API de texto (pdm_text_nxd) crea y actualiza tickets con información de interfaces externas, como la línea de comandos y el correo electrónico. Puede configurar el correo para que utilice Text API de modo que los usuarios (contactos) puedan actualizar tickets respondiendo a notificaciones de correo electrónico. El texto de la respuesta se agrega como actividad de comentario de registro al ticket.
Si desea configurar respuestas de notificación para actualizar tickets, realice lo siguiente:
  1. Establezca el método de notificación que utiliza el contacto en pdm_mail -T
    reply_email_address
    o pdm_mail -F
    reply_email_address.
    La opción
    reply_email_address
    especifica la dirección entrante para el buzón de correo. Cuando el contacto hace clic en Respuesta en un correo electrónico, esa dirección se rellena desde la dirección del remitente o respuesta del mensaje al que está respondiendo.
    -T establece la dirección de respuesta. -F establece la dirección del remitente, que se utiliza como dirección de respuesta si no se especifica una distinta.
    Algunos programas de correo no aceptan direcciones de respuesta
    .
  2. Cree o actualice una regla para el buzón de correo mediante una palabra clave de Text API.
    Los artefactos definidos por el usuario en los filtros de la regla para el buzón de correo reemplazan a las siguientes palabras clave de Text API:
Objeto
Palabra clave de Text API
Identificador
Incidente
%INCIDENT_ID
Ref_num
Problema
%PROBLEM_ID
Ref_num
Solicitud
%REQUEST_ID
Ref_num
Chg_ref_num
%CHANGE_ID
Chg_ref_num
Incidencia
%ISSUE_ID
Ref_num
  1. Cree o actualice una frase de notificación que coincida con la regla.
  2. Cree o actualice una plantilla de mensaje que utilice la frase de notificación.
  3. Actualice la regla de buzón de correo creada en el paso 2 para especificar la plantilla de mensaje creada en el paso 4.
Después de que el usuario recibe la notificación y la responde, se producen las siguientes acciones:
  1. Cuando se encuentra la cadena de filtro, la palabra clave de ID de ticket relevante y el valor indicado por el marcador de posición, de haberlos, se añaden al mensaje.
  2. Si se encuentra un artefacto de ID de ticket coincidente, el ticket correspondiente se actualiza, ya sea con un comentario de registro, una nueva descripción u otros valores de acuerdo con el texto, las palabras clave y los comandos en el mensaje.
  3. Si no se encuentra un artefacto de ID de ticket coincidente, sea crea un ticket con una descripción y otros parámetros de acuerdo con el texto, las palabras clave y los comandos en el mensaje.
Cómo configurar una respuesta en un ejemplo de notificación de incidente.
Este ejemplo muestra cómo configurar una respuesta en una notificación de incidente.
Para configurar una respuesta en una notificación de incidente, realice lo siguiente:
  1. Cree una regla para el buzón de correo con los siguientes campos y valores:
    • Filtro: el cuerpo contiene
    • Cadena de filtro: %Incident:{{object_id}}%
    • Omitir mayúsculas y minúsculas: SÍ
    • Acción: actualizar objeto
    • Objeto de acción: incidente
  2. Cree una frase de notificación que incluya la siguiente regla:
    • Símbolo: respuesta de incidente
    • Código: IncidentReply
    • Activo: activo
    • Descripción: comentario que incrusta la respuesta para un incidente/problema/solicitud.
    • Frase: para agregar un comentario a @{call_req_id.type.sym}, conteste este correo o incluya la línea siguiente (en una sola línea):
      %Incident:{call_req_id.ref_num}%
      En el texto de respuesta automática de la regla para el buzón de correo, omita el prefijo call_req_id. Este prefijo aplica un contexto en el que ya se encuentra el texto de la regla para el buzón de correo; dicho cambio de contexto no es válido cuando ya actúa dentro de ese contexto.
  3. Cree o actualice una plantilla de mensaje que utilice la siguiente frase de notificación:
    • Cuerpo del mensaje de notificación
      This is a simple notification. @{notification_phrase[IncidentURL1].phrase}
  4. Actualice la regla de buzón de correo creada en el paso 1 para especificar la plantilla de mensaje creada en el paso 3, de la siguiente forma:
    Plantilla de mensaje:
    nombre de la regla para el buzón de correo
Cómo actualizan ejemplos de ticket los usuarios finales
El siguiente ejemplo demuestra cómo responde un usuario final (Juan Pérez) a una notificación por correo electrónico para actualizar un ticket de incidentes.
El cuerpo o el asunto del correo electrónico incluye el identificador de objeto. El marcador de posición {{object_id}} dentro de la cadena de filtro indica el identificador de objeto.
  1. Se envía una notificación a Juan Pérez que incluye las siguientes instrucciones:
    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. Juan Pérez responde a la notificación de la siguiente manera:
    This is my response...
  3. El receptor de correo recibe la versión de texto siguiente del correo electrónico de Juan Pérez:
    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. El receptor de correo procesa las reglas en orden y encuentra el artefacto %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. El receptor de correo agrega las palabras clave de API de texto y el valor {{object_id}} a una declaración %INCIDENT_ID= y deja un marcador donde se encontró el valor {{object_id}}. El siguiente texto muestra los datos que se envían a la API de texto. El texto en negrita muestra los valores agregados por el receptor de correo.
    %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. La API de texto agrega un comentario de registro para el incidente 1234.
Métodos de conversión de la palabra clave
Muchas de las palabras clave definidas en el archivo text_api.cfg cuentan con un método asociado que permite convertir el valor especificado en el valor apropiado para el almacenamiento en la base de datos. Esta función permite a los usuarios especificar valores del mismo modo que se hace en la interfaz Web, sin necesidad de que tengan conocimientos de la implementación subyacente.
El archivo de configuración tiene varios ejemplos de este tipo de definición de la palabra clave, incluyendo ISSUE.PRIORITY y CONTACT.CONTACT_TYPE. Si necesita definir más palabras clave (por ejemplo, para permitir que la API de texto acceda a campos que haya agregado al personalizar su esquema de base de datos), puede utilizar uno de los siguientes métodos predefinidos:
Método
Tipo de salida
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
Si ninguno de los métodos anteriores es apropiado para el valor que se debe convertir, es necesario escribir un método personalizado. El método debe tomar un valor de CADENA como entrada y devolver otro valor (ENTERO, CADENA o UUID) como salida. Si se devuelve el valor -1 (o “-1”), se denota que el valor no se puede determinar y que, por consiguiente, no está definido. En el caso de UUID, se devuelve un valor nulo.
Por ejemplo, es posible desarrollar un método que convierta el ID de usuario en una referencia de la tabla ca_contact. El valor entrante, Administrador, por ejemplo, se traslada al método, que devuelve el ID de la tabla ca_contact correspondiente al ID de usuario del administrador.
La manera de definir las palabras clave en el archivo de configuración ofrece la ventaja de poder definir varias asignaciones de palabras clave para el mismo campo, incluidos diferentes métodos de conversión, en función del valor especificado. Por ejemplo, los asignatarios pueden tener varias asignaciones distintas de palabras clave que indiquen cómo se define su valor según los diversos valores de entrada. Las entradas pueden corresponder al ID de usuario, a los apellidos, al nombre o al segundo nombre y también al ID real de ca_contact (por ejemplo, 793ED69B4E87A545BD8E911834D829FC). Cada una de las palabras clave se asigna a un método de conversión diferente, salvo el último, que no necesita someterse a ninguna conversión.