Skip to content

Introduction

"Hello World" Example

XML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<srs label="Basic">
  <description><![CDATA[
   This is a simple SRS example that returns three datasets: `Hello`, `World` and `Hello World`
  ]]></description>
  <def>
    <itm model="param" name="param1">Hello</itm>
    <itm>select 'Hello' msg</itm>
    <itm name="data">select 'World' as msg</itm>
    <itm link="self">select @param1 || ' ' || msg as newtext from data</itm>
  </def>
</srs>

File location

  • SRS files are stored in the application srs/ folder, in any subfolder.
  • The file name starts with the SRS id, for example 100-warehouse-stock.xml. The id must have at least 3 digits.
  • srs/global.xml holds shared column and option definitions. They are added to every SRS that does not define an item with the same name and model. param and command items are not allowed in global.xml.
  • srs/!tenant/{tenant}/ holds tenant-specific versions. When the request tenant matches, a file in this folder replaces the default file with the same id.

Overview of the XML structure

This is a list of all the elements that can be used in the XML structure of an SRS file.

srs node attributes

  • label - display name; also used as the root element of the XML export
  • cache - cache duration in minutes; only GET requests are served from the cache, a POST executes the SRS again and refreshes the cache
  • acl - access control list; default when empty: app_[app_name]
  • opts - options
    • jq-SkipOptimization - commands are run one by one in the order of appearance; by default, when an SRS has more than one SQL Server command, the commands run in parallel
  • description child element - free text shown in the UI; server-side variables are available

Read-only srs node attributes (not settable via XML):

  • name - file name, for example 100-warehouse-stock
  • id - ID, for example 100; at least 3 digits
  • success - true or false
  • message - empty if successful
  • apipath
  • apimethod - GET or POST
  • basepath
  • filepath
  • executed_at
  • tables
  • def
  • data
  • debugger

itm node attributes

Only the attributes listed below are allowed. An unknown attribute stops the SRS with an err/attribute error.

  • model - default is command; other options: column, param, target, option, dsn, nav, var
  • name - default is d + position, for example d1, d2
  • label - default is the name
  • title - default is the first non-empty label or name
  • opts - options specific to the model, for example for a command: uiclipboard, uiheader, uifooter, uimenu
  • css - CSS class, for example xd-red, xd-blue, xd-green, xd-orange, xd-orange0 to xd-orange10
  • acl - permission required for a command or column
    • default ACL schema if empty: app_[app_name]
    • <itm acl="admin" ...> requires the admin role
    • <itm acl="@manager" ...> requires access to the manager team
    • <itm acl="user@user.pl" ...> requires a specific username
    • <itm acl="public" ...> allows public access
    • authenticated users have the default permissions public, authenticated, username, roles and @team_short
    • non-authenticated users have the default permission public
  • type
    • when model="command": v_srs_table, v_srs_map, v_srs_tiles
    • when model="column": tguid, tdate, tbool, tinteger, tdecimal, tstring
    • when model="column": UI extended types, see Column type
    • when model="dsn": mssql (default), MsExcel
    • when model="option": pa_post, pa_download, pa_post_single
  • scope - limit the scope to a name, for example for the param and option models; comma-separated values are allowed, for example name1,name2
  • cache
  • width
  • link - connection name for a command; empty uses the first connection, self queries other command results, srs lists SRS files; see DSN
  • lg - show on large screens; default is true
  • sm - show on small screens; default is lg
  • ex - show on export; default is lg; applies to .html, .xlsx, .md, .txt, .xml and --aioptimized JSON
  • active - default is true
  • element value (text or CDATA)
    • when model="command": SQL text or stored procedure name
    • when model="column", param or option: supports server-side variables, for example [[app_name]], [[kv.v.user.username]]; see server-side variables

A required parameter is set with opts="req", not with an attribute.

Read-only itm attributes (not settable via XML):

  • ix - item index, column ordinal
  • ec - estimated characters
  • aclv - ACL validation result, true or false