Skip to main content
Pentaho Documentation

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>
    

Status Codes

code description
200 Request was processed and XML response is returned.
500 Internal server error occurs during request processing.

/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.

GET

Example Request:

    GET /kettle/transImage?name=dummy-trans
    

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.

GET

Example Request:

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

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.

GET

Example Request:

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

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:

Overview

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

GET

Example Request:

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

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:

Overview

Executes transformation previously uploaded to Carte server.

GET

Example Request:

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

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.

GET

Example Request:

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

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.

GET

Example Request:

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

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:

Overview

Stops transformation execution on Carte server.

GET

Example Request:

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

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:

Overview

Removes specified transformation from Carte server.

GET

Example Request:

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

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.

GET

Example Request:

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

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:

Overview

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

GET

Example Request:

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

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.