Skip to main content
Pentaho Documentation

Jobs

Overview

Provides information on web service calls to create, run, and delete jobs.  Calls for getting images, statuses and for starting and stopping jobs are also included.

Provides web service calls to create, run, and delete jobs.  Calls for getting images, statuses and for starting and stopping jobs 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.

The following resources are applicable.

  • /kettle/addJobs
  • /kettle/jobImage
  • /kettle/jobStatus
  • /kettle/runJob
  • /kettle/startJob
  • /kettle/stopJob​
  • /kettle/removeJob

/kettle/addJobs

Overview

Uploads and executes job configuration XML file. 

POST

Uploads and executes job configuration XML file. Uploads xml file containing job and job_execution_configuration (wrapped in job_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 job_configuration xml is transferred within request body. Job name of the executed job 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/addJob/?xml=Y
    

Request body should contain xml containing job_configuration (job + job_execution_configuration wrapped in job_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 job 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>Job 'dummy_job' was added to the list with id 1e90eca8-4d4c-47f7-8e5c-99ec36525e7c</message>
   <id>1e90eca8-4d4c-47f7-8e5c-99ec36525e7c</id>
</webresult>

Status Codes

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

/kettle/jobImage

Overview

Generates and returns image of the specified job. 

GET

Generates PNG image of the specified job currently present on Carte server. Job name and Carte job ID (optional) is used for specifying job to get information for. Response is binary of the PNG image.

Example Request:

    GET /kettle/jobImage?name=dummy_job
    

Parameters

name description type
name Name of the job to be used for image generation. query
id Carte id of the job to be used for image generation. query, optional

Response Body

binary streak: image
media types: image/png

A binary PNG image or empty response if no job is found.

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/jobStatus

Overview

Retrieves status of the specified job.

GET

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

Example Request:

    GET /kettle/jobStatus/?name=dummy_job&xml=Y
    

Parameters

name description type
name Name of the job 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 job 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 job specified. If an error occurs during method invocation result field of the response will contain ERROR status.

Example Response:

    
    <jobstatus>
    <jobname>dummy_job</jobname>
    <id>a4d54106-25db-41c5-b9f8-73afd42766a6</id>
    <status_desc>Finished</status_desc>
    <error_desc/>
    <logging_string><![CDATA[H4sIAAAAAAAAADMyMDTRNzTUNzRXMDC3MjS2MjJQ0FVIKc3NrYzPyk8CsoNLEotKFPLTFEDc1IrU5NKSzPw8Xi4j4nRm5qUrpOaVFFUqRLuE+vpGxhKj0y0zL7M4IzUFYieybgWNotTi0pwS2+iSotLUWE1iTPNCdrhCGtRsXi4AOMIbLPwAAAA=]]></logging_string>
    <first_log_line_nr>0</first_log_line_nr>
    <last_log_line_nr>20</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>N</is_stopped>
      <log_channel_id/>
      <log_text>null</log_text>
      <result-file/>
      <result-rows/>
    </result>
  </jobstatus>
    

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/runJob

Overview

Executes job from enterprise repository.

GET

Executes job from enterprise repository. Repository should be configured in configuration.xml file. Response contains ERROR result if error happened during job execution.

Example Request:

    GET /kettle/runJob?job=home%2Fadmin%2Fdummy_job&level=Debug
    

Parameters

name description type
job Full path to the job in repository. query
level Logging level to be used for job 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 job execution, response also contains information about the error.

Example Response:

    <webresult>
      <result>OK</result>
      <message>Job started</message>
      <id>05d919b0-74a3-48d6-84d8-afce359d0449</id>
    </webresult> 
    

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/startJob

Overview

Starts the job.

GET

Starts the job. If the job cannot be started, an error is returned.

Example Request:

      GET /kettle/startJob/?name=dummy_job&xml=Y
      

Parameters

name description type
name Name of the job to be executed. query
xml Boolean flag which sets the output format required. Use Y to receive XML response. boolean, optional
id Carte job ID of the job 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>Job [dummy_job] was started.</message>
      <id>abd61143-8174-4f27-9037-6b22fbd3e229</id>
    </webresult>
    

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/stopJob

Overview

Stops job execution on Carte server.

GET

Stops job execution on Carte server.

Example Request:

      GET /kettle/stopJob/?name=dummy_job&xml=Y
      

Parameters

name description type
name Name of the job to be stopped. query
xml Boolean flag which sets the output format required. Use Y to receive XML response. boolean, optional
id Carte job ID of the job 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>Job [dummy_job] stop requested.</message>
      <id/>
    </webresult>
    

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.
 

/kettle/removeJob

Overview

Remove specified job from Carte server.

GET

Remove specified job from Carte server.

Example Request:

      GET /kettle/removeJob/?name=dummy_job&xml=Y
      

Parameters

name description type
name Name of the job to be removed. query
xml Boolean flag which sets the output format required. Use Y to receive XML response. boolean, optional
id Carte job ID of the job 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.