Alterações no formato da API - 15200
Este documento descreve as diferenças entre os formatos antigo e novo da API para solicitações, módulos personalizados, associações personalizadas e relacionamentos de CI.
O novo formato da API será aplicável para clientes que atualizaram para a build 15200 do ServiceDesk Plus. Recomendamos usar os novos formatos para todas as novas integrações.
Alterações no formato da API de solicitações
Principais alterações no formato da API
- Os campos contêiner de UDF, como cm_fields e udf_fields, foram removidos das APIs de módulo personalizado, associação personalizada e relacionamento de CI.
- A compatibilidade retroativa é suportada para as APIs de módulo personalizado e relacionamento de CI.
- As convenções de nomenclatura para campos adicionais foram padronizadas:
- Módulos padrão:
- Esta atualização se aplica aos seguintes módulos: Usuário, Técnico, CMDB, Release, Projeto, Registro de trabalho, Tarefa, Espaço, Instalação, Fornecedor, Associação de tipo de CI, Ativo, Grupos de suporte e Departamento.
- Os nomes dos campos da API agora seguem o formato udf_<entrada do usuário>.
Formato antigo
Novo formato
udf_<tipo_do_campo>_<entrada_do_usuário> (Exemplo: udf_date_date_of_birth)
ou,
<tipo_do_campo>_<entrada_do_usuário> (Exemplo: date_date_of_birth)
udf_<entrada do usuário>(Exemplo: udf_date_of_birth)
- Módulos personalizados e associações personalizadas:
- Módulos padrão:
- Os nomes dos campos da API agora são totalmente definidos pelo usuário e não incluem o prefixo udf_ . (Exemplo: date_of_birth). Esta atualização se aplica apenas aos campos criados após a migração.
- Os campos criados antes da migração permanecerão inalterados e manterão seu comportamento atual.
API de módulo personalizado
Método | URL | Formato antigo | Novo formato |
| POST / PUT | /api/v3/cm_test /api/v3/cm_test/<ID> | input_data { "cm_test": { "title": "test", "description": "desc", "cm_fields": { "sline_test": "sample", "per_percentage": "10" } } } | input_data { "cm_test": { "title": "test", "description": "desc", "test": "sample", "percentage": "10" } } |
| GET | /api/v3/cm_test/<ID> | Resposta de exemplo: { "response_status": { "status_code": 2000, "status": "success" }, "cm_test": { "created_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "updated_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "cm_fields": { "sline_test": "test", "per_percentage": "10.00" }, "is_trashed": false, "description": null, "id": "602", "title": "test", "created_by": { "email_id": "demo@zylker.com", "phone": "987654321", "name": "Howard Stern", "mobile": "987654321", "profile_pic": { "content-url": "/images/default-profile-pic2.svg" }, "is_vipuser": false, "id": "10", "department": { "site": null, "deleted": false, "name": "Engenharia", "id": "2" } } } } | Resposta de exemplo: { "response_status": { "status_code": 2000, "status": "success" }, "cm_test": { "created_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "updated_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "test": "test", "percentage": "10.00" "is_trashed": false, "description": null, "id": "602", "title": "test", "created_by": { "email_id": "demo@zylker.com", "phone": "987654321", "name": "Howard Stern", "mobile": "987654321", "profile_pic": { "content-url": "/images/default-profile-pic2.svg" }, "is_vipuser": false, "id": "10", "department": { "site": null, "deleted": false, "name": "Engenharia", "id": "2" } } } } |
| GET_ALL | /api/v3/cm_test | input_data { "list_info": { "row_count": "10", "start_index": 1, "get_total_count": true, "search_criteria": { "field": "cm_fields.sline_test", "value": "test", "condition": "contains", "logical_operator": "AND" }, "sort_field": "cm_fields.sline_test", "sort_order": "asc", "fields_required":["cm_fields.sline_test"] } } Resposta de exemplo: { "response_status": [ { "status_code": 2000, "status": "success" } ], "list_info": { "has_more_rows": false, "start_index": 1, "sort_field": "cm_fields.sline_test", "total_count": 1, "page": 1, "sort_order": "asc", "search_criteria": { "condition": "contains", "field": "cm_fields.sline_test", "logical_operator": "AND", "value": "test" }, "get_total_count": "true", "row_count": 1 }, "cm_test": [ { "created_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "updated_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "cm_fields": { "sline_test": "test", "per_percentage": "10.00" }, "is_trashed": false, "description": null, "id": "602", "title": "test", "created_by": { "email_id": "demo@zylker.com", "phone": "987654321", "name": "Howard Stern", "mobile": "987654321", "profile_pic": { "content-url": "/images/default-profile-pic2.svg" }, "is_vipuser": false, "id": "10", "department": { "site": null, "deleted": false, "name": "Engenharia", "id": "2" } } } ] } | input_data { "list_info": { "row_count": "10", "start_index": 1, "get_total_count": true, "search_criteria": { "field": "test", "value": "test", "condition": "contains", "logical_operator": "AND" }, "sort_field": "test", "sort_order": "asc", "fields_required":["test"] } } Resposta de exemplo: { "response_status": [ { "status_code": 2000, "status": "success" } ], "list_info": { "has_more_rows": false, "start_index": 1, "sort_field": "test", "total_count": 1, "page": 1, "sort_order": "asc", "search_criteria": { "condition": "contains", "field": "test", "logical_operator": "AND", "value": "test" }, "get_total_count": "true", "row_count": 1 }, "cm_test": [ { "created_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "updated_time": { "display_value": "25/08/2025 05:32 PM", "value": "1756123347308" }, "test": "test", "percentage": "10.00, "is_trashed": false, "description": null, "id": "602", "title": "test", "created_by": { "email_id": "demo@zylker.com", "phone": "987654321", "name": "Howard Stern", "mobile": "987654321", "profile_pic": { "content-url": "/images/default-profile-pic2.svg" }, "is_vipuser": false, "id": "10", "department": { "site": null, "deleted": false, "name": "Engenharia", "id": "2" } } } ] } |
API de relacionamento de CI
Método | URL | Formato antigo | Novo formato |
| POST | /api/v3/cmdb_apache_instance/1/assoc_apache_connected_to_windows_workstations | input_data: { "assoc_apache_connected_to_windows_workstations": [ { "destination": { "id": "2" }, "udf_fields": { "udf_source_no": "001", "udf_technician": { "id": "5" } } } ] } | input_data: { "assoc_apache_connected_to_windows_workstations": [ { "destination": { "id": "2" }, "udf_source_no": "001", "udf_technician": { "id": "5" } } ] } |
| GET_ALL | /api/v3/cmdb_apache_instance/1/assoc_apache_connected_to_windows_workstations | Resposta de exemplo: { "response_status": [ { "status_code": 2000, "status": "success" } ], "assoc_apache_connected_to_windows_workstations": [ { "udf_fields": { "udf_source_no": "001", "udf_technician": { "email_id": null, "phone": "1234455", "name": "administrator", "mobile": "1234567890", "profile_pic": { "content-url": "/images/default-profile-pic2.svg" }, "is_vipuser": false, "id": "5", "department": null } }, "destination": { "site": null, "inactive": false, "module": { "id": "190" }, "name": "estação de trabalho windows", "id": "2", "entity": { "api_plural_name": "cmdb_windows_workstation", "name": "cmdb_windows_workstation", "icon": { "id": "410" }, "id": "190", "display_name": "Windows Workstation", "display_plural_name": "Windows Workstation", "category": { "id": "18" } }, "status": null }, "id": "2", "association_type": { "name": "Conectado a", "id": 3 } } ], "list_info": { "has_more_rows": false, "start_index": 1, "row_count": 1 } } | Resposta de exemplo: { "response_status": [ { "status_code": 2000, "status": "success" } ], "assoc_apache_connected_to_windows_workstations": [ { "udf_source_no": "001", "udf_technician": { "email_id": null, "phone": "1234455", "name": "administrator", "mobile": "1234567890", "profile_pic": { "content-url": "/images/default-profile-pic2.svg" }, "is_vipuser": false, "id": "5", "department": null }, "destination": { "site": null, "inactive": false, "module": { "id": "190" }, "name": "estação de trabalho windows", "id": "2", "entity": { "api_plural_name": "cmdb_windows_workstation", "name": "cmdb_windows_workstation", "icon": { "id": "410" }, "id": "190", "display_name": "Windows Workstation", "display_plural_name": "Windows Workstation", "category": { "id": "18" } }, "status": null }, "id": "2", "association_type": { "name": "Conectado a", "id": 3 } } ], "list_info": { "has_more_rows": false, "start_index": 1, "row_count": 1 } } |
Alterações de compatibilidade retroativa
Durante a migração, os nomes de API dos módulos personalizados existentes ("web_tab","configuration","hidden","association",and "published") e os relacionamentos de CI são definidos para o atributo paramvalue em GlobalConfig.
Uma mensagem de aviso será exibida durante a migração, como mostrado:
Após a migração, uma mensagem de aviso será exibida na página de detalhes dos módulos personalizados e relacionamentos de CI para os quais a compatibilidade retroativa for fornecida.
Módulos personalizados
Relacionamentos de CI
Gerenciando a compatibilidade retroativa
Para adicionar ou remover módulos do suporte à compatibilidade retroativa, use a seguinte consulta:
Alterações no formato da API de solicitações
Este documento descreve as diferenças entre os formatos antigo e novo da API para campos obrigatórios, transições, estados conectados, níveis de aprovação, checklists e APIs de horário operacional.
O novo formato da API será aplicável para clientes que atualizaram para a build 15200.
Melhorias no fluxo de trabalho
API de campos obrigatórios
| Formato antigo | Novo formato |
URL | 1. api/v3/requests/status_mandatory_fields | 1. api/v3/requests/get_mandatory_fields |
Dados de entrada | {"template_id":5, "status_id":2} | {"template_id":"1","state_id":"2"} |
Resposta | { "status_mandatory_fields": { "checklists": [], "to_be_filled": [ "level", "item" ], "depends_on_requests": [], "optional_fields": [], "fields": [ "level", "item", "tasks" ], "tasks": [] } } | { "mandatory_fields": { "to_be_filled": [ "impact", "level" ], "optional_fields": [], "fields": [ "impact", "level" ] } } |
Observação: Os campos checklists, tasks e depends_on_requests aparecem na resposta somente quando são marcados como obrigatórios.
API de obtenção de transições
| Formato antigo | Novo formato |
URL | api/v3/requests/id/_get_transitions | api/v3/requests/id/_get_transitions |
Resposta | { "response_status": [ { "status_code": 2000, "status": "success" } ], "transitions": [ ... | { "response_status": [ { "status_code": 2000, "status": "success" } ], "transitions": [ ... |
API de obtenção de status conectados
| Formato antigo | Novo formato |
URL | api/v3/requests/id/_get_connected_statuses | api/v3/requests/id/_get_connected_states |
Dados de entrada | { "status_id": 3, "nodes_list_info": { "row_count": 100, "search_criteria": [ ... | { "state_id": 3, "nodes_list_info": { "row_count": 100, "search_criteria": [ ... |
Resposta | { "response_status": [ { "status_code": 2000, "status": "success" } ], "statuses": [ ... | { "response_status": [ { "status_code": 2000, "status": "success" } ], "status": [ ... |
API de obtenção de nós conectados
| Formato antigo | Novo formato |
URL | api/v3/request_lifecycles/<lifecycleid>/get_connected_nodes | /api/v3/request_workflows/<workflowid>/get_connected_nodes |
Dados de entrada | {"node_entity_id":0,"module":{"name":"request"}} | {"state_id":0,"module":{"name":"request"}} |
Resposta | { "response_status": [ ... | { "response_status": [ ... |
Resposta de nível de aprovação
O campo rule.value na resposta do nível de aprovação da solicitação usa os valores atualizados conforme mostrado abaixo:
Valor antigo | Novo valor |
anyone | anyone_approves |
all | everyone_approves |
first_response | first_response_action |
| Formato antigo | Novo formato |
URL | GET - /requests/{id}/approval_level/{id} | GET - /requests/{id}/approval_level/{id} |
RESPOSTA | ... | ... |
API de horário operacional
Principais diferenças no nível da entidade
Chave antiga | Nova chave | Observações |
site | associated_sites | Os detalhes do site foram alterados para o formato de array. |
days_of_operation | days |
|
hours_of_operation | hours |
|
site_type | (removido) | O tipo de site é selecionado com base no valor de horário global. |
day_type | (removido) | O tipo de dia é selecionado com base na chave is_standard |
exclude_weeks | exception_rules | exclude_weeks foi removido do objeto day e uma nova chave foi colocada externamente. |
Diferenças na resposta
Use a legenda abaixo para entender os códigos de cores usados na tabela:
Vermelho - Chaves removidas
Amarelo - Chaves modificadas
Verde - Chaves recém-adicionadas
Melhorias em checklists
Principais diferenças
Consulte a tabela abaixo para uma comparação rápida das principais alterações introduzidas com as atualizações da API.
Use a legenda abaixo para entender os códigos de cores usados na tabela:
Vermelho - Chaves removidas
Amarelo - Chaves modificadas
Verde - Chaves recém-adicionadas
Alterações no formato de entrada da API de checklist:
API | URL da API (ANTIGA) | URL da API (NOVA) | FORMATO DE ENTRADA ANTIGO | FORMATO DE ENTRADA NOVO |
Adicionar (campo de opção) | /api/v3/additional_fields | /api/v3/item_details | ... | ... |
