Soft1 Web Services Metadata API Overview

Beyond the standard data read/write services (getData, setData, SqlData, etc.), Soft1 Web Services expose a set of services that return metadata about an installation: which objects exist, which tables make up each object, which fields each table has, which gadgets are available, and what access rights a user has on a given object.

These services are particularly useful when building integrations, because they let a developer discover the structure of a Soft1 installation dynamically, without needing database access or the Designer.

General

All calls are made with HTTP POST to the endpoint:

https://[SerialNumber].oncloud.gr/s1services

The request body is JSON and always contains:

Parameter	Description
`service`	The name of the service being called
`clientID`	The token returned by the `login` / `authenticate` flow
`appId`	The application ID (e.g. `1199`)

Every response contains a success field (true/false) and, depending on the service, the corresponding data.

Note: In the examples below the clientID is shortened for readability.

1. getObjects — List of objects

Returns all objects available in the installation, with their name, type and caption.

Request

{
  "service": "getObjects",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199"
}

{
  "service": "getObjects",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199"
}

JavaScript

Response

{
  "success": true,
  "count": 1325,
  "objects": [
    {
      "name": "$ABCST",
      "type": "EditList",
      "caption": "Στοιχεία οριζόμενης διάστασης"
    },
    {
      "name": "$ABSPPRMS",
      "type": "EditList",
      "caption": "Γενικές παράμετροι azure blob storage"
    },
    {
      "name": "$ACNCATEGORY",
      "type": "EditList",
      "caption": "Κατηγορίες λογαριασμών"
    }
  ]
}

{
  "success": true,
  "count": 1325,
  "objects": [
    {
      "name": "$ABCST",
      "type": "EditList",
      "caption": "Στοιχεία οριζόμενης διάστασης"
    },
    {
      "name": "$ABSPPRMS",
      "type": "EditList",
      "caption": "Γενικές παράμετροι azure blob storage"
    },
    {
      "name": "$ACNCATEGORY",
      "type": "EditList",
      "caption": "Κατηγορίες λογαριασμών"
    }
  ]
}

JavaScript

Field	Description
`count`	Number of objects
`objects[].name`	Internal object name (used as the `OBJECT` parameter in other services)
`objects[].type`	Object type (e.g. `EditList`, `EditMaster`, etc.)
`objects[].caption`	Caption as shown in the UI

2. getObjectTables — Tables of an object

Returns the tables that make up a specific object. For example, the SALDOC object (Sales Documents) consists of the header (SALDOC → database table FINDOC), the item lines (MTRDOC), and others.

Parameters

Parameter	Description
`OBJECT`	The object name (e.g. `SALDOC`)

Request

{
  "service": "getObjectTables",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "OBJECT": "SALDOC"
}

{
  "service": "getObjectTables",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "OBJECT": "SALDOC"
}

JavaScript

Response

{
  "success": true,
  "count": 51,
  "tables": [
    {
      "name": "SALDOC",
      "dbname": "FINDOC",
      "caption": "Συναλλαγές (Πωλήσεων)",
      "filltype": "SQL"
    },
    {
      "name": "MTRDOC",
      "dbname": "MTRDOC",
      "caption": "Συναλλαγές υλικών",
      "filltype": "SQL"
    }
  ]
}

{
  "success": true,
  "count": 51,
  "tables": [
    {
      "name": "SALDOC",
      "dbname": "FINDOC",
      "caption": "Συναλλαγές (Πωλήσεων)",
      "filltype": "SQL"
    },
    {
      "name": "MTRDOC",
      "dbname": "MTRDOC",
      "caption": "Συναλλαγές υλικών",
      "filltype": "SQL"
    }
  ]
}

JavaScript

Field	Description
`tables[].name`	Logical table name within the object
`tables[].dbname`	Physical table name in the database
`tables[].caption`	Caption
`tables[].filltype`	Fill type (e.g. `SQL`)

name and dbname are not always identical. SALDOC, for instance, maps to the FINDOC database table.

3. getTableFields — Fields of a table

Returns the full list of fields of a table, along with their type, size, editor and display/editing attributes.

Parameters

Parameter	Description
`TABLE`	The table name (e.g. `MTRDOC`)

Request

{
  "service": "getTableFields",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "TABLE": "MTRDOC"
}

{
  "service": "getTableFields",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "TABLE": "MTRDOC"
}

JavaScript

Response

{
  "success": true,
  "count": 96,
  "fields": [
    {
      "name": "WHOUSE",
      "alias": "",
      "fullname": "MTRDOC.WHOUSE",
      "caption": "Α.Χ.",
      "size": "2",
      "type": "Smallint",
      "edittype": "Simple",
      "xtype": "s1intfield",
      "defaultvalue": "",
      "decimals": "",
      "editor": "WHOUSE",
      "readOnly": false,
      "visible": true,
      "required": false,
      "calculated": false
    },
    {
      "name": "BRANCHSEC",
      "alias": "",
      "fullname": "MTRDOC.BRANCHSEC",
      "caption": "Υποκ/μα 2",
      "size": "2",
      "type": "Smallint",
      "edittype": "Simple",
      "xtype": "s1intfield",
      "defaultvalue": "",
      "decimals": "",
      "editor": "BRANCH",
      "readOnly": false,
      "visible": true,
      "required": false,
      "calculated": false
    }
  ]
}

{
  "success": true,
  "count": 96,
  "fields": [
    {
      "name": "WHOUSE",
      "alias": "",
      "fullname": "MTRDOC.WHOUSE",
      "caption": "Α.Χ.",
      "size": "2",
      "type": "Smallint",
      "edittype": "Simple",
      "xtype": "s1intfield",
      "defaultvalue": "",
      "decimals": "",
      "editor": "WHOUSE",
      "readOnly": false,
      "visible": true,
      "required": false,
      "calculated": false
    },
    {
      "name": "BRANCHSEC",
      "alias": "",
      "fullname": "MTRDOC.BRANCHSEC",
      "caption": "Υποκ/μα 2",
      "size": "2",
      "type": "Smallint",
      "edittype": "Simple",
      "xtype": "s1intfield",
      "defaultvalue": "",
      "decimals": "",
      "editor": "BRANCH",
      "readOnly": false,
      "visible": true,
      "required": false,
      "calculated": false
    }
  ]
}

JavaScript

Field	Description
`name`	Field name
`fullname`	Fully qualified name, prefixed with the table (`TABLE.FIELD`)
`caption`	Caption in the UI
`size` / `type`	Size and data type (e.g. `Smallint`, `String`, `Float`)
`edittype` / `xtype`	Edit type and UI control type
`defaultvalue`	Default value
`decimals`	Decimal places (for numeric fields)
`editor`	The editor (lookup) linked to the field, e.g. `WHOUSE`, `BRANCH`
`readOnly` / `visible` / `required` / `calculated`	Field behaviour attributes

The editor field is especially useful: it tells you which reference table feeds the field, so you know which values are acceptable when calling setData.

4. getListGadgets — List of gadgets

Returns the list of gadgets (dashboard widgets) defined in the installation.

Request

{
  "service": "getListGadgets",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199"
}

{
  "service": "getListGadgets",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199"
}

JavaScript

Response

{
  "success": true,
  "rows": [
    {
      "CSTID": "380",
      "GUID": "soft1_grid0006",
      "TYPE": "1",
      "NAME": "Sales per group"
    },
    {
      "CSTID": "381",
      "GUID": "soft1_grid00061",
      "TYPE": "1",
      "NAME": "Sales per commercial category"
    }
  ]
}

{
  "success": true,
  "rows": [
    {
      "CSTID": "380",
      "GUID": "soft1_grid0006",
      "TYPE": "1",
      "NAME": "Sales per group"
    },
    {
      "CSTID": "381",
      "GUID": "soft1_grid00061",
      "TYPE": "1",
      "NAME": "Sales per commercial category"
    }
  ]
}

JavaScript

Field	Description
`CSTID`	Gadget identifier (used in `LoadGadget`)
`GUID`	Unique identifier
`TYPE`	Gadget type
`NAME`	Name

5. LoadGadget — Load a gadget definition

Returns the complete definition of a gadget: its configuration, column structure, axes and the SQL query that feeds it.

Parameters

Parameter	Description
`CSTID`	The gadget identifier from `getListGadgets`

Request

{
  "service": "LoadGadget",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "CSTID": "381"
}

{
  "service": "LoadGadget",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "CSTID": "381"
}

JavaScript

Response

{
  "success": true,
  "rows": {
    "name": "Sales per commercial category",
    "category": 1,
    "description": "Sales per commercial category",
    "config": {
      "type": "Dashboard.gadget.Grid",
      "title": "$0004:Sales per commercial category$",
      "height": 240
    },
    "data": {
      "structure": [
        {
          "name": "NAME",
          "type": "string",
          "caption": "$0005:Category$",
          "flex": 2
        },
        {
          "name": "VALUE",
          "type": "float",
          "caption": "$0006:Value$",
          "flex": 1
        }
      ],
      "axes": {
        "X": "NAME",
        "Y": "VALUE"
      },
      "sqlQuery": " SELECT G.NAME AS NAME, SUM($NVL(F.SALVAL,0)) AS VALUE FROM MTRL T, MTRCATEGORY G, MTRBALSHEET F WHERE T.COMPANY=:X.SYS.COMPANY AND T.SODTYPE in (51,52) AND T.COMPANY=G.COMPANY AND T.SODTYPE=G.SODTYPE AND T.MTRCATEGORY=G.MTRCATEGORY AND T.MTRL=F.MTRL AND F.FISCPRD=:X.SYS.FISCPRD GROUP BY G.NAME ORDER BY 2 DESC"
    }
  }
}

{
  "success": true,
  "rows": {
    "name": "Sales per commercial category",
    "category": 1,
    "description": "Sales per commercial category",
    "config": {
      "type": "Dashboard.gadget.Grid",
      "title": "$0004:Sales per commercial category$",
      "height": 240
    },
    "data": {
      "structure": [
        {
          "name": "NAME",
          "type": "string",
          "caption": "$0005:Category$",
          "flex": 2
        },
        {
          "name": "VALUE",
          "type": "float",
          "caption": "$0006:Value$",
          "flex": 1
        }
      ],
      "axes": {
        "X": "NAME",
        "Y": "VALUE"
      },
      "sqlQuery": " SELECT G.NAME AS NAME, SUM($NVL(F.SALVAL,0)) AS VALUE FROM MTRL T, MTRCATEGORY G, MTRBALSHEET F WHERE T.COMPANY=:X.SYS.COMPANY AND T.SODTYPE in (51,52) AND T.COMPANY=G.COMPANY AND T.SODTYPE=G.SODTYPE AND T.MTRCATEGORY=G.MTRCATEGORY AND T.MTRL=F.MTRL AND F.FISCPRD=:X.SYS.FISCPRD GROUP BY G.NAME ORDER BY 2 DESC"
    }
  }
}

JavaScript

Field	Description
`config.type`	Gadget type (e.g. `Dashboard.gadget.Grid`)
`config.title`	Title (with translation markers $id:text$ )
`data.structure`	The columns returned by the gadget
`data.axes`	Which columns map to the X and Y axes
`data.sqlQuery`	The SQL query. Note the system variables `:X.SYS.COMPANY` and `:X.SYS.FISCPRD` and the `$NVL` function

6. getAccessRights — User access rights on an object

Returns the access rights a specific user has on an object. Useful for checking, before a setData call, whether the logged-in user is allowed to create, update or delete records.

Parameters

Parameter	Description
`OBJECT`	The object name (e.g. `SALDOC`)
`USER`	The user ID

Request

{
  "service": "getAccessRights",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "OBJECT": "SALDOC",
  "USER": "262"
}

{
  "service": "getAccessRights",
  "clientID": "9J8pHqHKO...L5",
  "appId": "1199",
  "OBJECT": "SALDOC",
  "USER": "262"
}

JavaScript

Response

{
  "success": true,
  "browserOnly": false,
  "readOnly": false,
  "create": true,
  "remove": true,
  "update": true
}

{
  "success": true,
  "browserOnly": false,
  "readOnly": false,
  "create": true,
  "remove": true,
  "update": true
}

JavaScript

Field	Description
`browserOnly`	The user can only see the browser (list view), not the form
`readOnly`	Read-only access
`create`	Permission to create new records
`update`	Permission to modify records
`remove`	Permission to delete records

Summary

Service	Parameters	Returns
`getObjects`	—	All objects in the installation
`getObjectTables`	`OBJECT`	The tables of an object
`getTableFields`	`TABLE`	The fields of a table
`getListGadgets`	—	The list of gadgets
`LoadGadget`	`CSTID`	The full definition of a gadget
`getAccessRights`	`OBJECT`, `USER`	A user’s access rights on an object

Soft1 Web Services: Metadata Services

General

1. getObjects — List of objects

2. getObjectTables — Tables of an object

3. getTableFields — Fields of a table

4. getListGadgets — List of gadgets

5. LoadGadget — Load a gadget definition

6. getAccessRights — User access rights on an object

Summary

Leave a Reply Cancel reply

k.kourentzes.com