API actions (integration tables)
Action | Description |
|---|---|
alters table settings that are safe to modify, such as adding new fields | |
creates an integration table | |
deletes an integration table as long as there are no dependencies on it | |
returns all available information about each specified integration table | |
lists only the integration tables in a given database |
The "testIntegrationTableTransformSteps" action causes the server to test new transform steps against an integration table to verify they behave as expected.
It runs the transform steps you include in this action against the structure and records in the specified integration table. It does not run the transform steps assigned to the integration table. Thus, it is safe to use this action on a table actively collecting data because it will not affect the table's transform steps and data.
You can verify the transform steps work on the first record, last record, or on one or more records with the specified IDs. This action returns the before and after values in the response so you can compare them and verify the transform steps work as expected.
You can also verify the transform steps work on all records of an integration table by causing this action to create a test table, copy all records to it, and run the transform steps on all records in the test table. Afterwards, you can use SQL or JSON DB queries on the test table to find problematic records.
Use the "testTransformScope" property (required) to define the scope of this action:
"allRecords"returns immediately after starting a background thread that creates a test table, copies all records to it, and runs the transform steps on all records in that table."stop"immediately stops the background thread assigned to the test table. If there is no background thread, the action does nothing and returns an error."firstRecord"returns the first record's fields before and after being modified by the transform steps. It runs synchronously and does not persist any changes."lastRecord"returns the last record's fields before and after being modified by the transform steps. It runs synchronously and does not persist any changes."specificRecords"returns the specified record's fields before and after being modified by the transform steps. It runs synchronously and does not persist any changes.
The "allRecords" scope has the following limitations:
The server runs one
"allRecords"scope at a time. This applies to both the"rerunIntegrationTableTransformSteps"and"testIntegrationTableTransformSteps"actions.While running transform steps on all records in an integration table, you cannot alter the structure of the table.
Request examples
Minimal example stops testing transform steps on all records
The following example stops a background thread that copies records to the myTable2 table and transforms them. It uses the database and owner specified in the current JSON action session (see "createSession" and "alterSession"). It returns an error if the background thread is not currently running on myTable2.
{
"api": "hub",
"action": "testIntegrationTableTransformSteps",
"params": {
"testTableName": "myTable2",
"testTransformScope": "stop"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}The following example tests new transform steps on records 1 and 6 in myTable1. It returns the before and after image of each record without persisting any changes.
{
"api": "hub",
"action": "testIntegrationTableTransformSteps",
"params": {
"tableName": "myTable1",
"testTransformScope": "specificRecords",
"ids": [
1,
3
],
"transformSteps": [
{
"transformStepMethod": "javascript",
"codeName": "convertFahrenheitToCelsius"
}
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}The following example tests new transform steps on the most recently inserted record in myTable1. It returns the before and after image of the record without persisting the changes.
{
"api": "hub",
"action": "testIntegrationTableTransformSteps",
"params": {
"tableName": "myTable1",
"testTransformScope": "lastRecord",
"transformSteps": [
{
"transformStepMethod": "javascript",
"codeName": "convertFahrenheitToCelsius"
}
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
The following example tests new transformation steps on the earliest inserted record in myTable1 that has not been purged by the retention policy. It returns the before and after image of the record without persisting the changes.
{
"api": "hub",
"action": "testIntegrationTableTransformSteps",
"params": {
"tableName": "myTable1",
"testTransformScope": "firstRecord",
"transformSteps": [
{
"transformStepMethod": "javascript",
"codeName": "convertFahrenheitToCelsius"
}
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
The following example copies the records of myTable1 to myTable2 and runs the transform steps on all the records in myTable2. It uses fully qualified table names that specify the database and owner of each table.
{
"api": "hub",
"action": "testIntegrationTableTransformSteps",
"params": {
"databaseName": "myDb1",
"ownerName": "myOwner1",
"tableName": "myTable1",
"testDatabaseName": "myDb1",
"testOwnerName": "myOwner1",
"testTableName": "myTable2",
"testTransformScope": "allRecords",
"transformSteps": [
{
"transformStepMethod": "javascript",
"codeName": "convertFahrenheitToCelsius"
}
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
To see the results of the action, you must query the test table created by this action.
{
"result": {
"testTransformScope": "allRecords",
"databaseName": "myDb1",
"ownerName": "myOwner1",
"tableName": "myTable1",
"testDatabaseName": "myDb1",
"testOwnerName": "myOwner1",
"testTableName": "myTable2"
},
"errorCode": 0,
"errorMessage": "",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
{
"result": {
"testTransformScope": "firstRecord",
"databaseName": "myDb1",
"ownerName": "myOwner1",
"tableName": "myTable1",
"data":
[
{
"recordBeforeBeingTransformed":
{
"id": "1",
"changeId": "1291366",
"create_ts": "2025-06-24T17:39:03.412",
"source_payload": {
"t1": 21,
"t2": 54
},
"temperature": null
},
"recordAfterBeingTransformed":
{
"id": "1",
"changeId": "1291366",
"create_ts": "2025-06-24T17:39:03.412",
"source_payload": {
"t1": 21,
"t2": 54
},
"temperature": 21.54
}
}
]
},
"errorCode": 0,
"errorMessage": "",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
{
"result": {
"testTransformScope": "lastRecord",
"databaseName": "myDb1",
"ownerName": "myOwner1",
"tableName": "myTable1",
"data":
[
{
"recordBeforeBeingTransformed":
{
"id": "948",
"changeId": "1291366",
"create_ts": "2025-06-24T17:39:03.412",
"source_payload": {
"t1": 23,
"t2": 7
},
"temperature": null
},
"recordAfterBeingTransformed":
{
"id": "948",
"changeId": "1291366",
"create_ts": "2025-06-24T17:39:03.412",
"source_payload": {
"t1": 23,
"t2": 7
},
"temperature": 23.7
}
}
]
},
"errorCode": 0,
"errorMessage": "",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
{
"result": {
"testTransformScope": "specifiedRecords",
"databaseName": "myDb1",
"ownerName": "myOwner1",
"tableName": "myTable1",
"data":
[
{
"recordBeforeBeingTransformed":
{
"id": "1",
"changeId": "1291366",
"create_ts": "2025-06-24T17:39:03.412",
"source_payload": {
"t1": 21,
"t2": 54
},
"temperature": null
},
"recordAfterBeingTransformed":
{
"id": "1",
"changeId": "1291366",
"create_ts": "2025-06-24T17:39:03.412",
"source_payload": {
"t1": 21,
"t2": 54
},
"temperature": 21.54
}
},
{
"recordBeforeBeingTransformed":
{
"id": "3",
"changeId": "1291547",
"create_ts": "2025-06-24T17:40:41.002",
"source_payload": {
"t1": 21,
"t2": 61
},
"temperature": null
},
"recordAfterBeingTransformed":
{
"id": "3",
"changeId": "1291547",
"create_ts": "2025-06-24T17:40:41.002",
"source_payload": {
"t1": 21,
"t2": 61
},
"temperature": 21.61
}
}
]
},
"errorCode": 0,
"errorMessage": "",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
"params" property summariesProperty | Description | Default | Type | Limits (inclusive) | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
(optional) specifies the database of the source table that this action uses to create and populate the test table with records. | Defaults to the | string | 1 to 64 bytes | |||||||
(conditional) lists identifiers that specify a table row, indicating which records the action affects. | Required when the | array | 0 or more identifiers | |||||||
(optional) specifies the owner account of the source table that this action uses to create and populate the test table with records. | Defaults to the | string | 1 to 64 bytes | |||||||
(optional) specifies the name of the source table that this action uses to create and populate the test table with records. | Required - No default value | string | 1 to 64 bytes | |||||||
(optional) specifies the database of the test table where this action tests the transform steps. | Defaults to the | string | 1 to 64 bytes | |||||||
(optional) specifies the owner account of the test table where this action tests the transform steps. | Defaults to the | string | 1 to 64 bytes | |||||||
specifies the name of the test table where this action tests the transform steps. | Required - No default value | string | 1 to 64 bytes | |||||||
defines the scope of the test action. | Required - No default value | string enum |
| |||||||
specifies an array of transform objects. | Required - No default value | array of objects | 0 or more objects | |||||||
| specifies the name of a code package that runs when a record is inserted into an integration table. | Required - No default value | string | 1 to 64 bytes | ||||||
| specifies the transform method the step will use. | Required - No default value | string enum |
|
The optional "databaseName" property specifies the database of the source table that this action uses to create and populate the test table with records.
When set to null or omitted, the server uses the default "databaseName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultDatabaseName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The "ids" property is an array. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. It is required when the "testTransformScope" property is set to "specificRecords".
An integration table's id field contains the unique identifier of each record.
The optional "ownerName" property specifies the owner account of the source table that this action uses to create and populate the test table with records.
When set to null or omitted, the server uses the default "ownerName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultOwnerName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The required "tableName" property specifies the name of the source table that this action uses to create and populate the test table with records.
Note
The fully qualified name of a table includes the database, owner, and table names.
The optional "testDatabaseName" property specifies the database of the test table where this action tests the transform steps.
When set to null or omitted, the server uses the default "databaseName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultDatabaseName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The optional "testOwnerName" property specifies the owner account of the test table where this action tests the transform steps.
When set to null or omitted, the server uses the default "ownerName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultOwnerName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The required "testTableName" property specifies the name of the test table where this action tests the transform steps.
Note
The fully qualified name of a table includes the database, owner, and table names.
"testTransformScope"
The required "testTransformScope" property defines the behavior of this action. It is a string enum with one of the following values:
"allRecords"returns immediately and creates a background thread that asynchronously creates a test table, copies all records to it, and runs the transform steps on all records in that table.This option applies only to the
"testIntegrationTableTransformSteps"action.Once records are copied to the test table, it applies the transform steps.
You can stop this action by calling this action with
"testTransformScope": "stop".It regularly updates the
"transformStatus"and the"transformPercentComplete"properties, which are returned by the"describeIntegrationTables"action.If the test table's background thread is already running, the action returns an error indicating the
"testIntegrationTableTransformSteps"action is already running on the integration table. The user can decide if he wants to wait or stop the action.
"stop"immediately stops the background thread assigned to the test table.If no background thread is running, the action does nothing and returns an error.
The action may be stopped while it is creating the test table, copying records to the test table, or running transform steps on the test table's records.
It always deletes the test table because the action is incomplete. Otherwise, the action could leave the test table in an unexpected state, such as not being created, incompletely copying records, or incompletely transforming records.
"firstRecord"returns the first record's fields before and after being modified by the transform steps.It returns two properties:
"recordBeforeBeingTransformed"and"recordAferBeingTransformed".It runs synchronously and does not change the record in the database.
You can repeatedly run this scope because it will not affect your data, does not interfere with the
"rerunIntegrationTableTransformSteps"action, and does not interfere with the test table's background thread.
"lastRecord"returns the last record's fields before and after being modified by the transform steps.It returns two properties:
"recordBeforeBeingTransformed"and"recordAferBeingTransformed".It runs synchronously and does not change the record in the database.
You can repeatedly run this scope because it will not affect your data, does not interfere with the
"rerunIntegrationTableTransformSteps"action, and does not interfere with the test table's background thread.
"specificRecords"returns the specified record's fields before and after being modified by the transform steps.Each record has an
"id"field containing an integer number that uniquely identifies it. The action uses the"id"property to specify the ID number of the record.It returns two properties for each record listed in the
"ids"property:"recordBeforeBeingTransformed"and"recordAferBeingTransformed".It runs synchronously and does not change the record in the database.
You can repeatedly run this scope because it will not affect your data, does not interfere with the
"rerunIntegrationTableTransformSteps"action, and does not interfere with the test table's background thread.
The "logTransformOverwrites" property, when true, causes the action to log attempts by JavaScript to overwrite a field value.
The "transformSteps" property is an array of transform step objects.
Different actions interpret "transformSteps": [] differently.
In the
"alterIntegrationTable"action,"transformSteps"is optional. Setting it to[]removes transform steps from the integration table.In the
"createIntegrationTable"action,"transformSteps"is optional. Setting it to[]is the same as setting it tonullor omitting it.In the
"testIntegrationTableTransformSteps"actions,"transformSteps"is required; thus, omitting it or setting it to[]ornullis an error.
Each transform step object contains the required "transformStepMethod" property. It also supports the following optional properties:
"transformStepName""transformStepService"
Each transform step method also supports unique properties that are defined below.
"transformStepMethod": "javascript"
Required properties
"codeName"
Optional properties
"ownerName""databaseName"
"transformStepMethod": "tableFieldsToJson"
Required properties
"mapOfPropertiesToFields"
"transformStepMethod": "jsonToTableFields"
Required properties
"mapOfPropertiesToFields"
"transformStepMethod": "jsonToDifferentTableFields"
Required properties
"mapOfPropertiesToFields""targetTableName"
Optional properties
"targetOwnerName""targetDatabaseName"
The "codeName" property is a required string from 1 to 64 bytes. It is the name of a code package that runs when a record is inserted into an integration table. See "codeName" for more information.
It is an error to set "codeName" to the empty string "".
The "transformStepMethod" property is a required string that specifies the type of transform, such as the "javascript" transform method that runs JavaScript to change the table's data or the "jsonToTableFields" transform method that extracts values from properties in a JSON field and stores them in other fields.
Note
The "transformStepMethod" property replaces the deprecated "transformActionName" property.
The value of the "transformStepMethod" affects the value of the "transformService" property. The following table defines the possible values of the "transformService" property when combined with the "transformStepMethod". Notice that some transform step methods are built into the server and do not require you to specify the "transformService".
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
Note
If the "transformStepMethod" property is set to "javascript", the "transformService" property must be set to "v8TransformService".
"result" property summariesProperty | Description | Type | Contents | |||||
|---|---|---|---|---|---|---|---|---|
is an array of objects describing the record before and after being transformed. | array of objects | 0 or more objects | ||||||
| contains an object with one property for each field in the record after it was transformed. | object | 0 or more properties | |||||
| contains an object with one property for each field in the record before it was transformed. | object | 0 or more properties | |||||
specifies the database of the source table that this action uses to create and populate the test table with records. | string | 1 to 64 bytes | ||||||
specifies the owner account of the source table that this action uses to create and populate the test table with records. | string | 1 to 64 bytes | ||||||
specifies the name of the source table that this action uses to create and populate the test table with records. | string | 1 to 64 bytes | ||||||
specifies the database of the test table where this action tests the transform steps. | string | 1 to 64 bytes | ||||||
specifies the owner account of the test table where this action tests the transform steps. | string | 1 to 64 bytes | ||||||
specifies the name of the test table where this action tests the transform steps. | string | 1 to 64 bytes | ||||||
is the same value specified in the call to the | string enum |
|
The "data" property is an array of objects. Each object contains two properties: "recordBeforeBeingTransformed" and "recordAfterBeingTransformed".
The "recordAfterBeingTransformed" property contains an object with one property for each field in the record. Each property value is from the record after it was modified by the transform steps.
The "recordBeforeBeingTransformed" property contains an object with one property for each field in the record. Each property value is from the record before it was modified by the transform steps.
The optional "databaseName" property specifies the database of the source table that this action uses to create and populate the test table with records.
When set to null or omitted, the server uses the default "databaseName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultDatabaseName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The optional "ownerName" property specifies the owner account of the source table that this action uses to create and populate the test table with records.
When set to null or omitted, the server uses the default "ownerName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultOwnerName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The required "tableName" property specifies the name of the source table that this action uses to create and populate the test table with records.
Note
The fully qualified name of a table includes the database, owner, and table names.
The optional "testDatabaseName" property specifies the database of the test table where this action tests the transform steps.
When set to null or omitted, the server uses the default "databaseName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultDatabaseName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The optional "testOwnerName" property specifies the owner account of the test table where this action tests the transform steps.
When set to null or omitted, the server uses the default "ownerName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultOwnerName" property.
Note
The fully qualified name of a table includes the database, owner, and table names.
The required "testTableName" property specifies the name of the test table where this action tests the transform steps.
Note
The fully qualified name of a table includes the database, owner, and table names.
The "testTransformScope" property is the same value specified in the call to the "testIntegrationTableTransformSteps" to the action.