# Escrevendo um script personalizado - API V3

Você precisa ter conhecimento prático de:

- JSON
- Python

## Estrutura do arquivo de script personalizado

1. Importar os pacotes necessários
2. Obter os argumentos de entrada
3. Implementar a lógica
4. Retornar JSON

## Pacotes usados com frequência

| Pacote | Uso |
|---|---|
| Sys | Obtém os argumentos de entrada |
| json | Manipula dados JSON |
| requests | Faz chamadas de API |
| datetime | Transforma o tempo de milissegundos para o formato de data necessário |

## Obtendo argumentos de entrada

Os argumentos do arquivo de script podem ser obtidos usando `sys.argv[index]`, em que o índice começa de 1 até o número de argumentos passados.

Quando o argumento passado é `$COMPLETE_V3_JSON_FILE` (o caminho para o arquivo que contém a solicitação e o JSON Diff), o arquivo JSON pode ser lido usando o seguinte trecho:

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

## Implementando a lógica

Trecho para fazer chamada de API:

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

Construa `api_url`, `post_data` e `headers` conforme necessário.

Trecho para transformar o tempo de milissegundos para o formato de data necessário:

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

## Construindo JSON de Retorno

Um exemplo de construção de JSON, como `{"key":"value"}`:

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

Um exemplo de construção de array JSON, como `[{"key":"value"}]`:

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

Algumas operações podem ser realizadas usando o JSON retornado pelo script. Saiba mais sobre as operações realizadas usando JSON de retorno [aqui](https://www.manageengine.com/products/service-desk/help/adminguide/configurations/helpdesk/OutputFormat_JSONScript.html).

A seguir, há um exemplo que mostra a construção de um JSON que atualiza os campos adicionais de uma solicitação JIRA_ISSUE_ID & JIRA_ISSUE_URL e adiciona uma nota sobre isso.

**Atualizar os campos adicionais de uma solicitação**

```python
import requests
import sys
import json,os
resultjson={}
resultjson["operation"] = []
resultjson["result"]="success"
message = "Sample Python script for update request"
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)
```

**Adicionando uma nota**

```python
import sys
import json

resultjson={}

message = "Sample Python script for adding note using v3 API"
resultjson["operation"] = []
resultjson["result"]="success"
operationJson={"INPUT_DATA":[]}
operationJson["OPERATIONNAME"]="ADD_NOTE"
operationJson["FORMAT"]="V3"

requestNoteDetails={}
requestNoteDetails['description']="Jira Request Created"
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 suportado — $COMPLETE_V3_JSON_FILE

$COMPLETE_V3_JSON_FILE indica o caminho de um arquivo que contém detalhes completos da solicitação, valores anteriores e atualizados dos campos no formato JSON. O arquivo é temporário e será excluído automaticamente após a execução do script.

O arquivo JSON temporário é criado no diretório `SDP_Home\integration\custom_scripts\request\`, com o nome de arquivo sendo `<requestid_timestamp>.json`.

**Estrutura de $COMPLETE_V3_JSON_FILE**

```json
{
  "request":{
    <todas as propriedades da solicitação no 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":"Baixa"},
        "urgency":{"id":"4","name":"Baixa"},
        "impact_details":"Baixo impacto para servidores"
      }
    }
  },
  "LOGIN_NAME":"administrator",
  "LOGGEDIN_USER_TYPE":"Técnico",
  "LOGGEDIN_USER_NAME":"administrator",
  "OPERATION_TYPE":"adicionar"
}
```

## Entrada fornecida para o arquivo temporário $COMPLETE_V3_JSON_FILE

A entrada está em JSON. Aqui, a chave **request** contém todos os campos da solicitação no formato da API V3, exceto `resolution`, `first_response_due_by_time`, `due_by_time` e `sla`.

### Informações adicionais fornecidas no arquivo de entrada

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

## Formato JSON de saída para scripts personalizados

O script para o arquivo de solicitações deve retornar um JSON que contenha o status de sucesso/falha e uma mensagem que será exibida na guia de histórico da solicitação.

Formato geral:

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

- Result indica o status de sucesso/falha da ação.
- Message é a informação a ser exibida na guia de histórico da solicitação.

O script do servidor deve gravar o JSON de saída (se houver) no mesmo arquivo temporário fornecido ao script. Você não deve invocar chamadas de API externas para atualizar a mesma solicitação, pois isso não permitirá que os valores atualizados sejam levados adiante para as regras de negócio em cascata.

## $COMPLETE_V3_JSON_FILE

$COMPLETE_V3_JSON_FILE indica o caminho do arquivo que contém COMPLETE_JSON e DIFF_JSON juntos em um único JSON. Em vez de passar muitos parâmetros para a classe/script, o caminho do arquivo pode ser passado e o script pode abrir o arquivo e acessar os valores necessários.

O arquivo é criado temporariamente e é excluído após a execução do script.

O arquivo JSON temporário é criado no diretório `SDP_Home\integration\custom_scripts\request\`, com o nome do arquivo sendo `<requestid_timestamp>.json`.