Arquivos IAC - Integration as Code

A definição de módulos da plataforma pode ser feita através de arquivos IAC. São arquivos no formato JSON que seguem um schema predefinido e permitem que você defina os seus módulos de forma programática.

---

Definição

Um arquivo IAC contém todas as especificações de um módulo de forma estruturada. Você pode criar suas próprias definições de módulo e importar na plataforma.

Abaixo você encontra um exemplo de um módulo no formato IAC. Os parâmetros iniciais são do módulo e todas as operações são definidas dentro do array operations. A definição de cada operação também possui características básicas como nome e descrição. As demais características estão agrupadas em blocos específicos como parameters e request.

Exemplo de Arquivo IAC do tipo REST

{
    "name": "Test Module 001",
    "id": "",
    "description": "Test Module 001",
    "type": "REST",
    "settings": {
        "authentication_type": "Basic"
    },
    "operations": [
        {
            "name": "Operation 001",
            "id": "",
            "description": "Test Operation 001",
            "parameters": [
                {
                    "name": "key-value1",
                    "type": "string",
                    "description": "Description parameter 001",
                    "required": true,
                    "sensitive": true,
                    "sample": "XXXXXXXXXXXXXXXX"
                },
                {
                    "name": "header-value1",
                    "type": "string",
                    "description": "Description header-parameter",
                    "required": true,
                    "sensitive": true,
                    "sample": "YYYYYYYYYYYYYYYYY"
                }
            ],
            "request": {
                "method": "GET",
                "url": {
                    "path": [
                        "segment01",
                        "segment02"
                    ],
                    "query": [
                        {
                            "key": "key1",
                            "value": "<>key-value1</>"
                        },
                        {
                            "key": "key-static",
                            "value": "static-value"
                        }
                    ]
                },
                "header": [
                    {
                        "key": "Content-Type",
                        "value": "application/json"
                    },
                    {
                        "key": "Authorization",
                        "value": "<>header-value1</>"
                    }
                ]
            }
        }
    ]
}

A definição completa do schema se encontra a seguir:

Schema IAC

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "http://example.com/example.json",
  "type": "object",
  "default": {},
  "title": "Module Name",
  "required": ["name", "id", "type", "settings", "operations"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 30,
      "default": "New Module",
      "title": "Module Name",
      "examples": ["Test Module 001"]
    },
    "id": {
      "type": "string",
      "default": "",
      "title": "Module Id - Integra.Sky supplied",
      "examples": ["XXXXXXXXXXXXXXXX"]
    },
    "description": {
      "type": "string | null",
      "default": "New Module Description",
      "title": "Module Description (300 chars)",
      "examples": ["Test Module 001 description"]
    },
    "type": {
      "type": "string",
      "default": "",
      "title": "Type of the Module",
      "enum": ["REST", "SOAP", "database", "file", "email"]
    },
    "settings": {
      "type": "object",
      "default": {},
      "title": "Basic Module Settings",
      "required": ["authentication_type"],
      "properties": {
        "authentication_type": {
          "type": "string",
          "default": "",
          "title": "REST Authentication Type",
          "enum": [
            "No auth",
            "Basic",
            "Bearer Token",
            "OAauth",
            "Cookie",
            "AWS",
            "OAuth2 JWT"
          ]
        }
      },
      "database_type": {
        "type": "string",
        "default": "",
        "title": "Database Type",
        "enum": [
          "mysql",
          "postgresql",
          "mssql",
          "firebird",
          "firebird3+",
          "oracle"
        ]
      },
      "storage_type": {
        "type": "string",
        "default": "",
        "title": "Storage Type",
        "examples": ["ftp", "sftp"]
      },
      "service": {
        "type": "string",
        "default": "",
        "title": "Service Type",
        "enum": ["smtp", "aws-ses"]
      },
      "wsld": {
        "type": "string",
        "default": "",
        "title": "Wsld file",
        "examples": ["http://domain.com/file"]
      },
      "account": {
        "type": "string",
        "default": "",
        "title": "Integra.Sky access account",
        "examples": ["XXXXXXXXXXXXXXXX"]
      },
      "examples": [
        {
          "authentication_type": "Basic"
        }
      ]
    },
    "operations": {
      "type": "array",
      "default": [],
      "title": "List of Operations",
      "items": {
        "type": "object",
        "default": {},
        "title": "Operation Definition",
        "required": ["name", "request"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "default": "",
            "title": "Operation Name",
            "examples": ["Operation 0001"]
          },
          "id": {
            "type": "string",
            "default": "",
            "title": "Integra.Sky Operation Id",
            "examples": ["XXXXXXXXXXXXXXXX"]
          },
          "description": {
            "type": "string | null",
            "default": "",
            "title": "Operation Description",
            "examples": ["Test Operation 001"]
          },
          "parameters": {
            "type": "array",
            "default": [],
            "title": "List of parameters",
            "items": {
              "type": "object",
              "default": {},
              "title": "Parameter Definition",
              "required": ["name", "type", "required", "sensitive", "sample"],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 50,
                  "default": "",
                  "title": "Parameter Name",
                  "examples": ["ops_body"]
                },
                "type": {
                  "type": "string",
                  "default": "",
                  "title": "Parameter Type",
                  "enum": ["object", "string", "number", "array"]
                },
                "description": {
                  "type": "string | null",
                  "default": "",
                  "title": "Parameter Description",
                  "examples": ["Description parameter 001"]
                },
                "required": {
                  "type": "boolean",
                  "default": false,
                  "title": "Is mandatory",
                  "examples": [true]
                },
                "sensitive": {
                  "type": "boolean",
                  "default": false,
                  "title": "Is sensitive (clear when sharing)",
                  "examples": [true]
                },
                "sample": {
                  "type": "string",
                  "default": "",
                  "title": "Sample for the parameter",
                  "examples": ["{}"]
                }
              },
              "examples": [
                {
                  "name": "ops_body",
                  "type": "object",
                  "description": "Body for the REST call",
                  "required": true,
                  "sensitive": true,
                  "sample": "{ \"parm1\":\"value1\" }"
                }
              ]
            }
          },
          "request": {
            "type": "object",
            "default": {},
            "title": "Request Definition",
            "required": ["method", "url"],
            "properties": {
              "method": {
                "type": "string",
                "default": "",
                "title": "Request Method",
                "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
              },
              "url": {
                "type": "object",
                "default": {},
                "title": "URL description",
                "required": ["path"],
                "properties": {
                  "path": {
                    "type": "array",
                    "default": [],
                    "title": "List of path segments",
                    "items": {
                      "type": "string",
                      "title": "Path segments",
                      "examples": ["segment01", "segment02"]
                    }
                  },
                  "query": {
                    "type": "array",
                    "default": [],
                    "title": "Query Strings Definition",
                    "items": {
                      "type": "object",
                      "default": {},
                      "title": "Key/Value Pairs",
                      "required": ["key", "value"],
                      "properties": {
                        "key": {
                          "type": "string",
                          "default": "",
                          "title": "Query string key",
                          "examples": ["key"]
                        },
                        "value": {
                          "type": "string",
                          "default": "",
                          "title": "Query string value",
                          "examples": ["<>value</>"]
                        }
                      },
                      "examples": [
                        {
                          "key": "key",
                          "value": "<>value</>"
                        }
                      ]
                    }
                  }
                }
              },
              "header": {
                "type": "array",
                "default": [],
                "title": "Header Definition",
                "items": {
                  "type": "object",
                  "default": {},
                  "title": "Key/Value Pairs",
                  "required": ["key", "value"],
                  "properties": {
                    "key": {
                      "type": "string",
                      "default": "",
                      "title": "Header Key",
                      "examples": ["Content-Type"]
                    },
                    "value": {
                      "type": "string",
                      "default": "",
                      "title": "Header Value",
                      "examples": ["application/json"]
                    }
                  }
                }
              },
              "body": {
                "type": "object",
                "default": {},
                "title": "Body Definition",
                "required": ["mode"],
                "properties": {
                  "mode": {
                    "type": "string",
                    "default": "",
                    "title": "Body Mode",
                    "enum": ["raw"]
                  },
                  "raw": {
                    "type": "string",
                    "default": "",
                    "title": "Body content",
                    "examples": ["<>ops_body</>"]
                  },
                  "options": {
                    "type": "object",
                    "default": {},
                    "title": "Body Options",
                    "required": ["raw"],
                    "properties": {
                      "raw": {
                        "type": "object",
                        "default": {},
                        "title": "Raw options",
                        "required": ["language"],
                        "properties": {
                          "language": {
                            "type": "string",
                            "default": "",
                            "title": "Language Type",
                            "enum": ["json"]
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "examples": [
              {
                "method": "GET",
                "url": {
                  "path": ["leaf01", "leaf02"],
                  "query": [
                    {
                      "key": "key",
                      "value": "<>value</>"
                    }
                  ]
                },
                "header": [
                  {
                    "key": "exemplo-key",
                    "value": "<>exemplo</>"
                  }
                ],
                "body": {
                  "mode": "raw",
                  "raw": "<>ops_body</>",
                  "options": {
                    "raw": {
                      "language": "json"
                    }
                  }
                }
              }
            ]
          }
        }
      }
    }
  },
  "examples": [
    {
      "name": "Test Module REST 001",
      "id": "",
      "description": "Test Module 001",
      "type": "REST",
      "settings": {
        "authentication_type": "Basic"
      },
      "operations": [
        {
          "name": "Operation 0001",
          "id": "",
          "description": "Test Operation 001",
          "parameters": [
            {
              "name": "ops_body",
              "type": "object",
              "description": "Description parameter 001",
              "required": true,
              "sensitive": true,
              "sample": "{}"
            },
            {
              "name": "key-value",
              "type": "string",
              "description": "Description parameter 002",
              "required": true,
              "sensitive": true,
              "sample": "XXXXXXXXXXXXXXXX"
            }
          ],
          "request": {
            "method": "GET",
            "url": {
              "path": ["segment01", "segment02"],
              "query": [
                {
                  "key": "key",
                  "value": "<>key-value</>"
                }
              ]
            },
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "<>ops_body</>",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    },
    {
      "name": "Test Module Database 001",
      "id": "",
      "description": "Test Module 001",
      "type": "DATABASE",
      "settings": {
        "database_type": "ORACLE"
      },
      "operations": [
        {
          "name": "Operation 0001",
          "id": "",
          "description": "Test Operation 001",
          "parameters": [
            {
              "name": "ops_body",
              "type": "object",
              "description": "Description parameter 001",
              "required": true,
              "sensitive": true,
              "sample": "{}"
            }
          ],
          "query": {
            "query_string": "EXAMPLE   \n  WITH   \n(\nroot_ent_sai varchar(200)"
          }
        }
      ]
    },
    {
      "name": "Test Module RFC 001",
      "id": "",
      "description": "Test Module 001",
      "type": "RFC",
      "settings": {
        "type": "RFC"
      },
      "operations": [
        {
          "name": "Operation 0001",
          "id": "",
          "description": "Test Operation 001",
          "parameters": [
            {
              "name": "IN_ITEM",
              "type": "object",
              "description": "Description parameter 001",
              "required": true,
              "sensitive": true,
              "sample": "{}"
            }
          ],
          "rfc": {
            "function": "FUNCTION_NAME_LISTA",
            "parameter": "{\n    \"IN_OPERACAO\": \"I\",\n    \"IN_ITEM\":  \n            <>IN_ITEM</>\n}"
          }
        }
      ]
    }
  ]
}

A tabela abaixo descreve os principais campos da estrutura de um arquivo IAC:

Propriedade	Descrição
name	Nome do módulo conector
id	ID do módulo. Esse ID é fornecido pela plataforma durante a exportação. Para criar um módulo novo utilize um id vazio. A plataforma criar um novo módulo caso não reconheça o id fornecido
description	Descrição do módulo
type	Tipo do módulo. Tipos suportados: REST RFC Database
settings.authentication_type	Mecanismo de autenticação utilizado pelo módulo.
operations.[].name	Nome da operação
operations.[].id	ID da operação. Esse ID é fornecido pela plataforma durante a exportação. Para criar uma operação nova utilize um id vazio. A plataforma irá criar uma operação nova caso não reconheça o id fornecido.
description	Descrição da operação
operations.[].parameters.[].name	Nome do parâmetro
operations.[].parameters.[].type	Tipo de dado passado como parâmetro: object string
operations.[].parameters.[].description	Descrição do parâmetro
operations.[].parameters.[].required	Definição se trata-se de parâmetro obrigatório. true false
operations.[].parameters.[].sensitive	Definição se trata-se de parâmetros sensível true false
operations.[].parameters.[].sample	(optional) Exemplo de parâmetro. Pode vir como um objeto vazio ou uma string vazia. Objetos JSON devem ser passados como strings JSON
operations.[].request.method	Metodo utilizado pela operação: GET POST PUT PATCH DELETE
operations.[].request.url.path	O path é passado como uma lista contendo os seus componentes.
operations.[].request.url.query	Lista de pares key/value contendo as definições das query strings.
operations.[].request.header	Lista de pares key/value contendo as definições das entradas do header.
operations.[].request.body	Definição do body para requisições POST ou PATCH. ex: "body": { "mode": "raw", "raw": "{ "key1":"value1",\n\t"key2":<>body_parm1</>\n\t}", "options": { "raw": { "language": "json" } } }

As propriedades variam de acordo com o type escolhido. Veja a seguir mais exemplos:

Exemplo de arquivo IAC do tipo Database

{
    "name": "Test Database Module 001",
    "id": "",
    "description": "Test Database Module 001",
    "type": "DATABASE",
    "settings": {
        "database_type": "ORACLE"
    },
    "operations": [
        {
            "name": "Operation 0001",
            "id": "",
            "description": "Test Operation 001",
            "parameters": [
                {
                    "name": "array_regras",
                    "type": "array",
                    "description": "Description parameter 001",
                    "required": true,
                    "sensitive": true,
                    "sample": "[\n  {\n    \"root_ent_sai\": \"3\",\n    \"root_id_cenario\": \"1111427\"\n  }\n]"
                }
            ],
            "query": {
                "query_string": "DECLARE @json NVARCHAR(max)  = N'<>array_regras</>' \n INSERT INTO Systax_Retorno_Produtos\n   SELECT *   \n  FROM OPENJSON(@json)  \n  WITH   \n(\nroot_ent_sai varchar(200), \nroot_id_cenario varchar(200)\n)"
            }
        }
    ]
}

Exemplo de arquivo IAC do tipo RFC

{
    "name": "Test RFC Module 001",
    "id": "",
    "description": "Test RFC Module 001",
    "type": "RFC",
    "settings": {
        "type": "RFC"
    },
    "operations": [
        {
            "name": "Operation 0001",
            "id": "",
            "description": "Test Operation 001",
            "parameters": [
                {
                    "name": "IN_ITEM",
                    "type": "object",
                    "description": "Description parameter 001",
                    "required": true,
                    "sensitive": true,
                    "sample": "{\n\t\t\t\"SEQ_CARREGAMENTO\": 1,\n\t\t\t\"NOM_MANGA\": \"HPT\",\n\t\t\t\"NUM_VAGAO\": \"844661-0\",\n\t\t\t\"VAL_PESO_LIQUIDO\": 96.648,\n\t\t\t\"VAL_PESO_BRUTO\": 125.5,\n\t\t\t\"DATA_CADASTRO\": \"20220630\",\n\t\t\t\"HORA_CADASTRO\": \"150340\"\n}"
                }
            ],
            "rfc": {
                "function": "Z_SDF_CADASTRO_LISTA_TU",
                "parameter": "{\n    \"IN_OPERACAO\": \"I\",\n    \"IN_ITEM\":  \n            <>IN_ITEM</>\n}"
            }
        }
    ]
}

Próximos Passos

Você pode criar novos módulos fornecendo um arquivo IAC. Além disso, a plataforma permite que você exporte a especificação de um arquivo IAC existente para que você possa fazer atualizações através de um UPDATE.

Leia também: Criação de módulo com arquivo IAC