Components

Version:
2019.3
Last modified: October 10, 2019

REST API

Using Connect, you can create, populate, and delete staging tables via the REST API. Connect requires administrator permission for all web services.

Create and Populate Staging Table

/rest/1/dbstage/insert: Populate a new or existing staging table with data that follows defined JSON constraints.

Set these attributes:

  • connection: set to ignored.
  • table: set to the name of an existing table or a new table with the prefix EXT_.
  • cols: set to define the column names and data types, which should match the table structure.
  • rows: Set to the number of rows to be inserted into the table.
  • operation: set to create for new elements. Set to drop to delete elements. Operation can be set at the table or column level.
Existing Table Example

{ "connection": "ignored", "table": "DB_TABLES", "cols": { "load_code": "string", "catalog_name": "string", "catalog_environment": "string", "schema_name": "string", "create_time": "datetime", "table_name": "string" },

New Table Example

{ "connection": "ignored", "table": {"name":"EXT_DB_TABLES","operation":"create"}, "cols": { "load_code": {"type":"string","operation":"create"}, "catalog_name": {"type":"string","operation":"drop"}, "catalog_environment": "string", "schema_name": "string", "create_time": "datetime", "table_name": "string" } }

Table Population Example

[ { "connection":"ignored", "table":"FILES", "cols":{ "LOAD_CODE":"string", "SYSTEM_NAME":"string", "NAME":"string", "PATH":"string", "PATH_HASH":"string", "PARENT":"string", "PARENT_HASH":"string(255)", "TYPE":"string", "EXTENSION":"string", "SIZE":"ERROR:Int64", "CREATED":"datetime", "LAST_MODIFIED":"datetime", "ACCESS_TIME":"datetime", "HIDDEN":"ERROR:Int32", "READ_ONLY":"ERROR:Int32" }, "rows":[ { "LOAD_CODE":"31abffbc019f597dbc688dde6cfa077e", "SYSTEM_NAME":"ACME", "NAME":"AlteryxSampleData", "PATH":"\\\\ACME\\AlteryxSampleData\\", "PATH_HASH":"2ac01f9c26e55d33908bbd821dee5b7e", "TYPE":"D", "EXTENSION":"dir" }, { "LOAD_CODE":"31abffbc019f597dbc688dde6cfa077e", "SYSTEM_NAME":"ACME", "NAME":"AdArea polygons.yxdb", "PATH":"\\\\ACME\\AlteryxSampleData\\AdArea polygons.yxdb", "PATH_HASH":"52954616160973d7cd8e296e6c383547", "PARENT":"\\\\ACME\\AlteryxSampleData\\", "PARENT_HASH":"2ac01f9c26e55d33908bbd821dee5b7e", "TYPE":"F", "EXTENSION":"yxdb", "SIZE":17420, "CREATED":"2017-08-04 19:40:51 UTC", "LAST_MODIFIED":"2017-08-16 14:08:03 UTC", "ACCESS_TIME":"2017-08-04 19:40:51 UTC", "HIDDEN":0, "READ_ONLY":1 }, { "LOAD_CODE":"31abffbc019f597dbc688dde6cfa077e", "SYSTEM_NAME":"ACME", "NAME":"AddressData.yxdb", "PATH":"\\\\ACME\\AlteryxSampleData\\AddressData.yxdb", "PATH_HASH":"f47a071200f7fab53f0caf39ae5ba064", "PARENT":"\\\\ACME\\AlteryxSampleData\\", "PARENT_HASH":"2ac01f9c26e55d33908bbd821dee5b7e", "TYPE":"F", "EXTENSION":"yxdb", "SIZE":70294, "CREATED":"2017-08-04 19:40:51 UTC", "LAST_MODIFIED":"2017-08-16 14:08:03 UTC", "ACCESS_TIME":"2017-08-04 19:40:51 UTC", "HIDDEN":0, "READ_ONLY":1 } ] } ]

Successful upload returns the response:

Summary:

Wrote 88 rows to "FILES"

Delete Staging Table

/rest/1/dbstage/delete: Remove data from a staging table based on a load code.

loadCode=31abffbc019f597dbc688dde6cfa077e

Successful deletion returns the response:

{ "isError":false, "message":"Removed 88 rows from table FILES. \nRemoved 1 rows from table FILE_SYSTEMS. \n", "replacer0":{ "replaceType":"refreshTables", "refreshTables":[ "placeholder-stages" ] } }

Execute Job POST

/rest/1/jobs/execute: Execute the called loading job to Connect.

Parameters for the job execution:

  • type: Set to sync.
  • jobs: Set to the name of the job as defined in the configuration, completed with the suffix /_total.

Call Example

type=sync&jobs=load-alteryx-fs%2F_total

Successful execution returns the response:

{"isError":false,"message":"1 jobs have been executed"}

Upload Configuration Service Post

/rest/1/admin/upload: Upload configuration files and loading job configurations to Connect.

curl --data-binary "@configs.zip" -H "Content-Type: application/octet-stream" -H "X-File-Name:configs.zip" -H "xf3-login: admin" -H "xf3-password: Conn3ct!" -vvv -X POST https://connect.semanta.cloud/rest/1/admin/upload

See Data Upload Workflow.

Designer Connect Tools

Designer uses Connect tools to create valid JSON and push the formatted JSON to Connect.

Connect Json Builder

The Connect Json Builder tool creates formatted JSON.

  • Input: The name of the dataset containing metadata.
  • Input parameter: The table name of where the dataset is stored. Names and data types of the dataset must match those in the staging table.

Default staging tables

Connect comes with several standard staging tables: DB_SCHEMAS, DB_TABLES, and DB_COLUMNS. The user can write to these tables, but cannot change the tables.

Connect Output

The Connect Output tool sends metadata to the REST API to send the data to Connect, calling web services in a single tool.

  • Authenticate: Connection to the Connect instance.
  • Delete stage: Remove metadata pushed in the previous run.
  • Insert stage: Insert metadata into staging tables.
  • Execute: Call a job to create and index UI elements as they appear in Connect.
  • Input: Push formatted JSON from the Connect Json Builder tool.

See Data Upload Workflow.

Configuration Files

Configuration files declare the structure of your entries as they are displayed in Connect. To check the default configuration supplied with Connect, go to Administration > Export > Export Configuration Files.

Required Fields

  • xid: A unique identifier for the record.
  • entry-name: The name of the record.
  • icon: A visual representation of the entry.

See Configuration Files Creation Example.

Schema documents are available as .xsd files here.

Was This Helpful?

Need something else? Visit the Alteryx Community or contact support.