# Escribir un script personalizado - API V3

Necesita conocimientos prácticos de:

- JSON
- Python

## Estructura del archivo de script personalizado

1. Importar los paquetes requeridos
2. Obtener los argumentos de entrada
3. Implementar la lógica
4. Devolver JSON

## Paquetes de uso frecuente

| Paquete | Uso |
|---|---|
| Sys | Obtiene los argumentos de entrada |
| json | Manipula datos JSON |
| requests | Realiza llamadas API |
| datetime | Transforma el tiempo de milisegundos al formato de fecha requerido |

## Obtener argumentos de entrada

Los argumentos del archivo de script se pueden obtener usando `sys.argv[index]`, donde `index` comienza desde 1 hasta el número de argumentos pasados.

Cuando el argumento pasado es `$COMPLETE_V3_JSON_FILE` (la ruta al archivo que contiene la solicitud y el JSON Diff), el archivo JSON se puede leer usando el siguiente fragmento:

```python
file_Path = sys.argv[1]
with open(file_Path) as data_file:
    data = json.load(data_file)
```

## Implementar la lógica

Fragmento para realizar una llamada API:

```python
with requests.Session() as s:
    url = 'api_url'
    r = s.post(url, verify=True, data=post_data, headers=headers)
```

Construya `api_url`, `post_data` y `headers` según sea necesario.

Fragmento para transformar el tiempo de milisegundos al formato de fecha requerido:

```python
date = datetime.datetime.fromtimestamp(int(millisec)/1e3).strftime('%d %b %Y, %H:%M:%S')
```

## Construcción del JSON de retorno

Construcción de un JSON de ejemplo como `{"key":"value"}`:

```python
json = {}
json["key"] = "value"
print(json)
```

Construcción de un arreglo JSON de ejemplo como `[{"key":"value"}]`:

```python
json = {}
json["key"] = "value"
result = []
result.append(json)
print(result)
```

Algunas operaciones se pueden realizar usando el JSON devuelto por el script. Obtenga más información sobre las operaciones realizadas usando el JSON de retorno [aquí](https://www.manageengine.com/latam/service-desk/help/adminguide/configurations/helpdesk/OutputFormat_JSONScript.html).

A continuación se muestra un ejemplo que muestra la construcción de un JSON que actualiza los campos adicionales de una solicitud `JIRA_ISSUE_ID` y `JIRA_ISSUE_URL` y agrega una nota al respecto.

### Actualizar los campos adicionales de una solicitud

```python
import requests
import sys
import json,os
resultjson={}
resultjson["operation"] = []
resultjson["result"]="success"
message = "Script de Python de ejemplo para actualizar una solicitud"
resultjson["message"]=message
operationJson={"INPUT_DATA":[]}
operationJson["OPERATIONNAME"]="UPDATE"
operationJson["FORMAT"]="V3"
updateReqArray_field={}
updateReqArray_field['udf_sline_2101']="123"
updateReqArray_field['udf_sline_1803']="abcd"
updateReqArray={}
updateReqArray['udf_fields']=updateReqArray_field
updateReq={}
updateReq['request']=updateReqArray
operationJson['INPUT_DATA'].append(updateReq)
resultjson['operation'].append(operationJson)
print(resultjson)
```

### Agregar una nota

```python
import sys
import json

resultjson={}

message = "Script de Python de ejemplo para agregar una nota usando la API v3"
resultjson["operation"] = []
resultjson["result"]="success"
operationJson={"INPUT_DATA":[]}
operationJson["OPERATIONNAME"]="ADD_NOTE"
operationJson["FORMAT"]="V3"

requestNoteDetails={}
requestNoteDetails['description']="Solicitud de Jira creada"
requestNoteDetails['show_to_requester']="false"
requestNoteDetails['notify_technician']="true"
requestNoteDetails['mark_first_response']="false"
requestNoteDetails['add_to_linked_requests']="true"
requestNote={}
requestNote['request_note']=requestNoteDetails

resultjson["message"]=message
operationJson['INPUT_DATA'].append(requestNote)
resultjson['operation'].append(operationJson)

print(resultjson)
```

## Parámetro compatible: $COMPLETE_V3_JSON_FILE

`$COMPLETE_V3_JSON_FILE` indica la ruta de un archivo que tiene los detalles completos de la solicitud, los valores anteriores y actualizados de los campos en formato JSON. El archivo es temporal y se eliminará automáticamente después de ejecutar el script.

El archivo JSON temporal se crea en el directorio `SDP_Home\integration\custom_scripts\request\`, y el nombre del archivo es `<requestid_timestamp>.json`.

**Estructura de $COMPLETE_V3_JSON_FILE**

```json
{
  "request": {
    <todas las propiedades de la solicitud en formato V3>
  },
  "diff": {
    "old": {
      "request": {
        "priority": {
          "id": "4",
          "name": "Alta"
        },
        "urgency": {
          "id": "3",
          "name": "Normal"
        },
        "impact_details": "Alto impacto para servidores"
      }
    },
    "new": {
      "request": {
        "priority": {
          "id": "1",
          "name": "Baja"
        },
        "urgency": {
          "id": "4",
          "name": "Baja"
        },
        "impact_details": "Bajo impacto para servidores"
      }
    }
  },
  "LOGIN_NAME": "administrator",
  "LOGGEDIN_USER_TYPE": "Técnico",
  "LOGGEDIN_USER_NAME": "administrator",
  "OPERATION_TYPE": "add"
}
```

## Entrada proporcionada al archivo temporal $COMPLETE_V3_JSON_FILE

La entrada está en JSON. Aquí, la clave **request** contiene todos los campos de la solicitud en formato de API V3, excepto `resolution`, `first_response_due_by_time`, `due_by_time` y `sla`.

### Información adicional proporcionada en el archivo de entrada

1. LOGIN_NAME
2. LOGGEDIN_USER_NAME
3. LOGIN_USER_ID
4. LOGGEDIN_USER_TYPE
5. OPERATION_TYPE

## Formato JSON de salida para scripts personalizados

El script para el archivo de solicitudes debe devolver un JSON que tenga el estado de éxito/fracaso y un mensaje que se mostrará en la pestaña de historial de la solicitud.

Formato general:

```json
{
  "result": "success",
  "message": "Mensaje"
}
```

- Result indica el estado de éxito/fracaso de la acción.
- Message es la información que se mostrará en la pestaña de historial de la solicitud.

El script del servidor debe escribir el JSON de salida (si existe) en el mismo archivo temporal que se proporciona al script. No debe invocar llamadas API externas para actualizar la misma solicitud, ya que esto no permitirá que los valores actualizados se transfieran a las reglas de negocio en cascada.

## $COMPLETE_V3_JSON_FILE

`$COMPLETE_V3_JSON_FILE` indica la ruta del archivo que tiene tanto `COMPLETE_JSON` como `DIFF_JSON` juntos en un solo JSON. En lugar de pasar demasiados parámetros a la clase/script, se puede pasar la ruta del archivo y el script puede abrir el archivo y acceder a los valores requeridos.

El archivo se crea temporalmente y se elimina después de ejecutar el script.

El archivo JSON temporal se crea en el directorio `SDP_Home\integration\custom_scripts\request\` y el nombre del archivo es `<requestid_timestamp>.json`.