Transformations
Overview
Provides web services to create, update, and delete transformations. Calls for getting images, statuses and starting, pausing, preparing, and stopping transformations are also included.
Provides web service calls to create, update, and delete transformations. Calls for getting images, statuses and starting, pausing, preparing, and stopping transformations are also included.
You will need to modify the example URLs if you are working with the PDI server instead of a standalone Carte server.
These are the resources that are available:
- /kettle/addTrans (Deprecated)
- /kettle/transImage
- /kettle/transStatus
- /kettle/prepareExec
- /kettle/startExec
- /kettle/startTrans
- /kettle/runTrans
- /kettle/executeTrans
- /kettle/pauseTrans
- /kettle/stopTrans
- /kettle/removeTrans
- /kettle/cleanupTrans
- /kettle/sniffStep
- /kettle/registerTrans
An API marked as "deprecated" has been restructured and modified, with new classes and methods which provide similar functionality. Whenever possible, you should modify your application to remove references to deprecated methods and classes and use the new alternatives.
/kettle/addTrans (Deprecated)
This API has been deprecated. Use /kettle/registerTrans.
Overview
Uploads and executes transformation configuration XML file.
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/addTrans/?xml=Y
Request body should contain xml containing transformation_configuration (transformation and transformation_execution_configuration wrapped in transformation_configuration tag).
Parameters
name | description | type |
---|---|---|
xml | Boolean flag set to either Y or N describing if xml or html reply should be produced. | boolean, optional |
Response Body
element: | (custom) |
media types: | text/xml, text/html |
Response wraps transformation name that was executed or error stack trace if an error occurred. Response has result
OK if there were no errors. Otherwise it returns ERROR.
Example Response:
<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>
/kettle/transImage
The following operations are supported on this resource:
Overview
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.
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/transImage/ POST body name=dummy-trans
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be used for image generation. | query |
id | Carte id of the transformation to be used for image generation. | query, optional |
Response Body
binary streak: | image |
media types: | image/png |
A binary PNG image or empty response is presented if no transformation is found.
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/transStatus
The following operations are supported on this resource:
Overview
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.
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/transStatus/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be used for status generation. | query |
xml | Boolean flag which defines output format Y forces XML output to be generated. HTML is returned otherwise. | boolean, optional |
id | Carte id of the transformation to be used for status generation. | query, optional |
from | Start line number of the execution log to be included into response. | integer, optional |
Response Body
element: | (custom) |
media types: | text/xml, text/html |
Response XML or HTML response containing details about the transformation specified. If an error occurs during method invocation result
field of the response will contain ERROR
status.
Example Response:
<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-rows/> </result> <logging_string><![CDATA[H4sIAAAAAAAAADMyMDTRNzTUNzJRMDSyMrC0MjFV0FVIKc3NrdQtKUrMKwbyXDKLCxJLkjMy89IViksSi0pSUxTS8osUwPJARm5iSWZ+nkI0kq5YXi4AQVH5bFoAAAA=]]></logging_string> </transstatus>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/prepareExec
The following operations are supported on this resource:
Overview
Prepares previously loaded transformation for execution. Method is used for preparing previously uploaded transformation for execution by its name.
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/prepareExec/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be prepared for execution. | query |
xml | Boolean flag which sets the output format required. Use Y to receive XML response. | boolean |
id | Carte transformation ID of the transformation to be prepared for execution. | query, optional |
Response Body
text: | HTML |
media types: | text/xml, text/html |
Response XML or HTML containing operation result. When using xml=Y result
field indicates whether operation was successful (OK
) or not (ERROR
).
Example Response:
<webresult> <result>OK</result> <message/> <id/> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/startExec
The following operations are supported on this resource:
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/startExec/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be executed. | query |
xml | Boolean flag which sets the output format required. Use Y to receive XML response. | boolean, optional |
id | Carte transformation ID of the transformation to be executed. This parameter is optional when xml=Y is used. | query, optional |
Response Body
text: | HTML |
media types: | text/xml, text/html |
Response XML or HTML containing operation result. When using xml=Y result
field indicates whether operation was successful (OK
) or not (ERROR
).
Example Response:
<webresult> <result>OK</result> <message/> <id/> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/startTrans
The following operations are supported on this resource:
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/startTrans/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be executed. | query |
xml | Boolean flag which sets the output format required. Use Y to receive XML response. | boolean, optional |
id | Carte transformation ID of the transformation to be executed. This parameter is optional when xml=Y is used. | query, optional |
Response Body
text: | HTML |
media types: | text/xml, text/html |
Response XML or HTML containing operation result. When using xml=Y result
field indicates whether operation was successful (OK
) or not (ERROR
).
Example Response:
<webresult> <result>OK</result> <message>Transformation [dummy-trans] was started.</message> <id/> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/runTrans
The following operations are supported on this resource:
Overview
Execute transformation from enterprise repository. Repository should be configured in Carte xml file. Response contains ERROR
result if error happened during transformation execution.
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/runTrans/ POST body trans=home%2Fadmin%2Fdummy-trans&level=Debug
Parameters
name | description | type |
---|---|---|
trans | Full path to the transformation in repository. | query |
level | Logging level to be used for transformation execution (i.e. Debug). | query |
Response Body
element: | (custom) |
media types: | text/xml |
Response contains result of the operation. It is either OK
or ERROR
. If an error occurred during transformation execution, response also contains information about the error.
Example Response:
<webresult> <result>OK</result> <message>Transformation started</message> <id>7c082e8f-b4fe-40bc-b424-e0f881a61874</id> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/executeTrans
Overview
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.
GET
Example Request:
GET /kettle/executeTrans/?rep=my_repository&user=my_user&pass=my_password&trans=my_trans&level=INFO GET /kettle/executeTrans/?trans=PathToFile/&level=Debug
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/executeTrans/ POST body user=admin&pass=password&trans=home%2fadmin%2fdummy-trans&level=Debug&rep=di
Parameters
name | description | type |
---|---|---|
rep | Repository id to connect to. | query |
user | User name to be used to connect to repository. | query |
pass | User password to be used to connect to repository. | query |
trans | Transformation name to be loaded and executed. | query |
level | Logging level to be used for transformation execution (i.e. Debug). | query |
*any name* | All the other parameters will be sent to the transformation for using as variables. When necessary you can add custom parameters to the request. They will be used to set the transformation variables values.. | query |
Response Body
element: | (custom) |
media types: | application/xml |
Response contains error output of the transformation executed or nothing if the execution was successful.
Example Error Response:
<webresult> <result>ERROR</result> <message>Unexpected error executing the transformation: org.pentaho.di.core.exception.KettleException: Unable to find transformation 'dummy-trans.ktr' in directory :/home/admin at org.pentaho.di.www.ExecuteTransServlet.loadTransformation(ExecuteTransServlet.java:214) at org.pentaho.di.www.ExecuteTransServlet.doGet(ExecuteTransServlet.java:104) at javax.servlet.http.HttpServlet.service(HttpServlet.java:707) at javax.servlet.http.HttpServlet.service(HttpServlet.java:820) at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511) at org.mortbay.jetty.servlet.ServletHandler.handle(ServletHandler.java:390) at org.mortbay.jetty.servlet.SessionHandler.handle(SessionHandler.java:182) at org.mortbay.jetty.handler.ContextHandler.handle(ContextHandler.java:765) at org.mortbay.jetty.handler.ContextHandlerCollection.handle(ContextHandlerCollection.java:230) at org.mortbay.jetty.handler.HandlerCollection.handle(HandlerCollection.java:114) at org.mortbay.jetty.handler.HandlerWrapper.handle(HandlerWrapper.java:152) at org.mortbay.jetty.Server.handle(Server.java:326) at org.mortbay.jetty.HttpConnection.handleRequest(HttpConnection.java:536) at org.mortbay.jetty.HttpConnection$RequestHandler.headerComplete(HttpConnection.java:915) at org.mortbay.jetty.HttpParser.parseNext(HttpParser.java:539) at org.mortbay.jetty.HttpParser.parseAvailable(HttpParser.java:212) at org.mortbay.jetty.HttpConnection.handle(HttpConnection.java:405) at org.mortbay.jetty.bio.SocketConnector$Connection.run(SocketConnector.java:228) at org.mortbay.thread.QueuedThreadPool$PoolThread.run(QueuedThreadPool.java:582) </message> <id/> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/pauseTrans
The following operations are supported on this resource:
Overview
Pauses transformation to be executed. Method is used for pausing running transformation by its name.
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/pauseTrans/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be paused. | query |
xml | Boolean flag which sets the output format required. Use Y to receive XML response. | boolean, optional |
id | Carte transformation ID of the transformation to be paused. This parameter is optional when xml=Y is used. | query, optional |
Response Body
text: | HTML |
media types: | text/xml, text/html |
Response XML or HTML containing operation result. When using xml=Y result
field indicates whether operation was successful (OK
) or not (ERROR
).
Example Response:
<webresult> <result>OK</result> <message>Transformation [dummy-trans (master)] : pause requested.</message> <id/> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/stopTrans
The following operations are supported on this resource:
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/stopTrans/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be stopped. | query |
xml | Boolean flag which sets the output format required. Use Y to receive XML response. | boolean, optional |
id | Carte transformation ID of the transformation to be stopped. This parameter is optional when xml=Y is used. | query, optional |
Response Body
text: | HTML |
media types: | text/xml, text/html |
Response XML or HTML containing operation result. When using xml=Y result
field indicates whether operation was successful (OK
) or not (ERROR
).
Example Response:
<webresult> <result>OK</result> <message>Transformation [dummy-trans] stop requested.</message> <id>c56961b2-c848-49b8-abde-76c8015e29b0</id> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/removeTrans
The following operations are supported on this resource:
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/removeTrans/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be removed. | query |
xml | Boolean flag which sets the output format required. Use Y to receive XML response. | boolean, optional |
id | Carte transformation ID of the transformation to be removed. This parameter is optional when xml=Y is used. | query, optional |
Response Body
text: | HTML |
media types: | text/xml, text/html |
Response XML or HTML containing operation result. When using xml=Y result
field indicates whether operation was successful (OK
) or not (ERROR
).
Example Response:
<webresult> <result>OK</result> <message/> <id/> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/cleanupTrans
The following operations are supported on this resource:
Overview
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.
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/cleanupTrans/ POST body name=dummy-trans&xml=Y
Parameters
name | description | type |
---|---|---|
name | Name of the transformation to be cleaned. | query |
xml | Boolean flag which sets the output format required. Use Y to receive XML response. | boolean, optional |
id | Carte transformation ID of the transformation to be cleaned. | query, optional |
sockets | Boolean flag which indicates if full clean up or sockets only is required. Use Y to clean just sockets. | boolean, optional |
Response Body
text: | HTML |
media types: | text/xml, text/html |
Response XML or HTML containing operation result. When using xml=Y result
field indicates whether operation was successful (OK
) or not (ERROR
).
Example Response:
<webresult> <result>OK</result> <message>All server sockets ports for transformation [dummy-trans2] were deallocated. Transformation [dummy-trans2] was cleaned up.</message> <id/> </webresult>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/sniffStep
The following operations are supported on this resource:
POST
Content-Type: application/x-www-form-urlencoded should be set to use POST.
Example Request:
POST /kettle/sniffStep/ POST body trans=dummy-trans&step=Dummy (do nothing)&xml=Y
Parameters
name | description | type |
---|---|---|
trans | Name of the transformation containing required step. | query |
stepName | Name of the transformation step to collect data for. | query |
copynr | Copy number of the step to be used for collecting data. If not provided 0 is used. | integer, optional |
type | Type of the data to be collected (input or output ). If not provided output data is collected. | query, optional |
xml | Boolean flag which defines output format Y forces XML output to be generated. HTML is returned otherwise. | boolean, optional |
id | Carte id of the transformation to be used for step lookup. | query, optional |
lines | Number of lines to collect and include into response. If not provided 0 lines will be collected. | integer, optional |
Response Body
element: | (custom) |
media types: | text/xml, text/html |
Response XML or HTML response containing data and metadata of the step. If an error occurs during method invocation result
field of the response will contain ERROR
status.
Example Response:
<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>
Status Codes
code | description |
---|---|
200 | Request was processed. |
500 | Internal server error occurs during request processing. |
/kettle/registerTrans
Overview
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).
Parameters
name | description | type |
---|---|---|
xml | Boolean flag set to either Y or N describing if xml or html reply should be produced. | boolean, optional |
Response Body
element: | (custom) |
media types: | text/xml, text/html |
Response wraps transformation name that was executed or error stack trace if an error occurred. Response has result
OK if there were no errors. Otherwise it returns ERROR.
Example Response:
<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>
Status Codes
code | description |
---|---|
200 | Request was processed and XML response is returned. |
500 | Internal server error occurs during request processing. |