General DB x-callback-url API

To extract rows from General DB or Private DB into another app, or to run SQL statements, use the x-callback-url interface.

For a great working example, see the When the General Calls workflow by David Edson.

All parameters described below should be URL-encoded according to rfc1738.

Request URL for SELECT Statements

Use the scheme generaldb for General DB, and the scheme privatedb for Private DB. For increased safety when executing SELECT statements, the database is opened in read-only mode.

generaldb://x-callback-url/execute-select-statement

Required Parameters

x-success is the URL that will be opened if the SELECT statement succeeded.

statement is the SELECT statement to execute.

Optional Parameters

x-error is the URL that will be opened if the SELECT statement failed.

x-source is the name of the source app.

database is the name of the database file to use. If not specified, then general.db will be used.

Response Parameters

rows contains the rows in one URL-encoded string if the SELECT statement succeeded. Each row is separated by a line feed character 0x0A, and each field by a tab character 0x09.

errorCode is the integer error code if the SELECT statement failed.

errorMessage is a string describing the error if the SELECT statement failed.

Example Request from the Workflow App

generaldb://x-callback-url/execute-select-statement?
statement=select%20*%20from%20MyTable&
x-cancel=workflow://x-callback-url/ic-cancel/D08EA2C0-348D-4699-9C12-4E1CE98CA52B&
x-error=workflow://x-callback-url/ic-error/D08EA2C0-348D-4699-9C12-4E1CE98CA52B&
x-source=Workflow&
x-success=workflow://x-callback-url/ic-success/D08EA2C0-348D-4699-9C12-4E1CE98CA52B

Example Response from the Workflow App

workflow://x-callback-url/ic-success/D08EA2C0-348D-4699-9C12-4E1CE98CA52B?
x-source=General%20DB&
rows=2016-07-03%20-0400%09Hello%0A2016-07-04%20-0400%09World

Request URL for Any Other SQL Statements

Use the scheme generaldb for General DB, and the scheme privatedb for Private DB. For increased safety when executing SQL statements, the option in the App Info must be enabled, and the user will be prompted to confirm that the statement should run.

generaldb://x-callback-url/execute-any-statement

Required Parameters

x-success is the URL that will be opened if the SQL statement succeeded.

statement is the SQL statement to execute.

Optional Parameters

x-error is the URL that will be opened if the SQL statement failed.

x-source is the name of the source app.

database is the name of the database file to use. If not specified, then general.db will be used.

Response Parameters

num_rows_affected contains the number of rows affected if the statement succeeded.

last_insert_rowid contains the ROWID of the last inserted row if available if the statement succeeded.

errorCode is the integer error code if the select statement failed.

errorMessage is a string describing the error if the select statement failed.

Example Request from the Workflow App

generaldb://x-callback-url/execute-any-statement?
statement=update%20MyTable%20set%20%22Field%201%22%20%3D%20%27Dog%27%20where%20ROWID%3D1&
x-cancel=workflow://x-callback-url/ic-cancel/D08EA2C0-348D-4699-9C12-4E1CE98CA52B&
x-error=workflow://x-callback-url/ic-error/D08EA2C0-348D-4699-9C12-4E1CE98CA52B&
x-source=Workflow&
x-success=workflow://x-callback-url/ic-success/D08EA2C0-348D-4699-9C12-4E1CE98CA52B

Example Response from the Workflow App

workflow://x-callback-url/ic-success/D08EA2C0-348D-4699-9C12-4E1CE98CA52B?
x-source=General%20DB&
num_rows_affected=1&last_insert_rowid=0