Carte APIs Transformations

Provides web services to create, update, and delete transformations. Calls for getting images, statuses and starting, pausing, preparing, and stopping transformations are also included.

Deprecated

Upload and execute transformation

post

DEPRECATED: This endpoint is deprecated and may be removed in future versions.

Uploads and executes transformation configuration XML file. Uploads xml file containing transformation and transformation_execution_configuration (wrapped in transformation_configuration tag) to be executed and executes it. Method relies on the input parameter to determine if xml or html reply should be produced. The transformation_configuration xml is transferred within request body.

Example Request:

POST /kettle/addTrans/?xml=Y

Request body should contain xml containing transformation_configuration (transformation and transformation_execution_configuration wrapped in transformation_configuration tag).

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

xmlstring · enumOptional

Boolean flag set to either Y or N describing if xml or html reply should be produced.

Default: NPossible values:

Body

application/xml

stringOptional

Transformation configuration XML

Responses

200

Request was processed and XML response is returned

text/xml

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

post

/kettle/addTrans

HTTPcURLJavaScriptPython

POST /kettle/addTrans HTTP/1.1
Authorization: Basic username:password
Content-Type: application/xml
Accept: */*
Content-Length: 6

"text"

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message>Transformation 'dummy-trans' was added to Carte with id eb4a92ff-6852-4307-9f74-3c74bd61f829</message>
  <id>eb4a92ff-6852-4307-9f74-3c74bd61f829</id>
</webresult>

Generate transformation image

get

Generates PNG image of the specified transformation currently present on Carte server. Transformation name and Carte transformation ID (optional) are used for specifying which transformation to get information for. Response is a binary of the PNG image.

Example Request:

GET /kettle/transImage?name=dummy-trans

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be used for image generation.

idstringOptional

Carte id of the transformation to be used for image generation.

Responses

200

Request was processed

image/png

string · binaryOptional

Binary PNG image

500

Internal server error occurs during request processing

text/xml

get

/kettle/transImage

HTTPcURLJavaScriptPython

GET /kettle/transImage?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

binary

Get transformation status

get

Retrieves status of the specified transformation. Status is returned as HTML or XML output depending on the input parameters. Status contains information about last execution of the transformation.

Example Request:

GET /kettle/transStatus/?name=dummy-trans&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be used for status generation.

xmlstring · enumOptional

Boolean flag which defines output format Y forces XML output to be generated. HTML is returned otherwise.

Default: NPossible values:

idstringOptional

Carte id of the transformation to be used for status generation.

fromintegerOptional

Start line number of the execution log to be included into response.

Responses

200

Request was processed

text/xmltext/html

stringOptional

XML response containing transformation status details

500

Internal server error occurs during request processing

text/xml

get

/kettle/transStatus

HTTPcURLJavaScriptPython

GET /kettle/transStatus?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<transstatus>
  <transname>dummy-trans</transname>
  <id>c56961b2-c848-49b8-abde-76c8015e29b0</id>
  <status_desc>Stopped</status_desc>
  <error_desc/>
  <paused>N</paused>
  <stepstatuslist>
    <stepstatus>
      <stepname>Dummy (do nothing)</stepname>
      <copy>0</copy>
      <linesRead>0</linesRead>
      <linesWritten>0</linesWritten>
      <linesInput>0</linesInput>
      <linesOutput>0</linesOutput>
      <linesUpdated>0</linesUpdated>
      <linesRejected>0</linesRejected>
      <errors>0</errors>
      <statusDescription>Stopped</statusDescription>
      <seconds>0.0</seconds>
      <speed>-</speed>
      <priority>-</priority>
      <stopped>Y</stopped>
      <paused>N</paused>
    </stepstatus>
  </stepstatuslist>
  <first_log_line_nr>0</first_log_line_nr>
  <last_log_line_nr>37</last_log_line_nr>
  <result>
    <lines_input>0</lines_input>
    <lines_output>0</lines_output>
    <lines_read>0</lines_read>
    <lines_written>0</lines_written>
    <lines_updated>0</lines_updated>
    <lines_rejected>0</lines_rejected>
    <lines_deleted>0</lines_deleted>
    <nr_errors>0</nr_errors>
    <nr_files_retrieved>0</nr_files_retrieved>
    <entry_nr>0</entry_nr>
    <result>Y</result>
    <exit_status>0</exit_status>
    <is_stopped>Y</is_stopped>
    <log_channel_id>10e2c832-07da-409a-a5ba-4b90a234e957</log_channel_id>
    <log_text/>
    <result-file></result-file>
    <result-rows></result-rows>
  </result>
  <logging_string>&#x3c;&#x21;&#x5b;CDATA&#x5b;H4sIAAAAAAAAADMyMDTRNzTUNzJRMDSyMrC0MjFV0FVIKc3NrdQtKUrMKwbyXDKLCxJLkjMy89IViksSi0pSUxTS8osUwPJARm5iSWZ&#x2b;nkI0kq5YXi4AQVH5bFoAAAA&#x3d;&#x5d;&#x5d;&#x3e;</logging_string>
</transstatus>

Prepare transformation for execution

get

Prepares previously loaded transformation for execution. Method is used for preparing previously uploaded transformation for execution by its name.

Example Request:

GET /kettle/prepareExec/?name=dummy-trans2&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be prepared for execution.

xmlstring · enumRequired

Boolean flag which sets the output format required. Use Y to receive XML response.

Possible values:

idstringOptional

Carte transformation ID of the transformation to be prepared for execution.

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/prepareExec

HTTPcURLJavaScriptPython

GET /kettle/prepareExec?name=text&xml=Y HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message/>
  <id/>
</webresult>

Start transformation execution

get

Starts transformation. If the transformation is not ready, an error is returned.

Example Request:

GET /kettle/startExec/?name=dummy-trans&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be executed.

xmlstring · enumOptional

Boolean flag which sets the output format required. Use Y to receive XML response.

Default: NPossible values:

idstringOptional

Carte transformation ID of the transformation to be executed. This parameter is optional when xml=Y is used.

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/startExec

HTTPcURLJavaScriptPython

GET /kettle/startExec?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message/>
  <id/>
</webresult>

Execute transformation

get

Executes transformation previously uploaded to Carte server.

Example Request:

GET /kettle/startTrans/?name=dummy-trans&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be executed.

xmlstring · enumOptional

Boolean flag which sets the output format required. Use Y to receive XML response.

Default: NPossible values:

idstringOptional

Carte transformation ID of the transformation to be executed. This parameter is optional when xml=Y is used.

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/startTrans

HTTPcURLJavaScriptPython

GET /kettle/startTrans?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message>Transformation [dummy-trans] was started.</message>
  <id/>
</webresult>

Execute transformation from repository

get

Execute transformation from enterprise repository. Repository should be configured in Carte xml file. Response contains ERROR result if error happened during transformation execution.

Example Request:

GET /kettle/runTrans?trans=home%2Fadmin%2Fdummy-trans&level=Debug

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

transstringRequired

Full path to the transformation in repository.

levelstringRequired

Logging level to be used for transformation execution (i.e. Debug).

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/runTrans

HTTPcURLJavaScriptPython

GET /kettle/runTrans?trans=text&level=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<webresult>
  <result>OK</result>
  <message>Transformation started</message>
  <id>7c082e8f-b4fe-40bc-b424-e0f881a61874</id>
</webresult>

Execute transformation from repository

get

Executes transformation from the specified repository. Connects to the repository provided as a parameter, loads the transformation from it and executes it. Empty response is returned or response contains output of an error happened during the transformation execution. Response contains ERROR result if error happened during transformation execution.

Example Request:

GET /kettle/executeTrans/?rep=my_repository&user=my_user&pass=my_password&trans=my_trans&level=INFO

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

repstringRequired

Repository id to connect to.

userstringRequired

User name to be used to connect to repository.

passstringRequired

User password to be used to connect to repository.

transstringRequired

Transformation name to be loaded and executed.

levelstringRequired

Logging level to be used for transformation execution.

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/executeTrans

HTTPcURLJavaScriptPython

GET /kettle/executeTrans?rep=text&user=text&pass=text&trans=text&level=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<webresult>
  <result>OK</result>
  <message>Transformation started</message>
  <id>7c082e8f-b4fe-40bc-b424-e0f881a61874</id>
</webresult>

Pause transformation

get

Pauses transformation to be executed. Method is used for pausing running transformation by its name.

Example Request:

GET /kettle/pauseTrans/?name=dummy-trans&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be paused.

xmlstring · enumOptional

Boolean flag which sets the output format required. Use Y to receive XML response.

Default: NPossible values:

idstringOptional

Carte transformation ID of the transformation to be paused. This parameter is optional when xml=Y is used.

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/pauseTrans

HTTPcURLJavaScriptPython

GET /kettle/pauseTrans?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message>Transformation [dummy-trans (master)] : pause requested.</message>
  <id/>
</webresult>

Stop transformation

get

Stops transformation execution on Carte server.

Example Request:

GET /kettle/stopTrans/?name=dummy-trans&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be stopped.

xmlstring · enumOptional

Boolean flag which sets the output format required. Use Y to receive XML response.

Default: NPossible values:

idstringOptional

Carte transformation ID of the transformation to be stopped. This parameter is optional when xml=Y is used.

inputOnlystring · enumOptional

Boolean flag indicates which steps to stop. Use Y to Stop input processing

Possible values:

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/stopTrans

HTTPcURLJavaScriptPython

GET /kettle/stopTrans?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message>Transformation [dummy-trans] stop requested.</message>
  <id>c56961b2-c848-49b8-abde-76c8015e29b0</id>
</webresult>

Remove transformation

get

Removes specified transformation from Carte server.

Example Request:

GET /kettle/removeTrans/?name=dummy-trans&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be removed.

xmlstring · enumOptional

Boolean flag which sets the output format required. Use Y to receive XML response.

Default: NPossible values:

idstringOptional

Carte transformation ID of the transformation to be removed. This parameter is optional when xml=Y is used.

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/removeTrans

HTTPcURLJavaScriptPython

GET /kettle/removeTrans?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message/>
  <id/>
</webresult>

Clean up transformation

get

Cleans up transformation on Carte server. Method is used for cleaning previously uploaded transformation by its name on Carte server. There are two modes for this method: 1) Clean the server sockets only or 2) Clean everything, including the transformation.

Example Request:

GET /kettle/cleanupTrans/?name=dummy-trans2&xml=Y

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the transformation to be cleaned.

xmlstring · enumOptional

Boolean flag which sets the output format required. Use Y to receive XML response.

Default: NPossible values:

idstringOptional

Carte transformation ID of the transformation to be cleaned.

socketsstring · enumOptional

Boolean flag which indicates if full clean up or sockets only is required. Use Y to clean just sockets.

Possible values:

Responses

200

Request was processed

text/xmltext/html

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

get

/kettle/cleanupTrans

HTTPcURLJavaScriptPython

GET /kettle/cleanupTrans?name=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message>All server sockets ports for transformation [dummy-trans2] were deallocated. 
Transformation [dummy-trans2] was cleaned up.</message>
  <id/>
</webresult>

Sniff step metadata and data

get

Sniff metadata and data from the specified step of the specified transformation.

Example Request:

GET /kettle/sniffStep?trans=dummy-trans&step=tf&xml=Y&lines=10

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

transstringRequired

Name of the transformation containing required step.

stepNamestringRequired

Name of the transformation step to collect data for.

copynrintegerOptional

Copy number of the step to be used for collecting data. If not provided 0 is used.

Default: 0

typestring · enumOptional

Type of the data to be collected (input or output).

Possible values:

xmlstring · enumOptional

Boolean flag which sets the output format required. Use Y to receive XML response.

Default: NPossible values:

idstringOptional

Carte id of the transformation to be used for step lookup.

linesintegerOptional

Number of lines to collect. If not provided 0 is used.

Default: 0

Responses

200

Request was processed

text/xmltext/html

stringOptional

XML response containing step metadata and data

500

Internal server error occurs during request processing

text/xml

get

/kettle/sniffStep

HTTPcURLJavaScriptPython

GET /kettle/sniffStep?trans=text&stepName=text HTTP/1.1
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<step-sniff>
  <row-meta>
    <value-meta>
      <type>String</type>
      <storagetype>normal</storagetype>
      <name>Field1</name>
      <length>0</length>
      <precision>-1</precision>
      <origin>tf</origin>
      <comments/>
      <conversion_Mask/>
      <decimal_symbol>.</decimal_symbol>
      <grouping_symbol>,</grouping_symbol>
      <currency_symbol>$</currency_symbol>
      <trim_type>none</trim_type>
      <case_insensitive>N</case_insensitive>
      <sort_descending>N</sort_descending>
      <output_padding>N</output_padding>
      <date_format_lenient>Y</date_format_lenient>
      <date_format_locale>en_US</date_format_locale>
      <date_format_timezone>America/Bahia</date_format_timezone>
      <lenient_string_to_number>N</lenient_string_to_number>
    </value-meta>
  </row-meta>
  <nr_rows>10</nr_rows>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data </value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
  <row-data>
    <value-data>my-data</value-data>
  </row-data>
</step-sniff>

Deprecated

Uploads and executes transformation configuration XML file to the server.

post

Uploads xml file containing transformation and transformation_execution_configuration (wrapped in transformation_configuration tag) to be executed and executes it. Method relies on the input parameter to determine if xml or html reply should be produced. The transformation_configuration xml is transferred within request body. transformation name of the executed transformation will be returned in the Response object or message describing error occurred. To determine if the call successful or not you should rely on result parameter in response.

Example Request:

POST /kettle/registerTrans/?xml=Y

Request body should contain xml containing transformation_configuration (transformation and transformation_execution_configuration wrapped in transformation_configuration tag).

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

xmlstring · enumOptional

Boolean flag set to either Y or N describing if xml or html reply should be produced.

Default: NPossible values:

Body

application/xml

stringOptional

Transformation configuration XML

Responses

200

Request was processed and XML response is returned

text/xml

Standard response format for most Carte operations

resultstring · enumOptional

Result status of the operation

Possible values:

messagestringOptional

Human readable message describing the result

idstringOptional

Unique identifier for the created/modified resource

500

Internal server error occurs during request processing

text/xml

post

/kettle/registerTrans

HTTPcURLJavaScriptPython

POST /kettle/registerTrans HTTP/1.1
Authorization: Basic username:password
Content-Type: application/xml
Accept: */*
Content-Length: 6

"text"

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message>Transformation 'dummy-trans' was added to Carte with id eb4a92ff-6852-4307-9f74-3c74bd61f829</message>
  <id>eb4a92ff-6852-4307-9f74-3c74bd61f829</id>
</webresult>