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 way. You can create your own module definitions and import them into the platform.
Below you will find an example of a module in IAC format. The initial parameters are from the module and all operations are defined within the operations array. The definition of each operation also has basic characteristics like a name and a description. The other characteristics are grouped into specific blocks such as 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:
name
Connector module name
id
Module ID. This ID is provided by the platform during export. To create a new module use an empty id.
The platform will create a new module if it doesn’t recognize the id provided
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 the platform during export. To create a new module use an empty id.
The platform will create a new module if it doesn’t recognize the id provided
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. In addition, the platform allows you to export the specification of an existing IAC file so that you can make updates via an UPDATE.
Last updated