TRANSACTION – XML and JSON definitions for transaction processor – ubtransaction and ubtp

NAME

transaction – transaction processor records in XML and JSON format

DESCRIPTION

ubtransaction reads XML and JSON format records and processes them to do a range of updates and processes on the database.

ubtp processes a transaction enclosed in <transaction> tags. Transactions include sections to add records, delete records, update records, retrieve data, and execute commands.

The different commands are:

• ADD
• DATA
• DELETE
• DESCRIBE
• EXECUTE
• UPDATE
• TRANSACTION

ubtransaction is secure, requiring a valid session id before any functions can be executed.

For interactive sessions (the environment variable “REMOTE_USER” is set) this is provided by the SESSIONID cookie.

For C2C the session id is allocated after a successful login using OAuth2.0

Method 1. Local sessions will be processed if the environment variable “REMOTE_USER” is set. This is done automatically for web based access from ubprompt for data table updates etc.

Method 2. Remote sessions must include the element “password” (see below). If the user name password pair (from the Linux passwd database) do not match the transaction will not be processed. – Needs review

All transactions are logged in the system log and the details in matching log files.

If sendmail is running on the server, /usr/bin/ubtransaction.smrsh is linked to /etc/smrsh/ubtransaction allowing remote transactions to be delivered to ubtransaction@<server>. An entry is also put into /etc/aliases. To disable this feature, remove both the alias entry and the link in /etc/smrsh. For postfix, only the /etc/aliases entry is required. – Needs review. Replace with OAuth and API

ADD

Add records to a table. This can be specified in two ways: using the attribute element or using an element with the name of the attribute. NB The latter only works if there are no special characters in the attribute name (allowed by Unibase but not XML).

Add a record has several options. All options are optional.

• options <ubbatch options>
  • ubbatch command flags. Commonly used is -s to add new sequence numbers.
• array <format>
  • Output is enclosed in [ ]. Records are printed with format
• join <text>
  • Records are separated by given text
• head <format>
  • output format before any out from adding records
• body <format>
  • output format for each new record
• tail <format>
  • output format after adding all new records

array and join are normally used together. join is optional but useful to add separator such as a comma between records. The join text is not printed after the last record.

head, body, and tail are normally used together. Each is optional. head is printed before any records and is normally just text. body is a format used to echo record details as they are entered into the table. Typical use is to get a copy of a new sequence number. tail is a format printed after processing all records. It can be used to get total number of records processed or other totals.

A format is a Unibase record format including all Unibase format components such as attributes (from current table and other tables), text, and commands.

XML definition

<add table="..." options="..." head="..." body="..." tail="..." array="..." join="...">
  <records>
    <record>
      <attribute name="...">attribute value</attribute>|
      <attribute name>value</attribute name>
      ...
      </record>
    ...
    </records>
  </add>

JSON definition

{"add":
  { "table": "<table name>",
    "options": "<ubbatch options>",
    "head": "<format>",
    "body": "<format>",
    "tail": "<format>",
    "array": "<format>",
    "join": "<text">",
    "records":
      [
        { "<attribute>": "<value>",
          ...
          },
        ...
        ]
    }
  }

Example

{"add":
  { "table": "customer",
    "sequence": true,
    "array": "[customerId]",
    "join": ","
    "records":
      [ { "name": "Zenucom",
          "street": "123 Alpha St",
          "suburb": "Gotham City"
          }
        ]
    }
  }

DATA

Return records from the database using a specified format.

XML definition

<data table="..." key="..." match="...">
  <format>layout format</format>
  </data>

JSON definition

{"data": {
  "table": "table name",
  "key": "key name",
  "match": "match value",
  "format": "format text"
  }

DELETE

Delete records from a table.

NOTE: The matching index value is optional and if omitted, the entire table contents will be deleted.

XML definition

<delete table="..." key="..." match="..." />

JSON definition

{"delete":
  { "table": "table name",
    "key": "key name",
    "match": "match value"
    }
  }

DESCRIBE

Returns table definition. This is the dictionary text unless one of the options is requested.

XML definition

<describe table="..." options="attributes|keys|associations|restrictions|calculations|stored"/>

JSON definition

{ "describe":
  { "table": "...",
    "options": ["attributes"|"keys"|"associations"|"restrictions"|"calculations"|"stored"]
    }
  }

In the XML case options is a comma separated list chosen from values listed.

In the JSON case options is an array of one or values chosen from the list.

options is optional.

EXECUTE

Execute a system command.

NOTE: ubreport is a command interpreter, as are many other UNIBASE commands. However only ubreport in non-interactive mode is sensible (needs review). Other interpreters such as perl, tcl, python, etc are also suitable. The default is sh (bash).

XML definition

<execute>
  <command interpreter="...">
    command text
    </command>
  {<argument>argument value</argument>}
  ...
  {<input>input stream</input>}
  </execute>

JSON definition

{"execute":
  { "command":
    { "interpreter": "interpreter name",
      "text": "command text",
      "arguments":
        [
          {"argument 1": "argument value 1"},
          ...
          ],
      "input": "input stream"
      }
    }
  }

TRANSACTION

Wrapper for a transaction set.

The APPLICATION, DIRECTORY, and USER are determined by the SESSIONID.

XML definition

<transaction
  sessionid="..."
  sequence="system allocated sequence number"
  >
  ...transactions...
  </transaction>

Note: sequence is not yet implemented.

JSON definition

{"transaction":
  { "sessionid": "...",
    "sequence": "system allocated sequence number",
    "transactions": [
      ...
      ]
    }
  }

Details of the application, working directory, etc are determined by the session id used to transmit the transaction request.

UPDATE

Update attribute values in a record.

The key and match value for the record to be updated can be specified as attributes of the update element or as separate elements within the update.

Updates can be generic – value; or domain specific – date, number, text.

XML definition

<update table="..." key="..." options="..." head="..." body="..." tail="..." array="..." join="...">
  <record match="...">
    <updates>
      {<text attr="...">value</text>}
      ...
      {<number attr="...">value</number>}
      ...
      {<date attr="...">value</date>}
      ...
      </updates>
    </record>
    ...
  </update>

JSON definition

{"update":
  { "table": "table name",
    "key": "key name",
    "match": "match value",
    "options": "<ubdump options>",
    "head": "<format>",
    "body": "<format>",
    "tail": "<format>",
    "array": "<format>",
    "join": "<text>",
    "records": [
      { "match": "match value",
        "updates":
        [ {"text": {"attribute": "value", ...}}
          {"number": {"attribute": "value", ...}}
          {"date": {"attribute": "value"} ...},
          ...
          ]
        },
      ...
      ]
    }
  }

EXAMPLES

SEE ALSO