IAC Files - Integration as Code

The definition of modules can be done through IAC files. These are JSON format files that follow a pre-defined schema and allow you to define your modules programmatically.

---

Definitions

An IAC file contains all the specifications of a module in a structured format. You can create your own module definitions and import them into Skyone Studio.

Below is an example of a module in the IAC format. The initial parameters belong to the module, and all operations are defined within the operations array. Each operation definition also includes basic properties such as name and description. Other properties are grouped into specific blocks like parameters and request.

Example REST IAC File

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

The complete definition of schema can be seen below.

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

The table below describes the main fields of an IAC file structure:

Property	Description
name	Connector module name
id	Module ID. This ID is provided by Skyone Studio during export. To create a new module, use an empty ID. Skyone Studio will create a new module if it does not recognize the provided ID.
description	Module description
type	Module type. Supported types: REST RFC Database
settings.authentication_type	Authentication mechanism used by the module.
operations.[].name	Operation Name
operations.[].id	Operation ID. This ID is provided by Skyone Studio during export. To create a new operation, use an empty ID. Skyone Studio will create a new operation if it does not recognize the provided ID.
description	Operation description
operations.[].parameters.[].name	Parameters Name
operations.[].parameters.[].type	Type of data that you pass as a parameter: object string
operations.[].parameters.[].description	Parameter description
operations.[].parameters.[].required	Definition if it is a mandatory parameter. true false
operations.[].parameters.[].sensitive	Definition if it is a sensitive parameters true false
operations.[].parameters.[].sample	(optional) Parameter example. It can come as an empty object or an empty string. JSON objects must be send as JSON strings
operations.[].request.method	Method used by the operation: GET POST PUT PATCH DELETE
operations.[].request.url.path	The path is sent as a list that contains its components.
operations.[].request.url.query	List of key/value pairs containing the query string definitions.
operations.[].request.header	List of key/value pairs containing the definitions of the header entries.
operations.[].request.body	Body definition for POST or PATCH requests. e.g. "body": { "mode": "raw", "raw": "{ "key1":"value1",\n\t"key2":<>body_parm1</>\n\t}", "options": { "raw": { "language": "json" } } }

The properties change according to the type chosen. See below for more examples:

Example DATABASE IAC File

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

Example RFC IAC File

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

Next steps

You can create new modules by providing an IAC file. Additionally, Skyone Studio allows you to export the specification of an existing IAC file so that you can make updates via an UPDATE.

Read also: Creating a module with an IAC file