Archivos IAC - Integration as Code

La definición de módulos de Skyone Studio puede realizarse mediante archivos IAC. Son archivos en formato JSON que siguen un esquema (schema) predefinido y permiten definir tus módulos de forma programática.

Definición

Un archivo IAC contiene todas las especificaciones de un módulo de manera estructurada. Puedes crear tus propias definiciones de módulo e importarlas en Skyone Studio.

A continuación, encuentras un ejemplo de un módulo en formato IAC. Los parámetros iniciales pertenecen al módulo y todas las operaciones se definen dentro del arreglo operations. La definición de cada operación también posee características básicas como nombre y descripción. Las demás características están agrupadas en bloques específicos, como parameters y request.

Ejemplos de archivo IAC de 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</>"
                    }
                ]
            }
        }
    ]
}

La definición completa del schema se encuentra a continuación:

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}"
          }
        }
      ]
    }
  ]
}

La tabla siguiente describe los principales campos de la estructura de un archivo IAC:

Propiedad	Descripción
Name	Nombre del módulo.
id	ID del módulo. Este ID es proporcionado por Skyone Studio durante la exportación. Para crear un módulo nuevo, utiliza un id vacío. Skyone Studio creará un módulo nuevo si no reconoce el id proporcionado.
Descripción	Descripción del módulo.
type	Tipo de módulo. Tipos soportados: REST, RFC, Database.
settings.authentication_type	Mecanismo de autenticación utilizado por el módulo.
operations.[].name	Nombre de la operación.
operation.[].id	ID de la operación. Este ID es proporcionado por Skyone Studio durante la exportación. Para crear una operación nueva, utiliza un id vacío. Skyone Studio creará una operación nueva si no reconoce el id proporcionado.
description	Descripción de la operación.
operations.[].parameters.[].name	Nombre del parámetro.
operations.[].parameters.[].type	Tipo de dato pasado como parámetro: object, string.
operations.[].parameters.[].description	Descripción del parámetro.
operations.[].parameters.[].required	Define si el parámetro es obligatorio: true / false.
operations.[].parameters.[].sensitive	Define si el parámetro es sensible: true / false.
operations.[].parameters.[].sample	Ejemplo de parámetro. Puede venir como un objeto vacío o una cadena vacía. Los objetos JSON deben pasarse como cadenas JSON.
operations.[].request.method	Método utilizado por la operación: GET, POST, PUT, PATCH, DELETE.
operations.[].request.url.path	La ruta se pasa como una lista que contiene sus componentes.
operations.[].request.url.query	Lista de pares key/value con las definiciones de las query strings.
operations.[].request.header	Lista de pares key/value con las definiciones de las entradas del header.
operations.[].request.body	Definición del body para solicitudes POST o PATCH. Ver ejemplo abajo: "body": { "mode": "raw", "raw": "{ "key1":"value1",\n\t"key2":<>body_parm1</>\n\t}", "options": { "raw": { "language": "json" } } }

Ejemplo de body en el schema:

"body": {
  "mode": "raw",
  "raw": "{ \"key1\":\"value1\",\n\t\"key2\":<>body_parm1</>\n\t}",
  "options": {
    "raw": { "language": "json" }
  }
}

Las propiedades varían de acuerdo con el type elegido. A continuación, ver más ejemplos:

Ejemplo de archivo IAC del 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)"
            }
        }
    ]
}

Ejemplo de archivo IAC del 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 pasos

Puedes crear nuevos módulos proporcionando un archivo IAC. Además, Skyone Studio permite exportar la especificación de un archivo IAC existente para que puedas realizar actualizaciones mediante un UPDATE.

Lee también: Creación de módulo con archivo IAC.